[feature] Dev Sandbox & eID SDK

[coodos]

Description

Provide a dev sandbox that replicates eID wallet behaviour so developers can test platform auth, provisioning, and other W3DS flows without using the real eID wallet app or manually creating eVaults. The sandbox should offer a minimal UI to drive the same operations the wallet does (provision eVault, sign session for auth, sync public key, etc.) so that integration and E2E tests can run against a predictable, scriptable “wallet”.

To make this feasible and maintainable, eID wallet behaviour must first be extracted into an external SDK with a clear API and tests. The SDK should be bring your own crypto: it defines interfaces for key generation, public key export, and signing, but does not bundle or dictate a crypto implementation. The sandbox supplies its own (e.g. Web Crypto API or a test double); the real eID wallet supplies hardware/software key managers. The sandbox UI then consumes this SDK; the real eID wallet can later use the same SDK so behaviour stays in sync.

Context

• Today, testing auth and other wallet-driven flows requires either the real eID wallet (mobile) or ad‑hoc scripts, which is slow and brittle.
• A dedicated dev sandbox lets developers and QA exercise auth, provisioning, and signing in a browser (or simple desktop) UI without touching the real wallet or manually provisioning eVaults via eID wallet.
• Extracting wallet logic into an SDK ensures one source of truth, testable in isolation, and reusable by both the sandbox and the real wallet.

Current eID Wallet–relevant flows

Provisioning (onboarding / eVault creation)

sequenceDiagram
 participant User
 participant Wallet as eID Wallet
 participant Registry as Registry
 participant Provisioner as Provisioner Service
 participant EVault as eVault Core

 User->>Wallet: Open app / start onboarding
 Wallet->>Wallet: Generate key pair (HW or SW)
 Wallet->>Registry: GET /entropy
 Registry-->>Wallet: JWT entropy token
 Wallet->>Wallet: Generate namespace
 Wallet->>Provisioner: POST /provision (entropy, namespace, publicKey)
 Provisioner->>Registry: Key binding cert (if publicKey)
 Provisioner->>EVault: Create eVault instance
 Provisioner-->>Wallet: w3id, evaultUri
 Wallet->>Wallet: Store credentials locally
 Wallet-->>User: Onboarded (eName + eVault URL)

Loading

Platform authentication (login with signed session)

sequenceDiagram
 participant User
 participant Wallet as eID Wallet
 participant Platform as Platform API
 participant Validator as Signature Validator
 participant Registry as Registry
 participant EVault as User eVault

 User->>Platform: Request login
 Platform->>Platform: Generate session ID
 Platform-->>User: Show QR / w3ds://auth URI
 User->>Wallet: Scan QR / open deep link
 Wallet->>Wallet: Parse redirect, session, platform
 Wallet->>Wallet: Sign session ID (default key)
 Wallet->>Platform: POST redirect URL (w3id, session, signature)
 Platform->>Validator: verifySignature(...)
 Validator->>Registry: GET /resolve?w3id=...
 Registry-->>Validator: eVault URL
 Validator->>EVault: GET /whois (X-ENAME)
 EVault-->>Validator: keyBindingCertificates[]
 Validator->>Registry: GET /.well-known/jwks.json
 Validator->>Validator: Verify JWT, extract pubkey, verify signature
 Validator-->>Platform: Valid / invalid
 Platform-->>User: Auth token or error

Loading

Proposed sandbox flow

sequenceDiagram
 participant Dev as Developer / QA
 participant SandboxUI as Dev Sandbox UI
 participant SDK as eID Wallet SDK
 participant Registry as Registry
 participant Provisioner as Provisioner
 participant Platform as Platform
 participant EVault as eVault Core

 Dev->>SandboxUI: Open sandbox (browser or local)
 Dev->>SandboxUI: "Provision new eVault"
 SandboxUI->>SDK: provision(entropy, namespace, cryptoAdapter)
 Note over SandboxUI,SDK: cryptoAdapter = BYO (e.g. Web Crypto)
 SDK->>SDK: getPublicKey() via adapter
 SDK->>Registry: GET /entropy
 SDK->>Provisioner: POST /provision(...)
 SDK-->>SandboxUI: w3id, evaultUri
 SandboxUI->>SandboxUI: Store / display eName + eVault URL

 Dev->>SandboxUI: "Authenticate to platform"
 SandboxUI->>SandboxUI: Show platform list or enter auth offer URL
 SandboxUI->>SDK: signSession(sessionId) or handleAuthOffer(uri)
 SDK->>SDK: sign(payload) via cryptoAdapter
 SDK-->>SandboxUI: signature + payload
 SandboxUI->>Platform: POST /api/auth/login (w3id, session, signature)
 Platform-->>SandboxUI: Auth token or error
 SandboxUI-->>Dev: Logged in / error

Loading

