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

package/README.md

@@ -26,7 +26,9 @@ yarn add @coordination-network/user-app-link
 { id, version: "v1", ok: true, result } | { id, version: "v1", ok: false, code, message? }
 ```
 
-`code` is one of `USER_DENIED`, `CONSENT_DENIED`, `UNSUPPORTED_OP`, `INVALID_REQUEST`, `NOT_ONBOARDED`, `NO_CREDENTIAL`, `CREDENTIAL_REVOKED`, `PROOF_FAILED`, `ISSUER_UNREACHABLE`, `VERIFIER_UNREACHABLE`, `INTERNAL`.
+`code` is one of `USER_DENIED`, `CONSENT_DENIED`, `UNSUPPORTED_OP`, `INVALID_REQUEST`, `NOT_ONBOARDED`, `NO_CREDENTIAL`, `CREDENTIAL_REVOKED`, `PROOF_FAILED`, `ISSUER_UNREACHABLE`, `VERIFIER_UNREACHABLE`, `ISSUER_NOT_APPROVED`, `CHAIN_UNREACHABLE`, `INTERNAL`.
+
+`message` is one fixed sentence per code (`LINK_ERROR_MESSAGES`), so a response never carries detail about the holder. The one exception is `INVALID_REQUEST` for malformed params, which describes the caller's own request.
 
 **Size.** `encodeRequest`/`encodeResponse` throw `LinkPayloadTooLargeError` if the built URL exceeds `MAX_URL_LENGTH` (2000 characters) — the point past which platform `Linking.openURL` calls and some OSes start truncating or refusing a URL. Every result below fits comfortably; the two payloads that wouldn't (a credential and a ZK proof) never travel over a link at all — the user app fetches and posts both itself.
 
@@ -44,9 +46,9 @@ Three ops, one per flow, each behind exactly one consent.
 
 `securityLevel` is one of `STRONGBOX`, `TRUSTED_ENVIRONMENT`, `SOFTWARE`, `UNKNOWN`. `registration.sign`'s `request` is posted to the member server verbatim; the security level rides along because registration is the first thing every member app does and nothing else in the request says how the phone guards its keys.
 
-`credential.issue` runs the whole issuance inside the user app after one approval: it checks what it already holds, gets a nonce from `challengeUrl`, builds the proof-of-possession material, posts it to `credentialsUrl`, checks the credential it gets back against `issuersUrl` and `revocationsUrl`, and stores it. The revocation secret never leaves the user app. `refused` is the issuer server's own decision, in its own error vocabulary; a server that cannot be reached at all is an `ISSUER_UNREACHABLE` error, not a refusal.
+`credential.issue` runs the whole issuance inside the user app after one approval: it checks what it already holds, gets a nonce from `challengeUrl`, builds the proof-of-possession material, posts it to `credentialsUrl`, checks the credential it gets back against `issuersUrl` and `revocationsUrl` (lists that must hash to the chain's current roots, else `ISSUER_UNREACHABLE`), checks that its issuer key is one the chain lists for `issuerNetworkId` (`ISSUER_NOT_APPROVED`, or `CHAIN_UNREACHABLE` when the chain cannot be read), and stores it. The revocation secret never leaves the user app. `refused` is the issuer server's own decision, in its own error vocabulary; a server that cannot be reached at all is an `ISSUER_UNREACHABLE` error, not a refusal.
 
-`presentation.create` does not return a proof. `requestId` identifies a presentation request the member server already issued via `POST /v1/presentation-requests` (which returns `{ requestId, challenge, audience, currentTime, programme, country }`); the rest of the params are that same response, since the user app still needs them to build the proof inputs. The user app picks a matching credential, checks it against **its own issuer's** revocation snapshot (read from the user app's index, never a URL the verifier chose), proves it, asks the person once more before sharing, and itself `POST`s `{ requestId, proof, publicInputs }` to `responseUrl` (the member server's `/v1/verify`). The result is only the `verificationId`: the member app reads the outcome from its own server at `GET /v1/verifications/:id` rather than trusting a relayed answer. A proof is large — far past `MAX_URL_LENGTH` — so it never travels as a query parameter.
+`presentation.create` does not return a proof. `requestId` identifies a presentation request the member server already issued via `POST /v1/presentation-requests` (which returns `{ requestId, challenge, audience, currentTime, programme, country }`); the rest of the params are that same response, since the user app still needs them to build the proof inputs. The user app picks a matching credential, checks it against the chain's current roots (the verifier's served lists must hash to them, or the request fails with `VERIFIER_UNREACHABLE`), proves it, asks the person once more before sharing, and itself `POST`s `{ requestId, proof, publicInputs }` to `responseUrl` (the member server's `/v1/verify`). The result is only the `verificationId`: the member app reads the outcome from its own server at `GET /v1/verifications/:id` rather than trusting a relayed answer. A proof is large — far past `MAX_URL_LENGTH` — so it never travels as a query parameter.
 
 ## Using `createLinkClient` (member app side)
 
@@ -70,9 +72,68 @@ console.log(signed.request.networkId)
 
 `request` encodes the op, opens the request URL in the user app, and resolves with the typed result (or rejects with a `LinkError` carrying the response's `code`) once the matching callback URL arrives. One request may be in flight at a time per client; a second call while one is pending rejects immediately.
 
+### WS1 mobile presentation transport (#112)
+
+The holder's wallet and verifier's member app can run on **separate Android phones**. The verifier
+shows a public challenge QR; the holder scans it, reviews the request and consents to proving. The
+wallet posts the proof directly to the verifier server (HTTPS for hosted services). The verifier
+polls its server with its own member token; no app callback needs to cross devices. Both phones
+need connectivity, and the wallet also needs its configured chain RPC. This is an online reference
+demo, not a claim of offline suitability for every field deployment. The same-phone deep-link
+flow remains available. Both configurations must name a verifier URL reachable from each phone;
+localhost URLs require USB reverse forwarding on each device.
+
+1. In the member app, choose **Verify → Check another phone → Create challenge QR**. The server's
+   `POST /v1/presentation-requests` supplies the single-use challenge, audience, scope, time and
+   expiry. The screen renders `cn-present:v1:` with a compact encoding of these fields and one
+   server base URL. It carries no token, credential, proof or callback. URLs are reconstructed
+   from that base; encoded QR data is capped at 2,000 characters.
+2. In the wallet, choose **Scan proof → Scan challenge QR**. Before network access or consent,
+   the wallet checks the schema and time bounds and pins the audience and every endpoint to a
+   member in its previously configured stack. Scanning a QR never adds a new trusted verifier.
+   The person reviews the configured verifier and programme/country, then approves sharing.
+3. The wallet reads the verifier's lists and checks them against roots from its own chain RPC,
+   builds the proof, and posts `{ requestId, proof, publicInputs }` to `/v1/verify`. A proof
+   discloses time, challenge, audience, programme hash, country code and registry roots. The raw
+   credential, issuer identity and private keys are not sent. The wallet reports **submitted**,
+   not **verified**: only the verifier server's result establishes acceptance.
+4. The verifier uses authenticated `GET /v1/presentation-requests/:id` to obtain `pending`,
+   `expired`, `cancelled`, or `completed` with its stored verification record. This is how a lost
+   wallet HTTP response can be recovered without replaying the proof. Only the original attempt
+   can set this result; replay failures cannot replace a successful verdict. Polling stops on a
+   terminal result, connection error, cancellation or screen exit. **Retry status** queries the
+   same request after a connection error. **New check** creates a fresh challenge.
+5. **Cancel check** or leaving the verifier screen stops waiting and calls authenticated
+   `POST /v1/presentation-requests/:id/cancel`. Cancellation can invalidate an unsubmitted
+   request; once proof submission has claimed it, the server returns 409 and may still record
+   its result. The UI does not claim that an in-flight proof was cancelled.
+
+**Payload and limits.** The proof travels as hex in JSON, not in the QR. The real-proof HTTP E2E
+run measured 14,656 proof bytes, 29,886 JSON bytes and seven public inputs, within the server's
+100 KiB parser limit. Circuit/backend changes must repeat that measurement. The member UI tests
+rasterize the actual native QR Views and decode them with an independent QR decoder, checking
+that the challenge fits and contains no token. The same-phone link tests also check its separate
+2,000-character limit.
+
+**Offline behaviour.** There is no cached-root/offline acceptance. A list/verifier outage produces
+`VERIFIER_UNREACHABLE`; an RPC outage produces `CHAIN_UNREACHABLE` and no proof is submitted.
+A lost proof-POST response is not acceptance or rejection: the verifier checks its own request
+status. A consented no-credential/revoked-credential refusal sends no proof and closes the request
+with that refusal. Denied consent sends nothing; the verifier can cancel or let the request expire. By default requests expire after 300 seconds. After expiry or cancellation, start a new
+check rather than replaying the old proof. Hosted endpoints must use HTTPS; configured LAN HTTP
+is retained for the local demo, where QR contents and network traffic are not confidential.
+
+**Two-phone acceptance for #67.** Configure both phones against the same current Sepolia stack.
+Issue a credential to the holder, display a challenge on the verifier, scan and consent on the
+holder, and confirm that only the verifier shows the matching server verdict. Repeat with denied
+consent, a revoked credential, a stale/unknown-member QR, duplicate scan frames, cancellation,
+verifier/RPC outage, and loss of the wallet response after server acceptance. Never project member
+pairing tokens or record credentials/proofs. Automated UI and local HTTP/Anvil tests cover these
+boundaries, but do not replace physical-camera, secure-hardware and live-Sepolia acceptance.
+
 ### Browser transport
 
-Member apps choose a transport only when constructing the client; all six operations and the rest of
+Member apps choose a transport only when constructing the client; all three operations and the rest of
 their code stay the same when moving between web and mobile:
 
 ```typescript
