@coordination-network/user-app-link 0.0.1

package/dist/web.cjs

@@ -0,0 +1,560 @@
+'use strict';
+
+var zod = require('zod');
+
+/** 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 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";
+    }
+}
+
+/** 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 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 = zod.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 = zod.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) => zod.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 = zod.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) => zod.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 = zod.z
+    .object({
+    name: sentenceSafeTextSchema(64),
+    scheme: zod.z.string().min(1)
+})
+    .strict();
+const approvalScopeSchema = zod.z
+    .object({ programme: sentenceSafeTextSchema(64), country: zod.z.string().regex(/^[A-Z]{3}$/, "ISO 3166-1 alpha-3") })
+    .strict();
+const registrationSignParamsSchema = zod.z
+    .object({ chainId: zod.z.number().int().positive(), verifyingContract: hex20Schema })
+    .strict();
+const signedRegistrationRequestSchema = zod.z
+    .object({
+    version: zod.z.literal("v1"),
+    networkId: hex32Schema,
+    schemeId: zod.z.literal(1),
+    metaStealthAddress: hex66Schema,
+    chainId: zod.z.number().int().positive(),
+    verifyingContract: hex20Schema,
+    signature: hex65Schema
+})
+    .strict();
+zod.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 = zod.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})`
+            });
+        }
+    }
+});
+zod.z.discriminatedUnion("status", [
+    zod.z.object({ status: zod.z.literal("stored"), credentialId: zod.z.string().min(1) }).strict(),
+    zod.z.object({ status: zod.z.literal("alreadyHeld"), credentialId: zod.z.string().min(1) }).strict(),
+    zod.z.object({ status: zod.z.literal("refused"), code: zod.z.string().min(1), message: zod.z.string() }).strict()
+]);
+const presentationCreateParamsSchema = zod.z
+    .object({
+    requestId: zod.z.string().min(1).max(128),
+    challenge: hex31Schema,
+    audience: zod.z.string().min(1),
+    currentTime: zod.z.number().int().nonnegative(),
+    programme: sentenceSafeTextSchema(64),
+    country: zod.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})`
+            });
+        }
+    }
+});
+zod.z.object({ verificationId: zod.z.string().min(1) }).strict();
+/** 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 = zod.z
+    .object({
+    id: zod.z.string().min(1),
+    version: zod.z.literal("v1"),
+    caller: callerSchema,
+    callback: callbackSchema,
+    op: zod.z.string().min(1),
+    params: zod.z.unknown()
+})
+    .strict();
+const requestEnvelopeFields = {
+    id: zod.z.string().min(1),
+    version: zod.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. */
+zod.z.discriminatedUnion("op", [
+    zod.z
+        .object({ ...requestEnvelopeFields, op: zod.z.literal("registration.sign"), params: registrationSignParamsSchema })
+        .strict(),
+    zod.z
+        .object({ ...requestEnvelopeFields, op: zod.z.literal("credential.issue"), params: credentialIssueParamsSchema })
+        .strict(),
+    zod.z
+        .object({
+        ...requestEnvelopeFields,
+        op: zod.z.literal("presentation.create"),
+        params: presentationCreateParamsSchema
+    })
+        .strict()
+]);
+const linkErrorCodeSchema = zod.z.enum(LINK_ERROR_CODES);
+zod.z.discriminatedUnion("ok", [
+    zod.z.object({ id: zod.z.string().min(1), version: zod.z.literal("v1"), ok: zod.z.literal(true), result: zod.z.unknown() }).strict(),
+    zod.z
+        .object({
+        id: zod.z.string().min(1),
+        version: zod.z.literal("v1"),
+        ok: zod.z.literal(false),
+        code: linkErrorCodeSchema,
+        message: zod.z.string().optional()
+    })
+        .strict()
+]);
+
+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 decodePayload(payload) {
+    try {
+        return JSON.parse(new TextDecoder().decode(base64UrlDecode(payload)));
+    }
+    catch {
+        throw new LinkDecodeError("payload is not valid base64url-encoded JSON");
+    }
+}
+/**
+ * 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 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;
+}
+
+const DEFAULT_CLOSE_POLL_INTERVAL_MS = 100;
+const DEFAULT_HANDSHAKE_TIMEOUT_MS = 5000;
+const READY_MESSAGE = "coordination-network:user-app-ready:v1";
+const HELLO_MESSAGE = "coordination-network:member-app-hello:v1";
+function normalizedOrigin(value, option) {
+    let origin;
+    try {
+        origin = new URL(value).origin;
+    }
+    catch {
+        throw new Error(`${option} must be an absolute browser URL`);
+    }
+    if (origin === "null") {
+        throw new Error(`${option} must have an http or https origin`);
+    }
+    return origin;
+}
+/**
+ * Supplies the two transport functions consumed by `createLinkClient`. The protocol request stays
+ * unchanged; only its query string is carried to the browser user app instead of a mobile scheme.
+ */
+function createWebLinkTransport(options) {
+    const host = options.window ?? window;
+    const userAppOrigin = normalizedOrigin(options.userAppOrigin, "userAppOrigin");
+    const popupUrl = new URL(options.userAppUrl);
+    if (popupUrl.origin !== userAppOrigin) {
+        throw new Error("userAppUrl must belong to userAppOrigin");
+    }
+    let popup = null;
+    let listener = null;
+    let closeTimer = null;
+    let finishOpen = null;
+    let failOpen = null;
+    let closedAt = null;
+    function clearCloseTimer() {
+        if (closeTimer !== null) {
+            clearInterval(closeTimer);
+            closeTimer = null;
+        }
+    }
+    function handleMessage(event) {
+        if (!popup || event.source !== popup || event.origin !== userAppOrigin) {
+            return;
+        }
+        if (event.data === READY_MESSAGE) {
+            popup.postMessage(HELLO_MESSAGE, userAppOrigin);
+            return;
+        }
+        if (typeof event.data !== "string")
+            return;
+        const resolve = finishOpen;
+        finishOpen = null;
+        failOpen = null;
+        clearCloseTimer();
+        resolve?.();
+        listener?.(event.data);
+    }
+    return {
+        prepare() {
+            if (popup && !popup.closed)
+                return;
+            popup = host.open(popupUrl.toString(), options.popupName ?? "coordination-user-app", options.popupFeatures);
+        },
+        close() {
+            popup?.close();
+            popup = null;
+            const fail = failOpen;
+            finishOpen = null;
+            failOpen = null;
+            clearCloseTimer();
+            fail?.(new Error("user app popup closed before responding"));
+        },
+        onUrl(nextListener) {
+            listener = nextListener;
+            host.addEventListener("message", handleMessage);
+            return () => {
+                host.removeEventListener("message", handleMessage);
+                listener = null;
+                clearCloseTimer();
+                finishOpen?.();
+                finishOpen = null;
+                failOpen = null;
+            };
+        },
+        openUrl(requestUrl) {
+            const queryIndex = requestUrl.indexOf("?");
+            if (queryIndex === -1) {
+                return Promise.reject(new Error("browser link request is missing its encoded query"));
+            }
+            const destination = new URL(popupUrl.toString());
+            destination.search = requestUrl.slice(queryIndex);
+            if (popup && !popup.closed) {
+                popup.location.href = destination.toString();
+            }
+            else {
+                popup = host.open(destination.toString(), options.popupName ?? "coordination-user-app", options.popupFeatures);
+            }
+            if (!popup) {
+                return Promise.reject(new Error("user app popup was blocked"));
+            }
+            closedAt = null;
+            return new Promise((resolve, reject) => {
+                finishOpen = resolve;
+                failOpen = reject;
+                closeTimer = setInterval(() => {
+                    if (!popup?.closed)
+                        return;
+                    closedAt ?? (closedAt = Date.now());
+                    if (Date.now() - closedAt < (options.closeGracePeriodMs ?? 250))
+                        return;
+                    const fail = failOpen;
+                    finishOpen = null;
+                    failOpen = null;
+                    clearCloseTimer();
+                    fail?.(new Error("user app popup closed before responding"));
+                }, options.closePollIntervalMs ?? DEFAULT_CLOSE_POLL_INTERVAL_MS);
+            });
+        }
+    };
+}
+function authenticateMemberApp(host, recipient, allowedMemberOrigins, timeoutMs) {
+    return new Promise((resolve, reject) => {
+        const cleanup = () => {
+            clearTimeout(timer);
+            host.removeEventListener("message", handleMessage);
+        };
+        const handleMessage = (event) => {
+            if (event.source !== recipient || event.data !== HELLO_MESSAGE || !allowedMemberOrigins.has(event.origin))
+                return;
+            cleanup();
+            resolve(event.origin);
+        };
+        const timer = setTimeout(() => {
+            cleanup();
+            reject(new Error("member app origin handshake timed out"));
+        }, timeoutMs);
+        host.addEventListener("message", handleMessage);
+        recipient.postMessage(READY_MESSAGE, "*");
+    });
+}
+/** Authenticates the opener, dispatches the request, and posts the response to its verified origin. */
+async function respondToWebLinkRequest(options) {
+    const host = options.window ?? window;
+    const recipient = host.opener ?? (host.parent !== host ? host.parent : null);
+    if (!recipient)
+        throw new Error("user app was not opened or embedded by a member app");
+    try {
+        const allowedMemberOrigins = new Set(options.allowedMemberOrigins.map((origin) => normalizedOrigin(origin, "allowedMemberOrigins")));
+        if (allowedMemberOrigins.size === 0)
+            throw new Error("allowedMemberOrigins must not be empty");
+        const memberAppOrigin = await authenticateMemberApp(host, recipient, allowedMemberOrigins, options.handshakeTimeoutMs ?? DEFAULT_HANDSHAKE_TIMEOUT_MS);
+        const request = decodeRequest(host.location.href);
+        if (normalizedOrigin(request.caller.scheme, "caller.scheme") !== memberAppOrigin) {
+            throw new Error("request caller does not match the authenticated member app origin");
+        }
+        const response = await options.handler.handle(host.location.href);
+        recipient.postMessage(response, memberAppOrigin);
+        // Give the queued postMessage a task to reach the opener before closing the popup.
+        await new Promise((resolve) => setTimeout(resolve, 0));
+    }
+    finally {
+        if (host.opener && (options.closeAfterResponding ?? true))
+            host.close();
+    }
+}
+/** Carries the browser protocol through an in-page iframe, avoiding popup-blocker behavior. */
+function createEmbeddedWebLinkTransport(options) {
+    const host = options.window ?? window;
+    const userAppOrigin = normalizedOrigin(options.userAppOrigin, "userAppOrigin");
+    const userAppUrl = new URL(options.userAppUrl);
+    if (userAppUrl.origin !== userAppOrigin)
+        throw new Error("userAppUrl must belong to userAppOrigin");
+    let listener = null;
+    const handleMessage = (event) => {
+        if (event.origin !== userAppOrigin || event.source !== options.frame.contentWindow)
+            return;
+        if (event.data === READY_MESSAGE) {
+            options.frame.contentWindow?.postMessage(HELLO_MESSAGE, userAppOrigin);
+            return;
+        }
+        if (typeof event.data !== "string")
+            return;
+        listener?.(event.data);
+    };
+    return {
+        prepare() { },
+        close() {
+            options.frame.src = "about:blank";
+        },
+        onUrl(nextListener) {
+            listener = nextListener;
+            host.addEventListener("message", handleMessage);
+            return () => {
+                listener = null;
+                host.removeEventListener("message", handleMessage);
+            };
+        },
+        async openUrl(requestUrl) {
+            const queryIndex = requestUrl.indexOf("?");
+            if (queryIndex === -1)
+                throw new Error("browser link request is missing its encoded query");
+            const destination = new URL(userAppUrl);
+            destination.search = requestUrl.slice(queryIndex);
+            options.frame.src = destination.toString();
+        }
+    };
+}
+/** 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;
+    let after = 0;
+    return {
+        async openUrl(url) {
+            const response = await fetcher(`${relayUrl}/v1/requests`, {
+                method: "POST",
+                headers: { "content-type": "application/json" },
+                body: JSON.stringify({ sender: options.sender, url })
+            });
+            if (!response.ok)
+                throw new Error("wallet request could not be delivered");
+        },
+        onUrl(listener) {
+            let active = true;
+            let polling = false;
+            const poll = async () => {
+                if (!active || polling)
+                    return;
+                polling = true;
+                try {
+                    const response = await fetcher(`${relayUrl}/v1/responses?sender=${encodeURIComponent(options.sender)}&after=${after}`);
+                    if (!response.ok)
+                        return;
+                    const messages = (await response.json());
+                    for (const message of messages) {
+                        after = Math.max(after, message.seq);
+                        listener(message.url);
+                    }
+                }
+                catch {
+                    // The next poll retries while the local demo stack starts or restarts.
+                }
+                finally {
+                    polling = false;
+                }
+            };
+            void poll();
+            const timer = setInterval(() => void poll(), options.pollIntervalMs ?? 500);
+            return () => {
+                active = false;
+                clearInterval(timer);
+            };
+        }
+    };
+}
+
+exports.createEmbeddedWebLinkTransport = createEmbeddedWebLinkTransport;
+exports.createRelayWebLinkTransport = createRelayWebLinkTransport;
+exports.createWebLinkTransport = createWebLinkTransport;
+exports.respondToWebLinkRequest = respondToWebLinkRequest;