@coordination-network/user-app-core 0.0.2 → 0.1.0

package/src/service.ts

@@ -1,5 +1,6 @@
 import { deriveKeys, generateDeviceSecret, type Hex } from "@coordination-network/identity"
-import { parseZkCredential } from "@coordination-network/credential"
+import { deriveDeviceKeyCommitment, parseZkCredential } from "@coordination-network/credential"
+import { CREDENTIAL_PREFIX } from "@coordination-network/wallet"
 import { LinkError, type DecodedLinkRequest, type LinkHandlers } from "@coordination-network/user-app-link"
 import { buildConsentSummary } from "./consent"
 import { readDeviceSecret, writeDeviceSecret } from "./device-secret"
@@ -7,9 +8,10 @@ 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 { deleteIssuerEntries, listIssuerEntries } from "./issuer-index"
 import { nowFn } from "./now"
-import { buildWallet, neverLoadChainState } from "./wallet-factory"
+import { meetsSecurityLevel } from "./security-level"
+import { buildWallet, createIdentitySeedCache, neverLoadChainState } from "./wallet-factory"
 import type {
     HeldCredential,
     HeldCredentialStatus,
@@ -87,6 +89,8 @@ export function createUserAppService(ports: UserAppPorts): UserAppService {
         return secret
     }
 
+    const seeds = createIdentitySeedCache(ports.deviceKey)
+
     // 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()
@@ -104,12 +108,12 @@ export function createUserAppService(ports: UserAppPorts): UserAppService {
             serialize(async () => registrationSignHandler(ports, await requireOnboarded(), params)),
 
         "credential.issue": (params) =>
-            serialize(async () => credentialIssueHandler(ports, await requireOnboarded(), params)),
+            serialize(async () => credentialIssueHandler(ports, seeds, await requireOnboarded(), params)),
 
         "presentation.create": (params) =>
             serialize(async () => {
                 await requireOnboarded()
-                return presentationCreateHandler(ports, params)
+                return presentationCreateHandler(ports, seeds, params)
             })
     }
 
@@ -129,6 +133,15 @@ export function createUserAppService(ports: UserAppPorts): UserAppService {
                 if ((await resolveDeviceSecret()) !== null) {
                     throw new Error("createIdentity: an identity already exists — erase() before creating another")
                 }
+                const minimum = ports.minimumDeviceSecurityLevel
+                if (minimum !== undefined) {
+                    const level = await ports.deviceKey.getSecurityLevel()
+                    if (!meetsSecurityLevel(level, minimum)) {
+                        throw new Error(
+                            `This phone's key protection is ${level}; creating an identity needs a hardware-backed key (${minimum} or better).`
+                        )
+                    }
+                }
                 const secret = generateDeviceSecret()
                 const identity = await assembleIdentity(secret, ports.deviceKey)
                 await writeDeviceSecret(ports.store, secret)
@@ -155,7 +168,7 @@ export function createUserAppService(ports: UserAppPorts): UserAppService {
          * name and the plaintext programme survive — the credential body carries a hash.
          */
         async listCredentials(): Promise<HeldCredential[]> {
-            const wallet = await buildWallet(ports, neverLoadChainState)
+            const wallet = buildWallet(ports, seeds, neverLoadChainState, null)
             const held = await wallet.listCredentials()
             const entryByCredentialId = new Map(
                 (await listIssuerEntries(ports.store)).map((entry) => [entry.credentialId, entry])
@@ -191,6 +204,36 @@ export function createUserAppService(ports: UserAppPorts): UserAppService {
             )
         },
 
+        removeUnboundCredentials(): Promise<number> {
+            return serialize(async () => {
+                const commitment = deriveDeviceKeyCommitment(await ports.deviceKey.getPublicKeyJwk())
+                const wallet = buildWallet(ports, seeds, neverLoadChainState, null)
+                const unbound: string[] = []
+                for (const key of await ports.store.list()) {
+                    if (!key.startsWith(CREDENTIAL_PREFIX)) continue
+                    const id = key.slice(CREDENTIAL_PREFIX.length)
+                    try {
+                        const info = await wallet.getCredential(id)
+                        if (
+                            info !== null &&
+                            parseZkCredential(info.credential).body.deviceKeyCommitment !== commitment
+                        ) {
+                            unbound.push(id)
+                        }
+                    } catch {
+                        // Unreadable, so not proven unbound: left in place.
+                    }
+                }
+                if (unbound.length === 0) return 0
+                // Index entries first: a run killed before the credentials go leaves them still
+                // unbound, so the next run removes them.
+                await deleteIssuerEntries(ports.store, new Set(unbound))
+                for (const id of unbound) await wallet.deleteCredential(id)
+                seeds.clear()
+                return unbound.length
+            })
+        },
+
         /**
          * 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
@@ -200,6 +243,7 @@ export function createUserAppService(ports: UserAppPorts): UserAppService {
             return serialize(async () => {
                 for (const key of await ports.store.list()) await ports.store.delete(key)
                 deviceSecretCache = null
+                seeds.clear()
             })
         }
     }

package/src/types.ts

@@ -1,6 +1,6 @@
 import type { Hex } from "@coordination-network/identity"
-import type { DeviceSigner } from "@coordination-network/credential"
-import type { ProofGenerator, Store } from "@coordination-network/wallet"
+import type { DeviceSigner, Jwk } from "@coordination-network/credential"
+import type { ProofGenerator, Store, WalletChainState } from "@coordination-network/wallet"
 import type {
     Caller,
     DecodedLinkRequest,
@@ -12,15 +12,26 @@ import type {
     SecurityLevel
 } from "@coordination-network/user-app-link"
 
+/** The text of the system dialog a key use raises. The caller supplies it; the key only shows it. */
+export interface KeyPrompt {
+    title: string
+    subtitle?: string
+}
+
 /**
- * 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`.
+ * The holder's two P-256 hardware keys behind one port: a signing key, used per operation, and an
+ * agreement key for ECDH. Every use that unlocks a key takes the prompt the person will see; a
+ * cancelled or invalidated key throws `DeviceKeyError`.
  */
-export interface DeviceKey extends DeviceSigner {
-    /** X coordinate of hwPriv · peerPublicKey, 32 raw bytes. Feeds `deriveEddsaKeypair`. */
-    ecdh(peerPublicKey: Uint8Array): Promise<Uint8Array>
+export interface DeviceKey {
+    getPublicKeyJwk(): Promise<Jwk>
+    /** A signer whose `sign` and `signDigest` each raise `prompt`, so it fits `Wallet` and `buildZkPresentationInputs`. */
+    signerFor(prompt: KeyPrompt): DeviceSigner
+    /** X coordinate of agreementPriv · peerPublicKey, 32 raw bytes. Feeds `deriveEddsaKeypair`. */
+    ecdh(peerPublicKey: Uint8Array, prompt: KeyPrompt): Promise<Uint8Array>
     getSecurityLevel(): Promise<SecurityLevel>
+    /** Base64 DER certificates attesting the signing key to its hardware root of trust, leaf first; empty when it has none. */
+    getAttestationChain(): Promise<string[]>
 }
 
 /** A minimal HTTP JSON port: no DOM or RN fetch types needed, and a test fake is three lines. */
@@ -100,13 +111,49 @@ export interface RevocationAuthority {
     isRevoked(commitment: bigint): Promise<boolean | null>
 }
 
+/**
+ * What the chain says about a member. A rejection means the chain could not be read, never "no
+ * keys": an unknown member answers with an empty list. Unknown includes a removed member and one
+ * the wallet's own member list does not have. An implementation must not reveal to the chain node
+ * which member is asked about.
+ */
+export interface MemberDirectory {
+    /** Leaves of the member's live issuer keys, as `ApprovedIssuerSet.issuerKeysOf` returns them. */
+    issuerKeyLeavesOf(networkId: Hex32): Promise<bigint[]>
+}
+
+/**
+ * What a served list is checked against. The leaf count pins the issuer set's leaves, not only its
+ * root: an internal node can stand in for the leaves under it and keep the root.
+ */
+export type ChainRoots = Pick<WalletChainState, "approvedIssuerRoot" | "revocationRoot"> & {
+    approvedIssuerLeafCount: number
+}
+
+/**
+ * What the chain holds now: the network's one approved-issuer set and one revocation registry. A
+ * rejection means the chain could not be read. The lists a verifier or issuer serves are only
+ * bulk data that must hash to exactly these roots, so an implementation must read the chain, never
+ * a server, and all three values must come from one chain state (one block). It must not reveal to the chain node which credential or member prompted the read.
+ */
+export interface RootAuthority {
+    currentRoots(): Promise<ChainRoots>
+}
+
 export interface UserAppPorts {
     store: Store
     deviceKey: DeviceKey
+    /**
+     * The lowest level `createIdentity` accepts. Absent means no floor. UNKNOWN ranks with SOFTWARE.
+     * The issuer enforces its own minimum at issuance.
+     */
+    minimumDeviceSecurityLevel?: SecurityLevel
     proofGenerator: ProofGenerator
     http: HttpClient
     consent: UserConsentPrompt
     review: PresentationReviewPrompt
+    directory: MemberDirectory
+    roots: RootAuthority
     /** 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. */
@@ -171,5 +218,11 @@ export interface UserAppService {
     listCredentials(): Promise<HeldCredential[]>
     /** See {@link StealthScanKeys}. Throws if no identity has been created. */
     readStealthScanKeys(): Promise<StealthScanKeys>
+    /**
+     * Drops every held credential bound to a device key other than the current one, with its
+     * revocation secret and issuer-index entry, and resolves to how many. Reads only the public key,
+     * so it raises no prompt, and keeps the device secret, so the person stays registered.
+     */
+    removeUnboundCredentials(): Promise<number>
     erase(): Promise<void>
 }

package/src/wallet-factory.ts

@@ -1,8 +1,15 @@
 import { deriveEddsaKeypair, eddsaPeerPointBytes } from "@coordination-network/identity"
+import type { DeviceSigner } from "@coordination-network/credential"
 import { ChainStateLoader, Wallet } from "@coordination-network/wallet"
 import { hexToBytes } from "./hex"
 import { nowFn } from "./now"
-import type { DeviceKey, UserAppPorts } from "./types"
+import type { DeviceKey, KeyPrompt, UserAppPorts } from "./types"
+
+/** Its own text, so the person never sees two identical dialogs back to back. */
+const ECDH_PROMPT: KeyPrompt = {
+    title: "Unlock your credentials",
+    subtitle: "Needed once each time the app starts"
+}
 
 /**
  * The Baby Jubjub identity seed, rooted in the hardware ECDH rather than the device secret.
@@ -11,10 +18,36 @@ import type { DeviceKey, UserAppPorts } from "./types"
  * the 32 raw bytes decoded from it.
  */
 export async function resolveIdentitySeed(deviceKey: DeviceKey): Promise<Uint8Array> {
-    const sharedSecret = await deviceKey.ecdh(eddsaPeerPointBytes())
+    const sharedSecret = await deviceKey.ecdh(eddsaPeerPointBytes(), ECDH_PROMPT)
     return hexToBytes(deriveEddsaKeypair(sharedSecret).seed)
 }
 
+/** The seed is the same for the life of the process, so the person is asked for it once. */
+export interface IdentitySeedCache {
+    resolve(): Promise<Uint8Array>
+    clear(): void
+}
+
+export function createIdentitySeedCache(deviceKey: DeviceKey): IdentitySeedCache {
+    let pending: Promise<Uint8Array> | null = null
+    return {
+        resolve() {
+            if (pending === null) {
+                const attempt = resolveIdentitySeed(deviceKey)
+                pending = attempt
+                // A cancelled prompt must not be cached: the next operation asks again.
+                attempt.catch(() => {
+                    if (pending === attempt) pending = null
+                })
+            }
+            return pending
+        },
+        clear() {
+            pending = null
+        }
+    }
+}
+
 /**
  * `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.
@@ -23,16 +56,39 @@ export const neverLoadChainState: ChainStateLoader = async () => {
     throw new Error("chain state must not be requested outside a per-request authority")
 }
 
+/** A listing wallet's identity seed: like `neverLoadChainState`, loud if a future bug reaches for it. */
+export const neverSeed = async (): Promise<Uint8Array> => {
+    throw new Error("a listing must not ask the device key for the identity seed")
+}
+
+const neverSign = async (): Promise<Uint8Array> => {
+    throw new Error("a listing must not ask the device key to sign")
+}
+
+/** A listing wallet's signer: it reads the public key, which raises no prompt, and never signs. */
+export const listingSigner = (deviceKey: DeviceKey): DeviceSigner => ({
+    getPublicKeyJwk: () => deviceKey.getPublicKeyJwk(),
+    sign: neverSign,
+    signDigest: neverSign
+})
+
 /**
  * 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`.
+ *
+ * `prompt` is what a signature raises. `null` builds a wallet for listing and syncing, which must
+ * never touch a key: its seed and signer throw.
  */
-export async function buildWallet(ports: UserAppPorts, loadChainState: ChainStateLoader): Promise<Wallet> {
-    const identitySeed = await resolveIdentitySeed(ports.deviceKey)
+export function buildWallet(
+    ports: UserAppPorts,
+    seeds: IdentitySeedCache,
+    loadChainState: ChainStateLoader,
+    prompt: KeyPrompt | null
+): Wallet {
     return new Wallet({
-        identitySeed,
-        deviceSigner: ports.deviceKey,
+        identitySeed: prompt === null ? neverSeed : () => seeds.resolve(),
+        deviceSigner: prompt === null ? listingSigner(ports.deviceKey) : ports.deviceKey.signerFor(prompt),
         consent: async () => true,
         proofGenerator: ports.proofGenerator,
         store: ports.store,

package/types/index.d.ts

@@ -1,17 +1,28 @@
 import { Hex } from '@coordination-network/identity';
-import { DeviceSigner } from '@coordination-network/credential';
-import { Store, ProofGenerator, CredentialInfo } from '@coordination-network/wallet';
+import { Jwk, DeviceSigner } from '@coordination-network/credential';
+export { DEVICE_ATTESTATION_CHALLENGE } from '@coordination-network/credential';
+import { WalletChainState, Store, ProofGenerator, CredentialInfo } from '@coordination-network/wallet';
 import { Caller, SecurityLevel, Hex32, Hex66, Hex65, LinkOp, LinkHandlers, DecodedLinkRequest, LinkErrorCode, LinkError } from '@coordination-network/user-app-link';
 
+/** The text of the system dialog a key use raises. The caller supplies it; the key only shows it. */
+interface KeyPrompt {
+    title: string;
+    subtitle?: string;
+}
 /**
- * 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`.
+ * The holder's two P-256 hardware keys behind one port: a signing key, used per operation, and an
+ * agreement key for ECDH. Every use that unlocks a key takes the prompt the person will see; a
+ * cancelled or invalidated key throws `DeviceKeyError`.
  */
-interface DeviceKey extends DeviceSigner {
-    /** X coordinate of hwPriv · peerPublicKey, 32 raw bytes. Feeds `deriveEddsaKeypair`. */
-    ecdh(peerPublicKey: Uint8Array): Promise<Uint8Array>;
+interface DeviceKey {
+    getPublicKeyJwk(): Promise<Jwk>;
+    /** A signer whose `sign` and `signDigest` each raise `prompt`, so it fits `Wallet` and `buildZkPresentationInputs`. */
+    signerFor(prompt: KeyPrompt): DeviceSigner;
+    /** X coordinate of agreementPriv · peerPublicKey, 32 raw bytes. Feeds `deriveEddsaKeypair`. */
+    ecdh(peerPublicKey: Uint8Array, prompt: KeyPrompt): Promise<Uint8Array>;
     getSecurityLevel(): Promise<SecurityLevel>;
+    /** Base64 DER certificates attesting the signing key to its hardware root of trust, leaf first; empty when it has none. */
+    getAttestationChain(): Promise<string[]>;
 }
 /** A minimal HTTP JSON port: no DOM or RN fetch types needed, and a test fake is three lines. */
 interface HttpJsonResponse {
@@ -87,13 +98,46 @@ type PresentationReviewPrompt = (summary: PresentationReview) => Promise<boolean
 interface RevocationAuthority {
     isRevoked(commitment: bigint): Promise<boolean | null>;
 }
+/**
+ * What the chain says about a member. A rejection means the chain could not be read, never "no
+ * keys": an unknown member answers with an empty list. Unknown includes a removed member and one
+ * the wallet's own member list does not have. An implementation must not reveal to the chain node
+ * which member is asked about.
+ */
+interface MemberDirectory {
+    /** Leaves of the member's live issuer keys, as `ApprovedIssuerSet.issuerKeysOf` returns them. */
+    issuerKeyLeavesOf(networkId: Hex32): Promise<bigint[]>;
+}
+/**
+ * What a served list is checked against. The leaf count pins the issuer set's leaves, not only its
+ * root: an internal node can stand in for the leaves under it and keep the root.
+ */
+type ChainRoots = Pick<WalletChainState, "approvedIssuerRoot" | "revocationRoot"> & {
+    approvedIssuerLeafCount: number;
+};
+/**
+ * What the chain holds now: the network's one approved-issuer set and one revocation registry. A
+ * rejection means the chain could not be read. The lists a verifier or issuer serves are only
+ * bulk data that must hash to exactly these roots, so an implementation must read the chain, never
+ * a server, and all three values must come from one chain state (one block). It must not reveal to the chain node which credential or member prompted the read.
+ */
+interface RootAuthority {
+    currentRoots(): Promise<ChainRoots>;
+}
 interface UserAppPorts {
     store: Store;
     deviceKey: DeviceKey;
+    /**
+     * The lowest level `createIdentity` accepts. Absent means no floor. UNKNOWN ranks with SOFTWARE.
+     * The issuer enforces its own minimum at issuance.
+     */
+    minimumDeviceSecurityLevel?: SecurityLevel;
     proofGenerator: ProofGenerator;
     http: HttpClient;
     consent: UserConsentPrompt;
     review: PresentationReviewPrompt;
+    directory: MemberDirectory;
+    roots: RootAuthority;
     /** 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. */
@@ -153,11 +197,25 @@ interface UserAppService {
     listCredentials(): Promise<HeldCredential[]>;
     /** See {@link StealthScanKeys}. Throws if no identity has been created. */
     readStealthScanKeys(): Promise<StealthScanKeys>;
+    /**
+     * Drops every held credential bound to a device key other than the current one, with its
+     * revocation secret and issuer-index entry, and resolves to how many. Reads only the public key,
+     * so it raises no prompt, and keeps the device secret, so the person stays registered.
+     */
+    removeUnboundCredentials(): Promise<number>;
     erase(): Promise<void>;
 }
 
 declare function createUserAppService(ports: UserAppPorts): UserAppService;
 
+/**
+ * A key use the person or the platform ended: cancelled at the prompt, the key invalidated, or the
+ * authentication itself failed (lockout, no foreground activity, another prompt already showing).
+ */
+declare class DeviceKeyError extends Error {
+    readonly code: "USER_CANCELED" | "KEY_INVALIDATED" | "AUTHENTICATION_FAILED";
+    constructor(code: DeviceKeyError["code"], message?: string);
+}
 /**
  * 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.
@@ -176,8 +234,8 @@ interface CredentialSelectionRequest {
 /**
  * `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.
+ * is then synced against the verifier's lists, checked against the chain's roots, and a caller
+ * that finds none valid still needs to know whether it held a revoked one.
  */
 declare function matchingCredentials<T extends CredentialInfo>(credentials: T[], request: CredentialSelectionRequest): T[];
 /** Of the credentials still usable, the one that stays usable longest, tie-broken by id for determinism. */
@@ -220,9 +278,8 @@ 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. */
+    /** Where the issuer published its approved-issuer set at issuance. Nothing reads it back: a
+     *  presentation reads the verifier's lists. */
     issuersUrl: string;
     programme: string;
     country: string;
@@ -234,5 +291,5 @@ declare function listIssuerEntries(store: Store): Promise<(IssuerIndexEntry & {
     issuerNetworkId: Hex32;
 })[]>;
 
-export { CREDENTIAL_ISSUE_STEPS, DEVICE_SECRET_KEY, buildConsentSummary, createUserAppService, latestExpiring, listIssuerEntries, mapWalletError, matchingCredentials, readIssuerEntry };
-export type { ConsentDetail, ConsentScope, ConsentSummary, CredentialSelectionRequest, DeviceKey, HeldCredential, HeldCredentialStatus, HttpClient, HttpJsonResponse, IssuerIndexEntry, PresentationReview, PresentationReviewPrompt, PublicIdentity, RevocationAuthority, StealthScanKeys, UserAppPorts, UserAppService, UserConsentPrompt };
+export { CREDENTIAL_ISSUE_STEPS, DEVICE_SECRET_KEY, DeviceKeyError, buildConsentSummary, createUserAppService, latestExpiring, listIssuerEntries, mapWalletError, matchingCredentials, readIssuerEntry };
+export type { ChainRoots, ConsentDetail, ConsentScope, ConsentSummary, CredentialSelectionRequest, DeviceKey, HeldCredential, HeldCredentialStatus, HttpClient, HttpJsonResponse, IssuerIndexEntry, KeyPrompt, MemberDirectory, PresentationReview, PresentationReviewPrompt, PublicIdentity, RevocationAuthority, RootAuthority, StealthScanKeys, UserAppPorts, UserAppService, UserConsentPrompt };