@coordination-network/user-app-core 0.0.1

package/src/issuer-index.ts

@@ -0,0 +1,64 @@
+import type { Hex32 } from "@coordination-network/user-app-link"
+import type { Store } from "@coordination-network/wallet"
+import type { ConsentScope } from "./types"
+
+/**
+ * `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 entry per issuer the wallet holds a credential from. It carries what the credential body
+ * cannot give back — the plaintext programme and the issuer — so a listing can name both.
+ */
+export interface IssuerIndexEntry {
+    credentialId: string
+    /** The Baby Jubjub key that signed the credential, as decimal field elements. */
+    issuerPublicKey: [string, string]
+    /** Where the issuer published its own approved-issuer set at issuance. Nothing reads it yet:
+     *  a presentation reads the verifier's, which is why a hostile verifier can still probe for the
+     *  issuer by serving a subset. Recorded so that check can be anchored here instead. */
+    issuersUrl: string
+    programme: string
+    country: string
+    issuedAt: number
+}
+
+/**
+ * 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: Hex32, scope: ConsentScope): string =>
+    `${ISSUER_INDEX_PREFIX}${issuerNetworkId.toLowerCase()}:${encodeURIComponent(scope.programme)}:${encodeURIComponent(scope.country)}`
+
+export async function readIssuerEntry(
+    store: Store,
+    issuerNetworkId: Hex32,
+    scope: ConsentScope
+): Promise<IssuerIndexEntry | null> {
+    const raw = await store.get(keyFor(issuerNetworkId, scope))
+    return raw === null ? null : (JSON.parse(raw) as IssuerIndexEntry)
+}
+
+/** Every entry the wallet holds, for the joins that start from a credential rather than an issuer. */
+export async function listIssuerEntries(store: Store): Promise<(IssuerIndexEntry & { issuerNetworkId: Hex32 })[]> {
+    const entries: (IssuerIndexEntry & { issuerNetworkId: Hex32 })[] = []
+    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) as IssuerIndexEntry),
+            issuerNetworkId: key.slice(ISSUER_INDEX_PREFIX.length).split(":")[0] as Hex32
+        })
+    }
+    return entries
+}
+
+/** The entry carries its own scope, so it is what the key is built from. */
+export async function writeIssuerEntry(store: Store, issuerNetworkId: Hex32, entry: IssuerIndexEntry): Promise<void> {
+    await store.set(keyFor(issuerNetworkId, entry), JSON.stringify(entry))
+}

package/src/member-api.ts