flowchart LR
 subgraph Prerequisite
 A[eID Wallet Codebase] --> B[Extract wallet logic]
 B --> C[Wallet SDK + tests]
 end
 subgraph BYOC["Bring your own crypto"]
 C --> C1[CryptoAdapter interface]
 C1 --> C2[Sandbox: Web Crypto / test]
 C1 --> C3[Real wallet: HW/SW manager]
 end
 subgraph Sandbox
 C --> D[Dev Sandbox UI]
 C2 --> D
 D --> E[Provision eVault]
 D --> F[Auth to platform]
 D --> G[Sync public key]
 D --> H[Sign payload]
 end
 E --> I[Test without real wallet]
 F --> I
 G --> I
 H --> I

Loading

Prerequisite: eID Wallet SDK (bring your own crypto)

• Extract from the eID wallet codebase a reusable SDK (npm package or workspace package) that implements protocol and flow logic only. The SDK does not bundle or mandate a crypto implementation; it accepts a crypto adapter (bring your own crypto).
• Crypto adapter interface: SDK defines an interface (e.g. CryptoAdapter or KeyProvider) with methods such as:
  • generateKeyPair() (or equivalent) → public key + opaque key handle/ID.
  • getPublicKey(keyId) → public key in the format required by provisioning/whois (e.g. multibase).
  • sign(keyId, payload: string) → signature (base64 or multibase as required by the protocol).
  • No private key or raw bytes are exposed; the SDK only calls these methods.
• SDK responsibilities (using the adapter):
  • Provisioning: GET /entropy, namespace generation, call adapter for public key, POST /provision with that public key, return w3id and evaultUri.
  • Public key sync: e.g. PATCH to eVault using adapter’s getPublicKey.
  • Auth flow: Parse w3ds://auth (redirect, session, platform), call adapter’s sign(sessionId), POST to platform redirect URL with w3id, session, signature.
  • Sign payload: Call adapter’s sign(payload) for arbitrary strings (document signing, voting, etc.).
• Callers supply the adapter: Sandbox provides an adapter backed by Web Crypto API (or a test double); the real eID wallet provides an adapter backed by its existing hardware/software key managers. No default crypto implementation is shipped in the SDK package (or it is clearly optional/dev-only).
• API surface of the SDK is documented and stable enough for the sandbox and (later) the real wallet to depend on.
• Tests: Unit/integration tests for SDK using a test double for the crypto adapter (e.g. in-memory key + deterministic sign) so that entropy, provision, auth, and verify flows are tested without real hardware or browser crypto.

Acceptance criteria – Dev Sandbox

Sandbox UI and environment

• Sandbox app runs in a browser or as a simple local app (e.g. Vite + React/Svelte or static HTML/JS) and does not require the real eID wallet binary.
• Sandbox uses the eID Wallet SDK for all wallet-like operations (provision, auth, sign, sync key); no duplicate implementation of wallet logic.
• Configuration: Sandbox can be pointed at dev/staging Registry, Provisioner, and platform base URLs (env or config).

Provisioning (eVault creation)

• User can trigger “Provision new eVault” (or equivalent) in the sandbox.
• Sandbox uses SDK to obtain entropy, generate namespace, and call provision, passing its own crypto adapter (e.g. Web Crypto); SDK returns w3id and evaultUri.
• Sandbox displays (and optionally copies) the eName (w3id) and eVault URL so the developer can use them in platform tests or GraphQL clients.
• Optionally: sandbox can list or remember recently provisioned identities for the session so multiple eVaults can be created and switched.

Platform authentication

• User can “Authenticate to platform” (or equivalent): either paste a w3ds://auth URI or enter a platform auth-offer URL that returns such a URI.
• Sandbox uses SDK to parse the auth URI (redirect, session, platform), sign the session ID via the same crypto adapter used for that identity, and POST to the platform redirect URL with w3id, session, signature (and any other required fields).
• Sandbox displays success (e.g. “Logged in” or token) or failure (e.g. “Invalid signature” or platform error).
• Auth flow works against a real dev platform (e.g. blabsy or a minimal test platform) that implements /api/auth/offer and /api/auth/login and uses the signature validator.

Public key and signing

• After provisioning (or when selecting an identity), sandbox can sync the public key to the eVault via SDK (using the sandbox’s crypto adapter for getPublicKey), so that platforms can verify signatures via /whois and key binding certs.
• Sandbox exposes a way to sign an arbitrary payload (e.g. text field + “Sign” button) via SDK + its crypto adapter and show the signature, for testing signing flows without the real wallet.

Docs and usage

• README or docs explain how to run the sandbox, configure Registry/Provisioner/platform URLs, and run through “provision → auth” and “provision → sync key → auth” so developers can test auth and related flows without the eID wallet.
• No mention of “backfill” or internal migration details in the sandbox issue or sandbox-specific docs.

Out of scope (for this issue)

• Replacing or changing the real eID wallet app behaviour; the wallet may later adopt the SDK but that is a separate effort.
• The SDK shipping a default/production crypto implementation (BYOC only; sandbox and wallet each bring their own).
• Hardware key support in the sandbox (software keys only are sufficient for dev/testing).
• Production deployment or security hardening of the sandbox (dev-only tool).

References

• eID Wallet – overview, key management, provisioning, platform auth.
• Authentication – platform auth flow, session signing, verification.
• eVault – whois, key storage, provisioning from Provisioner.