@coordination-network/user-app-link 0.0.1

package/types/index.d.ts

@@ -0,0 +1,440 @@
+import { z } from 'zod';
+
+/** Protocol v1 types for the user-app <-> network-member-app deep link. */
+/** A `0x`-prefixed lowercase hexadecimal string. Byte-length aliases below are documentation only. */
+type Hex = `0x${string}`;
+/** A 20-byte address, e.g. `verifyingContract`. */
+type Hex20 = Hex;
+/** A 31-byte value, sized to fit under the BN254 scalar field for in-circuit use. */
+type Hex31 = Hex;
+/** A 32-byte value, e.g. a `networkId`. */
+type Hex32 = Hex;
+/** A 65-byte uncompressed secp256k1 public key, or a 65-byte signature with a recovery byte. */
+type Hex65 = Hex;
+/** A 66-byte ERC-6538 meta-stealth address (33-byte compressed spending key || 33-byte compressed viewing key). */
+type Hex66 = Hex;
+/** An EC public key in JWK form (RFC 7517). This protocol uses P-256 only. */
+interface Jwk {
+    kty: "EC";
+    crv: "P-256";
+    x: string;
+    y: string;
+}
+/** Where the user app's device key lives in the platform's key hierarchy. */
+declare const SECURITY_LEVELS: readonly ["STRONGBOX", "TRUSTED_ENVIRONMENT", "SOFTWARE", "UNKNOWN"];
+type SecurityLevel = (typeof SECURITY_LEVELS)[number];
+/** Identifies the member app making a request, as declared by that app (not verified by the OS). */
+interface Caller {
+    name: string;
+    scheme: string;
+}
+interface ApprovalScope {
+    programme: string;
+    country: string;
+}
+interface RegistrationSignParams {
+    chainId: number;
+    verifyingContract: Hex20;
+}
+/** Mirrors `RegistrationRequest` from `@coordination-network/user-client`, redeclared to avoid a cross-package dependency. */
+interface SignedRegistrationRequest {
+    version: "v1";
+    networkId: Hex32;
+    schemeId: 1;
+    metaStealthAddress: Hex66;
+    chainId: number;
+    verifyingContract: Hex20;
+    signature: Hex65;
+}
+/**
+ * `request` is posted to the member server verbatim. `securityLevel` rides along because
+ * registration is the one op every member app runs first, and it is the only thing a member needs
+ * about the wallet that the request itself does not already carry.
+ */
+interface RegistrationSignResult {
+    request: SignedRegistrationRequest;
+    securityLevel: SecurityLevel;
+}
+/**
+ * The wallet drives the whole issuance itself from these four endpoints, so a member app hands
+ * over the URLs rather than relaying each hop.
+ */
+interface CredentialIssueParams {
+    issuerNetworkId: Hex32;
+    approvalScope: ApprovalScope;
+    challengeUrl: string;
+    credentialsUrl: string;
+    /** The issuer's approved-issuer set, which the wallet checks the credential against before storing. */
+    issuersUrl: string;
+    /** The issuer's revocation snapshot, checked in the same step. */
+    revocationsUrl: string;
+}
+/**
+ * `refused` is the issuer server declining to issue, in its own error vocabulary — not a
+ * {@link LinkErrorCode}. A wallet-side failure throws instead.
+ */
+type CredentialIssueResult = {
+    status: "stored";
+    credentialId: string;
+} | {
+    status: "alreadyHeld";
+    credentialId: string;
+} | {
+    status: "refused";
+    code: string;
+    message: string;
+};
+interface PresentationCreateParams {
+    /** From the member server's `POST /v1/presentation-requests`; echoed back in the `/v1/verify` POST. */
+    requestId: string;
+    challenge: Hex31;
+    audience: string;
+    currentTime: number;
+    programme: string;
+    country: string;
+    issuersUrl: string;
+    /** One network-wide tree, so any member serves the same one; the verifier's is the one whose
+     *  root it will accept. */
+    revocationsUrl: string;
+    responseUrl: string;
+}
+/** The verifier records the outcome under this id; the caller reads it from its own server. */
+interface PresentationCreateResult {
+    verificationId: string;
+}
+/** Every op this protocol version defines, mapped to its params and result shapes. */
+interface LinkOpMap {
+    "registration.sign": {
+        params: RegistrationSignParams;
+        result: RegistrationSignResult;
+    };
+    "credential.issue": {
+        params: CredentialIssueParams;
+        result: CredentialIssueResult;
+    };
+    "presentation.create": {
+        params: PresentationCreateParams;
+        result: PresentationCreateResult;
+    };
+}
+declare const LINK_OPS: readonly ["registration.sign", "credential.issue", "presentation.create"];
+type LinkOp = (typeof LINK_OPS)[number];
+type Params<Op extends LinkOp> = LinkOpMap[Op]["params"];
+type Result<Op extends LinkOp> = LinkOpMap[Op]["result"];
+/** Distributive conditional: without it, `LinkRequest` (Op defaulting to `LinkOp`) would let any op pair with any op's params instead of only its own. */
+type LinkRequest<Op extends LinkOp = LinkOp> = Op extends LinkOp ? {
+    id: string;
+    version: "v1";
+    caller: Caller;
+    callback: string;
+    op: Op;
+    params: Params<Op>;
+} : never;
+/** A request whose envelope decoded successfully but whose `op`/`params` are not yet validated against a schema. */
+interface DecodedLinkRequest {
+    id: string;
+    version: "v1";
+    caller: Caller;
+    callback: string;
+    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"];
+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 ? {
+    id: string;
+    version: "v1";
+    ok: true;
+    result: Result<Op>;
+} : never) | {
+    id: string;
+    version: "v1";
+    ok: false;
+    code: LinkErrorCode;
+    message?: string;
+};
+/** The handlers a user app registers with {@link createRequestHandler}, one per op it supports. */
+type LinkHandlers = {
+    [Op in LinkOp]?: (params: Params<Op>, context: {
+        caller: Caller;
+    }) => Promise<Result<Op>>;
+};
+
+/**
+ * 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.
+ */
+declare const DENIED_CALLBACK_SCHEMES: readonly ["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.
+ */
+declare const ALLOWED_ENDPOINT_URL_SCHEMES: readonly ["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. */
+declare const callbackSchema: z.ZodString;
+declare const hex20Schema: z.ZodPipe<z.ZodString, z.ZodTransform<`0x${string}`, string>>;
+declare const hex31Schema: z.ZodPipe<z.ZodString, z.ZodTransform<`0x${string}`, string>>;
+declare const hex32Schema: z.ZodPipe<z.ZodString, z.ZodTransform<`0x${string}`, string>>;
+declare const hex65Schema: z.ZodPipe<z.ZodString, z.ZodTransform<`0x${string}`, string>>;
+declare const hex66Schema: z.ZodPipe<z.ZodString, z.ZodTransform<`0x${string}`, string>>;
+declare const securityLevelSchema: z.ZodEnum<{
+    STRONGBOX: "STRONGBOX";
+    TRUSTED_ENVIRONMENT: "TRUSTED_ENVIRONMENT";
+    SOFTWARE: "SOFTWARE";
+    UNKNOWN: "UNKNOWN";
+}>;
+declare const callerSchema: z.ZodObject<{
+    name: z.ZodString;
+    scheme: z.ZodString;
+}, z.core.$strict>;
+declare const approvalScopeSchema: z.ZodObject<{
+    programme: z.ZodString;
+    country: z.ZodString;
+}, z.core.$strict>;
+declare const registrationSignParamsSchema: z.ZodObject<{
+    chainId: z.ZodNumber;
+    verifyingContract: z.ZodPipe<z.ZodString, z.ZodTransform<`0x${string}`, string>>;
+}, z.core.$strict>;
+declare const signedRegistrationRequestSchema: z.ZodObject<{
+    version: z.ZodLiteral<"v1">;
+    networkId: z.ZodPipe<z.ZodString, z.ZodTransform<`0x${string}`, string>>;
+    schemeId: z.ZodLiteral<1>;
+    metaStealthAddress: z.ZodPipe<z.ZodString, z.ZodTransform<`0x${string}`, string>>;
+    chainId: z.ZodNumber;
+    verifyingContract: z.ZodPipe<z.ZodString, z.ZodTransform<`0x${string}`, string>>;
+    signature: z.ZodPipe<z.ZodString, z.ZodTransform<`0x${string}`, string>>;
+}, z.core.$strict>;
+declare const registrationSignResultSchema: z.ZodObject<{
+    request: z.ZodObject<{
+        version: z.ZodLiteral<"v1">;
+        networkId: z.ZodPipe<z.ZodString, z.ZodTransform<`0x${string}`, string>>;
+        schemeId: z.ZodLiteral<1>;
+        metaStealthAddress: z.ZodPipe<z.ZodString, z.ZodTransform<`0x${string}`, string>>;
+        chainId: z.ZodNumber;
+        verifyingContract: z.ZodPipe<z.ZodString, z.ZodTransform<`0x${string}`, string>>;
+        signature: z.ZodPipe<z.ZodString, z.ZodTransform<`0x${string}`, string>>;
+    }, z.core.$strict>;
+    securityLevel: z.ZodEnum<{
+        STRONGBOX: "STRONGBOX";
+        TRUSTED_ENVIRONMENT: "TRUSTED_ENVIRONMENT";
+        SOFTWARE: "SOFTWARE";
+        UNKNOWN: "UNKNOWN";
+    }>;
+}, z.core.$strict>;
+declare const credentialIssueParamsSchema: z.ZodObject<{
+    issuerNetworkId: z.ZodPipe<z.ZodString, z.ZodTransform<`0x${string}`, string>>;
+    approvalScope: z.ZodObject<{
+        programme: z.ZodString;
+        country: z.ZodString;
+    }, z.core.$strict>;
+    challengeUrl: z.ZodString;
+    credentialsUrl: z.ZodString;
+    issuersUrl: z.ZodString;
+    revocationsUrl: z.ZodString;
+}, z.core.$strict>;
+declare const credentialIssueResultSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    status: z.ZodLiteral<"stored">;
+    credentialId: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    status: z.ZodLiteral<"alreadyHeld">;
+    credentialId: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    status: z.ZodLiteral<"refused">;
+    code: z.ZodString;
+    message: z.ZodString;
+}, z.core.$strict>], "status">;
+declare const presentationCreateParamsSchema: 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>;
+declare const presentationCreateResultSchema: z.ZodObject<{
+    verificationId: z.ZodString;
+}, z.core.$strict>;
+/** Looked up by the decoded `op` string, so the same schema can be resolved dynamically at runtime. */
+declare const paramsSchemas: Record<LinkOp, z.ZodTypeAny>;
+declare const resultSchemas: Record<LinkOp, z.ZodTypeAny>;
+/** 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. */
+declare const linkRequestEnvelopeSchema: z.ZodObject<{
+    id: z.ZodString;
+    version: z.ZodLiteral<"v1">;
+    caller: z.ZodObject<{
+        name: z.ZodString;
+        scheme: z.ZodString;
+    }, z.core.$strict>;
+    callback: z.ZodString;
+    op: z.ZodString;
+    params: z.ZodUnknown;
+}, z.core.$strict>;
+/** 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. */
+declare const linkRequestSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    op: z.ZodLiteral<"registration.sign">;
+    params: z.ZodObject<{
+        chainId: z.ZodNumber;
+        verifyingContract: z.ZodPipe<z.ZodString, z.ZodTransform<`0x${string}`, string>>;
+    }, z.core.$strict>;
+    id: z.ZodString;
+    version: z.ZodLiteral<"v1">;
+    caller: z.ZodObject<{
+        name: z.ZodString;
+        scheme: z.ZodString;
+    }, z.core.$strict>;
+    callback: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    op: z.ZodLiteral<"credential.issue">;
+    params: z.ZodObject<{
+        issuerNetworkId: z.ZodPipe<z.ZodString, z.ZodTransform<`0x${string}`, string>>;
+        approvalScope: z.ZodObject<{
+            programme: z.ZodString;
+            country: z.ZodString;
+        }, z.core.$strict>;
+        challengeUrl: z.ZodString;
+        credentialsUrl: z.ZodString;
+        issuersUrl: z.ZodString;
+        revocationsUrl: z.ZodString;
+    }, z.core.$strict>;
+    id: z.ZodString;
+    version: z.ZodLiteral<"v1">;
+    caller: z.ZodObject<{
+        name: z.ZodString;
+        scheme: z.ZodString;
+    }, z.core.$strict>;
+    callback: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    op: z.ZodLiteral<"presentation.create">;
+    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>;
+    id: z.ZodString;
+    version: z.ZodLiteral<"v1">;
+    caller: z.ZodObject<{
+        name: z.ZodString;
+        scheme: z.ZodString;
+    }, z.core.$strict>;
+    callback: z.ZodString;
+}, z.core.$strict>], "op">;
+declare const linkErrorCodeSchema: z.ZodEnum<{
+    USER_DENIED: "USER_DENIED";
+    CONSENT_DENIED: "CONSENT_DENIED";
+    UNSUPPORTED_OP: "UNSUPPORTED_OP";
+    INVALID_REQUEST: "INVALID_REQUEST";
+    NOT_ONBOARDED: "NOT_ONBOARDED";
+    NO_CREDENTIAL: "NO_CREDENTIAL";
+    CREDENTIAL_REVOKED: "CREDENTIAL_REVOKED";
+    PROOF_FAILED: "PROOF_FAILED";
+    ISSUER_UNREACHABLE: "ISSUER_UNREACHABLE";
+    VERIFIER_UNREACHABLE: "VERIFIER_UNREACHABLE";
+    INTERNAL: "INTERNAL";
+}>;
+declare const linkResponseSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    id: z.ZodString;
+    version: z.ZodLiteral<"v1">;
+    ok: z.ZodLiteral<true>;
+    result: z.ZodUnknown;
+}, z.core.$strict>, z.ZodObject<{
+    id: z.ZodString;
+    version: z.ZodLiteral<"v1">;
+    ok: z.ZodLiteral<false>;
+    code: z.ZodEnum<{
+        USER_DENIED: "USER_DENIED";
+        CONSENT_DENIED: "CONSENT_DENIED";
+        UNSUPPORTED_OP: "UNSUPPORTED_OP";
+        INVALID_REQUEST: "INVALID_REQUEST";
+        NOT_ONBOARDED: "NOT_ONBOARDED";
+        NO_CREDENTIAL: "NO_CREDENTIAL";
+        CREDENTIAL_REVOKED: "CREDENTIAL_REVOKED";
+        PROOF_FAILED: "PROOF_FAILED";
+        ISSUER_UNREACHABLE: "ISSUER_UNREACHABLE";
+        VERIFIER_UNREACHABLE: "VERIFIER_UNREACHABLE";
+        INTERNAL: "INTERNAL";
+    }>;
+    message: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>], "ok">;
+
+/** A link-protocol failure, discriminated by the same `code` a wire `{ ok: false }` response carries. */
+declare class LinkError extends Error {
+    readonly code: LinkErrorCode;
+    constructor(code: LinkErrorCode, message?: string);
+}
+/** Thrown by encodeRequest/encodeResponse when the built URL exceeds MAX_URL_LENGTH. */
+declare class LinkPayloadTooLargeError extends LinkError {
+    constructor(message: string);
+}
+/**
+ * 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.
+ */
+declare class LinkDecodeError extends LinkError {
+    constructor(message: string);
+}
+
+declare const USER_APP_SCHEME = "userapp";
+/** Above this, a platform's `Linking.openURL` (and some OSes) start truncating or refusing the URL. */
+declare const MAX_URL_LENGTH = 2000;
+/** Encodes bytes with the base64url alphabet (RFC 4648 §5), unpadded. No Node `Buffer`: `atob`/`btoa` only. */
+declare function base64UrlEncode(bytes: Uint8Array): string;
+declare function base64UrlDecode(value: string): Uint8Array;
+declare function encodeRequest<Op extends LinkOp>(request: LinkRequest<Op>, options?: {
+    scheme?: string;
+}): string;
+declare function decodeRequest(url: string): DecodedLinkRequest;
+declare function encodeResponse<Op extends LinkOp>(callback: string, response: LinkResponse<Op>): string;
+declare function decodeResponse(url: string): LinkResponse;
+
+interface LinkClientOptions {
+    caller: Caller;
+    /** URL the user app opens with the response; must route back into this member app. */
+    callback: string;
+    openUrl: (url: string) => Promise<void>;
+    /** Subscribes to incoming URLs (e.g. `Linking.addEventListener`); returns an unsubscribe function. */
+    onUrl: (listener: (url: string) => void) => () => void;
+    /** Milliseconds before a request is abandoned. Default 120000. */
+    timeoutMs?: number;
+    /** Overrides the request `id` generator; tests pass a deterministic one. */
+    randomId?: () => string;
+    scheme?: string;
+}
+interface LinkClient {
+    request<Op extends LinkOp>(op: Op, params: Params<Op>): Promise<Result<Op>>;
+}
+/** One member-app-side client per callback URL: exactly one request in flight, matched by id. */
+declare function createLinkClient(options: LinkClientOptions): LinkClient;
+
+interface RequestHandlerOptions {
+    handlers: LinkHandlers;
+    /** Shows the user what's being requested and by whom; resolves to whether they approved it. */
+    consent: (request: DecodedLinkRequest) => Promise<boolean>;
+}
+interface RequestHandler {
+    /** Decodes and dispatches `url`, returning the response URL to open. Never rejects except on {@link LinkDecodeError}. */
+    handle(url: string): Promise<string>;
+}
+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 };