@@ -0,0 +1,68 @@
+import { z } from "zod"
+import { LinkError, type LinkErrorCode } from "@coordination-network/user-app-link"
+import type { HttpClient } from "./types"
+
+/**
+ * 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 = z
+    .string()
+    .regex(/^(0x)?[0-9a-fA-F]{64}$/i, "must be 32-byte hex")
+    .transform((value) => `0x${value.replace(/^0x/i, "")}`.toLowerCase() as `0x${string}`)
+
+export const challengeResponseSchema = z.object({ nonce: challengeNonceSchema, expiresAt: z.number() }).strict()
+
+export const issueCredentialResponseSchema = z.object({ id: z.string().min(1), credential: 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.
+ */
+export const verifyResponseSchema = z.object({ verificationId: z.string().min(1) })
+
+/** Not `.strict()`: an error body is read for `code`/`error`, whichever route sent it. */
+export const errorBodySchema = z.object({ error: z.string().optional(), code: z.string().optional() })
+
+/** A member answering with an error of its own, in its own vocabulary. */
+export interface MemberRefusal {
+    code?: string
+    message: string
+}
+
+/**
+ * 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.
+ */
+export async function postToMember<T>(
+    http: HttpClient,
+    url: string,
+    body: unknown,
+    expected: { status: number; schema: z.ZodType<T>; unreachable: LinkErrorCode }
+): Promise<{ value: T; refusal?: never } | { value?: never; refusal: MemberRefusal }> {
+    let response
+    try {
+        response = await http.postJson(url, body)
+    } catch (error) {
+        throw new 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 LinkError(expected.unreachable, `${url} returned an unusable response`)
+}

package/src/now.ts

@@ -0,0 +1,6 @@
+import type { UserAppPorts } from "./types"
+
+/** `ports.now` is optional (a test harness injects a deterministic clock); real ports omit it. */
+export function nowFn(ports: Pick<UserAppPorts, "now">): number {
+    return (ports.now ?? Date.now)()
+}

package/src/selection.ts

@@ -0,0 +1,38 @@
+import { countryCode, parseZkCredential, programmeHash } from "@coordination-network/credential"
+import type { CredentialInfo } from "@coordination-network/wallet"
+
+export interface CredentialSelectionRequest {
+    programme: string
+    country: string
+}
+
+/**
+ * `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.
+ */
+export function matchingCredentials<T extends CredentialInfo>(
+    credentials: T[],
+    request: CredentialSelectionRequest
+): T[] {
+    const wantedProgramme = programmeHash(request.programme)
+    const wantedCountry = countryCode(request.country)
+
+    return credentials.filter((info) => {
+        const { body } = 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. */
+export function latestExpiring<T extends CredentialInfo>(credentials: T[]): T | null {
+    if (credentials.length === 0) return null
+
+    return credentials.reduce((best, candidate) => {
+        const bestExpiry = parseZkCredential(best.credential).body.expiresAt
+        const candidateExpiry = parseZkCredential(candidate.credential).body.expiresAt
+        if (candidateExpiry !== bestExpiry) return candidateExpiry > bestExpiry ? candidate : best
+        return candidate.id < best.id ? candidate : best
+    })
+}

package/src/service.ts

@@ -0,0 +1,206 @@
+import { deriveKeys, generateDeviceSecret, type Hex } from "@coordination-network/identity"
+import { parseZkCredential } from "@coordination-network/credential"
+import { LinkError, type DecodedLinkRequest, type LinkHandlers } from "@coordination-network/user-app-link"
+import { buildConsentSummary } from "./consent"
+import { readDeviceSecret, writeDeviceSecret } from "./device-secret"
+import { credentialIssueHandler } from "./handlers/credential-issue"
+import { presentationCreateHandler } from "./handlers/presentation-create"
+import { registrationSignHandler } from "./handlers/registration-sign"
+import { assembleIdentity } from "./identity"
+import { listIssuerEntries } from "./issuer-index"
+import { nowFn } from "./now"
+import { buildWallet, neverLoadChainState } from "./wallet-factory"
+import type {
+    HeldCredential,
+    HeldCredentialStatus,
+    RevocationAuthority,
+    PublicIdentity,
+    StealthScanKeys,
+    UserAppPorts,
+    UserAppService
+} from "./types"
+
+/**
+ * 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: number, expiresAt: number, nowSeconds: number): HeldCredentialStatus {
+    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: number,
+    expiresAt: number,
+    nowSeconds: number,
+    revocationCommitment: bigint,
+    authority: RevocationAuthority | undefined
+): Promise<HeldCredentialStatus> {
+    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: boolean | null
+    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: number): string {
+    return String.fromCharCode((code >> 16) & 0xff, (code >> 8) & 0xff, code & 0xff)
+}
+
+export function createUserAppService(ports: UserAppPorts): UserAppService {
+    // `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: Hex | null | undefined
+
+    async function resolveDeviceSecret(): Promise<Hex | null> {
+        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(): Promise<Hex> {
+        const secret = await resolveDeviceSecret()
+        if (secret === null) throw new 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<unknown> = Promise.resolve()
+    function serialize<T>(run: () => Promise<T>): Promise<T> {
+        const result = queue.then(run)
+        queue = result.then(
+            () => undefined,
+            () => undefined
+        )
+        return result
+    }
+
+    const handlers: LinkHandlers = {
+        "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: DecodedLinkRequest): Promise<boolean> {
+            return ports.consent(buildConsentSummary(request))
+        },
+
+        async isOnboarded(): Promise<boolean> {
+            return (await resolveDeviceSecret()) !== null
+        },
+
+        createIdentity(): Promise<PublicIdentity> {
+            return serialize(async () => {
+                if ((await resolveDeviceSecret()) !== null) {
+                    throw new Error("createIdentity: an identity already exists — erase() before creating another")
+                }
+                const secret = generateDeviceSecret()
+                const identity = await assembleIdentity(secret, ports.deviceKey)
+                await writeDeviceSecret(ports.store, secret)
+                deviceSecretCache = secret
+                return identity
+            })
+        },
+
+        async readIdentity(): Promise<PublicIdentity> {
+            const secret = await resolveDeviceSecret()
+            if (secret === null) throw new Error("readIdentity: no identity has been created yet")
+            return assembleIdentity(secret, ports.deviceKey)
+        },
+
+        async readStealthScanKeys(): Promise<StealthScanKeys> {
+            const secret = await resolveDeviceSecret()
+            if (secret === null) throw new Error("readStealthScanKeys: no identity has been created yet")
+            const keys = 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(): Promise<HeldCredential[]> {
+            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: 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(): Promise<void> {
+            return serialize(async () => {
+                for (const key of await ports.store.list()) await ports.store.delete(key)
+                deviceSecretCache = null
+            })
+        }
+    }
+}

package/src/steps.ts

@@ -0,0 +1,13 @@
+/**
+ * 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.
+ */
+export 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"
+} as const

package/src/types.ts

@@ -0,0 +1,175 @@
+import type { Hex } from "@coordination-network/identity"
+import type { DeviceSigner } from "@coordination-network/credential"
+import type { ProofGenerator, Store } from "@coordination-network/wallet"
+import type {
+    Caller,
+    DecodedLinkRequest,
+    Hex32,
+    Hex65,
+    Hex66,
+    LinkHandlers,
+    LinkOp,
+    SecurityLevel
+} from "@coordination-network/user-app-link"
+
+/**
+ * The holder P-256 device key. Extends `DeviceSigner` (rather than replacing it) so a `DeviceKey`
+ * is accepted as-is anywhere a `DeviceSigner` is expected — `Wallet`, `buildZkPresentationInputs`,
+ * `deriveDeviceKeyCommitment`.
+ */
+export interface DeviceKey extends DeviceSigner {
+    /** X coordinate of hwPriv · peerPublicKey, 32 raw bytes. Feeds `deriveEddsaKeypair`. */
+    ecdh(peerPublicKey: Uint8Array): Promise<Uint8Array>
+    getSecurityLevel(): Promise<SecurityLevel>
+}
+
+/** A minimal HTTP JSON port: no DOM or RN fetch types needed, and a test fake is three lines. */
+export interface HttpJsonResponse {
+    status: number
+    body: unknown
+}
+
+export interface HttpClient {
+    getJson(url: string): Promise<HttpJsonResponse>
+    postJson(url: string, body: unknown): Promise<HttpJsonResponse>
+}
+
+/** One human-readable line of a consent screen, e.g. `{ label: "Programme", value: "demo-programme" }`. */
+export interface ConsentDetail {
+    label: string
+    value: string
+    /** Set false for a value whose full text is the point and must never hide behind a tap - the callback. */
+    truncate?: boolean
+}
+
+/** The programme and country a consent sentence names, on the two ops that scope one. */
+export interface ConsentScope {
+    programme: string
+    country: string
+}
+
+interface ConsentSummaryBase {
+    caller: Caller
+    /** The technical rows the consent sheet folds away, in the order it lists them. */
+    details: ConsentDetail[]
+}
+
+/**
+ * What a request amounts to, in values rather than sentences: the wallet writes every line a
+ * person reads, so that it can name the caller mid-sentence in the caller's own colour. Keyed by
+ * `op` so a screen that switches on it gets `scope` typed rather than optional.
+ */
+export type ConsentSummary =
+    | (ConsentSummaryBase & { op: "registration.sign" })
+    | (ConsentSummaryBase & { op: "credential.issue"; scope: ConsentScope })
+    | (ConsentSummaryBase & { op: "presentation.create"; scope: ConsentScope })
+
+/** The single consent gate: shown once per deep link, before dispatch. */
+export type UserConsentPrompt = (summary: ConsentSummary) => Promise<boolean>
+
+interface PresentationReviewBase {
+    verifier: string
+    programme: string
+    country: string
+    issuerNetworkId: Hex32
+}
+
+/**
+ * What a verifier would learn. `proof` is what the built proof reveals, which is no longer the
+ * issuer: a presentation proves membership of the whole approved set and carries one network-wide
+ * revocation root, so nothing in it singles an issuer out. `issuerNetworkId` is still here because
+ * the person is shown which of their own credentials answered. `revoked` is the refusal itself:
+ * telling a verifier that the person holds a revoked credential says something about them that no
+ * proof would have, so it is theirs to allow.
+ */
+export type PresentationReview =
+    (PresentationReviewBase & { kind: "proof" }) | (PresentationReviewBase & { kind: "revoked" })
+
+/**
+ * The second gate, on `presentation.create` only: nothing has left the phone yet, so the person
+ * can be shown what would. `false` refuses with `CONSENT_DENIED`.
+ */
+export type PresentationReviewPrompt = (summary: PresentationReview) => Promise<boolean>
+
+/**
+ * Whether a held credential has been revoked, from the one registry the whole network writes to.
+ * `null` is "nobody to ask": no stack is configured, or it could not be reached. The caller then
+ * says it has not checked, rather than calling a credential valid on the strength of its dates.
+ */
+export interface RevocationAuthority {
+    isRevoked(commitment: bigint): Promise<boolean | null>
+}
+
+export interface UserAppPorts {
+    store: Store
+    deviceKey: DeviceKey
+    proofGenerator: ProofGenerator
+    http: HttpClient
+    consent: UserConsentPrompt
+    review: PresentationReviewPrompt
+    /** Absent leaves every held credential's revocation unchecked; see {@link RevocationAuthority}. */
+    revocations?: RevocationAuthority
+    /** Named steps inside a long handler, for a screen that shows what the wallet is doing. */
+    progress: (op: LinkOp, step: string) => void
+    now?: () => number
+}
+
+/** What the app's own Identity screen shows; assembled from the device secret, never from a link. */
+export interface PublicIdentity {
+    networkId: Hex32
+    metaStealthAddress: Hex66
+    accountPublicKey: Hex65
+    securityLevel: SecurityLevel
+}
+
+/**
+ * What a held credential's state can honestly be called here. The validity window is signed into
+ * the credential body, so it is answerable offline. Revocation takes an authority, and there is now
+ * exactly one for the whole network — asking it names no issuer, which is what makes this listing
+ * able to say "revoked" at all. Issuer approval stays out: an approved-issuer set is still each
+ * member's own, so this screen has no one to ask and reports nothing.
+ *
+ * `unchecked` is a credential inside its window whose revocation could not be established. It is
+ * deliberately not folded into `valid`: the difference between "the network says this is live" and
+ * "nobody could be asked" is the whole point of showing a status.
+ */
+export type HeldCredentialStatus = "valid" | "revoked" | "not-yet-valid" | "expired" | "unchecked"
+
+export interface HeldCredential {
+    id: string
+    /** See {@link HeldCredentialStatus}: the window and revocation, never issuer approval. */
+    status: HeldCredentialStatus
+    /** The three fields the credential body cannot give back, kept in the issuer index at issuance. */
+    issuerNetworkId: Hex32
+    programme: string
+    issuedAt: number
+    /** A one-way hash of {@link programme}, as signed into the credential. */
+    programmeHash: string
+    /** Unlike `programmeHash`, exactly invertible: `countryCode` just packs three ASCII bytes. */
+    country: string
+    notBefore: number
+    expiresAt: number
+}
+
+/**
+ * The two keys an app needs to scan ERC-5564 announcements for itself, where there is no indexer.
+ * `viewingPrivateKey` is a private key: it detects incoming payments but cannot spend, and it is
+ * deliberately the narrowest thing that does the job — far less than the device secret every other
+ * key derives from.
+ */
+export interface StealthScanKeys {
+    spendingPublicKey: Hex
+    viewingPrivateKey: Hex
+}
+
+export interface UserAppService {
+    readonly handlers: LinkHandlers
+    consent(request: DecodedLinkRequest): Promise<boolean>
+    isOnboarded(): Promise<boolean>
+    createIdentity(): Promise<PublicIdentity>
+    readIdentity(): Promise<PublicIdentity>
+    listCredentials(): Promise<HeldCredential[]>
+    /** See {@link StealthScanKeys}. Throws if no identity has been created. */
+    readStealthScanKeys(): Promise<StealthScanKeys>
+    erase(): Promise<void>
+}

package/src/wallet-factory.ts

@@ -0,0 +1,42 @@
+import { deriveEddsaKeypair, eddsaPeerPointBytes } from "@coordination-network/identity"
+import { ChainStateLoader, Wallet } from "@coordination-network/wallet"
+import { hexToBytes } from "./hex"
+import { nowFn } from "./now"
+import type { DeviceKey, UserAppPorts } from "./types"
+
+/**
+ * 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.
+ */
+export async function resolveIdentitySeed(deviceKey: DeviceKey): Promise<Uint8Array> {
+    const sharedSecret = await deviceKey.ecdh(eddsaPeerPointBytes())
+    return hexToBytes(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.
+ */
+export const neverLoadChainState: ChainStateLoader = 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`.
+ */
+export async function buildWallet(ports: UserAppPorts, loadChainState: ChainStateLoader): Promise<Wallet> {
+    const identitySeed = await resolveIdentitySeed(ports.deviceKey)
+    return new Wallet({
+        identitySeed,
+        deviceSigner: ports.deviceKey,
+        consent: async () => true,
+        proofGenerator: ports.proofGenerator,
+        store: ports.store,
+        now: () => nowFn(ports),
+        loadChainState
+    })
+}