@cef-ai/wallet-identity 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,443 @@
+import { ApiClient } from '@cef-ai/wallet-api-client';
+
+/** Spec §3.1. Public contract for the identity layer. */
+interface Addresses {
+    cere: string;
+    solana: string;
+    evm: string;
+}
+type Chain = 'cere' | 'solana' | 'evm';
+interface Identity {
+    readonly isAuthenticated: boolean;
+    readonly addresses: Addresses | null;
+    readonly credentialId: string | null;
+    register(opts?: {
+        label?: string;
+    }): Promise<void>;
+    login(): Promise<void>;
+    logout(): void;
+    /** Returns a valid JWT; runs the passkey ceremony if needed. */
+    getJwt(): Promise<string>;
+    /**
+     * Release any browser-owned handles this identity holds (cross-tab channel,
+     * timers, broadcast listeners). After `dispose()` the identity is unusable.
+     *
+     * Idempotent: callable multiple times safely.
+     */
+    dispose(): void;
+}
+/**
+ * Signers/* receive this function via a constructor-time closure handoff
+ * from a concrete Identity instance. It is exported as a type-only alias so
+ * dependents can annotate the closures they receive, but it is intentionally
+ * absent from the `Identity` interface — there is no public `sign()` method.
+ */
+type InternalSign = (chain: Chain, payload: Uint8Array) => Promise<Uint8Array>;
+
+/** Spec §3.2 locked decision #14. Permanent for v1; rotate via "-v2" suffix. */
+declare const PRF_INPUT_LABEL = "cere-wallet-prf-v1";
+/**
+ * SHA-256("cere-wallet-prf-v1") — 32 bytes. Fed to WebAuthn `prf.eval.first`.
+ *
+ * Implementation note: `createHash` runs at module evaluation time. In the test
+ * environment (Vitest on Node) this works natively via `node:crypto`. In the
+ * browser this depends on a `node:crypto` polyfill — `vite-plugin-node-polyfills`
+ * is wired in by Cycle 1 Task 8. A follow-up cycle should replace this expression
+ * with a hard-coded `Uint8Array` literal to eliminate the polyfill dependency.
+ */
+declare const PRF_INPUT_SEED: Uint8Array;
+/** Spec §3.2. Used as HKDF-SHA256 info to derive the secp256k1 32-byte secret. */
+declare const EVM_HKDF_INFO = "cere-wallet-evm-secp256k1-v1";
+
+/**
+ * Runtime support detection for WebAuthn + PRF.
+ *
+ * Spec §3.7. Real PRF capability is only knowable from a completed ceremony
+ * (via `clientExtensionResults.prf.enabled` or `prf.results.first`). This
+ * pre-check returns the best signal we can get without spending a credential.
+ */
+interface PrfSupportResult {
+    webAuthn: boolean;
+    /**
+     * Whether a platform authenticator (Touch ID / Windows Hello) is enrolled.
+     * INFORMATIONAL ONLY — it is NOT a precondition for using the wallet, which
+     * also works with roaming security keys and phone passkeys (via hybrid).
+     */
+    platformAuthenticator: boolean;
+    /**
+     * Best-effort PRF signal. `true` unless we can prove otherwise: modern
+     * browsers expose `PublicKeyCredential.getClientCapabilities()`, which gives
+     * a definitive `extensions:prf` answer. When that API is absent (older
+     * browsers) we stay optimistic and let the ceremony be the final arbiter
+     * (it throws `prf-unsupported` if the authenticator returns no PRF output).
+     */
+    prfPotentiallySupported: boolean;
+}
+declare function detectPrfSupport(): Promise<PrfSupportResult>;
+/**
+ * Inspect a `PublicKeyCredential.getClientExtensionResults()` payload to
+ * determine whether PRF actually worked in the ceremony. Spec §3.7 calls this
+ * "final answer; the pre-check above is best-effort only".
+ */
+declare function isPrfSupportedResult(extensions: {
+    prf?: {
+        enabled?: boolean;
+        results?: {
+            first?: Uint8Array;
+        };
+    };
+}): boolean;
+
+/** Cere's SS58 network prefix. Spec §3.2. */
+declare const CERE_SS58_PREFIX = 54;
+/**
+ * SS58 address for the Cere network.
+ *
+ * SS58 spec (Substrate): for prefixes 0–63 the format is:
+ *   [prefix byte] || [32-byte pubkey] || [2-byte checksum]
+ * where checksum = blake2b-512("SS58PRE" || prefix || pubkey)[0..2].
+ * The whole thing is base58-encoded. We use prefix 54 (Cere) which fits in
+ * the 1-byte encoding (< 64).
+ *
+ * @param edPubkey 32-byte Ed25519 public key.
+ */
+declare function deriveCereAddress(edPubkey: Uint8Array): string;
+/**
+ * Solana address: base58(Ed25519 pubkey). No prefix, no checksum.
+ *
+ * @param edPubkey 32-byte Ed25519 public key.
+ */
+declare function deriveSolanaAddress(edPubkey: Uint8Array): string;
+/**
+ * Recover the raw 32-byte Ed25519 public key from a Solana address.
+ *
+ * The Solana address is `base58(edPubkey)` with no prefix or checksum
+ * ({@link deriveSolanaAddress}), so a base58 decode yields the pubkey directly.
+ * The public key is not secret — it IS the address — so this introduces no key
+ * exposure beyond what the address already reveals; the session keys never
+ * leave `SessionVault`. The same Ed25519 key backs the Cere SS58 address.
+ *
+ * @param solanaAddress base58 Solana address.
+ * @returns the 32-byte Ed25519 public key.
+ */
+declare function decodeEd25519Pubkey(solanaAddress: string): Uint8Array;
+/**
+ * EVM address: '0x' + last 20 bytes of keccak256(secp256k1 uncompressed pubkey X||Y).
+ *
+ * Accepts either 64-byte (raw X||Y) or 65-byte (0x04||X||Y) input. The 0x04
+ * prefix byte is stripped if present.
+ *
+ * @param secpPubkey secp256k1 public key.
+ */
+declare function deriveEvmAddress(secpPubkey: Uint8Array): string;
+
+interface DerivedKeys {
+    /** Ed25519 32-byte secret key seed; used for Cere + Solana signing. */
+    edSeed: Uint8Array;
+    /** secp256k1 32-byte secret key; used for EVM signing. */
+    secpKey: Uint8Array;
+    /** 32-byte Ed25519 public key derived from edSeed. */
+    edPubkey: Uint8Array;
+    /** 65-byte uncompressed secp256k1 public key (0x04 || X || Y) derived from secpKey. */
+    secpPubkeyUncompressed: Uint8Array;
+}
+/**
+ * Derive the v2 session keys from a WebAuthn PRF output. Spec §3.2.
+ *
+ *   edSeed  = prfOutput
+ *   secpKey = HKDF-SHA256(prfOutput, salt="", info="cere-wallet-evm-secp256k1-v1", L=32)
+ *
+ * @param prfOutput 32-byte PRF output from `prf.results.first`.
+ */
+declare function derivedKeys(prfOutput: Uint8Array): DerivedKeys;
+
+/**
+ * `hints` is a top-level field on the WebAuthn creation/request options
+ * (WebAuthn L3), but our TS DOM lib doesn't ship it yet. Declare-merge the
+ * precise W3C union so the ceremony can request authenticator hints without
+ * casts. Drop this augmentation once the workspace lib.dom.d.ts ships `hints`.
+ */
+declare global {
+    interface PublicKeyCredentialCreationOptions {
+        hints?: ('client-device' | 'hybrid' | 'security-key')[];
+    }
+    interface PublicKeyCredentialRequestOptions {
+        hints?: ('client-device' | 'hybrid' | 'security-key')[];
+    }
+}
+/**
+ * Adapter that runs WebAuthn ceremonies. Production implementations call
+ * `navigator.credentials.create/get`; the test implementation in
+ * `SoftAuthenticator` produces deterministic results without browser APIs.
+ *
+ * Spec §3.7. The `prfOutput` field is the result of the WebAuthn PRF extension
+ * — present when the authenticator supports PRF, absent otherwise.
+ */
+interface CeremonyAdapter {
+    register(opts: RegisterOptions): Promise<RegisterResult>;
+    login(opts: LoginOptions): Promise<LoginResult>;
+}
+interface RegisterOptions {
+    rpId: string;
+    challenge: Uint8Array;
+    userHandle: Uint8Array;
+    /** 32-byte PRF input (typically `PRF_INPUT_SEED`). */
+    prfInput: Uint8Array;
+    /** Human-readable label for the credential. Currently a hint, not stored. */
+    label?: string;
+}
+interface RegisterResult {
+    credentialId: string;
+    clientDataJSON: string;
+    attestationObject: string;
+    transports: string[];
+    /** Present iff PRF extension worked. */
+    prfOutput?: Uint8Array;
+}
+interface LoginOptions {
+    rpId: string;
+    challenge: Uint8Array;
+    /** Optional: if absent, the authenticator picks a credential. Present from us. */
+    credentialId?: string;
+    prfInput: Uint8Array;
+}
+interface LoginResult {
+    credentialId: string;
+    clientDataJSON: string;
+    authenticatorData: string;
+    signature: string;
+    prfOutput?: Uint8Array;
+}
+interface WebAuthnCeremonyAdapterOptions {
+    /**
+     * Override for the WebAuthn credentials manager. Defaults to
+     * `globalThis.navigator?.credentials`. Tests inject a mock.
+     */
+    credentials?: CredentialsContainer;
+}
+/**
+ * Production WebAuthn ceremony adapter. Calls `navigator.credentials.create/get`
+ * with the PRF extension. Spec §3.7.
+ *
+ * - `register`: requires a platform authenticator, user verification, Ed25519
+ *   (`alg: -8`), and the PRF extension with the wallet's input seed.
+ * - `login`: allows a specific credentialId if known; otherwise lets the
+ *   authenticator pick (resident key).
+ *
+ * Returned ArrayBuffers are base64url-encoded for API transport.
+ */
+declare class WebAuthnCeremonyAdapter implements CeremonyAdapter {
+    private readonly credentials?;
+    constructor(opts?: WebAuthnCeremonyAdapterOptions);
+    register(opts: RegisterOptions): Promise<RegisterResult>;
+    login(opts: LoginOptions): Promise<LoginResult>;
+}
+
+/**
+ * Base64url (RFC 4648 §5) helpers used by the WebAuthn ceremony adapter.
+ * Trailing `=` padding is stripped on encode; both padded and unpadded inputs
+ * are accepted on decode.
+ */
+/** Encode a Uint8Array or ArrayBuffer as a base64url string (no padding). */
+declare function bytesToB64u(input: Uint8Array | ArrayBuffer): string;
+/** Decode a base64url string into a Uint8Array. Padding is optional. */
+declare function b64uToBytes(s: string): Uint8Array;
+
+interface SoftAuthenticatorOptions {
+    /**
+     * If provided, derive the per-registration `edSeed`, `prfSecret`, and
+     * `credentialId` deterministically from this seed (mixed with a monotonic
+     * counter so multiple register() calls on the same instance still produce
+     * distinct credentials). Used by Playwright e2e specs that pin server-side
+     * address stubs against the SoftAuthenticator's output. Production code
+     * never sets this — the `useSoft` branch in `createIdentity.ts` is itself
+     * forbidden in production builds.
+     *
+     * Default: undefined (each register() draws fresh CSPRNG bytes, matching
+     * the pre-cycle-8.1 behavior used by unit tests in `ceremony.test.ts`).
+     */
+    seed?: string;
+    /**
+     * When the caller invokes login() without a credentialId, fall back to the
+     * most-recently-registered credential in memory. Default: false (login()
+     * throws when credentialId is missing, matching pre-cycle-8 behavior).
+     *
+     * Required for e2e flows that simulate the user signing back in after the
+     * vault has been cleared (post-logout re-login): the wallet has discarded
+     * the credentialId locally, but the soft authenticator's in-memory creds
+     * map still holds the registration, and the spec test needs login() to
+     * succeed anyway. Production code must never enable this — real WebAuthn's
+     * no-allowCredentials path shows an OS credential picker; the fallback
+     * here is a deterministic test convenience, not a real picker, so leaving
+     * it on by default would silently let a single registered credential
+     * impersonate any login.
+     */
+    fallbackToLastRegistered?: boolean;
+}
+/**
+ * Deterministic in-memory WebAuthn authenticator for tests. NOT for production.
+ *
+ * - Stores credentials in a private Map keyed by credentialId.
+ * - `prfOutput` is computed as HKDF-SHA256(prfSecret, salt="", info=prfInput, L=32),
+ *   so for a given credential and prfInput the result is stable across login calls.
+ * - `signature` is a valid Ed25519 signature over `authenticatorData || sha256(clientDataJSON)`.
+ *
+ * The output shapes match the real WebAuthn response well enough that the
+ * `Identity` integration tests (Task 6) can drive register → login → derive
+ * → cross-check without a real browser.
+ */
+declare class SoftAuthenticator implements CeremonyAdapter {
+    private readonly creds;
+    private readonly seedBytes;
+    private readonly fallbackToLastRegistered;
+    /** Monotonic counter mixed into the seed-derived material so successive
+     *  register() calls on a seeded instance produce distinct credentials. */
+    private regCounter;
+    constructor(opts?: SoftAuthenticatorOptions);
+    register(opts: RegisterOptions): Promise<RegisterResult>;
+    login(opts: LoginOptions): Promise<LoginResult>;
+    /** Public-key bytes for a credential. Used by integration tests for cross-checks. */
+    getEd25519PublicKey(credentialId: string): Uint8Array;
+    private computePrf;
+}
+
+interface VaultSnapshot {
+    addresses: Addresses;
+    credentialId: string;
+}
+interface SessionVault {
+    isOpen(): boolean;
+    /** Public-safe view: never includes raw keys. */
+    snapshot(): VaultSnapshot | null;
+    /** Open the vault with derived keys + the addresses they yielded + the credentialId. */
+    set(args: {
+        keys: DerivedKeys;
+        addresses: Addresses;
+        credentialId: string;
+    }): void;
+    /** Drop the keys and address state. Safe to call when already closed. */
+    clear(): void;
+    /**
+     * Sign a payload with the chain-appropriate key. Spec §3.6 invariant:
+     * this is the only way the rest of the package can reach the keys.
+     *
+     * - 'cere' / 'solana': Ed25519 signature over the raw payload (64 bytes).
+     * - 'evm': secp256k1 ECDSA over the raw payload (65 bytes: r || s || v).
+     *   The caller (an EVM signer) is responsible for framing (e.g. EIP-191)
+     *   and hashing (keccak256) before passing the digest as the payload.
+     */
+    sign(chain: Chain, payload: Uint8Array): Promise<Uint8Array>;
+}
+/**
+ * Closure-encapsulated session vault. The keys live in the closure variables
+ * `state.edSeed` / `state.secpKey` and are not reachable from outside.
+ *
+ * Spec §3.4. Lifetime: from `set()` until `clear()` or tab unload.
+ */
+declare function createSessionVault(): SessionVault;
+
+interface IdentityImplOptions {
+    apiClient: ApiClient;
+    ceremony: CeremonyAdapter;
+}
+declare class IdentityImpl implements Identity {
+    private readonly opts;
+    private readonly vault;
+    private cachedJwt;
+    /** Server-returned credential ID (used as the public identity.credentialId). */
+    private serverCredentialId;
+    private readonly _isAuthenticated;
+    private readonly _addresses;
+    private readonly _credentialId;
+    /** Cross-tab logout coordination via BroadcastChannel('scp-wallet-v2'). */
+    private readonly crossTabSync;
+    /** Handle to detach the cross-tab logout subscriber on dispose(). */
+    private readonly crossTabSyncUnsubscribe;
+    /** Idempotency flag for dispose(). */
+    private disposed;
+    constructor(opts: IdentityImplOptions);
+    get isAuthenticated(): boolean;
+    get addresses(): Addresses | null;
+    /**
+     * Returns the server-returned credentialId from the last register/login ceremony.
+     * The vault internally tracks the authenticator-generated credential ID for login use.
+     */
+    get credentialId(): string | null;
+    /**
+     * Read the (non-observable) vault snapshot + cached server credential ID and
+     * push the values into the three public observable boxes. Call after any
+     * mutation that could change the public derived state: register, login,
+     * logout, or constructor (hydration).
+     */
+    private syncPublicState;
+    register(opts?: {
+        label?: string;
+    }): Promise<void>;
+    login(): Promise<void>;
+    logout(): void;
+    getJwt(): Promise<string>;
+    /** Helper used by callers (e.g. ApiClient.getAuthToken). */
+    getCachedJwtForApiClient(): string | null;
+    /**
+     * Returns the session vault. Used by popup-side `wallet:sign` handlers
+     * which need direct access to `vault.sign(chain, payload)`. NOT for host-
+     * side use — keys never reach the host. Spec §3.6 invariant 1.
+     */
+    getVault(): SessionVault;
+    /**
+     * Release the BroadcastChannel + cross-tab subscriber. Idempotent.
+     *
+     * Called by:
+     *   - WalletProvider's useEffect cleanup (SPA unmount / apiBaseUrl change)
+     *   - test afterEach hooks (prevent listener leakage across tests)
+     *
+     * After dispose(), the identity is unusable: register/login/logout/getJwt
+     * still execute their normal logic, but cross-tab broadcasts no longer
+     * propagate (channel is closed) and the local subscriber is detached.
+     * The vault remains cleared (logout() runs locally). Spec §9.4 lifecycle.
+     */
+    dispose(): void;
+    private crossCheckAddresses;
+}
+
+/**
+ * Cross-tab session synchronisation helper.
+ *
+ * Wraps a `BroadcastChannel` on a fixed channel name so all tabs of the same
+ * origin can coordinate. Today we only use it for `{ type: 'logout' }` — when
+ * one tab logs out, every other tab clears its in-memory vault + JWT so its
+ * MobX-reactive UI immediately reflects the logged-out state.
+ *
+ * The channel name must match `BROADCAST_CHANNEL_NAME` in
+ * `packages/embed-sdk/src/protocol.ts` ('scp-wallet-v2'). Defined here as a
+ * local constant rather than imported to avoid a circular dep between
+ * `@cef-ai/wallet-identity` and `@cef-ai/wallet`. The name is part of the
+ * wire protocol — if you change one, change the other (and bump the major).
+ *
+ * Spec §9.4 (cross-tab session sharing).
+ */
+type CrossTabMessage = {
+    type: 'logout';
+};
+declare class CrossTabSync {
+    private channel;
+    private readonly listeners;
+    constructor();
+    /** Broadcast a message to all other tabs (and not to this tab — that's the
+     * BroadcastChannel spec). The originating tab is expected to have already
+     * applied the state change locally before broadcasting. */
+    broadcast(msg: CrossTabMessage): void;
+    /** Subscribe to messages from other tabs. Returns an unsubscribe function. */
+    subscribe(fn: (msg: CrossTabMessage) => void): () => void;
+    /**
+     * Close the underlying channel and drop all listeners. Idempotent.
+     *
+     * Sets `this.channel = null` so subsequent `broadcast()` calls become a
+     * no-op (the `?.postMessage` short-circuits) and we don't accidentally
+     * postMessage on a closed BroadcastChannel (which throws InvalidStateError
+     * in some implementations).
+     */
+    close(): void;
+}
+
+export { type Addresses, CERE_SS58_PREFIX, type CeremonyAdapter, type Chain, type CrossTabMessage, CrossTabSync, type DerivedKeys, EVM_HKDF_INFO, type Identity, IdentityImpl, type IdentityImplOptions, type InternalSign, type LoginOptions, type LoginResult, PRF_INPUT_LABEL, PRF_INPUT_SEED, type PrfSupportResult, type RegisterOptions, type RegisterResult, type SessionVault, SoftAuthenticator, type VaultSnapshot, WebAuthnCeremonyAdapter, type WebAuthnCeremonyAdapterOptions, b64uToBytes, bytesToB64u, createSessionVault, decodeEd25519Pubkey, deriveCereAddress, deriveEvmAddress, deriveSolanaAddress, derivedKeys, detectPrfSupport, isPrfSupportedResult };