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

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.