Andriy Oblivantsev
978e0403eb
CI / test (push) Successful in 5s
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
82 lines
2.9 KiB
Markdown
82 lines
2.9 KiB
Markdown
# 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.
|