@coordination-network/wallet 0.0.2 → 0.1.0

package/README.md

@@ -7,6 +7,9 @@ The wallet verifies a credential's issuer signature and its holder, device, and
 revocation-secret bindings before storing it. Before presenting, it requires
 fresh approved-issuer and revocation trees, asks for consent, builds the private
 circuit inputs, and delegates proof generation to the configured proof system.
+It refuses a verifier-supplied `currentTime` more than 300 seconds from the
+holder's clock before consent, signing, or proving, so a verifier cannot search
+the credential's validity window by choosing arbitrary times.
 
 ## Use
 
@@ -50,25 +53,26 @@ const proof = await wallet.present(
         programme: "demo-programme",
         country: "ZZZ"
     },
-    // The state this credential is judged and proved against, read from its own issuer.
-    loadIssuerChainState
+    // The state this credential is judged and proved against: lists from the server the caller
+    // names, roots from chain.
+    loadChainStateForPresentation
 )
 
 stopSync()
 await proofGenerator.destroy()
 ```
 
-`loadChainState` returns each reconstructed tree alongside the authoritative
-root fetched from chain. The wallet rejects a mismatch before storing or
+`loadChainState` returns each reconstructed tree alongside its authoritative
+root. The caller must read the roots from chain, not from the server that
+served the lists: a root served beside its own list always matches it. The
+wallet rejects a tree that does not hash to its root before storing or
 presenting a credential. It uses the validated local trees to check every held
 credential without revealing to an RPC provider which credential it owns.
 
-Each issuer publishes its own approved-issuer-set and revocation endpoints, so
-a credential can only be judged against its own issuer's state.
-`syncCredential(id, load)` refreshes one credential against a `load` the
-caller points at that credential's own issuer, and `present(id, request, load)`
-takes the same kind of `load` so that the issuer the proof names and the
-revocation tree it is checked against come from one read.
+The lists come from whichever server the caller names and the roots from chain.
+`syncCredential(id, load)` refreshes one credential against a `load`, and
+`present(id, request, load)` takes the same kind of `load` so that the proof
+and the checks before it come from one read.
 `syncRevocations`/`startRevocationSync` refresh every held credential against
 the single `loadChainState` configured on the wallet, for background use.
 
@@ -76,12 +80,11 @@ the single `loadChainState` configured on the wallet, for background use.
 
 - Invalid, unapproved, revoked, not-yet-valid, or expired credentials are not
   stored.
-- A presentation proves membership against a set holding only the
-  credential's own issuer, not the wallet's full approved set, so the proof's
-  issuer root is that issuer's own leaf. This tells the verifier which issuer
-  signed and, so, which registry the revocation root must be valid in.
-  Membership of the full approved set is still checked beforehand, against the
-  state the presentation itself loaded.
+- A presentation proves membership against the whole approved set, so the
+  proof's issuer root is the set's root and names no issuer. One network-wide
+  revocation registry lets the verifier check the revocation root without
+  picking a registry. Membership is checked beforehand, against the state the
+  presentation itself loaded.
 - A presentation restamps the credential from its own `load` before judging it,
   so it never proves against state an earlier sync left behind. Background sync
   runs every 30 seconds by default.

package/dist/errors.d.ts

@@ -1,5 +1,6 @@
 export type WalletErrorCode = "NOT_FOUND" | "ALREADY_STORED" | "CREDENTIAL_INVALID" | "CONSENT_DENIED" | "REVOKED" | "CHAIN_STATE_UNAVAILABLE" | "CHAIN_STATE_INVALID" | "NOT_YET_VALID" | "EXPIRED" | "ISSUER_NOT_APPROVED" | "PRESENTATION_FAILED";
 export declare class WalletError extends Error {
     readonly code: WalletErrorCode;
-    constructor(code: WalletErrorCode, message: string);
+    readonly cause?: unknown;
+    constructor(code: WalletErrorCode, message: string, cause?: unknown);
 }

package/dist/errors.js

@@ -2,10 +2,11 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.WalletError = void 0;
 class WalletError extends Error {
-    constructor(code, message) {
+    constructor(code, message, cause) {
         super(message);
         this.name = "WalletError";
         this.code = code;
+        this.cause = cause;
     }
 }
 exports.WalletError = WalletError;

package/dist/wallet.d.ts

@@ -21,10 +21,10 @@ export interface ConsentRequest {
 export type ConsentPrompt = (request: ConsentRequest) => Promise<boolean>;
 export interface WalletChainState {
     approvedIssuers: ApprovedIssuerSet;
-    /** Authoritative root fetched independently of the reconstructed issuer tree. */
+    /** Authoritative root, read from chain by the caller, never from the server that served the leaves. */
     approvedIssuerRoot: bigint;
     revocations: RevocationRegistry;
-    /** Authoritative root fetched independently of the reconstructed revocation tree. */
+    /** Authoritative root, read from chain by the caller, never from the server that served the snapshot. */
     revocationRoot: bigint;
 }
 /** Fetches and validates the latest public issuer and revocation trees. */
@@ -41,8 +41,11 @@ export interface CredentialInfo {
     checkedAt: number;
 }
 export interface WalletOptions {
-    /** Raw 32-byte Semaphore identity seed derived from the hardware P-256 ECDH output. */
-    identitySeed: Uint8Array;
+    /**
+     * Raw 32-byte Semaphore identity seed derived from the hardware P-256 ECDH output. A thunk is
+     * called once per `addCredential` and `present`, so a device key can prompt only when needed.
+     */
+    identitySeed: Uint8Array | (() => Promise<Uint8Array>);
     deviceSigner: DeviceSigner;
     consent: ConsentPrompt;
     loadChainState: ChainStateLoader;
@@ -100,6 +103,7 @@ export declare class Wallet {
     private stamp;
     private statusOf;
     private loadAndValidateChainState;
+    private resolveIdentitySeed;
     private listCredentialIds;
     private readRecord;
     private writeRecord;

package/dist/wallet.js

@@ -14,13 +14,17 @@ exports.CREDENTIAL_PREFIX = "vc:";
 exports.REVOCATION_SECRET_PREFIX = "revsec:";
 /** How often background sync restamps held credentials (issue #47 asks for 60s or better). */
 exports.SYNC_INTERVAL_MS = 30000;
+/** Match the verifier's default freshness window before a caller-chosen time reaches the prover. */
+const MAX_PRESENTATION_TIME_SKEW_SECONDS = 300;
 /** Device keys and held ZK credentials, with consent and fresh public tree state around presentation. */
 class Wallet {
     constructor(options) {
-        if (options.identitySeed.length !== 32)
+        if (typeof options.identitySeed !== "function" && options.identitySeed.length !== 32) {
             throw new Error("identity seed must be exactly 32 bytes");
+        }
         this.store = options.store ?? new store_1.MemoryStore();
-        this.identitySeed = options.identitySeed.slice();
+        this.identitySeed =
+            typeof options.identitySeed === "function" ? options.identitySeed : options.identitySeed.slice();
         this.deviceSigner = options.deviceSigner;
         this.consent = options.consent;
         this.loadChainState = options.loadChainState;
@@ -64,7 +68,7 @@ class Wallet {
             const credential = (0, credential_1.parseZkCredential)(options.credential);
             if (!(0, credential_1.verifyZkCredential)(credential))
                 throw new Error("credential issuer signature is invalid");
-            if (new identity_1.Identity(this.identitySeed).commitment !== credential.body.holderKeyCommitment) {
+            if (new identity_1.Identity(await this.resolveIdentitySeed()).commitment !== credential.body.holderKeyCommitment) {
                 throw new Error("identity seed does not open the credential holder commitment");
             }
             if ((0, credential_1.deriveRevocationCommitment)(options.revocationSecret) !== credential.body.revocationCommitment) {
@@ -103,7 +107,7 @@ class Wallet {
         catch (error) {
             if (error instanceof errors_1.WalletError)
                 throw error;
-            throw new errors_1.WalletError("CREDENTIAL_INVALID", error instanceof Error ? error.message : "credential verification failed");
+            throw new errors_1.WalletError("CREDENTIAL_INVALID", error instanceof Error ? error.message : "credential verification failed", error);
         }
     }
     async listCredentials() {
@@ -149,6 +153,11 @@ class Wallet {
         if (status === "issuer-not-approved") {
             throw new errors_1.WalletError("ISSUER_NOT_APPROVED", `credential ${id}'s issuer is no longer approved`);
         }
