@coordination-network/user-app-link 0.0.1

package/dist/index.js

@@ -0,0 +1,539 @@
+import { z } from 'zod';
+
+/** Protocol v1 types for the user-app <-> network-member-app deep link. */
+/** Where the user app's device key lives in the platform's key hierarchy. */
+const SECURITY_LEVELS = ["STRONGBOX", "TRUSTED_ENVIRONMENT", "SOFTWARE", "UNKNOWN"];
+const LINK_OPS = [
+    "registration.sign",
+    "credential.issue",
+    "presentation.create"
+];
+const LINK_ERROR_CODES = [
+    "USER_DENIED",
+    /** Declined at the share step, after the proof was built and the person saw what it reveals. */
+    "CONSENT_DENIED",
+    "UNSUPPORTED_OP",
+    "INVALID_REQUEST",
+    "NOT_ONBOARDED",
+    "NO_CREDENTIAL",
+    /** A credential for this programme and country is held, but its issuer has revoked it. */
+    "CREDENTIAL_REVOKED",
+    "PROOF_FAILED",
+    "ISSUER_UNREACHABLE",
+    "VERIFIER_UNREACHABLE",
+    "INTERNAL"
+];
+
+/**
+ * A response must stay on-device, in a custom app scheme: `http(s)` would let it leave the device
+ * entirely, and Android additionally resolves `intent`/`file`/`content`/`javascript`/`data` to
+ * behavior beyond opening another app (launching an arbitrary component, reading a local file, or
+ * running script), none of which this protocol's `callback` is meant to reach.
+ *
+ * The browser schemes map straight onto `http(s)://host/path` - `googlechrome://evil/cb` fetches
+ * `http://evil/cb` - so they defeat the rule exactly as `https` would. This list cannot be
+ * exhaustive: any installed app may register a scheme that proxies to the network, and nothing in
+ * the string says so. Closing it properly needs the signed response envelope and a consent screen
+ * showing the resolved callback, both already tracked as follow-ups.
+ */
+const DENIED_CALLBACK_SCHEMES = [
+    "http",
+    "https",
+    "intent",
+    "file",
+    "content",
+    "javascript",
+    "data",
+    "googlechrome",
+    "googlechromes",
+    "x-safari-http",
+    "x-safari-https",
+    "microsoft-edge-http",
+    "microsoft-edge-https",
+    "firefox",
+    "ftp",
+    "ws",
+    "wss"
+];
+/**
+ * These fields name server endpoints the app itself fetches or posts to, arriving from an
+ * unauthenticated deep-link caller - an allowlist has no unknown-scheme bypass to worry about.
+ * TODO: production should require https only; that belongs in configuration, not this schema.
+ */
+const ALLOWED_ENDPOINT_URL_SCHEMES = ["http", "https"];
+/** `encodeResponse` always appends its own `?payload=` to `callback`, so a `?`/`#` already in it would bury or hide that parameter and leave the client waiting until timeout instead of ever decoding a response. */
+const callbackSchema = z
+    .string()
+    .regex(/^[a-z][a-z0-9+.-]*:\/\/[^\s?#]+$/i, "must be an absolute URL with no query string or fragment")
+    .refine((value) => !DENIED_CALLBACK_SCHEMES.includes(value.slice(0, value.indexOf(":")).toLowerCase()), {
+    message: `scheme must not be one of: ${DENIED_CALLBACK_SCHEMES.join(", ")}`
+});
+/** No `z.string().url()`: it relies on the global `URL` class, which Hermes/React Native lack without a polyfill. */
+const urlLikeSchema = z
+    .string()
+    .regex(/^[a-z][a-z0-9+.-]*:\/\/\S+$/i, "must be an absolute URL")
+    .refine((value) => ALLOWED_ENDPOINT_URL_SCHEMES.includes(value.slice(0, value.indexOf(":")).toLowerCase()), {
+    message: `scheme must be one of: ${ALLOWED_ENDPOINT_URL_SCHEMES.join(", ")}`
+});
+const hexOfLength = (byteLength) => z
+    .string()
+    .regex(new RegExp(`^0x[0-9a-fA-F]{${byteLength * 2}}$`), `must be ${byteLength}-byte 0x-prefixed hex`)
+    .transform((value) => value.toLowerCase());
+const hex20Schema = hexOfLength(20);
+const hex31Schema = hexOfLength(31);
+const hex32Schema = hexOfLength(32);
+const hex65Schema = hexOfLength(65);
+const hex66Schema = hexOfLength(66);
+const securityLevelSchema = z.enum(["STRONGBOX", "TRUSTED_ENVIRONMENT", "SOFTWARE", "UNKNOWN"]);
+/**
+ * `name` and `programme` are both rendered verbatim, on their own line and interpolated into a
+ * caption sentence the wallet wrote, so an unbounded or unclean value is a caller reshaping
+ * content it doesn't author: past the limit its text crowds the wallet's own closing sentence out
+ * of the three-line clip, and a control, formatting, or line/paragraph-separator character can
+ * hide text or relayout the line, as a bidi override does.
+ */
+const sentenceSafeTextSchema = (maxLength) => z
+    .string()
+    .min(1)
+    .max(maxLength)
+    .regex(/^[^\p{Cc}\p{Cf}\p{Zl}\p{Zp}]*$/u, "must not contain control, formatting or line-break characters");
+const callerSchema = z
+    .object({
+    name: sentenceSafeTextSchema(64),
+    scheme: z.string().min(1)
+})
+    .strict();
+const approvalScopeSchema = z
+    .object({ programme: sentenceSafeTextSchema(64), country: z.string().regex(/^[A-Z]{3}$/, "ISO 3166-1 alpha-3") })
+    .strict();
+const registrationSignParamsSchema = z
+    .object({ chainId: z.number().int().positive(), verifyingContract: hex20Schema })
+    .strict();
+const signedRegistrationRequestSchema = z
+    .object({
+    version: z.literal("v1"),
+    networkId: hex32Schema,
+    schemeId: z.literal(1),
+    metaStealthAddress: hex66Schema,
+    chainId: z.number().int().positive(),
+    verifyingContract: hex20Schema,
+    signature: hex65Schema
+})
+    .strict();
+const registrationSignResultSchema = z
+    .object({ request: signedRegistrationRequestSchema, securityLevel: securityLevelSchema })
+    .strict();
+/** Scheme, host and port, as `urlLikeSchema` guarantees them: everything before the path. No
+ *  `new URL` here either, for the same Hermes reason. */
+function originOf(url) {
+    const pathStart = url.indexOf("/", url.indexOf("://") + 3);
+    return (pathStart === -1 ? url : url.slice(0, pathStart)).toLowerCase();
+}
+/** The four URLs are one server's, so they must say so. The wallet stores `revocationsUrl` for the
+ *  credential's life and shows it once, at issuance, as the issuer's server: split origins would
+ *  let a caller drive a genuine issuance while pointing every later revocation read at itself. */
+const sameOriginEndpoints = ["credentialsUrl", "issuersUrl", "revocationsUrl"];
+const credentialIssueParamsSchema = z
+    .object({
+    issuerNetworkId: hex32Schema,
+    approvalScope: approvalScopeSchema,
+    challengeUrl: urlLikeSchema,
+    credentialsUrl: urlLikeSchema,
+    issuersUrl: urlLikeSchema,
+    revocationsUrl: urlLikeSchema
+})
+    .strict()
+    .superRefine((params, ctx) => {
+    const origin = originOf(params.challengeUrl);
+    for (const field of sameOriginEndpoints) {
+        if (originOf(params[field]) !== origin) {
+            ctx.addIssue({
+                code: "custom",
+                path: [field],
+                message: `${field} must be on the same origin as challengeUrl (${origin})`
+            });
+        }
+    }
+});
+const credentialIssueResultSchema = z.discriminatedUnion("status", [
+    z.object({ status: z.literal("stored"), credentialId: z.string().min(1) }).strict(),
+    z.object({ status: z.literal("alreadyHeld"), credentialId: z.string().min(1) }).strict(),
+    z.object({ status: z.literal("refused"), code: z.string().min(1), message: z.string() }).strict()
+]);
+const presentationCreateParamsSchema = z
+    .object({
+    requestId: z.string().min(1).max(128),
+    challenge: hex31Schema,
+    audience: z.string().min(1),
+    currentTime: z.number().int().nonnegative(),
+    programme: sentenceSafeTextSchema(64),
+    country: z.string().regex(/^[A-Z]{3}$/, "ISO 3166-1 alpha-3"),
+    issuersUrl: urlLikeSchema,
+    revocationsUrl: urlLikeSchema,
+    responseUrl: urlLikeSchema
+})
+    .strict()
+    .superRefine((params, ctx) => {
+    // The verifier serves all three, and it is the party that must accept the roots the proof
+    // carries. A split origin would let it send the wallet to read somebody else's tree.
+    const origin = originOf(params.responseUrl);
+    for (const field of ["issuersUrl", "revocationsUrl"]) {
+        if (originOf(params[field]) !== origin) {
+            ctx.addIssue({
+                code: "custom",
+                path: [field],
+                message: `${field} must be on the same origin as responseUrl (${origin})`
+            });
+        }
+    }
+});
+const presentationCreateResultSchema = z.object({ verificationId: z.string().min(1) }).strict();
+/** Looked up by the decoded `op` string, so the same schema can be resolved dynamically at runtime. */
+const paramsSchemas = {
+    "registration.sign": registrationSignParamsSchema,
+    "credential.issue": credentialIssueParamsSchema,
+    "presentation.create": presentationCreateParamsSchema
+};
+const resultSchemas = {
+    "registration.sign": registrationSignResultSchema,
+    "credential.issue": credentialIssueResultSchema,
+    "presentation.create": presentationCreateResultSchema
+};
+/** Envelope only: `op`/`params` stay unvalidated because a request that fails those checks still needs a usable `id`/`callback` to answer with an `ok: false` response. */
+const linkRequestEnvelopeSchema = z
+    .object({
+    id: z.string().min(1),
+    version: z.literal("v1"),
+    caller: callerSchema,
+    callback: callbackSchema,
+    op: z.string().min(1),
+    params: z.unknown()
+})
+    .strict();
+const requestEnvelopeFields = {
+    id: z.string().min(1),
+    version: z.literal("v1"),
+    caller: callerSchema,
+    callback: callbackSchema
+};
+/** Written out per op rather than mapped from `LINK_OPS`: `z.discriminatedUnion` needs each branch's literal `op` at the type level, which a `z.ZodTypeAny`-typed loop erases. */
+const linkRequestSchema = z.discriminatedUnion("op", [
+    z
+        .object({ ...requestEnvelopeFields, op: z.literal("registration.sign"), params: registrationSignParamsSchema })
+        .strict(),
+    z
+        .object({ ...requestEnvelopeFields, op: z.literal("credential.issue"), params: credentialIssueParamsSchema })
+        .strict(),
+    z
+        .object({
+        ...requestEnvelopeFields,
+        op: z.literal("presentation.create"),
+        params: presentationCreateParamsSchema
+    })
+        .strict()
+]);
+const linkErrorCodeSchema = z.enum(LINK_ERROR_CODES);
+const linkResponseSchema = z.discriminatedUnion("ok", [
+    z.object({ id: z.string().min(1), version: z.literal("v1"), ok: z.literal(true), result: z.unknown() }).strict(),
+    z
+        .object({
+        id: z.string().min(1),
+        version: z.literal("v1"),
+        ok: z.literal(false),
+        code: linkErrorCodeSchema,
+        message: z.string().optional()
+    })
+        .strict()
+]);
+
+/** A link-protocol failure, discriminated by the same `code` a wire `{ ok: false }` response carries. */
+class LinkError extends Error {
+    constructor(code, message) {
+        super(message ?? code);
+        this.name = "LinkError";
+        this.code = code;
+    }
+}
+/** Thrown by encodeRequest/encodeResponse when the built URL exceeds MAX_URL_LENGTH. */
+class LinkPayloadTooLargeError extends LinkError {
+    constructor(message) {
+        super("INVALID_REQUEST", message);
+        this.name = "LinkPayloadTooLargeError";
+    }
+}
+/**
+ * Thrown by decodeRequest/decodeResponse when a URL can't be decoded into a well-formed v1
+ * envelope - the only failure this package ever throws rather than turning into an `ok: false`
+ * response, because without a valid `id`/`callback` there is nowhere to send that response.
+ */
+class LinkDecodeError extends LinkError {
+    constructor(message) {
+        super("INVALID_REQUEST", message);
+        this.name = "LinkDecodeError";
+    }
+}
+
+const USER_APP_SCHEME = "userapp";
+/** Above this, a platform's `Linking.openURL` (and some OSes) start truncating or refusing the URL. */
+const MAX_URL_LENGTH = 2000;
+/** Encodes bytes with the base64url alphabet (RFC 4648 §5), unpadded. No Node `Buffer`: `atob`/`btoa` only. */
+function base64UrlEncode(bytes) {
+    let binary = "";
+    for (const byte of bytes) {
+        binary += String.fromCharCode(byte);
+    }
+    return globalThis.btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+function base64UrlDecode(value) {
+    const base64 = value.replace(/-/g, "+").replace(/_/g, "/");
+    const padded = base64.padEnd(base64.length + ((4 - (base64.length % 4)) % 4), "=");
+    const binary = globalThis.atob(padded);
+    const bytes = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i += 1) {
+        bytes[i] = binary.charCodeAt(i);
+    }
+    return bytes;
+}
+function encodePayload(value) {
+    return base64UrlEncode(new TextEncoder().encode(JSON.stringify(value)));
+}
+function decodePayload(payload) {
+    try {
+        return JSON.parse(new TextDecoder().decode(base64UrlDecode(payload)));
+    }
+    catch {
+        throw new LinkDecodeError("payload is not valid base64url-encoded JSON");
+    }
+}
+function checkUrlLength(url) {
+    if (url.length > MAX_URL_LENGTH) {
+        throw new LinkPayloadTooLargeError(`link URL is ${url.length} characters, over the ${MAX_URL_LENGTH} limit`);
+    }
+}
+/**
+ * Reads a query parameter by hand rather than via the `URL`/`URLSearchParams` globals, which
+ * Hermes (React Native's JS engine) doesn't provide without a polyfill.
+ */
+function getQueryParam(url, key) {
+    const queryIndex = url.indexOf("?");
+    if (queryIndex === -1) {
+        return null;
+    }
+    for (const pair of url.slice(queryIndex + 1).split("&")) {
+        const [rawKey, rawValue = ""] = pair.split("=");
+        if (decodeURIComponent(rawKey) === key) {
+            return decodeURIComponent(rawValue);
+        }
+    }
+    return null;
+}
+function encodeRequest(request, options = {}) {
+    const scheme = options.scheme ?? USER_APP_SCHEME;
+    // The request URL is built as `${scheme}://...`, so a `?`/`#` in scheme would corrupt it the
+    // same way a bad callback corrupts the response URL below.
+    if (scheme.includes("?") || scheme.includes("#")) {
+        throw new LinkError("INVALID_REQUEST", "scheme must not contain a query string or fragment");
+    }
+    if (DENIED_CALLBACK_SCHEMES.includes(scheme.toLowerCase())) {
+        throw new LinkError("INVALID_REQUEST", `scheme must not be one of: ${DENIED_CALLBACK_SCHEMES.join(", ")}`);
+    }
+    const parsedCaller = callerSchema.safeParse(request.caller);
+    if (!parsedCaller.success) {
+        // Otherwise a caller decodeRequest's own callerSchema would refuse (too long a name, say)
+        // gets a URL the user app can't decode, and the member app just waits out its own timeout.
+        throw new LinkError("INVALID_REQUEST", `caller ${parsedCaller.error.issues[0].message}`);
+    }
+    const parsedCallback = callbackSchema.safeParse(request.callback);
+    if (!parsedCallback.success) {
+        // Surfaces callbackSchema's own issue message so a denied scheme and a query
+        // string/fragment report distinct reasons instead of one hardcoded message for both.
+        throw new LinkError("INVALID_REQUEST", `callback ${parsedCallback.error.issues[0].message}`);
+    }
+    const url = `${scheme}://v1/request?payload=${encodePayload(request)}`;
+    checkUrlLength(url);
+    return url;
+}
+function decodeRequest(url) {
+    const payload = getQueryParam(url, "payload");
+    if (payload === null) {
+        throw new LinkDecodeError("link URL is missing the payload query parameter");
+    }
+    const parsed = linkRequestEnvelopeSchema.safeParse(decodePayload(payload));
+    if (!parsed.success) {
+        throw new LinkDecodeError(`malformed request payload: ${parsed.error.message}`);
+    }
+    return parsed.data;
+}
+function encodeResponse(callback, response) {
+    const url = `${callback}?payload=${encodePayload(response)}`;
+    checkUrlLength(url);
+    return url;
+}
+function decodeResponse(url) {
+    const payload = getQueryParam(url, "payload");
+    if (payload === null) {
+        throw new LinkDecodeError("link URL is missing the payload query parameter");
+    }
+    const parsed = linkResponseSchema.safeParse(decodePayload(payload));
+    if (!parsed.success) {
+        throw new LinkDecodeError(`malformed response payload: ${parsed.error.message}`);
+    }
+    // The envelope carries no `op`, so the schema can only prove `result` is present, not which
+    // op's shape it has - the caller (client.ts) knows that from the id it matches the response to.
+    return parsed.data;
+}
+
+const DEFAULT_TIMEOUT_MS = 120000;
+function defaultRandomId() {
+    const cryptoObj = globalThis.crypto;
+    if (typeof cryptoObj?.randomUUID === "function") {
+        return cryptoObj.randomUUID();
+    }
+    const bytes = new Uint8Array(16);
+    cryptoObj.getRandomValues(bytes);
+    bytes[6] = (bytes[6] & 0x0f) | 0x40;
+    bytes[8] = (bytes[8] & 0x3f) | 0x80;
+    const hex = Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join("");
+    return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+}
+/** One member-app-side client per callback URL: exactly one request in flight, matched by id. */
+function createLinkClient(options) {
+    const randomId = options.randomId ?? defaultRandomId;
+    const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    let pending = null;
+    // Handles a stray/duplicate/unrelated URL (pending already cleared, or some other deep link)
+    // by returning early; every other exit clears `pending` itself rather than sharing a "settle"
+    // helper, since by the time those exits run they already hold their own non-null references.
+    function handleUrl(url) {
+        if (!pending) {
+            return;
+        }
+        let response;
+        try {
+            response = decodeResponse(url);
+        }
+        catch {
+            return; // Not a response this client understands - some other deep link, ignore it.
+        }
+        if (response.id !== pending.id) {
+            return; // A response to a different (already-settled or stale) request.
+        }
+        const { op, resolve, reject, timer, unsubscribe } = pending;
+        pending = null;
+        clearTimeout(timer);
+        unsubscribe();
+        if (response.ok) {
+            // Mirrors handler.ts's own check on the responder side: a result that decoded fine but
+            // has the wrong shape for its op is a responder bug, not a transport glitch.
+            const parsedResult = resultSchemas[op].safeParse(response.result);
+            if (parsedResult.success) {
+                resolve(parsedResult.data);
+            }
+            else {
+                reject(new LinkError("INTERNAL", `response result failed its schema: ${parsedResult.error.message}`));
+            }
+        }
+        else {
+            reject(new LinkError(response.code, response.message));
+        }
+    }
+    return {
+        request(op, params) {
+            if (pending) {
+                return Promise.reject(new Error("createLinkClient: a request is already in flight"));
+            }
+            return new Promise((resolve, reject) => {
+                // randomId/encodeRequest can throw (a caller-supplied randomId, a callback failing
+                // its own schema, an oversized payload); thrown here, before resolve/reject has
+                // been called, it rejects this promise automatically instead of escaping request()
+                // as a synchronous throw.
+                const id = randomId();
+                // op and params are correlated by this call's own Op, but a deferred conditional
+                // type like LinkRequest<Op> doesn't resolve for an unsubstituted generic - assert
+                // it here.
+                const request = {
+                    id,
+                    version: "v1",
+                    caller: options.caller,
+                    callback: options.callback,
+                    op,
+                    params
+                };
+                const url = encodeRequest(request, { scheme: options.scheme });
+                const unsubscribe = options.onUrl(handleUrl);
+                const timer = setTimeout(() => {
+                    pending = null;
+                    unsubscribe();
+                    reject(new Error(`createLinkClient: request timed out after ${timeoutMs}ms`));
+                }, timeoutMs);
+                // resolve only ever receives this call's own response, matched by id in handleUrl above;
+                // the cast to `(result: unknown) => void` just erases that per-call Op for storage below.
+                pending = { id, op, resolve: resolve, reject, unsubscribe, timer };
+                options.openUrl(url).catch((error) => {
+                    pending = null;
+                    clearTimeout(timer);
+                    unsubscribe();
+                    reject(error);
+                });
+            });
+        }
+    };
+}
+
+function isLinkOp(op) {
+    return LINK_OPS.includes(op);
+}
+/** A zod error can name every unrecognized key in a params object, easily blowing the response URL's budget. */
+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);
+        return encodeResponse(request.callback, {
+            id: request.id,
+            version: "v1",
+            ok: false,
+            code,
+            message: cappedMessage
+        });
+    }
+    return {
+        async handle(url) {
+            const request = decodeRequest(url);
+            if (!isLinkOp(request.op)) {
+                return respond(request, "UNSUPPORTED_OP");
+            }
+            const handler = handlers[request.op];
+            if (!handler) {
+                return respond(request, "UNSUPPORTED_OP");
+            }
+            const parsedParams = paramsSchemas[request.op].safeParse(request.params);
+            if (!parsedParams.success) {
+                return respond(request, "INVALID_REQUEST", parsedParams.error.message);
+            }
+            if (!(await consent(request))) {
+                return respond(request, "USER_DENIED");
+            }
+            try {
+                const result = await handler(parsedParams.data, { caller: request.caller });
+                // A handler's return type isn't checked against Result<Op> at compile time
+                // (AnyLinkHandler erased that), so a wrong shape here is a bug in this app's own
+                // handler, not the caller's fault - report it as INTERNAL, not INVALID_REQUEST.
+                const parsedResult = resultSchemas[request.op].safeParse(result);
+                if (!parsedResult.success) {
+                    return respond(request, "INTERNAL");
+                }
+                const response = { id: request.id, version: "v1", ok: true, result: parsedResult.data };
+                return encodeResponse(request.callback, response);
+            }
+            catch (error) {
+                if (error instanceof LinkError) {
+                    return respond(request, error.code, error.message);
+                }
+                return respond(request, "INTERNAL");
+            }
+        }
+    };
+}
+
+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 };