@coordination-network/user-app-core 0.0.1

package/dist/index.cjs

@@ -0,0 +1,754 @@
+'use strict';
+
+var identity = require('@coordination-network/identity');
+var credential = require('@coordination-network/credential');
+var userAppLink = require('@coordination-network/user-app-link');
+var issuerSet = require('@coordination-network/issuer-set');
+var revocationRegistry = require('@coordination-network/revocation-registry');
+var wallet = require('@coordination-network/wallet');
+var zod = require('zod');
+var userClient = require('@coordination-network/user-client');
+
+/**
+ * `createRequestHandler` calls this after confirming `request.op` is a known op and validating
+ * `params` against its schema, so the casts below are re-attaching types the caller already
+ * proved, not asserting past them — an exhaustive switch covers every case with no defensive
+ * default branch needed. Every value here ends up behind the sheet's "Technical details" toggle;
+ * the sentence above it is the app's, not this package's.
+ */
+function buildConsentSummary(request) {
+    const caller = request.caller;
+    // The callback is the only signal against a spoofed caller, so it is never shortened.
+    const callback = { label: "Callback", value: request.callback, truncate: false };
+    switch (request.op) {
+        case "registration.sign": {
+            const p = request.params;
+            return {
+                op: "registration.sign",
+                caller,
+                details: [
+                    callback,
+                    // The signature is bound to this contract, so it names what approving commits to.
+                    { label: "Registry contract", value: p.verifyingContract },
+                    { label: "Chain ID", value: String(p.chainId) }
+                ]
+            };
+        }
+        case "credential.issue": {
+            const p = request.params;
+            return {
+                op: "credential.issue",
+                caller,
+                scope: { programme: p.approvalScope.programme, country: p.approvalScope.country },
+                details: [
+                    { label: "Issuer", value: p.issuerNetworkId },
+                    // This app posts the binding signatures there itself, so this row is the one
+                    // that says where they go. The caller picks the URL, and the schema holds all
+                    // four issuance URLs to that one origin, so this row speaks for the rest.
+                    { label: "Issuer server", value: p.credentialsUrl },
+                    { label: "Programme", value: p.approvalScope.programme },
+                    { label: "Country", value: p.approvalScope.country },
+                    callback
+                ]
+            };
+        }
+        case "presentation.create": {
+            const p = request.params;
+            return {
+                op: "presentation.create",
+                caller,
+                scope: { programme: p.programme, country: p.country },
+                details: [
+                    { label: "Verifier", value: p.audience },
+                    // The proof is posted by this app, not handed back to the caller, so this row
+                    // is the one that says where it actually goes. Unlike the callback, this URL
+                    // is not scheme-restricted, and a caller picks it.
+                    { label: "Proof is sent to", value: p.responseUrl },
+                    callback,
+                    { label: "Programme", value: p.programme },
+                    { label: "Country", value: p.country }
+                ]
+            };
+        }
+    }
+}
+
+/**
+ * This package holds exactly one identity, so unlike `Wallet`'s `key:`-prefixed store (built for
+ * several imported keys) the device secret lives under one fixed key.
+ */
+const DEVICE_SECRET_KEY = "user-app-core:device-secret";
+async function readDeviceSecret(store) {
+    return (await store.get(DEVICE_SECRET_KEY));
+}
+async function writeDeviceSecret(store, secret) {
+    await store.set(DEVICE_SECRET_KEY, secret);
+}
+
+/**
+ * `GET /v1/issuers` carries a `root` the server read from chain independently of the `leaves` it
+ * also served, so `Wallet`'s comparison between the tree rebuilt from `leaves` and
+ * `approvedIssuerRoot` catches a server that served a mismatched pair.
+ */
+async function readIssuerSet(http, issuersUrl) {
+    const response = await http.getJson(issuersUrl);
+    if (response.status !== 200) {
+        throw new Error(`GET ${issuersUrl} returned ${response.status}`);
+    }
+    const { leaves, root } = response.body;
+    return {
+        approvedIssuers: issuerSet.ApprovedIssuerSet.fromLeaves(leaves.map((leaf) => BigInt(leaf))),
+        approvedIssuerRoot: BigInt(root)
+    };
+}
+/** The snapshot's own `root` gives the revocation side the same cross-check. */
+async function readRevocations(http, revocationsUrl) {
+    const response = await http.getJson(revocationsUrl);
+    if (response.status !== 200) {
+        throw new Error(`GET ${revocationsUrl} returned ${response.status}`);
+    }
+    const { root, snapshot } = response.body;
+    return { revocations: revocationRegistry.RevocationRegistry.import(snapshot), revocationRoot: BigInt(root) };
+}
+/**
+ * Both lists are named per request by `issuersUrl`/`revocationsUrl`, so this is built fresh per
+ * request and never held onto. A handler with several credentials to check reads the two halves
+ * itself instead, so one read of each serves them all (see `presentation-create.ts`).
+ */
+function buildChainStateLoader(http, issuersUrl, revocationsUrl) {
+    return async () => ({
+        ...(await readIssuerSet(http, issuersUrl)),
+        ...(await readRevocations(http, revocationsUrl))
+    });
+}
+
+/**
+ * `WalletError` and `LinkError` speak different vocabularies for the same underlying failures.
+ * Split along one line: a malformed or structurally-invalid credential is `INVALID_REQUEST`;
+ * a well-formed credential that is simply not usable right now (not yet valid, expired, its
+ * issuer retired) is `NO_CREDENTIAL`, while a revoked one says so outright. A chain-state failure
+ * means whichever server published those lists is unreachable or inconsistent, not a fault in
+ * this app, hence an unreachable code rather than `INTERNAL`.
+ */
+const WALLET_ERROR_TO_LINK_ERROR_CODE = {
+    NOT_FOUND: "NO_CREDENTIAL",
+    ALREADY_STORED: "INVALID_REQUEST",
+    CREDENTIAL_INVALID: "INVALID_REQUEST",
+    CONSENT_DENIED: "CONSENT_DENIED",
+    REVOKED: "CREDENTIAL_REVOKED",
+    CHAIN_STATE_UNAVAILABLE: "VERIFIER_UNREACHABLE",
+    CHAIN_STATE_INVALID: "VERIFIER_UNREACHABLE",
+    NOT_YET_VALID: "NO_CREDENTIAL",
+    EXPIRED: "NO_CREDENTIAL",
+    ISSUER_NOT_APPROVED: "NO_CREDENTIAL",
+    PRESENTATION_FAILED: "PROOF_FAILED"
+};
+/**
+ * Preserves the original message on the thrown `LinkError`. `chainStateCode` names the side whose
+ * lists were being read: during issuance that is the issuer, not a verifier.
+ *
+ * Takes `unknown` rather than `WalletError` because the wallet's sync methods are not total over
+ * `WalletError`: they parse each stored credential and write each record back, so a corrupt record
+ * or a failing device store throws something else entirely. Indexing the table with that error's
+ * absent `code` would have produced a `LinkError` with no code at all.
+ */
+function mapWalletError(error, chainStateCode) {
+    if (!(error instanceof wallet.WalletError)) {
+        return new userAppLink.LinkError("INTERNAL", error instanceof Error ? error.message : String(error));
+    }
+    const isChainState = error.code === "CHAIN_STATE_UNAVAILABLE" || error.code === "CHAIN_STATE_INVALID";
+    const code = isChainState && chainStateCode ? chainStateCode : WALLET_ERROR_TO_LINK_ERROR_CODE[error.code];
+    return new userAppLink.LinkError(code, error.message);
+}
+
+/** Encodes a field element as the 32-byte big-endian value the binding and commitment builders expect. */
+function bigintToBytes32(value) {
+    return identity.hexToBytes(`0x${value.toString(16).padStart(64, "0")}`);
+}
+
+/**
+ * The member-server responses the wallet reads for itself: the two issuance routes it now drives
+ * alone, and the verify route it posts a proof to. `@coordination-network/network-member-app-core`
+ * keeps its own schemas for the routes the member app still calls; the two packages do not depend on
+ * each other, and both are fixed by `apps/issuer-service`.
+ */
+/**
+ * `POST /v1/challenge` writes its nonce with `@noble/hashes`' `bytesToHex`, which never adds the
+ * `0x` prefix every other hex field in this protocol carries - accept it either way and normalize
+ * to the `0x`-prefixed, lowercase form the binding builders require.
+ */
+const challengeNonceSchema = zod.z
+    .string()
+    .regex(/^(0x)?[0-9a-fA-F]{64}$/i, "must be 32-byte hex")
+    .transform((value) => `0x${value.replace(/^0x/i, "")}`.toLowerCase());
+const challengeResponseSchema = zod.z.object({ nonce: challengeNonceSchema, expiresAt: zod.z.number() }).strict();
+const issueCredentialResponseSchema = zod.z.object({ id: zod.z.string().min(1), credential: zod.z.unknown() }).strict();
+/**
+ * Not `.strict()`: `POST /v1/verify` also answers with its own `ok`/`code`, which the wallet
+ * deliberately does not relay — the member app reads the outcome from its own server instead.
+ */
+const verifyResponseSchema = zod.z.object({ verificationId: zod.z.string().min(1) });
+/** Not `.strict()`: an error body is read for `code`/`error`, whichever route sent it. */
+const errorBodySchema = zod.z.object({ error: zod.z.string().optional(), code: zod.z.string().optional() });
+/**
+ * One POST to a member's own server. An answer the route is specified to give is a value; any
+ * other answer carrying an error is handed back as the member's own words, for the caller to say
+ * what they amount to; anything else means the server is not usefully there, under whichever
+ * unreachable code names the side being talked to.
+ */
+async function postToMember(http, url, body, expected) {
+    let response;
+    try {
+        response = await http.postJson(url, body);
+    }
+    catch (error) {
+        throw new userAppLink.LinkError(expected.unreachable, error instanceof Error ? error.message : `POST ${url} failed`);
+    }
+    const parsed = expected.schema.safeParse(response.body);
+    if (response.status === expected.status && parsed.success)
+        return { value: parsed.data };
+    const failure = errorBodySchema.safeParse(response.body);
+    if (failure.success && failure.data.error !== undefined) {
+        return { refusal: { code: failure.data.code, message: failure.data.error } };
+    }
+    throw new userAppLink.LinkError(expected.unreachable, `${url} returned an unusable response`);
+}
+
+/**
+ * `issuerNetworkId` is asserted by the caller and cannot be verified here. An established mapping
+ * still cannot be taken over while the credential under it is valid: `credential.issue` answers
+ * `alreadyHeld` for such a key rather than issuing against it again.
+ */
+const ISSUER_INDEX_PREFIX = "user-app-core:issuer-index:";
+/**
+ * One key per issuer *and* approval scope, so a member running two programmes can issue for both.
+ * The two scope parts are percent-encoded, which escapes the separator, so the issuer id is always
+ * the first of exactly three segments.
+ */
+const keyFor = (issuerNetworkId, scope) => `${ISSUER_INDEX_PREFIX}${issuerNetworkId.toLowerCase()}:${encodeURIComponent(scope.programme)}:${encodeURIComponent(scope.country)}`;
+async function readIssuerEntry(store, issuerNetworkId, scope) {
+    const raw = await store.get(keyFor(issuerNetworkId, scope));
+    return raw === null ? null : JSON.parse(raw);
+}
+/** Every entry the wallet holds, for the joins that start from a credential rather than an issuer. */
+async function listIssuerEntries(store) {
+    const entries = [];
+    for (const key of await store.list()) {
+        if (!key.startsWith(ISSUER_INDEX_PREFIX))
+            continue;
+        const raw = await store.get(key);
+        if (raw === null)
+            continue;
+        entries.push({
+            ...JSON.parse(raw),
+            issuerNetworkId: key.slice(ISSUER_INDEX_PREFIX.length).split(":")[0]
+        });
+    }
+    return entries;
+}
+/** The entry carries its own scope, so it is what the key is built from. */
+async function writeIssuerEntry(store, issuerNetworkId, entry) {
+    await store.set(keyFor(issuerNetworkId, entry), JSON.stringify(entry));
+}
+
+/** `ports.now` is optional (a test harness injects a deterministic clock); real ports omit it. */
+function nowFn(ports) {
+    return (ports.now ?? Date.now)();
+}
+
+/**
+ * The steps `credential.issue` reports, in the order it reports them. Named here rather than
+ * spelled out twice, so the screen that groups the six into the three a person approved cannot
+ * drift from the handler reporting them.
+ */
+const CREDENTIAL_ISSUE_STEPS = {
+    held: "Checking what you hold",
+    lists: "Checking the lists",
+    challenge: "Getting a challenge",
+    binding: "Binding to this phone",
+    signing: "Asking the issuer to sign",
+    storing: "Saving to your wallet"
+};
+
+/**
+ * The Baby Jubjub identity seed, rooted in the hardware ECDH rather than the device secret.
+ * `deriveEddsaKeypair` returns `seed` as a `0x`-prefixed hex string — handing that string to
+ * Semaphore derives a different identity (`DERIVATION.md` §12.4); `Wallet.identitySeed` must be
+ * the 32 raw bytes decoded from it.
+ */
+async function resolveIdentitySeed(deviceKey) {
+    const sharedSecret = await deviceKey.ecdh(identity.eddsaPeerPointBytes());
+    return identity.hexToBytes(identity.deriveEddsaKeypair(sharedSecret).seed);
+}
+/**
+ * `listCredentials` never syncs — there is no single authority to sync a mixed-issuer listing
+ * against — so this sentinel documents that, and would surface loudly if a future bug called it.
+ */
+const neverLoadChainState = async () => {
+    throw new Error("chain state must not be requested outside a per-request authority");
+};
+/**
+ * A fresh `Wallet` per request, scoped to one member's authority. The private `Wallet` gets a
+ * constant-`true` consent prompt: the person has already been asked once, at the link boundary,
+ * and prompting again here would show a second screen for one `presentation.create`.
+ */
+async function buildWallet(ports, loadChainState) {
+    const identitySeed = await resolveIdentitySeed(ports.deviceKey);
+    return new wallet.Wallet({
+        identitySeed,
+        deviceSigner: ports.deviceKey,
+        consent: async () => true,
+        proofGenerator: ports.proofGenerator,
+        store: ports.store,
+        now: () => nowFn(ports),
+        loadChainState
+    });
+}
+
+/** The issuer answered, but named no reason of its own. */
+const UNNAMED_REFUSAL = "ISSUANCE_REFUSED";
+/** A Baby Jubjub point as the decimal-string pair the wire protocol carries. */
+const pointToStrings = (point) => [String(point[0]), String(point[1])];
+/** Relayed in the issuer's own words, under a stand-in code when it named none of its own. */
+const refused = ({ code, message }) => ({
+    status: "refused",
+    code: code ?? UNNAMED_REFUSAL,
+    message
+});
+/**
+ * Whether an indexed credential still stops this member issuing another for the same programme.
+ * Only one that is valid right now does: a revoked or expired credential, or an entry whose
+ * credential is gone, would otherwise leave the person with no way back but erasing everything.
+ */
+async function isStillValid(wallet, credentialId, load) {
+    if ((await wallet.getCredential(credentialId)) === null)
+        return false;
+    await wallet.syncCredential(credentialId, load);
+    return (await wallet.getCredential(credentialId))?.status === "valid";
+}
+/**
+ * The whole issuance, behind the one consent the link boundary already took: hold check, nonce,
+ * binding, the issuer's signature, the two authority checks, storage. Assembly over existing
+ * functions, no new cryptography.
+ *
+ * The revocation secret is generated and opened inside this one call, so it never leaves the
+ * function and nothing has to persist it between two deep links.
+ */
+async function credentialIssueHandler(ports, deviceSecret, params) {
+    const step = (name) => ports.progress("credential.issue", name);
+    step(CREDENTIAL_ISSUE_STEPS.held);
+    const held = await readIssuerEntry(ports.store, params.issuerNetworkId, params.approvalScope);
+    // Read before the issuer signs: the revocation secret below never leaves this call, so a
+    // failure after the 201 would orphan the credential at the issuer with nothing able to open it.
+    step(CREDENTIAL_ISSUE_STEPS.lists);
+    let chainState;
+    try {
+        chainState = await buildChainStateLoader(ports.http, params.issuersUrl, params.revocationsUrl)();
+    }
+    catch (error) {
+        throw new userAppLink.LinkError("ISSUER_UNREACHABLE", error instanceof Error
+            ? error.message
+            : "the issuer's approved-issuer set or revocation snapshot is unreadable");
+    }
+    const loadChainState = async () => chainState;
+    const wallet = await buildWallet(ports, loadChainState);
+    if (held !== null && (await isStillValid(wallet, held.credentialId, loadChainState))) {
+        return { status: "alreadyHeld", credentialId: held.credentialId };
+    }
+    const keys = identity.deriveKeys(deviceSecret);
+    step(CREDENTIAL_ISSUE_STEPS.challenge);
+    const challenge = await postToMember(ports.http, params.challengeUrl, { subjectNetworkId: keys.networkId }, { status: 200, schema: challengeResponseSchema, unreachable: "ISSUER_UNREACHABLE" });
+    if (challenge.refusal)
+        return refused(challenge.refusal);
+    const nonce = challenge.value.nonce;
+    step(CREDENTIAL_ISSUE_STEPS.binding);
+    const confirmationKey = await ports.deviceKey.getPublicKeyJwk();
+    const eddsa = identity.deriveEddsaKeypair(await ports.deviceKey.ecdh(identity.eddsaPeerPointBytes()));
+    const revocationSecret = credential.generateRevocationSecret();
+    const ownership = credential.signCommitmentOwnership(revocationSecret, identity.hexToBytes(nonce));
+    const deviceBindingMessage = identity.buildDeviceBindingMessage(nonce, keys.networkId, bigintToBytes32(eddsa.commitment));
+    const devicePopSignature = identity.bytesToHex(await ports.deviceKey.sign(deviceBindingMessage));
+    const { signature: accountPopSignature } = identity.signAccountBinding(keys.account.privateKey, nonce, credential.jwkToPublicKeyBytes(confirmationKey));
+    step(CREDENTIAL_ISSUE_STEPS.signing);
+    const issued = await postToMember(ports.http, params.credentialsUrl, {
+        subjectNetworkId: keys.networkId,
+        approvalScope: params.approvalScope,
+        confirmationKey,
+        accountPublicKey: keys.account.uncompressedPublicKey,
+        devicePopSignature,
+        accountPopSignature,
+        identityPublicKey: pointToStrings(eddsa.publicKey),
+        revocation: {
+            commitment: credential.deriveRevocationCommitment(revocationSecret).toString(),
+            publicKey: pointToStrings(ownership.publicKey),
+            ownershipSignature: {
+                R8: pointToStrings(ownership.signature.R8),
+                S: String(ownership.signature.S)
+            }
+        }
+    }, { status: 201, schema: issueCredentialResponseSchema, unreachable: "ISSUER_UNREACHABLE" });
+    if (issued.refusal)
+        return refused(issued.refusal);
+    let issuerPublicKey;
+    try {
+        const parsed = credential.parseZkCredential(issued.value.credential);
+        issuerPublicKey = [parsed.issuerPublicKey[0].toString(), parsed.issuerPublicKey[1].toString()];
+    }
+    catch (error) {
+        throw new userAppLink.LinkError("ISSUER_UNREACHABLE", error instanceof Error ? error.message : "malformed credential");
+    }
+    // Built above for the hold check; the lists are read before the signature, so this is the
+    // only step left that can fail.
+    step(CREDENTIAL_ISSUE_STEPS.storing);
+    let credentialId;
+    try {
+        credentialId = await wallet.addCredential({
+            id: issued.value.id,
+            credential: issued.value.credential,
+            revocationSecret
+        });
+    }
+    catch (error) {
+        throw mapWalletError(error, "ISSUER_UNREACHABLE");
+    }
+    await writeIssuerEntry(ports.store, params.issuerNetworkId, {
+        credentialId,
+        issuerPublicKey,
+        issuersUrl: params.issuersUrl,
+        programme: params.approvalScope.programme,
+        country: params.approvalScope.country,
+        issuedAt: Math.floor(nowFn(ports) / 1000)
+    });
+    return { status: "stored", credentialId };
+}
+
+/**
+ * `presentation.create` carries no credential id, so this narrows by what the credential body
+ * says: the requested programme and country. Status is deliberately not a filter — each candidate
+ * is then synced against its own issuer's snapshot, and a caller that finds none valid still
+ * needs to know whether it held a revoked one.
+ */
+function matchingCredentials(credentials, request) {
+    const wantedProgramme = credential.programmeHash(request.programme);
+    const wantedCountry = credential.countryCode(request.country);
+    return credentials.filter((info) => {
+        const { body } = credential.parseZkCredential(info.credential);
+        return body.programmeHash === wantedProgramme && body.countryCode === wantedCountry;
+    });
+}
+/** Of the credentials still usable, the one that stays usable longest, tie-broken by id for determinism. */
+function latestExpiring(credentials) {
+    if (credentials.length === 0)
+        return null;
+    return credentials.reduce((best, candidate) => {
+        const bestExpiry = credential.parseZkCredential(best.credential).body.expiresAt;
+        const candidateExpiry = credential.parseZkCredential(candidate.credential).body.expiresAt;
+        if (candidateExpiry !== bestExpiry)
+            return candidateExpiry > bestExpiry ? candidate : best;
+        return candidate.id < best.id ? candidate : best;
+    });
+}
+
+async function presentationCreateHandler(ports, params) {
+    const step = (name) => ports.progress("presentation.create", name);
+    // The state is read below, once the request is known to have candidates, so the wallet is built
+    // without an authority and handed one per call.
+    const wallet$1 = await buildWallet(ports, neverLoadChainState);
+    /**
+     * The same for every candidate, so the request reads it once however many credentials it has
+     * to check — and a verifier that cannot serve it fails the whole request, since no candidate
+     * can be judged without it.
+     */
+    async function verifierIssuerSet() {
+        try {
+            return await readIssuerSet(ports.http, params.issuersUrl);
+        }
+        catch (error) {
+            throw new userAppLink.LinkError("VERIFIER_UNREACHABLE", error instanceof Error ? error.message : `GET ${params.issuersUrl} failed`);
+        }
+    }
+    /** Same reasoning as the issuer set: the verifier is the party that must accept this root. */
+    async function verifierRevocations() {
+        try {
+            return await readRevocations(ports.http, params.revocationsUrl);
+        }
+        catch (error) {
+            throw new userAppLink.LinkError("VERIFIER_UNREACHABLE", error instanceof Error ? error.message : `GET ${params.revocationsUrl} failed`);
+        }
+    }
+    async function readCandidates() {
+        const infoById = new Map((await wallet$1.listCredentials()).map((info) => [info.id, info]));
+        const held = (await listIssuerEntries(ports.store)).flatMap(({ issuerNetworkId, ...entry }) => {
+            const info = infoById.get(entry.credentialId);
+            // An entry whose credential is gone names a snapshot for nothing; a credential with
+            // no entry has no snapshot to be checked against. Neither can be proved.
+            return info === undefined ? [] : [{ ...info, issuerNetworkId, entry }];
+        });
+        return matchingCredentials(held, params);
+    }
+    step("Checking your credential");
+    const candidates = await readCandidates();
+    // One read for the whole request: every member serves the same network tree, and reading it
+    // per issuer was itself what told whoever served it which issuer a credential came from. The
+    // state is kept so the proof is built from the same read, not a second one that could disagree.
+    let chainState;
+    if (candidates.length > 0) {
+        const state = { ...(await verifierIssuerSet()), ...(await verifierRevocations()) };
+        chainState = state;
+        for (const candidate of candidates) {
+            try {
+                await wallet$1.syncCredential(candidate.id, async () => state);
+            }
+            catch (error) {
+                // A served root that does not match the tree served beside it is the verifier's
+                // fault, not this wallet's; without mapping it the caller is told INTERNAL.
+                throw mapWalletError(error, "VERIFIER_UNREACHABLE");
+            }
+        }
+    }
+    const synced = (await readCandidates()).flatMap((candidate) => chainState === undefined ? [] : [{ ...candidate, chainState }]);
+    const selected = latestExpiring(synced.filter((candidate) => candidate.status === "valid"));
+    if (selected === null) {
+        const revoked = latestExpiring(synced.filter((candidate) => candidate.status === "revoked"));
+        if (revoked !== null) {
+            // The refusal itself says the person holds a revoked credential, which a proof never
+            // would, so it goes through the same gate the proof does.
+            const told = await ports.review({
+                kind: "revoked",
+                verifier: params.audience,
+                programme: params.programme,
+                country: params.country,
+                issuerNetworkId: revoked.issuerNetworkId
+            });
+            if (!told)
+                throw new userAppLink.LinkError("CONSENT_DENIED", "the refusal was not shared");
+            throw new userAppLink.LinkError("CREDENTIAL_REVOKED", `the ${params.programme} credential you hold has been revoked`);
+        }
+        throw new userAppLink.LinkError("NO_CREDENTIAL", `no held credential matches programme "${params.programme}"/"${params.country}"`);
+    }
+    step("Proving");
+    let proof;
+    try {
+        proof = await wallet$1.present(selected.id, {
+            challenge: identity.hexToBytes(params.challenge),
+            audience: params.audience,
+            currentTime: params.currentTime,
+            programme: params.programme,
+            country: params.country
+        }, async () => selected.chainState);
+    }
+    catch (error) {
+        if (error instanceof wallet.WalletError)
+            throw mapWalletError(error);
+        // A raw prover failure, not a WalletError - keep it distinguishable from NO_CREDENTIAL above.
+        throw new userAppLink.LinkError("PROOF_FAILED", error instanceof Error ? error.message : "proof generation failed");
+    }
+    const approved = await ports.review({
+        kind: "proof",
+        verifier: params.audience,
+        programme: params.programme,
+        country: params.country,
+        issuerNetworkId: selected.issuerNetworkId
+    });
+    if (!approved)
+        throw new userAppLink.LinkError("CONSENT_DENIED", "the proof was built but not shared");
+    step("Sharing");
+    // Only the id comes back: the verifier's own `ok` would be the verifier reporting on itself,
+    // and its member app can read the recorded outcome from its own server under this id.
+    const posted = await postToMember(ports.http, params.responseUrl, { requestId: params.requestId, proof: identity.bytesToHex(proof.proof), publicInputs: proof.publicInputs }, { status: 200, schema: verifyResponseSchema, unreachable: "VERIFIER_UNREACHABLE" });
+    // An issuer's error body is the issuer refusing this person, and the wallet relays it. A
+    // verifier has nothing to refuse — it is answering a request the wallet made — so an error
+    // body from it is just an answer the wallet cannot use.
+    if (posted.refusal) {
+        throw new userAppLink.LinkError("VERIFIER_UNREACHABLE", `${params.responseUrl} returned an unusable response`);
+    }
+    return { verificationId: posted.value.verificationId };
+}
+
+async function registrationSignHandler(ports, deviceSecret, params) {
+    const keys = identity.deriveKeys(deviceSecret);
+    return {
+        request: userClient.buildRegistrationRequest(keys, {
+            chainId: params.chainId,
+            verifyingContract: params.verifyingContract
+        }),
+        securityLevel: await ports.deviceKey.getSecurityLevel()
+    };
+}
+
+/** Assembles the four values the Identity screen shows — `Wallet` exposes none of them directly. */
+async function assembleIdentity(deviceSecret, deviceKey) {
+    const keys = identity.deriveKeys(deviceSecret);
+    return {
+        networkId: keys.networkId,
+        metaStealthAddress: userClient.metaStealthAddressFromKeys(keys),
+        accountPublicKey: keys.account.uncompressedPublicKey,
+        securityLevel: await deviceKey.getSecurityLevel()
+    };
+}
+
+/**
+ * Still not `Wallet`'s own status: that also carries `issuer-not-approved`, which `syncRevocations`
+ * stamps against whichever single member last asked for a presentation, and reporting one member's
+ * verdict on another member's credential would be worse than reporting nothing.
+ *
+ * Revocation is no longer in that category. It used to be - one registry per issuer left a
+ * mixed-issuer listing with no single authority to sync against - but the whole network now revokes
+ * into one registry, so there is exactly one thing to ask and asking it names no issuer.
+ */
+function windowStatus(notBefore, expiresAt, nowSeconds) {
+    if (nowSeconds < notBefore)
+        return "not-yet-valid";
+    if (nowSeconds > expiresAt)
+        return "expired";
+    return "valid";
+}
+/**
+ * The window first, since it is signed into the credential and needs no one to confirm: a
+ * credential already outside its dates is reported as such without disclosing anything to a node.
+ * Only an otherwise usable credential is worth asking the registry about.
+ */
+async function statusOf(notBefore, expiresAt, nowSeconds, revocationCommitment, authority) {
+    const window = windowStatus(notBefore, expiresAt, nowSeconds);
+    if (window !== "valid")
+        return window;
+    if (authority === undefined)
+        return "unchecked";
+    // A listing has to render whatever the network is doing, so an unreachable authority is an
+    // answer here - "not checked" - rather than a failure that blanks the screen.
+    let revoked;
+    try {
+        revoked = await authority.isRevoked(revocationCommitment);
+    }
+    catch {
+        revoked = null;
+    }
+    if (revoked === null)
+        return "unchecked";
+    return revoked ? "revoked" : "valid";
+}
+/** Inverse of `packages/credential`'s `countryCode`: three ASCII bytes packed into one integer. */
+function decodeCountryCode(code) {
+    return String.fromCharCode((code >> 16) & 0xff, (code >> 8) & 0xff, code & 0xff);
+}
+function createUserAppService(ports) {
+    // `undefined` means "not yet read from the store"; `null` means "confirmed not onboarded".
+    // Distinguishing the two means onboarding status is read from the store at most once.
+    let deviceSecretCache;
+    async function resolveDeviceSecret() {
+        if (deviceSecretCache === undefined) {
+            deviceSecretCache = await readDeviceSecret(ports.store);
+        }
+        return deviceSecretCache;
+    }
+    /** The gate every handler shares: onboarding is an explicit app action, never implicit. */
+    async function requireOnboarded() {
+        const secret = await resolveDeviceSecret();
+        if (secret === null)
+            throw new userAppLink.LinkError("NOT_ONBOARDED", "no identity has been created yet");
+        return secret;
+    }
+    // One slot deep: a handler body reads and writes the same store a concurrent one might be
+    // mid-sync against, so two deep links run their handler bodies one at a time, never interleaved.
+    let queue = Promise.resolve();
+    function serialize(run) {
+        const result = queue.then(run);
+        queue = result.then(() => undefined, () => undefined);
+        return result;
+    }
+    const handlers = {
+        "registration.sign": (params) => serialize(async () => registrationSignHandler(ports, await requireOnboarded(), params)),
+        "credential.issue": (params) => serialize(async () => credentialIssueHandler(ports, await requireOnboarded(), params)),
+        "presentation.create": (params) => serialize(async () => {
+            await requireOnboarded();
+            return presentationCreateHandler(ports, params);
+        })
+    };
+    return {
+        handlers,
+        async consent(request) {
+            return ports.consent(buildConsentSummary(request));
+        },
+        async isOnboarded() {
+            return (await resolveDeviceSecret()) !== null;
+        },
+        createIdentity() {
+            return serialize(async () => {
+                if ((await resolveDeviceSecret()) !== null) {
+                    throw new Error("createIdentity: an identity already exists — erase() before creating another");
+                }
+                const secret = identity.generateDeviceSecret();
+                const identity$1 = await assembleIdentity(secret, ports.deviceKey);
+                await writeDeviceSecret(ports.store, secret);
+                deviceSecretCache = secret;
+                return identity$1;
+            });
+        },
+        async readIdentity() {
+            const secret = await resolveDeviceSecret();
+            if (secret === null)
+                throw new Error("readIdentity: no identity has been created yet");
+            return assembleIdentity(secret, ports.deviceKey);
+        },
+        async readStealthScanKeys() {
+            const secret = await resolveDeviceSecret();
+            if (secret === null)
+                throw new Error("readStealthScanKeys: no identity has been created yet");
+            const keys = identity.deriveKeys(secret);
+            return { spendingPublicKey: keys.spending.publicKey, viewingPrivateKey: keys.viewing.privateKey };
+        },
+        /**
+         * Joined by credential id with the issuer index, which is the only place the issuer's
+         * name and the plaintext programme survive — the credential body carries a hash.
+         */
+        async listCredentials() {
+            const wallet = await buildWallet(ports, neverLoadChainState);
+            const held = await wallet.listCredentials();
+            const entryByCredentialId = new Map((await listIssuerEntries(ports.store)).map((entry) => [entry.credentialId, entry]));
+            const nowSeconds = Math.floor(nowFn(ports) / 1000);
+            const named = held.flatMap((info) => {
+                const entry = entryByCredentialId.get(info.id);
+                // A credential with no entry predates the index and cannot be named or proved;
+                // the demo erases and reinstalls rather than migrating.
+                if (entry === undefined)
+                    return [];
+                return [{ info, entry, body: credential.parseZkCredential(info.credential).body }];
+            });
+            // One registry read per usable credential, all in flight together: a listing of two
+            // credentials should not cost two round trips in sequence.
+            return Promise.all(named.map(async ({ info, entry, body }) => ({
+                id: info.id,
+                status: await statusOf(body.notBefore, body.expiresAt, nowSeconds, body.revocationCommitment, ports.revocations),
+                issuerNetworkId: entry.issuerNetworkId,
+                programme: entry.programme,
+                issuedAt: entry.issuedAt,
+                programmeHash: body.programmeHash.toString(),
+                country: decodeCountryCode(body.countryCode),
+                notBefore: body.notBefore,
+                expiresAt: body.expiresAt
+            })));
+        },
+        /**
+         * Clears the entire store, not only this package's own keys — a host app shares it, and an
+         * "erase everything" that left its configuration behind would be a half-erase. A caller
+         * must therefore drop whatever it keeps in there too.
+         */
+        erase() {
+            return serialize(async () => {
+                for (const key of await ports.store.list())
+                    await ports.store.delete(key);
+                deviceSecretCache = null;
+            });
+        }
+    };
+}
+
+exports.CREDENTIAL_ISSUE_STEPS = CREDENTIAL_ISSUE_STEPS;
+exports.DEVICE_SECRET_KEY = DEVICE_SECRET_KEY;
+exports.buildConsentSummary = buildConsentSummary;
+exports.createUserAppService = createUserAppService;
+exports.latestExpiring = latestExpiring;
+exports.listIssuerEntries = listIssuerEntries;
+exports.mapWalletError = mapWalletError;
+exports.matchingCredentials = matchingCredentials;
+exports.readIssuerEntry = readIssuerEntry;