@coordination-network/wallet 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ethereum Foundation
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,113 @@
+# `@coordination-network/wallet`
+
+The holder-side SDK for device keys, ZK credentials, consent-gated presentations,
+and local issuer/revocation state.
+
+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.
+
+## Use
+
+```ts
+import { ZkCredentialProofSystem } from "@coordination-network/credential"
+import { Wallet } from "@coordination-network/wallet"
+
+const proofGenerator = await ZkCredentialProofSystem.create(circuit)
+
+const wallet = new Wallet({
+    identitySeed, // raw 32-byte Semaphore identity seed
+    deviceSigner, // hardware-backed P-256 signer on device
+    consent: async (request) => showConsentSheet(request),
+    loadChainState: async () => {
+        // Rebuild both public trees and pin their roots to authoritative chain state.
+        return {
+            approvedIssuers,
+            approvedIssuerRoot,
+            revocations,
+            revocationRoot
+        }
+    },
+    proofGenerator,
+    store // use a keystore-backed Store on device; MemoryStore is the default
+})
+
+await wallet.addCredential({
+    id: credentialId,
+    credential, // the issuer's response, unparsed; addCredential parses and verifies it
+    revocationSecret
+})
+
+const stopSync = wallet.startRevocationSync()
+
+const proof = await wallet.present(
+    credentialId,
+    {
+        challenge,
+        audience: verifierUrn,
+        currentTime,
+        programme: "demo-programme",
+        country: "ZZZ"
+    },
+    // The state this credential is judged and proved against, read from its own issuer.
+    loadIssuerChainState
+)
+
+stopSync()
+await proofGenerator.destroy()
+```
+
+`loadChainState` returns each reconstructed tree alongside the authoritative
+root fetched from chain. The wallet rejects a mismatch 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.
+`syncRevocations`/`startRevocationSync` refresh every held credential against
+the single `loadChainState` configured on the wallet, for background use.
+
+## Rules enforced
+
+- 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 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.
+- Consent is requested only after all local eligibility checks pass. Holder and
+  device signatures, and proof generation, happen only after consent succeeds.
+- A `Store` receives the credential under `vc:<id>`, its revocation secret
+  under `revsec:<id>`, and account keys under `key:<networkId>`. Secrets must
+  go to secure storage; a caller can route by the exported `KEY_PREFIX`,
+  `CREDENTIAL_PREFIX`, and `REVOCATION_SECRET_PREFIX`.
+- `createFromSeed` accepts high-entropy bytes, not a human-memorable password.
+
+Expected failures throw `WalletError` with a stable `code`, such as `REVOKED`,
+`EXPIRED`, or `CONSENT_DENIED`. A failure to fetch public state uses
+`CHAIN_STATE_UNAVAILABLE`, allowing callers to retry without treating the
+credential as invalid. Failures while constructing presentation inputs use
+`PRESENTATION_FAILED`.
+
+## Tests
+
+The suite proves against the circuit published by
+`@coordination-network/zk-artifacts`, so it needs no local Noir toolchain:
+
+```sh
+yarn workspace @coordination-network/wallet test --runInBand --watchman=false
+```
+
+The end-to-end test uses the real Noir circuit and Barretenberg backend to
+issue, store, present, and verify a credential, then refreshes the revocation
+tree and confirms the wallet blocks another presentation.

package/dist/errors.d.ts

@@ -0,0 +1,5 @@
+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);
+}

package/dist/errors.js

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

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+/** `@coordination-network/wallet` — device keys, held credentials, consent, revocation. */
+export * from "./errors";
+export * from "./store";
+export * from "./wallet";

package/dist/index.js

@@ -0,0 +1,20 @@
+"use strict";
+/** `@coordination-network/wallet` — device keys, held credentials, consent, revocation. */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./errors"), exports);
+__exportStar(require("./store"), exports);
+__exportStar(require("./wallet"), exports);

package/dist/store.d.ts

@@ -0,0 +1,16 @@
+/** Device secrets and credentials. String values, so SecureStore fits it as-is. */
+export interface Store {
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string): Promise<void>;
+    delete(key: string): Promise<void>;
+    /** SecureStore cannot enumerate itself, so that adapter keeps its own index. */
+    list(): Promise<string[]>;
+}
+/** Nothing survives a restart, so device builds pass their own. */
+export declare class MemoryStore implements Store {
+    private readonly entries;
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string): Promise<void>;
+    delete(key: string): Promise<void>;
+    list(): Promise<string[]>;
+}

package/dist/store.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MemoryStore = void 0;
+/** Nothing survives a restart, so device builds pass their own. */
+class MemoryStore {
+    constructor() {
+        this.entries = new Map();
+    }
+    async get(key) {
+        return this.entries.get(key) ?? null;
+    }
+    async set(key, value) {
+        this.entries.set(key, value);
+    }
+    async delete(key) {
+        this.entries.delete(key);
+    }
+    async list() {
+        return [...this.entries.keys()];
+    }
+}
+exports.MemoryStore = MemoryStore;

package/dist/wallet.d.ts

