@coordination-network/user-app-link 0.0.1

package/src/client.ts

@@ -0,0 +1,138 @@
+import { decodeResponse, encodeRequest } from "./codec"
+import { LinkError } from "./errors"
+import { resultSchemas } from "./schemas"
+import type { Caller, LinkOp, LinkRequest, Params, Result } from "./types"
+
+export 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
+}
+
+export interface LinkClient {
+    request<Op extends LinkOp>(op: Op, params: Params<Op>): Promise<Result<Op>>
+}
+
+const DEFAULT_TIMEOUT_MS = 120_000
+
+function defaultRandomId(): string {
+    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)}`
+}
+
+interface PendingRequest {
+    id: string
+    op: LinkOp
+    resolve: (result: unknown) => void
+    reject: (error: unknown) => void
+    unsubscribe: () => void
+    timer: ReturnType<typeof setTimeout>
+}
+
+/** One member-app-side client per callback URL: exactly one request in flight, matched by id. */
+export function createLinkClient(options: LinkClientOptions): LinkClient {
+    const randomId = options.randomId ?? defaultRandomId
+    const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS
+    let pending: PendingRequest | null = 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: string): void {
+        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 extends LinkOp>(op: Op, params: Params<Op>): Promise<Result<Op>> {
+            if (pending) {
+                return Promise.reject(new Error("createLinkClient: a request is already in flight"))
+            }
+
+            return new Promise<Result<Op>>((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
+                } as LinkRequest<Op>
+                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 as (result: unknown) => void, reject, unsubscribe, timer }
+
+                options.openUrl(url).catch((error: unknown) => {
+                    pending = null
+                    clearTimeout(timer)
+                    unsubscribe()
+                    reject(error)
+                })
+            })
+        }
+    }
+}

package/src/codec.ts

@@ -0,0 +1,134 @@
+import { LinkDecodeError, LinkError, LinkPayloadTooLargeError } from "./errors"
+import {
+    callbackSchema,
+    callerSchema,
+    DENIED_CALLBACK_SCHEMES,
+    linkRequestEnvelopeSchema,
+    linkResponseSchema
+} from "./schemas"
+import type { DecodedLinkRequest, LinkOp, LinkRequest, LinkResponse } from "./types"
+
+export const USER_APP_SCHEME = "userapp"
+
+/** Above this, a platform's `Linking.openURL` (and some OSes) start truncating or refusing the URL. */
+export const MAX_URL_LENGTH = 2000
+
+/** Encodes bytes with the base64url alphabet (RFC 4648 §5), unpadded. No Node `Buffer`: `atob`/`btoa` only. */
+export function base64UrlEncode(bytes: Uint8Array): string {
+    let binary = ""
+    for (const byte of bytes) {
+        binary += String.fromCharCode(byte)
+    }
+    return globalThis.btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "")
+}
+
+export function base64UrlDecode(value: string): Uint8Array {
+    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: unknown): string {
+    return base64UrlEncode(new TextEncoder().encode(JSON.stringify(value)))
+}
+
+function decodePayload(payload: string): unknown {
+    try {
+        return JSON.parse(new TextDecoder().decode(base64UrlDecode(payload)))
+    } catch {
+        throw new LinkDecodeError("payload is not valid base64url-encoded JSON")
+    }
+}
+
+function checkUrlLength(url: string): void {
+    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: string, key: string): string | null {
+    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
+}
+
+export function encodeRequest<Op extends LinkOp>(request: LinkRequest<Op>, options: { scheme?: string } = {}): string {
+    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 as readonly string[]).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
+}
+
+export function decodeRequest(url: string): DecodedLinkRequest {
+    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
+}
+
+export function encodeResponse<Op extends LinkOp>(callback: string, response: LinkResponse<Op>): string {
+    const url = `${callback}?payload=${encodePayload(response)}`
+    checkUrlLength(url)
+    return url
+}
+
+export function decodeResponse(url: string): LinkResponse {
+    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 as LinkResponse
+}

package/src/errors.ts

@@ -0,0 +1,32 @@
+import type { LinkErrorCode } from "./types"
+
+/** A link-protocol failure, discriminated by the same `code` a wire `{ ok: false }` response carries. */
+export class LinkError extends Error {
+    readonly code: LinkErrorCode
+
+    constructor(code: LinkErrorCode, message?: string) {
+        super(message ?? code)
+        this.name = "LinkError"
+        this.code = code
+    }
+}
+
+/** Thrown by encodeRequest/encodeResponse when the built URL exceeds MAX_URL_LENGTH. */
+export class LinkPayloadTooLargeError extends LinkError {
+    constructor(message: string) {
+        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.
+ */
+export class LinkDecodeError extends LinkError {
+    constructor(message: string) {
+        super("INVALID_REQUEST", message)
+        this.name = "LinkDecodeError"
+    }
+}

package/src/handler.ts

@@ -0,0 +1,95 @@
+import { decodeRequest, encodeResponse } from "./codec"
+import { LinkError } from "./errors"
+import { paramsSchemas, resultSchemas } from "./schemas"
+import {
+    LINK_OPS,
+    type Caller,
+    type DecodedLinkRequest,
+    type LinkErrorCode,
+    type LinkHandlers,
+    type LinkOp,
+    type LinkResponse
+} from "./types"
+
+export 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>
+}
+
+export interface RequestHandler {
+    /** Decodes and dispatches `url`, returning the response URL to open. Never rejects except on {@link LinkDecodeError}. */
+    handle(url: string): Promise<string>
+}
+
+function isLinkOp(op: string): op is LinkOp {
+    return (LINK_OPS as readonly string[]).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
+
+/**
+ * Dispatch is inherently dynamic (the op comes from the decoded URL, not a type parameter), so the
+ * per-op correlation `LinkHandlers` gives callers has to be widened away here rather than threaded through.
+ */
+type AnyLinkHandler = (params: unknown, context: { caller: Caller }) => Promise<unknown>
+
+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)
+        return encodeResponse(request.callback, {
+            id: request.id,
+            version: "v1",
+            ok: false,
+            code,
+            message: cappedMessage
+        })
+    }
+
+    return {
+        async handle(url: string): Promise<string> {
+            const request = decodeRequest(url)
+
+            if (!isLinkOp(request.op)) {
+                return respond(request, "UNSUPPORTED_OP")
+            }
+
+            const handler = handlers[request.op] as AnyLinkHandler | undefined
+            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 } as LinkResponse
+                return encodeResponse(request.callback, response)
+            } catch (error) {
+                if (error instanceof LinkError) {
+                    return respond(request, error.code, error.message)
+                }
+                return respond(request, "INTERNAL")
+            }
+        }
+    }
+}

package/src/index.ts

@@ -0,0 +1,6 @@
+export * from "./types"
+export * from "./schemas"
+export * from "./errors"
+export * from "./codec"
+export * from "./client"
+export * from "./handler"

package/src/schemas.ts

@@ -0,0 +1,261 @@
+import { z } from "zod"
+import { LINK_ERROR_CODES, type Hex20, type Hex31, type Hex32, type Hex65, type Hex66, type LinkOp } from "./types"
+
+/**
+ * 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.
+ */
+export 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"
+] as const
+
+/**
+ * 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.
+ */
+export const ALLOWED_ENDPOINT_URL_SCHEMES = ["http", "https"] as const
+
+/** `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. */
+export 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 as readonly string[]).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 as readonly string[]).includes(
+                value.slice(0, value.indexOf(":")).toLowerCase()
+            ),
+        {
+            message: `scheme must be one of: ${ALLOWED_ENDPOINT_URL_SCHEMES.join(", ")}`
+        }
+    )
+
+const hexOfLength = <T extends string>(byteLength: number) =>
+    z
+        .string()
+        .regex(new RegExp(`^0x[0-9a-fA-F]{${byteLength * 2}}$`), `must be ${byteLength}-byte 0x-prefixed hex`)
+        .transform((value) => value.toLowerCase() as T)
+
+export const hex20Schema = hexOfLength<Hex20>(20)
+export const hex31Schema = hexOfLength<Hex31>(31)
+export const hex32Schema = hexOfLength<Hex32>(32)
+export const hex65Schema = hexOfLength<Hex65>(65)
+export const hex66Schema = hexOfLength<Hex66>(66)
+
+export 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: number) =>
+    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")
+
+export const callerSchema = z
+    .object({
+        name: sentenceSafeTextSchema(64),
+        scheme: z.string().min(1)
+    })
+    .strict()
+
+export const approvalScopeSchema = z
+    .object({ programme: sentenceSafeTextSchema(64), country: z.string().regex(/^[A-Z]{3}$/, "ISO 3166-1 alpha-3") })
+    .strict()
+
+export const registrationSignParamsSchema = z
+    .object({ chainId: z.number().int().positive(), verifyingContract: hex20Schema })
+    .strict()
+
+export 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()
+
+export 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: string): string {
+    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"] as const
+
+export 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})`
+                })
+            }
+        }
+    })
+
+export 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()
+])
+
+export 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"] as const) {
+            if (originOf(params[field]) !== origin) {
+                ctx.addIssue({
+                    code: "custom",
+                    path: [field],
+                    message: `${field} must be on the same origin as responseUrl (${origin})`
+                })
+            }
+        }
+    })
+
+export 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. */
+export const paramsSchemas: Record<LinkOp, z.ZodTypeAny> = {
+    "registration.sign": registrationSignParamsSchema,
+    "credential.issue": credentialIssueParamsSchema,
+    "presentation.create": presentationCreateParamsSchema
+}
+
+export const resultSchemas: Record<LinkOp, z.ZodTypeAny> = {
+    "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. */
+export 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. */
+export 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()
+])
+
+export const linkErrorCodeSchema = z.enum(LINK_ERROR_CODES)
+
+export 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()
+])