package/types/web.d.ts

@@ -0,0 +1,81 @@
+/** Identifies the member app making a request, as declared by that app (not verified by the OS). */
+interface Caller {
+    name: string;
+    scheme: string;
+}
+
+interface LinkClientOptions {
+    caller: Caller;
+    /** URL the user app opens with the response; must route back into this member app. */
+    callback: string;
+    openUrl: (url: string) => Promise<void>;
+    /** Subscribes to incoming URLs (e.g. `Linking.addEventListener`); returns an unsubscribe function. */
+    onUrl: (listener: (url: string) => void) => () => void;
+    /** Milliseconds before a request is abandoned. Default 120000. */
+    timeoutMs?: number;
+    /** Overrides the request `id` generator; tests pass a deterministic one. */
+    randomId?: () => string;
+    scheme?: string;
+}
+
+interface RequestHandler {
+    /** Decodes and dispatches `url`, returning the response URL to open. Never rejects except on {@link LinkDecodeError}. */
+    handle(url: string): Promise<string>;
+}
+
+interface WebLinkTransportOptions {
+    /** Browser URL of the user web app. The encoded request query is appended to this URL. */
+    userAppUrl: string;
+    /** Exact origin trusted to return responses, for example `http://localhost:5173`. */
+    userAppOrigin: string;
+    popupName?: string;
+    popupFeatures?: string;
+    /** How often to detect a popup closed before responding. Default 100ms. */
+    closePollIntervalMs?: number;
+    /** Time to wait for an already-posted response after observing a closed popup. Default 250ms. */
+    closeGracePeriodMs?: number;
+    /** Injectable for tests; defaults to the current browser window. */
+    window?: Window;
+}
+type WebLinkTransport = Pick<LinkClientOptions, "openUrl" | "onUrl"> & {
+    /** Reserves the popup synchronously inside a click handler before asynchronous flow work begins. */
+    prepare(): void;
+    close(): void;
+};
+/**
+ * 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.
+ */
+declare function createWebLinkTransport(options: WebLinkTransportOptions): WebLinkTransport;
+interface WebLinkResponderOptions {
+    handler: RequestHandler;
+    /** Member-app origins allowed to open the user app and receive a response. */
+    allowedMemberOrigins: readonly string[];
+    /** Maximum time to wait for the opener handshake. Default 5000ms. */
+    handshakeTimeoutMs?: number;
+    /** Close the user-app popup after posting. Default true. */
+    closeAfterResponding?: boolean;
+    /** Injectable for tests; defaults to the current browser window. */
+    window?: Window;
+}
+/** Authenticates the opener, dispatches the request, and posts the response to its verified origin. */
+declare function respondToWebLinkRequest(options: WebLinkResponderOptions): Promise<void>;
+interface EmbeddedWebLinkTransportOptions {
+    userAppUrl: string;
+    userAppOrigin: string;
+    frame: HTMLIFrameElement;
+    window?: Window;
+}
+/** Carries the browser protocol through an in-page iframe, avoiding popup-blocker behavior. */
+declare function createEmbeddedWebLinkTransport(options: EmbeddedWebLinkTransportOptions): WebLinkTransport;
+interface RelayWebLinkTransportOptions {
+    relayUrl: string;
+    sender: string;
+    pollIntervalMs?: number;
+    fetcher?: typeof fetch;
+}
+/** 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 type { EmbeddedWebLinkTransportOptions, RelayWebLinkTransportOptions, WebLinkResponderOptions, WebLinkTransport, WebLinkTransportOptions };