@@ -0,0 +1,106 @@
+import { type DerivedKeys, type Hex } from "@coordination-network/identity";
+import { type DeviceSigner, type SerializedZkCredential, type ZkPresentationInputs, type ZkPresentationProof, type ZkPresentationRequest } from "@coordination-network/credential";
+import { ApprovedIssuerSet } from "@coordination-network/issuer-set";
+import { RevocationRegistry } from "@coordination-network/revocation-registry";
+import { type Store } from "./store";
+export declare const KEY_PREFIX = "key:";
+export declare const CREDENTIAL_PREFIX = "vc:";
+/** Stored apart from its credential, under its own prefix, so a `Store` can route it differently. */
+export declare const REVOCATION_SECRET_PREFIX = "revsec:";
+/** How often background sync restamps held credentials (issue #47 asks for 60s or better). */
+export declare const SYNC_INTERVAL_MS = 30000;
+export type CredentialStatus = "valid" | "revoked" | "not-yet-valid" | "expired" | "issuer-not-approved";
+export interface ConsentRequest {
+    kind: "present" | "prove-ownership";
+    credentialId: string;
+    audience: string;
+    programme: string;
+    country: string;
+}
+/** True allows the proof to be built; anything else stops it before any presentation signature. */
+export type ConsentPrompt = (request: ConsentRequest) => Promise<boolean>;
+export interface WalletChainState {
+    approvedIssuers: ApprovedIssuerSet;
+    /** Authoritative root fetched independently of the reconstructed issuer tree. */
+    approvedIssuerRoot: bigint;
+    revocations: RevocationRegistry;
+    /** Authoritative root fetched independently of the reconstructed revocation tree. */
+    revocationRoot: bigint;
+}
+/** Fetches and validates the latest public issuer and revocation trees. */
+export type ChainStateLoader = () => Promise<WalletChainState>;
+/** ZkCredentialProofSystem satisfies this without making the wallet own its lifecycle. */
+export interface ProofGenerator {
+    generateProof(inputs: ZkPresentationInputs): Promise<ZkPresentationProof>;
+}
+export interface CredentialInfo {
+    id: string;
+    credential: SerializedZkCredential;
+    status: CredentialStatus;
+    /** When the public issuer and revocation trees were last refreshed, in milliseconds since epoch. */
+    checkedAt: number;
+}
+export interface WalletOptions {
+    /** Raw 32-byte Semaphore identity seed derived from the hardware P-256 ECDH output. */
+    identitySeed: Uint8Array;
+    deviceSigner: DeviceSigner;
+    consent: ConsentPrompt;
+    loadChainState: ChainStateLoader;
+    proofGenerator: ProofGenerator;
+    /** Defaults to memory; on device, use a keystore-backed implementation. */
+    store?: Store;
+    /** Injectable clock for deterministic tests. Returns milliseconds since epoch. */
+    now?: () => number;
+    /** Receives background-sync failures instead of creating unhandled promise rejections. */
+    onSyncError?: (error: unknown) => void;
+}
+export interface AddCredentialOptions {
+    id: string;
+    /** Whatever the issuer sent: `addCredential` parses and verifies it, and stores that. */
+    credential: unknown;
+    /** Raw 32-byte secret whose Semaphore commitment is signed into this credential. */
+    revocationSecret: Uint8Array;
+}
+/** Device keys and held ZK credentials, with consent and fresh public tree state around presentation. */
+export declare class Wallet {
+    private readonly store;
+    private readonly identitySeed;
+    private readonly deviceSigner;
+    private readonly consent;
+    private readonly loadChainState;
+    private readonly proofGenerator;
+    private readonly now;
+    private readonly onSyncError;
+    constructor(options: WalletOptions);
+    /** Derives a device secret from high-entropy seed material. Do not pass a human-memorable password. */
+    createFromSeed(seed: Uint8Array): Promise<Hex>;
+    /** The networkId falls out of the secret, so re-importing overwrites rather than duplicates. */
+    importKey(secret: Uint8Array | Hex): Promise<Hex>;
+    listKeys(): Promise<Hex[]>;
+    getKey(networkId: Hex): Promise<DerivedKeys | null>;
+    deleteKey(networkId: Hex): Promise<void>;
+    /** Verifies the signed body, all three holder bindings, issuer membership and revocation before storing. */
+    addCredential(options: AddCredentialOptions): Promise<string>;
+    listCredentials(): Promise<CredentialInfo[]>;
+    getCredential(id: string): Promise<CredentialInfo | null>;
+    deleteCredential(id: string): Promise<void>;
+    present(id: string, request: ZkPresentationRequest, load: ChainStateLoader): Promise<ZkPresentationProof>;
+    proveOwnership(id: string, request: ZkPresentationRequest, load: ChainStateLoader): Promise<ZkPresentationProof>;
+    private buildPresentation;
+    /** Refreshes both public trees once, then updates every held credential without a per-credential RPC lookup. */
+    syncRevocations(): Promise<void>;
+    /**
+     * Refreshes one credential against the state `load` reads. The caller supplies that state
+     * rather than the wallet fetching it, so a request checking several credentials reads once and
+     * every one of them is judged against the same network state.
+     */
+    syncCredential(id: string, load: ChainStateLoader): Promise<void>;
+    /** Starts background status refresh and returns its stop function. */
+    startRevocationSync(intervalMs?: number): () => void;
+    private stamp;
+    private statusOf;
+    private loadAndValidateChainState;
+    private listCredentialIds;
+    private readRecord;
+    private writeRecord;
+}