+        const nowSeconds = Math.floor(this.now() / 1000);
+        if (!Number.isSafeInteger(request.currentTime) ||
+            Math.abs(request.currentTime - nowSeconds) > MAX_PRESENTATION_TIME_SKEW_SECONDS) {
+            throw new errors_1.WalletError("PRESENTATION_FAILED", "presentation request time is not current");
+        }
         const allowed = await this.consent({
             kind,
             credentialId: id,
@@ -161,7 +170,7 @@ class Wallet {
         let inputs;
         try {
             inputs = await (0, credential_1.buildZkPresentationInputs)(record.credential, {
-                identitySeed: this.identitySeed,
+                identitySeed: await this.resolveIdentitySeed(),
                 revocationSecret: (0, utils_1.hexToBytes)(revocationSecret.slice(2)),
                 deviceSigner: this.deviceSigner
             }, {
@@ -176,7 +185,7 @@ class Wallet {
         catch (error) {
             if (error instanceof errors_1.WalletError)
                 throw error;
-            throw new errors_1.WalletError("PRESENTATION_FAILED", error instanceof Error ? error.message : "failed to build presentation inputs");
+            throw new errors_1.WalletError("PRESENTATION_FAILED", error instanceof Error ? error.message : "failed to build presentation inputs", error);
         }
         return this.proofGenerator.generateProof(inputs);
     }
@@ -247,6 +256,14 @@ class Wallet {
         }
         return chainState;
     }
+    async resolveIdentitySeed() {
+        if (typeof this.identitySeed !== "function")
+            return this.identitySeed;
+        const seed = await this.identitySeed();
+        if (seed.length !== 32)
+            throw new Error("identity seed must be exactly 32 bytes");
+        return seed;
+    }
     async listCredentialIds() {
         return (await this.store.list())
             .filter((key) => key.startsWith(exports.CREDENTIAL_PREFIX))

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coordination-network/wallet",
-  "version": "0.0.2",
+  "version": "0.1.0",
   "description": "Wallet SDK for the coordination network: device key management, credential storage, consent-gated presentation and revocation sync.",
   "license": "MIT",
   "repository": {
@@ -32,7 +32,7 @@
     "test:e2e": "tsx --test tests/wallet.e2e.ts"
   },
   "devDependencies": {
-    "@coordination-network/zk-artifacts": "^0.0.2",
+    "@coordination-network/zk-artifacts": "^0.1.0",
     "@noble/curves": "^1.9.7",
     "@types/jest": "^30.0.0",
     "@types/node": "^26.1.0",
@@ -42,11 +42,11 @@
     "typescript": "^6.0.3"
   },
   "dependencies": {
-    "@coordination-network/credential": "^0.0.2",
-    "@coordination-network/identity": "^0.0.2",
-    "@coordination-network/issuer-set": "^0.0.2",
-    "@coordination-network/revocation-registry": "^0.0.2",
+    "@coordination-network/credential": "^0.1.0",
+    "@coordination-network/identity": "^0.1.0",
+    "@coordination-network/issuer-set": "^0.1.0",
+    "@coordination-network/revocation-registry": "^0.1.0",
     "@noble/hashes": "^1.8.0",
-    "@semaphore-protocol/identity": "4.14.3"
+    "@semaphore-protocol/identity": "4.14.4"
   }
 }

package/src/errors.ts

@@ -13,10 +13,12 @@ export type WalletErrorCode =
 
 export class WalletError extends Error {
     readonly code: WalletErrorCode
+    readonly cause?: unknown
 
-    constructor(code: WalletErrorCode, message: string) {
+    constructor(code: WalletErrorCode, message: string, cause?: unknown) {
         super(message)
         this.name = "WalletError"
         this.code = code
+        this.cause = cause
     }
 }

package/src/wallet.ts

@@ -44,10 +44,10 @@ export type ConsentPrompt = (request: ConsentRequest) => Promise<boolean>
 
 export interface WalletChainState {
     approvedIssuers: ApprovedIssuerSet
-    /** Authoritative root fetched independently of the reconstructed issuer tree. */
+    /** Authoritative root, read from chain by the caller, never from the server that served the leaves. */
     approvedIssuerRoot: bigint
     revocations: RevocationRegistry
-    /** Authoritative root fetched independently of the reconstructed revocation tree. */
+    /** Authoritative root, read from chain by the caller, never from the server that served the snapshot. */
     revocationRoot: bigint
 }
 
@@ -75,8 +75,11 @@ interface CredentialRecord {
 }
 
 export interface WalletOptions {
-    /** Raw 32-byte Semaphore identity seed derived from the hardware P-256 ECDH output. */
-    identitySeed: Uint8Array
+    /**
+     * Raw 32-byte Semaphore identity seed derived from the hardware P-256 ECDH output. A thunk is
+     * called once per `addCredential` and `present`, so a device key can prompt only when needed.
+     */
+    identitySeed: Uint8Array | (() => Promise<Uint8Array>)
     deviceSigner: DeviceSigner
     consent: ConsentPrompt
     loadChainState: ChainStateLoader
@@ -89,6 +92,9 @@ export interface WalletOptions {
     onSyncError?: (error: unknown) => void
 }
 
+/** Match the verifier's default freshness window before a caller-chosen time reaches the prover. */
+const MAX_PRESENTATION_TIME_SKEW_SECONDS = 300
+
 export interface AddCredentialOptions {
     id: string
     /** Whatever the issuer sent: `addCredential` parses and verifies it, and stores that. */
@@ -100,7 +106,7 @@ export interface AddCredentialOptions {
 /** Device keys and held ZK credentials, with consent and fresh public tree state around presentation. */
 export class Wallet {
     private readonly store: Store
-    private readonly identitySeed: Uint8Array
+    private readonly identitySeed: Uint8Array | (() => Promise<Uint8Array>)
     private readonly deviceSigner: DeviceSigner
     private readonly consent: ConsentPrompt
     private readonly loadChainState: ChainStateLoader
@@ -109,9 +115,12 @@ export class Wallet {
     private readonly onSyncError: (error: unknown) => void
 
     constructor(options: WalletOptions) {
-        if (options.identitySeed.length !== 32) throw new Error("identity seed must be exactly 32 bytes")
+        if (typeof options.identitySeed !== "function" && options.identitySeed.length !== 32) {
+            throw new Error("identity seed must be exactly 32 bytes")
+        }
         this.store = options.store ?? new MemoryStore()
-        this.identitySeed = options.identitySeed.slice()
+        this.identitySeed =
+            typeof options.identitySeed === "function" ? options.identitySeed : options.identitySeed.slice()
         this.deviceSigner = options.deviceSigner
         this.consent = options.consent
         this.loadChainState = options.loadChainState
@@ -159,7 +168,7 @@ export class Wallet {
         try {
             const credential = parseZkCredential(options.credential)
             if (!verifyZkCredential(credential)) throw new Error("credential issuer signature is invalid")
-            if (new Identity(this.identitySeed).commitment !== credential.body.holderKeyCommitment) {
+            if (new Identity(await this.resolveIdentitySeed()).commitment !== credential.body.holderKeyCommitment) {
                 throw new Error("identity seed does not open the credential holder commitment")
             }
             if (deriveRevocationCommitment(options.revocationSecret) !== credential.body.revocationCommitment) {
@@ -206,7 +215,8 @@ export class Wallet {
             if (error instanceof WalletError) throw error
             throw new WalletError(
                 "CREDENTIAL_INVALID",
-                error instanceof Error ? error.message : "credential verification failed"
+                error instanceof Error ? error.message : "credential verification failed",
+                error
             )
         }
     }
@@ -267,6 +277,14 @@ export class Wallet {
             throw new WalletError("ISSUER_NOT_APPROVED", `credential ${id}'s issuer is no longer approved`)
         }
 
+        const nowSeconds = Math.floor(this.now() / 1000)
+        if (
+            !Number.isSafeInteger(request.currentTime) ||
+            Math.abs(request.currentTime - nowSeconds) > MAX_PRESENTATION_TIME_SKEW_SECONDS
+        ) {
+            throw new WalletError("PRESENTATION_FAILED", "presentation request time is not current")
+        }
+
         const allowed = await this.consent({
             kind,
             credentialId: id,
@@ -281,7 +299,7 @@ export class Wallet {
             inputs = await buildZkPresentationInputs(
                 record.credential,
                 {
-                    identitySeed: this.identitySeed,
+                    identitySeed: await this.resolveIdentitySeed(),
                     revocationSecret: hexToBytes(revocationSecret.slice(2)),
                     deviceSigner: this.deviceSigner
                 },
@@ -299,7 +317,8 @@ export class Wallet {
             if (error instanceof WalletError) throw error
             throw new WalletError(
                 "PRESENTATION_FAILED",
-                error instanceof Error ? error.message : "failed to build presentation inputs"
+                error instanceof Error ? error.message : "failed to build presentation inputs",
+                error
             )
         }
         return this.proofGenerator.generateProof(inputs)
@@ -376,6 +395,13 @@ export class Wallet {
         return chainState
     }
 
+    private async resolveIdentitySeed(): Promise<Uint8Array> {
+        if (typeof this.identitySeed !== "function") return this.identitySeed
+        const seed = await this.identitySeed()
+        if (seed.length !== 32) throw new Error("identity seed must be exactly 32 bytes")
+        return seed
+    }
+
     private async listCredentialIds(): Promise<string[]> {
         return (await this.store.list())
             .filter((key) => key.startsWith(CREDENTIAL_PREFIX))