From 978e0403eb4e5d694c9e18224caadeead89cf214 Mon Sep 17 00:00:00 2001
From: Andriy Oblivantsev <eslider@gmail.com>
Date: Sun, 1 Mar 2026 12:25:53 +0000
Subject: [PATCH] Add Ed25519 security use-case diagrams for developers.

Document identification, challenge-response authentication, protected feature collection write/read flows, and invitation lineage with Mermaid diagrams, and link the guide from README.

Made-with: Cursor
---
 README.md                          |  1 +
 docs/ed25519-security-use-cases.md | 81 ++++++++++++++++++++++++++++++
 2 files changed, 82 insertions(+)
 create mode 100644 docs/ed25519-security-use-cases.md

diff --git a/README.md b/README.md
index 03d3472..e41564e 100644
--- a/README.md
+++ b/README.md
@@ -90,6 +90,7 @@ bun run build
 Frontend TypeScript integration guide:
 
 - `docs/typescript-frontend-integration.md`
+- `docs/ed25519-security-use-cases.md`
 
 ## CI
 
diff --git a/docs/ed25519-security-use-cases.md b/docs/ed25519-security-use-cases.md
new file mode 100644
index 0000000..5b50a73
--- /dev/null
+++ b/docs/ed25519-security-use-cases.md
@@ -0,0 +1,81 @@
+# Ed25519 Security Use Cases
+
+This document describes how Ed25519 key pairs are used for identity, authentication, and secure access to feature collection data.
+
+## 1) Identification by Public Key
+
+Each user identity is represented by an Ed25519 public key. The backend never needs the private key.
+
+```mermaid
+flowchart LR
+  userClient[UserClient] -->|"holds private key locally"| privateKey[PrivateKey]
+  userClient -->|"shares public key"| backendApi[BackendAPI]
+  backendApi -->|"registers identity by public key"| usersTable[(UsersByPublicKey)]
+```
+
+## 2) Authentication via Challenge Signature
+
+Authentication is challenge-response: client signs server nonce with private key; server verifies with stored public key.
+
+```mermaid
+sequenceDiagram
+  participant C as Client
+  participant A as API
+  participant U as UsersStore
+
+  C->>A: POST /v1/auth/challenge {publicKey}
+  A-->>C: {nonce, messageToSign}
+  C->>C: sign(messageToSign, privateKey)
+  C->>A: POST /v1/auth/login {publicKey, nonce, signature}
+  A->>U: load user by publicKey
+  A->>A: verify signature with publicKey
+  A-->>C: {accessToken}
+```
+
+## 3) Secure Data Storing (Write Feature Collection Data)
+
+Only an authenticated token linked to a verified public key can create collections and features for that owner key.
+
+```mermaid
+flowchart TD
+  requestCreate[CreateCollectionOrFeatureRequest] --> bearerCheck[BearerTokenValidation]
+  bearerCheck --> sessionStore[(Sessions)]
+  sessionStore --> ownerKey[ResolvedOwnerPublicKey]
+  ownerKey --> ownershipRule[OwnershipValidation]
+  ownershipRule --> writeData[(CollectionsAndFeatures)]
+  ownershipRule --> reject403[RejectForbidden]
+```
+
+## 4) Secure Data Receiving (Read Feature Collection Data)
+
+Reads are filtered by ownership. A token from one key cannot read another key's collections/features.
+
+```mermaid
+flowchart TD
+  requestRead[ReadCollectionsOrFeaturesRequest] --> validateToken[ValidateBearerToken]
+  validateToken --> ownerKey[OwnerPublicKeyFromSession]
+  ownerKey --> queryOwned[QueryOnlyOwnerRows]
+  queryOwned --> responseData[ReturnOwnedCollectionsFeatures]
+  ownerKey --> denyOther[RejectOtherOwnerAccess]
+```
+
+## 5) Invitation-Based Identity Expansion
+
+Existing users can issue signed invitations. New users prove ownership of their own private key at registration.
+
+```mermaid
+flowchart LR
+  inviter[InviterUser] -->|"sign invite payload"| invitePayload[InvitePayloadAndSignature]
+  newUser[NewUser] -->|"submit public key + invite + proof signature"| registerEndpoint[RegisterEndpoint]
+  registerEndpoint --> verifyInvite[VerifyInviteSignatureAndRules]
+  registerEndpoint --> verifyProof[VerifyNewUserProofSignature]
+  verifyInvite --> usersStore[(UsersStore)]
+  verifyProof --> usersStore
+```
+
+## Security Notes
+
+- Private keys stay client-side.
+- Public keys are stable user identifiers.
+- Session tokens are granted only after valid Ed25519 signature verification.
+- Collection/feature access is enforced by owner key derived from session identity.