package/dist/wallet.js

@@ -0,0 +1,263 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Wallet = exports.SYNC_INTERVAL_MS = exports.REVOCATION_SECRET_PREFIX = exports.CREDENTIAL_PREFIX = exports.KEY_PREFIX = void 0;
+const identity_1 = require("@semaphore-protocol/identity");
+const sha2_1 = require("@noble/hashes/sha2");
+const utils_1 = require("@noble/hashes/utils");
+const identity_2 = require("@coordination-network/identity");
+const credential_1 = require("@coordination-network/credential");
+const errors_1 = require("./errors");
+const store_1 = require("./store");
+exports.KEY_PREFIX = "key:";
+exports.CREDENTIAL_PREFIX = "vc:";
+/** Stored apart from its credential, under its own prefix, so a `Store` can route it differently. */
+exports.REVOCATION_SECRET_PREFIX = "revsec:";
+/** How often background sync restamps held credentials (issue #47 asks for 60s or better). */
+exports.SYNC_INTERVAL_MS = 30000;
+/** Device keys and held ZK credentials, with consent and fresh public tree state around presentation. */
+class Wallet {
+    constructor(options) {
+        if (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.deviceSigner = options.deviceSigner;
+        this.consent = options.consent;
+        this.loadChainState = options.loadChainState;
+        this.proofGenerator = options.proofGenerator;
+        this.now = options.now ?? Date.now;
+        this.onSyncError = options.onSyncError ?? (() => { });
+    }
+    /** Derives a device secret from high-entropy seed material. Do not pass a human-memorable password. */
+    async createFromSeed(seed) {
+        if (seed.length === 0)
+            throw new Error("seed must not be empty");
+        return this.importKey((0, sha2_1.sha256)(seed));
+    }
+    /** The networkId falls out of the secret, so re-importing overwrites rather than duplicates. */
+    async importKey(secret) {
+        const bytes = (0, identity_2.normalizeDeviceSecret)(secret);
+        const { networkId } = (0, identity_2.deriveKeys)(bytes);
+        await this.store.set(`${exports.KEY_PREFIX}${networkId}`, `0x${(0, utils_1.bytesToHex)(bytes)}`);
+        return networkId;
+    }
+    async listKeys() {
+        return (await this.store.list())
+            .filter((key) => key.startsWith(exports.KEY_PREFIX))
+            .map((key) => key.slice(exports.KEY_PREFIX.length));
+    }
+    async getKey(networkId) {
+        const secret = await this.store.get(`${exports.KEY_PREFIX}${networkId}`);
+        return secret === null ? null : (0, identity_2.deriveKeys)(secret);
+    }
+    async deleteKey(networkId) {
+        await this.store.delete(`${exports.KEY_PREFIX}${networkId}`);
+    }
+    /** Verifies the signed body, all three holder bindings, issuer membership and revocation before storing. */
+    async addCredential(options) {
+        if (options.id.trim().length === 0)
+            throw new errors_1.WalletError("CREDENTIAL_INVALID", "credential id is empty");
+        if (options.revocationSecret.length !== 32) {
+            throw new errors_1.WalletError("CREDENTIAL_INVALID", "revocation secret must be exactly 32 bytes");
+        }
+        try {
+            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) {
+                throw new Error("identity seed does not open the credential holder commitment");
+            }
+            if ((0, credential_1.deriveRevocationCommitment)(options.revocationSecret) !== credential.body.revocationCommitment) {
+                throw new Error("revocation secret does not open the credential revocation commitment");
+            }
+            if ((0, credential_1.deriveDeviceKeyCommitment)(await this.deviceSigner.getPublicKeyJwk()) !==
+                credential.body.deviceKeyCommitment) {
+                throw new Error("device signer does not open the credential device commitment");
+            }
+            const chainState = await this.loadAndValidateChainState();
+            if (!chainState.approvedIssuers.isApproved(credential.issuerPublicKey)) {
+                throw new Error("credential issuer is not in the approved set");
+            }
+            if (chainState.revocations.isRevoked(credential.body.revocationCommitment)) {
+                throw new errors_1.WalletError("REVOKED", `credential ${options.id} has been revoked`);
+            }
+            const nowSeconds = Math.floor(this.now() / 1000);
+            if (nowSeconds < credential.body.notBefore) {
+                throw new errors_1.WalletError("NOT_YET_VALID", `credential ${options.id} is not yet valid`);
+            }
+            if (nowSeconds > credential.body.expiresAt) {
+                throw new errors_1.WalletError("EXPIRED", `credential ${options.id} has expired`);
+            }
+            if ((await this.readRecord(options.id)) !== null) {
+                throw new errors_1.WalletError("ALREADY_STORED", `credential ${options.id} is already stored`);
+            }
+            await this.store.set(`${exports.REVOCATION_SECRET_PREFIX}${options.id}`, `0x${(0, utils_1.bytesToHex)(options.revocationSecret)}`);
+            await this.writeRecord(options.id, {
+                credential: (0, credential_1.serializeZkCredential)(credential),
+                revoked: false,
+                issuerApproved: true,
+                checkedAt: this.now()
+            });
+            return options.id;
+        }
+        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");
+        }
+    }
+    async listCredentials() {
+        const infos = await Promise.all((await this.listCredentialIds()).map((id) => this.getCredential(id)));
+        return infos.filter((info) => info !== null);
+    }
+    async getCredential(id) {
+        const record = await this.readRecord(id);
+        if (record === null)
+            return null;
+        return { id, credential: record.credential, status: this.statusOf(record), checkedAt: record.checkedAt };
+    }
+    async deleteCredential(id) {
+        await this.store.delete(`${exports.CREDENTIAL_PREFIX}${id}`);
+        await this.store.delete(`${exports.REVOCATION_SECRET_PREFIX}${id}`);
+    }
+    async present(id, request, load) {
+        return this.buildPresentation(id, "present", request, load);
+    }
+    async proveOwnership(id, request, load) {
+        return this.buildPresentation(id, "prove-ownership", request, load);
+    }
+    async buildPresentation(id, kind, request, load) {
+        const record = await this.readRecord(id);
+        if (record === null)
+            throw new errors_1.WalletError("NOT_FOUND", `no credential stored under ${id}`);
+        const revocationSecret = await this.store.get(`${exports.REVOCATION_SECRET_PREFIX}${id}`);
+        if (revocationSecret === null) {
+            throw new errors_1.WalletError("NOT_FOUND", `no revocation secret stored for credential ${id}`);
+        }
+        // One read decides both what the proof names as issuer and which tree it is checked
+        // against. Reading them apart was only ever correct by call order.
+        const chainState = await this.loadAndValidateChainState(load);
+        this.stamp(record, chainState, this.now());
+        await this.writeRecord(id, record);
+        const status = this.statusOf(record);
+        if (status === "revoked")
+            throw new errors_1.WalletError("REVOKED", `credential ${id} has been revoked`);
+        if (status === "not-yet-valid")
+            throw new errors_1.WalletError("NOT_YET_VALID", `credential ${id} is not yet valid`);
+        if (status === "expired")
+            throw new errors_1.WalletError("EXPIRED", `credential ${id} has expired`);
+        if (status === "issuer-not-approved") {
+            throw new errors_1.WalletError("ISSUER_NOT_APPROVED", `credential ${id}'s issuer is no longer approved`);
+        }
+        const allowed = await this.consent({
+            kind,
+            credentialId: id,
+            audience: request.audience,
+            programme: request.programme,
+            country: request.country
+        });
+        if (!allowed)
+            throw new errors_1.WalletError("CONSENT_DENIED", "the user declined this presentation");
+        let inputs;
+        try {
+            inputs = await (0, credential_1.buildZkPresentationInputs)(record.credential, {
+                identitySeed: this.identitySeed,
+                revocationSecret: (0, utils_1.hexToBytes)(revocationSecret.slice(2)),
+                deviceSigner: this.deviceSigner
+            }, {
+                // The whole approved set, so the proof's issuer root is the set's root and
+                // names no issuer. One network-wide revocation registry is what allows this:
+                // the verifier checks the revocation root without having to pick a registry,
+                // and picking one was what gave the issuer away.
+                approvedIssuers: chainState.approvedIssuers,
+                revocations: chainState.revocations
+            }, request);
+        }
+        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");
+        }
+        return this.proofGenerator.generateProof(inputs);
+    }
+    /** Refreshes both public trees once, then updates every held credential without a per-credential RPC lookup. */
+    async syncRevocations() {
+        const chainState = await this.loadAndValidateChainState();
+        const checkedAt = this.now();
+        for (const id of await this.listCredentialIds()) {
+            const record = await this.readRecord(id);
+            if (record === null)
+                continue;
+            this.stamp(record, chainState, checkedAt);
+            await this.writeRecord(id, record);
+        }
+    }
+    /**
+     * Refreshes one credential against the state `load` reads. The caller supplies that state
+     * rather than the wallet fetching it, so a request checking several credentials reads once and
+     * every one of them is judged against the same network state.
+     */
+    async syncCredential(id, load) {
+        const record = await this.readRecord(id);
+        if (record === null)
+            throw new errors_1.WalletError("NOT_FOUND", `no credential stored under ${id}`);
+        const chainState = await this.loadAndValidateChainState(load);
+        this.stamp(record, chainState, this.now());
+        await this.writeRecord(id, record);
+    }
+    /** Starts background status refresh and returns its stop function. */
+    startRevocationSync(intervalMs = exports.SYNC_INTERVAL_MS) {
+        const timer = setInterval(() => {
+            void this.syncRevocations().catch(this.onSyncError);
+        }, intervalMs);
+        return () => clearInterval(timer);
+    }
+    stamp(record, chainState, checkedAt) {
+        const credential = (0, credential_1.parseZkCredential)(record.credential);
+        record.revoked = chainState.revocations.isRevoked(credential.body.revocationCommitment);
+        record.issuerApproved = chainState.approvedIssuers.isApproved(credential.issuerPublicKey);
+        record.checkedAt = checkedAt;
+    }
+    statusOf(record) {
+        if (record.revoked)
+            return "revoked";
+        if (!record.issuerApproved)
+            return "issuer-not-approved";
+        const nowSeconds = Math.floor(this.now() / 1000);
+        const { body } = (0, credential_1.parseZkCredential)(record.credential);
+        if (nowSeconds < body.notBefore)
+            return "not-yet-valid";
+        if (nowSeconds > body.expiresAt)
+            return "expired";
+        return "valid";
+    }
+    async loadAndValidateChainState(load = this.loadChainState) {
+        let chainState;
+        try {
+            chainState = await load();
+        }
+        catch (error) {
+            throw new errors_1.WalletError("CHAIN_STATE_UNAVAILABLE", error instanceof Error ? error.message : "failed to load chain state");
+        }
+        if (chainState.approvedIssuers.root !== chainState.approvedIssuerRoot) {
+            throw new errors_1.WalletError("CHAIN_STATE_INVALID", "approved issuer tree does not match its authoritative root");
+        }
+        if (chainState.revocations.root !== chainState.revocationRoot) {
+            throw new errors_1.WalletError("CHAIN_STATE_INVALID", "revocation tree does not match its authoritative root");
+        }
+        return chainState;
+    }
+    async listCredentialIds() {
+        return (await this.store.list())
+            .filter((key) => key.startsWith(exports.CREDENTIAL_PREFIX))
+            .map((key) => key.slice(exports.CREDENTIAL_PREFIX.length));
+    }
+    async readRecord(id) {
+        const raw = await this.store.get(`${exports.CREDENTIAL_PREFIX}${id}`);
+        return raw === null ? null : JSON.parse(raw);
+    }
+    async writeRecord(id, record) {
+        await this.store.set(`${exports.CREDENTIAL_PREFIX}${id}`, JSON.stringify(record));
+    }
+}
+exports.Wallet = Wallet;

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@coordination-network/wallet",
+  "version": "0.0.1",
+  "description": "Wallet SDK for the coordination network: device key management, credential storage, consent-gated presentation and revocation sync.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/zk-kit/coordination-network.git",
+    "directory": "packages/wallet"
+  },
+  "homepage": "https://github.com/zk-kit/coordination-network/tree/main/packages/wallet",
+  "bugs": "https://github.com/zk-kit/coordination-network/issues",
+  "sideEffects": false,
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist/",
+    "src/",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "installConfig": {
+    "hoistingLimits": "workspaces"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "test": "yarn test:unit && yarn test:e2e",
+    "test:unit": "cd ../.. && jest --selectProjects wallet",
+    "test:e2e": "tsx --test tests/wallet.e2e.ts"
+  },
+  "devDependencies": {
+    "@coordination-network/zk-artifacts": "^0.0.1",
+    "@noble/curves": "^1.9.7",
+    "@types/jest": "^30.0.0",
+    "@types/node": "^26.1.0",
+    "jest": "^30.4.2",
+    "ts-jest": "^29.4.11",
+    "tsx": "^4.23.0",
+    "typescript": "^6.0.3"
+  },
+  "dependencies": {
+    "@coordination-network/credential": "^0.0.1",
+    "@coordination-network/identity": "^0.0.1",
+    "@coordination-network/issuer-set": "^0.0.1",
+    "@coordination-network/revocation-registry": "^0.0.1",
+    "@noble/hashes": "^1.8.0",
+    "@semaphore-protocol/identity": "4.14.3"
+  }
+}