@@ -135,6 +196,14 @@ await Linking.openURL(responseUrl)
 - **No cross-device support.** Both apps are assumed to be installed on the same phone, communicating through the OS's own URL-scheme routing. There is no pairing, QR handoff, or relay for a user app and member app on different devices.
 - **No responder authentication.** See "Security notes" above: this protocol alone doesn't prove `callback` belongs to the app the user thinks it does.
 
+### Local demo relay
+
+`createRelayWebLinkTransport` requires a private `token` for the running demo session. It sends it
+in the Authorization header for requests, response polls and delivery acknowledgements. The relay
+URL and the public stack descriptor must never carry that token. `browserSessionKey` reads an
+operator pairing fragment or prompt, removes the fragment key and stores it only for that tab and
+service. See the [relay setup](../../apps/integration-testbed/README.md#browser-link-relay-e1--l7).
+
 ## License
 
 MIT, see [`LICENSE`](./LICENSE).

package/dist/index.cjs

@@ -23,6 +23,10 @@ const LINK_ERROR_CODES = [
     "PROOF_FAILED",
     "ISSUER_UNREACHABLE",
     "VERIFIER_UNREACHABLE",
+    /** The credential's issuer key is not among those the chain lists for the member the caller named. */
+    "ISSUER_NOT_APPROVED",
+    /** A chain read that would check the issuer keys or the current roots could not be made, so nothing was issued or proved. */
+    "CHAIN_UNREACHABLE",
     "INTERNAL"
 ];
 
@@ -482,6 +486,23 @@ function createLinkClient(options) {
     };
 }
 
+/** The only error text that leaves the wallet, bar the zod text for malformed params; other detail stays on the device. */
+const LINK_ERROR_MESSAGES = {
+    USER_DENIED: "The person declined the request.",
+    CONSENT_DENIED: "The person declined to share.",
+    UNSUPPORTED_OP: "This wallet does not support that operation.",
+    INVALID_REQUEST: "The request was not valid.",
+    NOT_ONBOARDED: "The wallet has no identity yet.",
+    NO_CREDENTIAL: "No matching credential.",
+    CREDENTIAL_REVOKED: "The matching credential has been revoked.",
+    PROOF_FAILED: "The wallet could not build the proof.",
+    ISSUER_UNREACHABLE: "The wallet could not use the issuer's server.",
+    VERIFIER_UNREACHABLE: "The wallet could not use the verifier's server.",
+    ISSUER_NOT_APPROVED: "The credential's issuer key is not approved on chain.",
+    CHAIN_UNREACHABLE: "The wallet could not read the chain.",
+    INTERNAL: "The wallet failed."
+};
+
 function isLinkOp(op) {
     return LINK_OPS.includes(op);
 }
