# 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.