package/src/errors.ts

@@ -0,0 +1,22 @@
+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 class WalletError extends Error {
+    readonly code: WalletErrorCode
+
+    constructor(code: WalletErrorCode, message: string) {
+        super(message)
+        this.name = "WalletError"
+        this.code = code
+    }
+}

package/src/index.ts

@@ -0,0 +1,5 @@
+/** `@coordination-network/wallet` — device keys, held credentials, consent, revocation. */
+
+export * from "./errors"
+export * from "./store"
+export * from "./wallet"

package/src/store.ts

@@ -0,0 +1,29 @@
+/** Device secrets and credentials. String values, so SecureStore fits it as-is. */
+export interface Store {
+    get(key: string): Promise<string | null>
+    set(key: string, value: string): Promise<void>
+    delete(key: string): Promise<void>
+    /** SecureStore cannot enumerate itself, so that adapter keeps its own index. */
+    list(): Promise<string[]>
+}
+
+/** Nothing survives a restart, so device builds pass their own. */
+export class MemoryStore implements Store {
+    private readonly entries = new Map<string, string>()
+
+    async get(key: string): Promise<string | null> {
+        return this.entries.get(key) ?? null
+    }
+
+    async set(key: string, value: string): Promise<void> {
+        this.entries.set(key, value)
+    }
+
+    async delete(key: string): Promise<void> {
+        this.entries.delete(key)
+    }
+
+    async list(): Promise<string[]> {
+        return [...this.entries.keys()]
+    }
+}