@@ -489,8 +510,8 @@ function isLinkOp(op) {
 const MAX_RESPONSE_MESSAGE_LENGTH = 256;
 function createRequestHandler(options) {
     const { handlers, consent } = options;
-    function respond(request, code, message) {
-        const cappedMessage = message?.slice(0, MAX_RESPONSE_MESSAGE_LENGTH);
+    function respond(request, code, message = LINK_ERROR_MESSAGES[code]) {
+        const cappedMessage = message.slice(0, MAX_RESPONSE_MESSAGE_LENGTH);
         return encodeResponse(request.callback, {
             id: request.id,
             version: "v1",
@@ -530,7 +551,7 @@ function createRequestHandler(options) {
             }
             catch (error) {
                 if (error instanceof LinkError) {
-                    return respond(request, error.code, error.message);
+                    return respond(request, error.code);
                 }
                 return respond(request, "INTERNAL");
             }
@@ -538,9 +559,83 @@ function createRequestHandler(options) {
     };
 }
 
+const PREFIX = "cn-present:v1:";
+const publicBase = zod.z
+    .string()
+    .regex(/^https?:\/\/[^/?#@\s]+(?:\/[^?#@\s]*)?$/, "Server base must not contain credentials, query or fragment");
+const schema = zod.z
+    .object({
+    params: presentationCreateParamsSchema,
+    expiresAt: zod.z.number().int().positive()
+})
+    .strict();
+/** Public challenge only. No credential, proof, callback or member bearer token crosses devices. */
+function encodePresentationQr(value) {
+    const parsed = schema.parse(value);
+    const { params, expiresAt } = parsed;
+    const base = params.responseUrl.replace(/\/v1\/verify$/, "");
+    if (base === params.responseUrl ||
+        params.issuersUrl !== `${base}/v1/issuers` ||
+        params.revocationsUrl !== `${base}/v1/revocations/snapshot`)
+        throw new Error("Unsupported presentation endpoints");
+    publicBase.parse(base);
+    // Compact keys and one shared endpoint keep the QR readable at phone-screen sizes.
+    const wire = {
+        r: params.requestId,
+        c: params.challenge,
+        a: params.audience,
+        t: params.currentTime,
+        p: params.programme,
+        k: params.country,
+        u: base,
+        e: expiresAt
+    };
+    const encoded = PREFIX + base64UrlEncode(new TextEncoder().encode(JSON.stringify(wire)));
+    if (encoded.length > MAX_URL_LENGTH)
+        throw new Error("Presentation QR is too large");
+    return encoded;
+}
+function decodePresentationQr(raw) {
+    if (!raw.startsWith(PREFIX) || raw.length > MAX_URL_LENGTH)
+        throw new Error("Not a presentation QR");
+    try {
+        const wire = zod.z
+            .object({
+            r: zod.z.string(),
+            c: zod.z.string(),
+            a: zod.z.string(),
+            t: zod.z.number(),
+            p: zod.z.string(),
+            k: zod.z.string(),
+            u: publicBase,
+            e: zod.z.number()
+        })
+            .strict()
+            .parse(JSON.parse(new TextDecoder().decode(base64UrlDecode(raw.slice(PREFIX.length)))));
+        return schema.parse({
+            expiresAt: wire.e,
+            params: {
+                requestId: wire.r,
+                challenge: wire.c,
+                audience: wire.a,
+                currentTime: wire.t,
+                programme: wire.p,
+                country: wire.k,
+                issuersUrl: `${wire.u}/v1/issuers`,
+                revocationsUrl: `${wire.u}/v1/revocations/snapshot`,
+                responseUrl: `${wire.u}/v1/verify`
+            }
+        });
+    }
+    catch {
+        throw new Error("Invalid presentation QR");
+    }
+}
+
 exports.ALLOWED_ENDPOINT_URL_SCHEMES = ALLOWED_ENDPOINT_URL_SCHEMES;
 exports.DENIED_CALLBACK_SCHEMES = DENIED_CALLBACK_SCHEMES;
 exports.LINK_ERROR_CODES = LINK_ERROR_CODES;
+exports.LINK_ERROR_MESSAGES = LINK_ERROR_MESSAGES;
 exports.LINK_OPS = LINK_OPS;
 exports.LinkDecodeError = LinkDecodeError;
 exports.LinkError = LinkError;
@@ -557,8 +652,10 @@ exports.createLinkClient = createLinkClient;
 exports.createRequestHandler = createRequestHandler;
 exports.credentialIssueParamsSchema = credentialIssueParamsSchema;
 exports.credentialIssueResultSchema = credentialIssueResultSchema;
+exports.decodePresentationQr = decodePresentationQr;
 exports.decodeRequest = decodeRequest;
 exports.decodeResponse = decodeResponse;
+exports.encodePresentationQr = encodePresentationQr;
 exports.encodeRequest = encodeRequest;
 exports.encodeResponse = encodeResponse;
 exports.hex20Schema = hex20Schema;

package/dist/index.js

@@ -21,6 +21,10 @@ const LINK_ERROR_CODES = [
     "PROOF_FAILED",
     "ISSUER_UNREACHABLE",
     "VERIFIER_UNREACHABLE",
+    /** The credential's issuer key is not among those the chain lists for the member the caller named. */
+    "ISSUER_NOT_APPROVED",
+    /** A chain read that would check the issuer keys or the current roots could not be made, so nothing was issued or proved. */
+    "CHAIN_UNREACHABLE",
     "INTERNAL"
 ];
 
@@ -480,6 +484,23 @@ function createLinkClient(options) {
     };
 }
 
+/** The only error text that leaves the wallet, bar the zod text for malformed params; other detail stays on the device. */
+const LINK_ERROR_MESSAGES = {
+    USER_DENIED: "The person declined the request.",
+    CONSENT_DENIED: "The person declined to share.",
+    UNSUPPORTED_OP: "This wallet does not support that operation.",
+    INVALID_REQUEST: "The request was not valid.",
+    NOT_ONBOARDED: "The wallet has no identity yet.",
+    NO_CREDENTIAL: "No matching credential.",
+    CREDENTIAL_REVOKED: "The matching credential has been revoked.",
+    PROOF_FAILED: "The wallet could not build the proof.",
+    ISSUER_UNREACHABLE: "The wallet could not use the issuer's server.",
+    VERIFIER_UNREACHABLE: "The wallet could not use the verifier's server.",
+    ISSUER_NOT_APPROVED: "The credential's issuer key is not approved on chain.",
+    CHAIN_UNREACHABLE: "The wallet could not read the chain.",
+    INTERNAL: "The wallet failed."
+};
+
 function isLinkOp(op) {
     return LINK_OPS.includes(op);
 }
@@ -487,8 +508,8 @@ function isLinkOp(op) {
 const MAX_RESPONSE_MESSAGE_LENGTH = 256;
 function createRequestHandler(options) {
     const { handlers, consent } = options;
-    function respond(request, code, message) {
-        const cappedMessage = message?.slice(0, MAX_RESPONSE_MESSAGE_LENGTH);
+    function respond(request, code, message = LINK_ERROR_MESSAGES[code]) {
+        const cappedMessage = message.slice(0, MAX_RESPONSE_MESSAGE_LENGTH);
         return encodeResponse(request.callback, {
             id: request.id,
             version: "v1",
@@ -528,7 +549,7 @@ function createRequestHandler(options) {
             }
             catch (error) {
                 if (error instanceof LinkError) {
-                    return respond(request, error.code, error.message);
+                    return respond(request, error.code);
                 }
                 return respond(request, "INTERNAL");
             }
@@ -536,4 +557,77 @@ function createRequestHandler(options) {
     };
 }
 
-export { ALLOWED_ENDPOINT_URL_SCHEMES, DENIED_CALLBACK_SCHEMES, LINK_ERROR_CODES, LINK_OPS, LinkDecodeError, LinkError, LinkPayloadTooLargeError, MAX_URL_LENGTH, SECURITY_LEVELS, USER_APP_SCHEME, approvalScopeSchema, base64UrlDecode, base64UrlEncode, callbackSchema, callerSchema, createLinkClient, createRequestHandler, credentialIssueParamsSchema, credentialIssueResultSchema, decodeRequest, decodeResponse, encodeRequest, encodeResponse, hex20Schema, hex31Schema, hex32Schema, hex65Schema, hex66Schema, linkErrorCodeSchema, linkRequestEnvelopeSchema, linkRequestSchema, linkResponseSchema, paramsSchemas, presentationCreateParamsSchema, presentationCreateResultSchema, registrationSignParamsSchema, registrationSignResultSchema, resultSchemas, securityLevelSchema, signedRegistrationRequestSchema };
+const PREFIX = "cn-present:v1:";
+const publicBase = z
+    .string()
+    .regex(/^https?:\/\/[^/?#@\s]+(?:\/[^?#@\s]*)?$/, "Server base must not contain credentials, query or fragment");
+const schema = z
+    .object({
+    params: presentationCreateParamsSchema,
+    expiresAt: z.number().int().positive()
+})
+    .strict();
+/** Public challenge only. No credential, proof, callback or member bearer token crosses devices. */
+function encodePresentationQr(value) {
+    const parsed = schema.parse(value);
+    const { params, expiresAt } = parsed;
+    const base = params.responseUrl.replace(/\/v1\/verify$/, "");
+    if (base === params.responseUrl ||
+        params.issuersUrl !== `${base}/v1/issuers` ||
+        params.revocationsUrl !== `${base}/v1/revocations/snapshot`)
+        throw new Error("Unsupported presentation endpoints");
+    publicBase.parse(base);
+    // Compact keys and one shared endpoint keep the QR readable at phone-screen sizes.
+    const wire = {
+        r: params.requestId,
+        c: params.challenge,
+        a: params.audience,
+        t: params.currentTime,
+        p: params.programme,
+        k: params.country,
+        u: base,
+        e: expiresAt
+    };
+    const encoded = PREFIX + base64UrlEncode(new TextEncoder().encode(JSON.stringify(wire)));
+    if (encoded.length > MAX_URL_LENGTH)
+        throw new Error("Presentation QR is too large");
+    return encoded;
+}
+function decodePresentationQr(raw) {
+    if (!raw.startsWith(PREFIX) || raw.length > MAX_URL_LENGTH)
+        throw new Error("Not a presentation QR");
+    try {
+        const wire = z
+            .object({
+            r: z.string(),
+            c: z.string(),
+            a: z.string(),
+            t: z.number(),
+            p: z.string(),
+            k: z.string(),
+            u: publicBase,
+            e: z.number()
+        })
+            .strict()
+            .parse(JSON.parse(new TextDecoder().decode(base64UrlDecode(raw.slice(PREFIX.length)))));
+        return schema.parse({
+            expiresAt: wire.e,
+            params: {
+                requestId: wire.r,
+                challenge: wire.c,
+                audience: wire.a,
+                currentTime: wire.t,
+                programme: wire.p,
+                country: wire.k,
+                issuersUrl: `${wire.u}/v1/issuers`,
+                revocationsUrl: `${wire.u}/v1/revocations/snapshot`,
+                responseUrl: `${wire.u}/v1/verify`
+            }
+        });
+    }
+    catch {
+        throw new Error("Invalid presentation QR");
+    }
+}
+
+export { ALLOWED_ENDPOINT_URL_SCHEMES, DENIED_CALLBACK_SCHEMES, LINK_ERROR_CODES, LINK_ERROR_MESSAGES, LINK_OPS, LinkDecodeError, LinkError, LinkPayloadTooLargeError, MAX_URL_LENGTH, SECURITY_LEVELS, USER_APP_SCHEME, approvalScopeSchema, base64UrlDecode, base64UrlEncode, callbackSchema, callerSchema, createLinkClient, createRequestHandler, credentialIssueParamsSchema, credentialIssueResultSchema, decodePresentationQr, decodeRequest, decodeResponse, encodePresentationQr, encodeRequest, encodeResponse, hex20Schema, hex31Schema, hex32Schema, hex65Schema, hex66Schema, linkErrorCodeSchema, linkRequestEnvelopeSchema, linkRequestSchema, linkResponseSchema, paramsSchemas, presentationCreateParamsSchema, presentationCreateResultSchema, registrationSignParamsSchema, registrationSignResultSchema, resultSchemas, securityLevelSchema, signedRegistrationRequestSchema };

package/dist/web.cjs

@@ -37,6 +37,10 @@ const LINK_ERROR_CODES = [
     "PROOF_FAILED",
     "ISSUER_UNREACHABLE",
     "VERIFIER_UNREACHABLE",
+    /** The credential's issuer key is not among those the chain lists for the member the caller named. */
+    "ISSUER_NOT_APPROVED",
+    /** A chain read that would check the issuer keys or the current roots could not be made, so nothing was issued or proved. */
+    "CHAIN_UNREACHABLE",
     "INTERNAL"
 ];
 
@@ -505,16 +509,36 @@ function createEmbeddedWebLinkTransport(options) {
         }
     };
 }
+/** Reads the private demo key from a pairing fragment or asks the operator once per tab. */
+function browserSessionKey(serviceUrl, host = window, fragmentKey = "relayKey") {
+    const storageKey = `coordination-session-key:${fragmentKey}:${new URL(serviceUrl).origin}`;
+    const current = new URL(host.location.href);
+    const fragment = new URLSearchParams(current.hash.slice(1));
+    const paired = fragment.get(fragmentKey);
+    if (paired !== null) {
+        fragment.delete(fragmentKey);
+        current.hash = fragment.toString();
+        host.history.replaceState(null, "", current.toString());
+    }
+    const token = paired ??
+        host.sessionStorage.getItem(storageKey) ??
+        host.prompt(fragmentKey === "memberKey" ? "Member connection key" : "Demo connection key")?.trim();
+    if (!token || !/^[0-9a-f]{64}$/i.test(token))
+        throw new Error("A demo connection key is required");
+    host.sessionStorage.setItem(storageKey, token);
+    return token;
+}
 /** Carries unchanged link URLs through the local demo relay between independently opened pages. */
 function createRelayWebLinkTransport(options) {
     const fetcher = options.fetcher ?? fetch;
     const relayUrl = new URL(options.relayUrl).origin;
+    const headers = { authorization: `Bearer ${options.token}` };
     let after = 0;
     return {
         async openUrl(url) {
             const response = await fetcher(`${relayUrl}/v1/requests`, {
                 method: "POST",
-                headers: { "content-type": "application/json" },
+                headers: { "content-type": "application/json", ...headers },
                 body: JSON.stringify({ sender: options.sender, url })
             });
             if (!response.ok)
@@ -528,7 +552,7 @@ function createRelayWebLinkTransport(options) {
                     return;
                 polling = true;
                 try {
-                    const response = await fetcher(`${relayUrl}/v1/responses?sender=${encodeURIComponent(options.sender)}&after=${after}`);
+                    const response = await fetcher(`${relayUrl}/v1/responses?sender=${encodeURIComponent(options.sender)}&after=${after}`, { headers });
                     if (!response.ok)
                         return;
                     const messages = (await response.json());
@@ -536,6 +560,9 @@ function createRelayWebLinkTransport(options) {
                         after = Math.max(after, message.seq);
                         listener(message.url);
                     }
+                    if (messages.length > 0) {
+                        await fetcher(`${relayUrl}/v1/responses?sender=${encodeURIComponent(options.sender)}&after=${after}`, { method: "DELETE", headers });
+                    }
                 }
                 catch {
                     // The next poll retries while the local demo stack starts or restarts.
@@ -554,6 +581,7 @@ function createRelayWebLinkTransport(options) {
     };
 }
 
+exports.browserSessionKey = browserSessionKey;
 exports.createEmbeddedWebLinkTransport = createEmbeddedWebLinkTransport;
 exports.createRelayWebLinkTransport = createRelayWebLinkTransport;
 exports.createWebLinkTransport = createWebLinkTransport;

package/dist/web.js

@@ -35,6 +35,10 @@ const LINK_ERROR_CODES = [
     "PROOF_FAILED",
     "ISSUER_UNREACHABLE",
     "VERIFIER_UNREACHABLE",
+    /** The credential's issuer key is not among those the chain lists for the member the caller named. */
+    "ISSUER_NOT_APPROVED",
+    /** A chain read that would check the issuer keys or the current roots could not be made, so nothing was issued or proved. */
+    "CHAIN_UNREACHABLE",
     "INTERNAL"
 ];
 
@@ -503,16 +507,36 @@ function createEmbeddedWebLinkTransport(options) {
         }
     };
 }
+/** Reads the private demo key from a pairing fragment or asks the operator once per tab. */
+function browserSessionKey(serviceUrl, host = window, fragmentKey = "relayKey") {
+    const storageKey = `coordination-session-key:${fragmentKey}:${new URL(serviceUrl).origin}`;
+    const current = new URL(host.location.href);
+    const fragment = new URLSearchParams(current.hash.slice(1));
+    const paired = fragment.get(fragmentKey);
+    if (paired !== null) {
+        fragment.delete(fragmentKey);
+        current.hash = fragment.toString();
+        host.history.replaceState(null, "", current.toString());
+    }
+    const token = paired ??
+        host.sessionStorage.getItem(storageKey) ??
+        host.prompt(fragmentKey === "memberKey" ? "Member connection key" : "Demo connection key")?.trim();
+    if (!token || !/^[0-9a-f]{64}$/i.test(token))
+        throw new Error("A demo connection key is required");
+    host.sessionStorage.setItem(storageKey, token);
+    return token;
+}
 /** Carries unchanged link URLs through the local demo relay between independently opened pages. */
 function createRelayWebLinkTransport(options) {
     const fetcher = options.fetcher ?? fetch;
     const relayUrl = new URL(options.relayUrl).origin;
+    const headers = { authorization: `Bearer ${options.token}` };
     let after = 0;
     return {
         async openUrl(url) {
             const response = await fetcher(`${relayUrl}/v1/requests`, {
                 method: "POST",
-                headers: { "content-type": "application/json" },
+                headers: { "content-type": "application/json", ...headers },
                 body: JSON.stringify({ sender: options.sender, url })
             });
             if (!response.ok)
@@ -526,7 +550,7 @@ function createRelayWebLinkTransport(options) {
                     return;
                 polling = true;
                 try {
-                    const response = await fetcher(`${relayUrl}/v1/responses?sender=${encodeURIComponent(options.sender)}&after=${after}`);
+                    const response = await fetcher(`${relayUrl}/v1/responses?sender=${encodeURIComponent(options.sender)}&after=${after}`, { headers });
                     if (!response.ok)
                         return;
                     const messages = (await response.json());
@@ -534,6 +558,9 @@ function createRelayWebLinkTransport(options) {
                         after = Math.max(after, message.seq);
                         listener(message.url);
                     }
+                    if (messages.length > 0) {
+                        await fetcher(`${relayUrl}/v1/responses?sender=${encodeURIComponent(options.sender)}&after=${after}`, { method: "DELETE", headers });
+                    }
                 }
                 catch {
                     // The next poll retries while the local demo stack starts or restarts.
@@ -552,4 +579,4 @@ function createRelayWebLinkTransport(options) {
     };
 }
 
-export { createEmbeddedWebLinkTransport, createRelayWebLinkTransport, createWebLinkTransport, respondToWebLinkRequest };
+export { browserSessionKey, createEmbeddedWebLinkTransport, createRelayWebLinkTransport, createWebLinkTransport, respondToWebLinkRequest };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coordination-network/user-app-link",
-  "version": "0.0.2",
+  "version": "0.1.0",
   "description": "Deep-link protocol between the user app (keys, credentials, proving) and network member apps on the same device.",
   "license": "MIT",
   "repository": {

package/src/handler.ts

@@ -1,5 +1,6 @@
 import { decodeRequest, encodeResponse } from "./codec"
 import { LinkError } from "./errors"
+import { LINK_ERROR_MESSAGES } from "./messages"
 import { paramsSchemas, resultSchemas } from "./schemas"
 import {
     LINK_OPS,
@@ -38,8 +39,12 @@ type AnyLinkHandler = (params: unknown, context: { caller: Caller }) => Promise<
 export function createRequestHandler(options: RequestHandlerOptions): RequestHandler {
     const { handlers, consent } = options
 
-    function respond(request: DecodedLinkRequest, code: LinkErrorCode, message?: string): string {
-        const cappedMessage = message?.slice(0, MAX_RESPONSE_MESSAGE_LENGTH)
+    function respond(
+        request: DecodedLinkRequest,
+        code: LinkErrorCode,
+        message: string = LINK_ERROR_MESSAGES[code]
+    ): string {
+        const cappedMessage = message.slice(0, MAX_RESPONSE_MESSAGE_LENGTH)
         return encodeResponse(request.callback, {
             id: request.id,
             version: "v1",
@@ -86,7 +91,7 @@ export function createRequestHandler(options: RequestHandlerOptions): RequestHan
                 return encodeResponse(request.callback, response)
             } catch (error) {
                 if (error instanceof LinkError) {
-                    return respond(request, error.code, error.message)
+                    return respond(request, error.code)
                 }
                 return respond(request, "INTERNAL")
             }

package/src/index.ts

@@ -4,3 +4,5 @@ export * from "./errors"
 export * from "./codec"
 export * from "./client"
 export * from "./handler"
+export * from "./messages"
+export * from "./presentation-qr"

package/src/messages.ts

@@ -0,0 +1,18 @@
+import type { LinkErrorCode } from "./types"
+
+/** The only error text that leaves the wallet, bar the zod text for malformed params; other detail stays on the device. */
+export const LINK_ERROR_MESSAGES: Record<LinkErrorCode, string> = {
+    USER_DENIED: "The person declined the request.",
+    CONSENT_DENIED: "The person declined to share.",
+    UNSUPPORTED_OP: "This wallet does not support that operation.",
+    INVALID_REQUEST: "The request was not valid.",
+    NOT_ONBOARDED: "The wallet has no identity yet.",
+    NO_CREDENTIAL: "No matching credential.",
+    CREDENTIAL_REVOKED: "The matching credential has been revoked.",
+    PROOF_FAILED: "The wallet could not build the proof.",
+    ISSUER_UNREACHABLE: "The wallet could not use the issuer's server.",
+    VERIFIER_UNREACHABLE: "The wallet could not use the verifier's server.",
+    ISSUER_NOT_APPROVED: "The credential's issuer key is not approved on chain.",
+    CHAIN_UNREACHABLE: "The wallet could not read the chain.",
+    INTERNAL: "The wallet failed."
+}

package/src/presentation-qr.ts

@@ -0,0 +1,79 @@
+import { z } from "zod"
+import { base64UrlDecode, base64UrlEncode, MAX_URL_LENGTH } from "./codec"
+import { presentationCreateParamsSchema } from "./schemas"
+
+const PREFIX = "cn-present:v1:"
+const publicBase = z
+    .string()
+    .regex(/^https?:\/\/[^/?#@\s]+(?:\/[^?#@\s]*)?$/, "Server base must not contain credentials, query or fragment")
+const schema = z
+    .object({
+        params: presentationCreateParamsSchema,
+        expiresAt: z.number().int().positive()
+    })
+    .strict()
+
+export type PresentationQr = z.infer<typeof schema>
+
+/** Public challenge only. No credential, proof, callback or member bearer token crosses devices. */
+export function encodePresentationQr(value: PresentationQr): string {
+    const parsed = schema.parse(value)
+    const { params, expiresAt } = parsed
+    const base = params.responseUrl.replace(/\/v1\/verify$/, "")
+    if (
+        base === params.responseUrl ||
+        params.issuersUrl !== `${base}/v1/issuers` ||
+        params.revocationsUrl !== `${base}/v1/revocations/snapshot`
+    )
+        throw new Error("Unsupported presentation endpoints")
+    publicBase.parse(base)
+    // Compact keys and one shared endpoint keep the QR readable at phone-screen sizes.
+    const wire = {
+        r: params.requestId,
+        c: params.challenge,
+        a: params.audience,
+        t: params.currentTime,
+        p: params.programme,
+        k: params.country,
+        u: base,
+        e: expiresAt
+    }
+    const encoded = PREFIX + base64UrlEncode(new TextEncoder().encode(JSON.stringify(wire)))
+    if (encoded.length > MAX_URL_LENGTH) throw new Error("Presentation QR is too large")
+    return encoded
+}
+
+export function decodePresentationQr(raw: string): PresentationQr {
+    if (!raw.startsWith(PREFIX) || raw.length > MAX_URL_LENGTH) throw new Error("Not a presentation QR")
+    try {
+        const wire = z
+            .object({
+                r: z.string(),
+                c: z.string(),
+                a: z.string(),
+                t: z.number(),
+                p: z.string(),
+                k: z.string(),
+                u: publicBase,
+                e: z.number()
+            })
+            .strict()
+            .parse(JSON.parse(new TextDecoder().decode(base64UrlDecode(raw.slice(PREFIX.length)))))
+        return schema.parse({
+            expiresAt: wire.e,
+            params: {
+                requestId: wire.r,
+                challenge: wire.c,
+                audience: wire.a,
+                currentTime: wire.t,
+                programme: wire.p,
+                country: wire.k,
+                issuersUrl: `${wire.u}/v1/issuers`,
+                revocationsUrl: `${wire.u}/v1/revocations/snapshot`,
+                responseUrl: `${wire.u}/v1/verify`
+            }
+        })
+    } catch {
+        throw new Error("Invalid presentation QR")
+    }
+}

package/src/types.ts

@@ -160,6 +160,10 @@ export const LINK_ERROR_CODES = [
     "PROOF_FAILED",
     "ISSUER_UNREACHABLE",
     "VERIFIER_UNREACHABLE",
+    /** The credential's issuer key is not among those the chain lists for the member the caller named. */
+    "ISSUER_NOT_APPROVED",
+    /** A chain read that would check the issuer keys or the current roots could not be made, so nothing was issued or proved. */
+    "CHAIN_UNREACHABLE",
     "INTERNAL"
 ] as const
 

package/src/web.ts

@@ -271,7 +271,29 @@ export function createEmbeddedWebLinkTransport(options: EmbeddedWebLinkTransport
     }
 }
 
+/** Reads the private demo key from a pairing fragment or asks the operator once per tab. */
+export function browserSessionKey(serviceUrl: string, host: Window = window, fragmentKey = "relayKey"): string {
+    const storageKey = `coordination-session-key:${fragmentKey}:${new URL(serviceUrl).origin}`
+    const current = new URL(host.location.href)
+    const fragment = new URLSearchParams(current.hash.slice(1))
+    const paired = fragment.get(fragmentKey)
+    if (paired !== null) {
+        fragment.delete(fragmentKey)
+        current.hash = fragment.toString()
+        host.history.replaceState(null, "", current.toString())
+    }
+    const token =
+        paired ??
+        host.sessionStorage.getItem(storageKey) ??
+        host.prompt(fragmentKey === "memberKey" ? "Member connection key" : "Demo connection key")?.trim()
+    if (!token || !/^[0-9a-f]{64}$/i.test(token)) throw new Error("A demo connection key is required")
+    host.sessionStorage.setItem(storageKey, token)
+    return token
+}
+
 export interface RelayWebLinkTransportOptions {
+    /** Private key for this demo relay session; never put it in stack.json. */
+    token: string
     relayUrl: string
     sender: string
     pollIntervalMs?: number
@@ -284,12 +306,13 @@ export function createRelayWebLinkTransport(
 ): Pick<LinkClientOptions, "openUrl" | "onUrl"> {
     const fetcher = options.fetcher ?? fetch
     const relayUrl = new URL(options.relayUrl).origin
+    const headers = { authorization: `Bearer ${options.token}` }
     let after = 0
     return {
         async openUrl(url) {
             const response = await fetcher(`${relayUrl}/v1/requests`, {
                 method: "POST",
-                headers: { "content-type": "application/json" },
+                headers: { "content-type": "application/json", ...headers },
                 body: JSON.stringify({ sender: options.sender, url })
             })
             if (!response.ok) throw new Error("wallet request could not be delivered")
@@ -302,7 +325,8 @@ export function createRelayWebLinkTransport(
                 polling = true
                 try {
                     const response = await fetcher(
-                        `${relayUrl}/v1/responses?sender=${encodeURIComponent(options.sender)}&after=${after}`
+                        `${relayUrl}/v1/responses?sender=${encodeURIComponent(options.sender)}&after=${after}`,
+                        { headers }
                     )
                     if (!response.ok) return
                     const messages = (await response.json()) as Array<{ seq: number; url: string }>
@@ -310,6 +334,12 @@ export function createRelayWebLinkTransport(
                         after = Math.max(after, message.seq)
                         listener(message.url)
                     }
+                    if (messages.length > 0) {
+                        await fetcher(
+                            `${relayUrl}/v1/responses?sender=${encodeURIComponent(options.sender)}&after=${after}`,
+                            { method: "DELETE", headers }
+                        )
+                    }
                 } catch {
                     // The next poll retries while the local demo stack starts or restarts.
                 } finally {

package/types/index.d.ts

@@ -139,7 +139,7 @@ interface DecodedLinkRequest {
     op: string;
     params: unknown;
 }
-declare const LINK_ERROR_CODES: readonly ["USER_DENIED", "CONSENT_DENIED", "UNSUPPORTED_OP", "INVALID_REQUEST", "NOT_ONBOARDED", "NO_CREDENTIAL", "CREDENTIAL_REVOKED", "PROOF_FAILED", "ISSUER_UNREACHABLE", "VERIFIER_UNREACHABLE", "INTERNAL"];
+declare const LINK_ERROR_CODES: readonly ["USER_DENIED", "CONSENT_DENIED", "UNSUPPORTED_OP", "INVALID_REQUEST", "NOT_ONBOARDED", "NO_CREDENTIAL", "CREDENTIAL_REVOKED", "PROOF_FAILED", "ISSUER_UNREACHABLE", "VERIFIER_UNREACHABLE", "ISSUER_NOT_APPROVED", "CHAIN_UNREACHABLE", "INTERNAL"];
 type LinkErrorCode = (typeof LINK_ERROR_CODES)[number];
 /** The response envelope. Unlike the request, it carries no `op`: the caller already knows which op it asked for. */
 type LinkResponse<Op extends LinkOp = LinkOp> = (Op extends LinkOp ? {
@@ -348,6 +348,8 @@ declare const linkErrorCodeSchema: z.ZodEnum<{
     PROOF_FAILED: "PROOF_FAILED";
     ISSUER_UNREACHABLE: "ISSUER_UNREACHABLE";
     VERIFIER_UNREACHABLE: "VERIFIER_UNREACHABLE";
+    ISSUER_NOT_APPROVED: "ISSUER_NOT_APPROVED";
+    CHAIN_UNREACHABLE: "CHAIN_UNREACHABLE";
     INTERNAL: "INTERNAL";
 }>;
 declare const linkResponseSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
@@ -370,6 +372,8 @@ declare const linkResponseSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
         PROOF_FAILED: "PROOF_FAILED";
         ISSUER_UNREACHABLE: "ISSUER_UNREACHABLE";
         VERIFIER_UNREACHABLE: "VERIFIER_UNREACHABLE";
+        ISSUER_NOT_APPROVED: "ISSUER_NOT_APPROVED";
+        CHAIN_UNREACHABLE: "CHAIN_UNREACHABLE";
         INTERNAL: "INTERNAL";
     }>;
     message: z.ZodOptional<z.ZodString>;
@@ -436,5 +440,27 @@ interface RequestHandler {
 }
 declare function createRequestHandler(options: RequestHandlerOptions): RequestHandler;
 
-export { ALLOWED_ENDPOINT_URL_SCHEMES, DENIED_CALLBACK_SCHEMES, LINK_ERROR_CODES, LINK_OPS, LinkDecodeError, LinkError, LinkPayloadTooLargeError, MAX_URL_LENGTH, SECURITY_LEVELS, USER_APP_SCHEME, approvalScopeSchema, base64UrlDecode, base64UrlEncode, callbackSchema, callerSchema, createLinkClient, createRequestHandler, credentialIssueParamsSchema, credentialIssueResultSchema, decodeRequest, decodeResponse, encodeRequest, encodeResponse, hex20Schema, hex31Schema, hex32Schema, hex65Schema, hex66Schema, linkErrorCodeSchema, linkRequestEnvelopeSchema, linkRequestSchema, linkResponseSchema, paramsSchemas, presentationCreateParamsSchema, presentationCreateResultSchema, registrationSignParamsSchema, registrationSignResultSchema, resultSchemas, securityLevelSchema, signedRegistrationRequestSchema };
-export type { ApprovalScope, Caller, CredentialIssueParams, CredentialIssueResult, DecodedLinkRequest, Hex, Hex20, Hex31, Hex32, Hex65, Hex66, Jwk, LinkClient, LinkClientOptions, LinkErrorCode, LinkHandlers, LinkOp, LinkOpMap, LinkRequest, LinkResponse, Params, PresentationCreateParams, PresentationCreateResult, RegistrationSignParams, RegistrationSignResult, RequestHandler, RequestHandlerOptions, Result, SecurityLevel, SignedRegistrationRequest };
+/** The only error text that leaves the wallet, bar the zod text for malformed params; other detail stays on the device. */
+declare const LINK_ERROR_MESSAGES: Record<LinkErrorCode, string>;
+
+declare const schema: z.ZodObject<{
+    params: z.ZodObject<{
+        requestId: z.ZodString;
+        challenge: z.ZodPipe<z.ZodString, z.ZodTransform<`0x${string}`, string>>;
+        audience: z.ZodString;
+        currentTime: z.ZodNumber;
+        programme: z.ZodString;
+        country: z.ZodString;
+        issuersUrl: z.ZodString;
+        revocationsUrl: z.ZodString;
+        responseUrl: z.ZodString;
+    }, z.core.$strict>;
+    expiresAt: z.ZodNumber;
+}, z.core.$strict>;
+type PresentationQr = z.infer<typeof schema>;
+/** Public challenge only. No credential, proof, callback or member bearer token crosses devices. */
+declare function encodePresentationQr(value: PresentationQr): string;
+declare function decodePresentationQr(raw: string): PresentationQr;
+
+export { ALLOWED_ENDPOINT_URL_SCHEMES, DENIED_CALLBACK_SCHEMES, LINK_ERROR_CODES, LINK_ERROR_MESSAGES, LINK_OPS, LinkDecodeError, LinkError, LinkPayloadTooLargeError, MAX_URL_LENGTH, SECURITY_LEVELS, USER_APP_SCHEME, approvalScopeSchema, base64UrlDecode, base64UrlEncode, callbackSchema, callerSchema, createLinkClient, createRequestHandler, credentialIssueParamsSchema, credentialIssueResultSchema, decodePresentationQr, decodeRequest, decodeResponse, encodePresentationQr, encodeRequest, encodeResponse, hex20Schema, hex31Schema, hex32Schema, hex65Schema, hex66Schema, linkErrorCodeSchema, linkRequestEnvelopeSchema, linkRequestSchema, linkResponseSchema, paramsSchemas, presentationCreateParamsSchema, presentationCreateResultSchema, registrationSignParamsSchema, registrationSignResultSchema, resultSchemas, securityLevelSchema, signedRegistrationRequestSchema };
+export type { ApprovalScope, Caller, CredentialIssueParams, CredentialIssueResult, DecodedLinkRequest, Hex, Hex20, Hex31, Hex32, Hex65, Hex66, Jwk, LinkClient, LinkClientOptions, LinkErrorCode, LinkHandlers, LinkOp, LinkOpMap, LinkRequest, LinkResponse, Params, PresentationCreateParams, PresentationCreateResult, PresentationQr, RegistrationSignParams, RegistrationSignResult, RequestHandler, RequestHandlerOptions, Result, SecurityLevel, SignedRegistrationRequest };

package/types/web.d.ts

@@ -68,7 +68,11 @@ interface EmbeddedWebLinkTransportOptions {
 }
 /** Carries the browser protocol through an in-page iframe, avoiding popup-blocker behavior. */
 declare function createEmbeddedWebLinkTransport(options: EmbeddedWebLinkTransportOptions): WebLinkTransport;
+/** Reads the private demo key from a pairing fragment or asks the operator once per tab. */
+declare function browserSessionKey(serviceUrl: string, host?: Window, fragmentKey?: string): string;
 interface RelayWebLinkTransportOptions {
+    /** Private key for this demo relay session; never put it in stack.json. */
+    token: string;
     relayUrl: string;
     sender: string;
     pollIntervalMs?: number;
@@ -77,5 +81,5 @@ interface RelayWebLinkTransportOptions {
 /** Carries unchanged link URLs through the local demo relay between independently opened pages. */
 declare function createRelayWebLinkTransport(options: RelayWebLinkTransportOptions): Pick<LinkClientOptions, "openUrl" | "onUrl">;
 
-export { createEmbeddedWebLinkTransport, createRelayWebLinkTransport, createWebLinkTransport, respondToWebLinkRequest };
+export { browserSessionKey, createEmbeddedWebLinkTransport, createRelayWebLinkTransport, createWebLinkTransport, respondToWebLinkRequest };
 export type { EmbeddedWebLinkTransportOptions, RelayWebLinkTransportOptions, WebLinkResponderOptions, WebLinkTransport, WebLinkTransportOptions };