Files

CI / test (push) Successful in 5s

Details

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

2026-03-01 12:26:05 +00:00

2.9 KiB

Raw Blame History

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.

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.

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.

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.

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.

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.

2.9 KiB Raw Blame History