package/src/wallet.ts

@@ -0,0 +1,393 @@
+import { Identity } from "@semaphore-protocol/identity"
+import { sha256 } from "@noble/hashes/sha2"
+import { bytesToHex, hexToBytes } from "@noble/hashes/utils"
+import { deriveKeys, normalizeDeviceSecret, type DerivedKeys, type Hex } from "@coordination-network/identity"
+import {
+    buildZkPresentationInputs,
+    deriveDeviceKeyCommitment,
+    deriveRevocationCommitment,
+    parseZkCredential,
+    serializeZkCredential,
+    verifyZkCredential,
+    type DeviceSigner,
+    type SerializedZkCredential,
+    type ZkPresentationInputs,
+    type ZkPresentationProof,
+    type ZkPresentationRequest
+} from "@coordination-network/credential"
+import { ApprovedIssuerSet } from "@coordination-network/issuer-set"
+import { RevocationRegistry } from "@coordination-network/revocation-registry"
+import { WalletError } from "./errors"
+import { MemoryStore, type Store } from "./store"
+
+export const KEY_PREFIX = "key:"
+export const CREDENTIAL_PREFIX = "vc:"
+
+/** Stored apart from its credential, under its own prefix, so a `Store` can route it differently. */
+export const REVOCATION_SECRET_PREFIX = "revsec:"
+
+/** How often background sync restamps held credentials (issue #47 asks for 60s or better). */
+export const SYNC_INTERVAL_MS = 30_000
+
+export type CredentialStatus = "valid" | "revoked" | "not-yet-valid" | "expired" | "issuer-not-approved"
+
+export interface ConsentRequest {
+    kind: "present" | "prove-ownership"
+    credentialId: string
+    audience: string
+    programme: string
+    country: string
+}
+
+/** True allows the proof to be built; anything else stops it before any presentation signature. */
+export type ConsentPrompt = (request: ConsentRequest) => Promise<boolean>
+
+export interface WalletChainState {
+    approvedIssuers: ApprovedIssuerSet
+    /** Authoritative root fetched independently of the reconstructed issuer tree. */
+    approvedIssuerRoot: bigint
+    revocations: RevocationRegistry
+    /** Authoritative root fetched independently of the reconstructed revocation tree. */
+    revocationRoot: bigint
+}
+
+/** Fetches and validates the latest public issuer and revocation trees. */
+export type ChainStateLoader = () => Promise<WalletChainState>
+
+/** ZkCredentialProofSystem satisfies this without making the wallet own its lifecycle. */
+export interface ProofGenerator {
+    generateProof(inputs: ZkPresentationInputs): Promise<ZkPresentationProof>
+}
+
+export interface CredentialInfo {
+    id: string
+    credential: SerializedZkCredential
+    status: CredentialStatus
+    /** When the public issuer and revocation trees were last refreshed, in milliseconds since epoch. */
+    checkedAt: number
+}
+
+interface CredentialRecord {
+    credential: SerializedZkCredential
+    revoked: boolean
+    issuerApproved: boolean
+    checkedAt: number
+}
+
+export interface WalletOptions {
+    /** Raw 32-byte Semaphore identity seed derived from the hardware P-256 ECDH output. */
+    identitySeed: Uint8Array
+    deviceSigner: DeviceSigner
+    consent: ConsentPrompt
+    loadChainState: ChainStateLoader
+    proofGenerator: ProofGenerator
+    /** Defaults to memory; on device, use a keystore-backed implementation. */
+    store?: Store
+    /** Injectable clock for deterministic tests. Returns milliseconds since epoch. */
+    now?: () => number
+    /** Receives background-sync failures instead of creating unhandled promise rejections. */
+    onSyncError?: (error: unknown) => void
+}
+
+export interface AddCredentialOptions {
+    id: string
+    /** Whatever the issuer sent: `addCredential` parses and verifies it, and stores that. */
+    credential: unknown
+    /** Raw 32-byte secret whose Semaphore commitment is signed into this credential. */
+    revocationSecret: Uint8Array
+}
+
+/** 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 deviceSigner: DeviceSigner
+    private readonly consent: ConsentPrompt
+    private readonly loadChainState: ChainStateLoader
+    private readonly proofGenerator: ProofGenerator
+    private readonly now: () => number
+    private readonly onSyncError: (error: unknown) => void
+
+    constructor(options: WalletOptions) {
+        if (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.deviceSigner = options.deviceSigner
+        this.consent = options.consent
+        this.loadChainState = options.loadChainState
+        this.proofGenerator = options.proofGenerator
+        this.now = options.now ?? Date.now
+        this.onSyncError = options.onSyncError ?? (() => {})
+    }
+
+    /** Derives a device secret from high-entropy seed material. Do not pass a human-memorable password. */
+    async createFromSeed(seed: Uint8Array): Promise<Hex> {
+        if (seed.length === 0) throw new Error("seed must not be empty")
+        return this.importKey(sha256(seed))
+    }
+
+    /** The networkId falls out of the secret, so re-importing overwrites rather than duplicates. */
+    async importKey(secret: Uint8Array | Hex): Promise<Hex> {
+        const bytes = normalizeDeviceSecret(secret)
+        const { networkId } = deriveKeys(bytes)
+        await this.store.set(`${KEY_PREFIX}${networkId}`, `0x${bytesToHex(bytes)}`)
+        return networkId
+    }
+
+    async listKeys(): Promise<Hex[]> {
+        return (await this.store.list())
+            .filter((key) => key.startsWith(KEY_PREFIX))
+            .map((key) => key.slice(KEY_PREFIX.length) as Hex)
+    }
+
+    async getKey(networkId: Hex): Promise<DerivedKeys | null> {
+        const secret = await this.store.get(`${KEY_PREFIX}${networkId}`)
+        return secret === null ? null : deriveKeys(secret as Hex)
+    }
+
+    async deleteKey(networkId: Hex): Promise<void> {
+        await this.store.delete(`${KEY_PREFIX}${networkId}`)
+    }
+
+    /** Verifies the signed body, all three holder bindings, issuer membership and revocation before storing. */
+    async addCredential(options: AddCredentialOptions): Promise<string> {
+        if (options.id.trim().length === 0) throw new WalletError("CREDENTIAL_INVALID", "credential id is empty")
+        if (options.revocationSecret.length !== 32) {
+            throw new WalletError("CREDENTIAL_INVALID", "revocation secret must be exactly 32 bytes")
+        }
+
+        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) {
+                throw new Error("identity seed does not open the credential holder commitment")
+            }
+            if (deriveRevocationCommitment(options.revocationSecret) !== credential.body.revocationCommitment) {
+                throw new Error("revocation secret does not open the credential revocation commitment")
+            }
+            if (
+                deriveDeviceKeyCommitment(await this.deviceSigner.getPublicKeyJwk()) !==
+                credential.body.deviceKeyCommitment
+            ) {
+                throw new Error("device signer does not open the credential device commitment")
+            }
+
+            const chainState = await this.loadAndValidateChainState()
+            if (!chainState.approvedIssuers.isApproved(credential.issuerPublicKey)) {
+                throw new Error("credential issuer is not in the approved set")
+            }
+            if (chainState.revocations.isRevoked(credential.body.revocationCommitment)) {
+                throw new WalletError("REVOKED", `credential ${options.id} has been revoked`)
+            }
+
+            const nowSeconds = Math.floor(this.now() / 1000)
+            if (nowSeconds < credential.body.notBefore) {
+                throw new WalletError("NOT_YET_VALID", `credential ${options.id} is not yet valid`)
+            }
+            if (nowSeconds > credential.body.expiresAt) {
+                throw new WalletError("EXPIRED", `credential ${options.id} has expired`)
+            }
+            if ((await this.readRecord(options.id)) !== null) {
+                throw new WalletError("ALREADY_STORED", `credential ${options.id} is already stored`)
+            }
+
+            await this.store.set(
+                `${REVOCATION_SECRET_PREFIX}${options.id}`,
+                `0x${bytesToHex(options.revocationSecret)}`
+            )
+            await this.writeRecord(options.id, {
+                credential: serializeZkCredential(credential),
+                revoked: false,
+                issuerApproved: true,
+                checkedAt: this.now()
+            })
+            return options.id
+        } catch (error) {
+            if (error instanceof WalletError) throw error
+            throw new WalletError(
+                "CREDENTIAL_INVALID",
+                error instanceof Error ? error.message : "credential verification failed"
+            )
+        }
+    }
+
+    async listCredentials(): Promise<CredentialInfo[]> {
+        const infos = await Promise.all((await this.listCredentialIds()).map((id) => this.getCredential(id)))
+        return infos.filter((info): info is CredentialInfo => info !== null)
+    }
+
+    async getCredential(id: string): Promise<CredentialInfo | null> {
+        const record = await this.readRecord(id)
+        if (record === null) return null
+        return { id, credential: record.credential, status: this.statusOf(record), checkedAt: record.checkedAt }
+    }
+
+    async deleteCredential(id: string): Promise<void> {
+        await this.store.delete(`${CREDENTIAL_PREFIX}${id}`)
+        await this.store.delete(`${REVOCATION_SECRET_PREFIX}${id}`)
+    }
+
+    async present(id: string, request: ZkPresentationRequest, load: ChainStateLoader): Promise<ZkPresentationProof> {
+        return this.buildPresentation(id, "present", request, load)
+    }
+
+    async proveOwnership(
+        id: string,
+        request: ZkPresentationRequest,
+        load: ChainStateLoader
+    ): Promise<ZkPresentationProof> {
+        return this.buildPresentation(id, "prove-ownership", request, load)
+    }
+
+    private async buildPresentation(
+        id: string,
+        kind: ConsentRequest["kind"],
+        request: ZkPresentationRequest,
+        load: ChainStateLoader
+    ): Promise<ZkPresentationProof> {
+        const record = await this.readRecord(id)
+        if (record === null) throw new WalletError("NOT_FOUND", `no credential stored under ${id}`)
+
+        const revocationSecret = await this.store.get(`${REVOCATION_SECRET_PREFIX}${id}`)
+        if (revocationSecret === null) {
+            throw new WalletError("NOT_FOUND", `no revocation secret stored for credential ${id}`)
+        }
+
+        // One read decides both what the proof names as issuer and which tree it is checked
+        // against. Reading them apart was only ever correct by call order.
+        const chainState = await this.loadAndValidateChainState(load)
+        this.stamp(record, chainState, this.now())
+        await this.writeRecord(id, record)
+
+        const status = this.statusOf(record)
+        if (status === "revoked") throw new WalletError("REVOKED", `credential ${id} has been revoked`)
+        if (status === "not-yet-valid") throw new WalletError("NOT_YET_VALID", `credential ${id} is not yet valid`)
+        if (status === "expired") throw new WalletError("EXPIRED", `credential ${id} has expired`)
+        if (status === "issuer-not-approved") {
+            throw new WalletError("ISSUER_NOT_APPROVED", `credential ${id}'s issuer is no longer approved`)
+        }
+
+        const allowed = await this.consent({
+            kind,
+            credentialId: id,
+            audience: request.audience,
+            programme: request.programme,
+            country: request.country
+        })
+        if (!allowed) throw new WalletError("CONSENT_DENIED", "the user declined this presentation")
+
+        let inputs: ZkPresentationInputs
+        try {
+            inputs = await buildZkPresentationInputs(
+                record.credential,
+                {
+                    identitySeed: this.identitySeed,
+                    revocationSecret: hexToBytes(revocationSecret.slice(2)),
+                    deviceSigner: this.deviceSigner
+                },
+                {
+                    // The whole approved set, so the proof's issuer root is the set's root and
+                    // names no issuer. One network-wide revocation registry is what allows this:
+                    // the verifier checks the revocation root without having to pick a registry,
+                    // and picking one was what gave the issuer away.
+                    approvedIssuers: chainState.approvedIssuers,
+                    revocations: chainState.revocations
+                },
+                request
+            )
+        } catch (error) {
+            if (error instanceof WalletError) throw error
+            throw new WalletError(
+                "PRESENTATION_FAILED",
+                error instanceof Error ? error.message : "failed to build presentation inputs"
+            )
+        }
+        return this.proofGenerator.generateProof(inputs)
+    }
+
+    /** Refreshes both public trees once, then updates every held credential without a per-credential RPC lookup. */
+    async syncRevocations(): Promise<void> {
+        const chainState = await this.loadAndValidateChainState()
+        const checkedAt = this.now()
+
+        for (const id of await this.listCredentialIds()) {
+            const record = await this.readRecord(id)
+            if (record === null) continue
+            this.stamp(record, chainState, checkedAt)
+            await this.writeRecord(id, record)
+        }
+    }
+
+    /**
+     * Refreshes one credential against the state `load` reads. The caller supplies that state
+     * rather than the wallet fetching it, so a request checking several credentials reads once and
+     * every one of them is judged against the same network state.
+     */
+    async syncCredential(id: string, load: ChainStateLoader): Promise<void> {
+        const record = await this.readRecord(id)
+        if (record === null) throw new WalletError("NOT_FOUND", `no credential stored under ${id}`)
+
+        const chainState = await this.loadAndValidateChainState(load)
+        this.stamp(record, chainState, this.now())
+        await this.writeRecord(id, record)
+    }
+
+    /** Starts background status refresh and returns its stop function. */
+    startRevocationSync(intervalMs: number = SYNC_INTERVAL_MS): () => void {
+        const timer = setInterval(() => {
+            void this.syncRevocations().catch(this.onSyncError)
+        }, intervalMs)
+        return () => clearInterval(timer)
+    }
+
+    private stamp(record: CredentialRecord, chainState: WalletChainState, checkedAt: number): void {
+        const credential = parseZkCredential(record.credential)
+        record.revoked = chainState.revocations.isRevoked(credential.body.revocationCommitment)
+        record.issuerApproved = chainState.approvedIssuers.isApproved(credential.issuerPublicKey)
+        record.checkedAt = checkedAt
+    }
+
+    private statusOf(record: CredentialRecord): CredentialStatus {
+        if (record.revoked) return "revoked"
+        if (!record.issuerApproved) return "issuer-not-approved"
+        const nowSeconds = Math.floor(this.now() / 1000)
+        const { body } = parseZkCredential(record.credential)
+        if (nowSeconds < body.notBefore) return "not-yet-valid"
+        if (nowSeconds > body.expiresAt) return "expired"
+        return "valid"
+    }
+
+    private async loadAndValidateChainState(load: ChainStateLoader = this.loadChainState): Promise<WalletChainState> {
+        let chainState: WalletChainState
+        try {
+            chainState = await load()
+        } catch (error) {
+            throw new WalletError(
+                "CHAIN_STATE_UNAVAILABLE",
+                error instanceof Error ? error.message : "failed to load chain state"
+            )
+        }
+        if (chainState.approvedIssuers.root !== chainState.approvedIssuerRoot) {
+            throw new WalletError("CHAIN_STATE_INVALID", "approved issuer tree does not match its authoritative root")
+        }
+        if (chainState.revocations.root !== chainState.revocationRoot) {
+            throw new WalletError("CHAIN_STATE_INVALID", "revocation tree does not match its authoritative root")
+        }
+        return chainState
+    }
+
+    private async listCredentialIds(): Promise<string[]> {
+        return (await this.store.list())
+            .filter((key) => key.startsWith(CREDENTIAL_PREFIX))
+            .map((key) => key.slice(CREDENTIAL_PREFIX.length))
+    }
+
+    private async readRecord(id: string): Promise<CredentialRecord | null> {
+        const raw = await this.store.get(`${CREDENTIAL_PREFIX}${id}`)
+        return raw === null ? null : (JSON.parse(raw) as CredentialRecord)
+    }
+
+    private async writeRecord(id: string, record: CredentialRecord): Promise<void> {
+        await this.store.set(`${CREDENTIAL_PREFIX}${id}`, JSON.stringify(record))
+    }
+}