[feature] eVault Self-Registration + Token Grant via Crypto Challenge

[coodos]

Platform Auth — eVault Self-Registration + Token Grant via Crypto Challenge

Overview

• A Platform creates a Platform eVault.
• On creation, the platform eVault self-registers with the Control Panel so it appears in the platform list.
• An Admin can then grant access by issuing a challenge.
• The platform must prove key ownership (cryptographic challenge-response).
• If verified, the Control Panel issues an access token.

---

Actors & Components

• Platform: the integrator/service that owns the Platform eVault
• Platform eVault: platform-side vault instance
• Control Panel: admin UI + management API
• Auth Service: issues challenges, verifies proofs, mints tokens
• Registry DB: stores registered platforms + status
• Token Store: stores issued tokens / grants

---

Sequence — Create Platform eVault → Auto-Register

sequenceDiagram
  autonumber
  actor Platform
  participant Vault as Platform eVault
  participant CP as Control Panel API
  participant Reg as Registry DB

  Platform->>Vault: Create Platform eVault
  Vault->>CP: discovered via registry (uri, publicKey, vaultId)
  CP->>Reg: Insert platform (status=UNVERIFIED)
  Reg-->>CP: ok
  CP-->>Vault: 201 Created (platformId)
  Vault-->>Platform: Platform eVault ready (platformId)

  note over CP,Reg: Platform appears in Control Panel list (UNVERIFIED)

Loading

---

Sequence — Admin Grants Token → Crypto Challenge → Token Issued

sequenceDiagram
  autonumber
  actor Admin
  participant CP as Control Panel UI/API
  participant Auth as Auth Service
  participant Reg as Registry DB
  participant Vault as Platform eVault
  participant Tok as Token Store

  Admin->>CP: Grant access token for platformId
  CP->>Reg: Load platform (publicKey, status)
  Reg-->>CP: platform record
  CP->>Auth: Create challenge (platformId)
  Auth-->>CP: challengeId, nonce, expiresAt

  CP-->>Vault: Deliver challenge (challengeId, nonce, expiresAt)
  Vault->>Vault: Sign/Prove nonce with platform private key
  Vault-->>CP: POST /platforms/challenge/response (challengeId, proof)

  CP->>Auth: Verify proof (challengeId, proof, publicKey)
  Auth->>Auth: Verify signature / proof-of-possession
  Auth-->>CP: verified=true

  CP->>Tok: Mint access token (platformId, scopes, ttl)
  Tok-->>CP: accessToken
  CP->>Reg: Update status=VERIFIED, lastVerifiedAt=now
  CP-->>Admin: Token granted (accessToken)

Loading

---

State — Platform Registration & Token Grant

stateDiagram-v2
  [*] --> UNVERIFIED: eVault self-registers
  UNVERIFIED --> CHALLENGE_ISSUED: Admin starts grant
  CHALLENGE_ISSUED --> VERIFIED: Proof verified + token minted
  CHALLENGE_ISSUED --> UNVERIFIED: Proof invalid
  CHALLENGE_ISSUED --> UNVERIFIED: Challenge expired
  VERIFIED --> CHALLENGE_ISSUED: Re-grant / rotate token (optional)

Loading

---

Data Model (Minimal)

erDiagram
  PLATFORM {
    string platformId PK
    string vaultId
    string displayName
    string publicKey
    string status  "UNVERIFIED|VERIFIED"
    datetime createdAt
    datetime lastVerifiedAt
  }

  CHALLENGE {
    string challengeId PK
    string platformId FK
    string nonce
    datetime expiresAt
    datetime createdAt
    string status "PENDING|USED|EXPIRED"
  }

  TOKEN_GRANT {
    string tokenId PK
    string platformId FK
    string accessTokenHash
    string scopes
    datetime issuedAt
    datetime expiresAt
    string status "ACTIVE|REVOKED|EXPIRED"
  }

  PLATFORM ||--o{ CHALLENGE : issues
  PLATFORM ||--o{ TOKEN_GRANT : has

Loading