@shuttle.technology/authorization 0.0.0-stage → 0.1.0

package/dist/modeCLinked.js

@@ -0,0 +1,270 @@
+// Mode C on the person's own linked wallet (owner decision, 14 October 2026).
+//
+// The person enrolls, once and with a passkey, a request key bounded to one of
+// their linked wallets: the network the transfers are made on, a ceiling for
+// one transfer of each asset, a ceiling on the network fee and the recipients
+// (none: any). Each later transfer goes with no passkey: the app shows the
+// transfer, signs it and the device share it sealed for the Wallet with the
+// enrolled key (proof 2.0), and hands the request to its own backend, which
+// forwards it unchanged with its service key. The service key never reaches
+// this code, and nothing here sends the request: forwarding belongs to the
+// backend. Every locally detectable fault is refused before the signing key
+// is touched.
+import { ClientFlowError, base64url, canonicalDecimal, integer, opaqueId, record } from "./auth.js";
+import { canonicalJSON, canonicalJSONBytes, sha256HexLower } from "./canonicalize.js";
+import { MaxModeCProofLifetimeSeconds, ModeCJtiBytes, ModeCProofAudience, ModeCProofKind, modeCProtectedHeader } from "./modeC.js";
+import { MaxRequestGrantLifetimeSeconds, MaxRequestGrantRecipients } from "./requestGrant.js";
+export { ModeCServerClock, MaxModeCProofLifetimeSeconds } from "./modeC.js";
+export { generateRequestSigningKey } from "./requestGrant.js";
+/** ModeCLinkedProofVersion is the proof of a transfer from a linked wallet. */
+export const ModeCLinkedProofVersion = "2.0";
+/** The assets a linked grant may name. */
+export const LinkedModeCAssets = ["native", "usdt", "usdc"];
+const maxUint256 = (1n << 256n) - 1n;
+const uuid = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+const linkedNetwork = /^[-a-z0-9]{3,8}:[-_a-zA-Z0-9]{1,32}$/;
+const printable = /^[\x21-\x7e]{1,256}$/;
+const grantToken = /^[A-Za-z0-9_-]{43}$/;
+const fault = (code) => { throw new ClientFlowError(code); };
+function quantity(value, positive) {
+    return canonicalDecimal(value) && BigInt(value) <= maxUint256 && (!positive || BigInt(value) > 0n);
+}
+/**
+ * canonicalAddress is a recipient in the form the network compares addresses
+ * by, as the provider keeps it: an EVM address in lower case, a TON address
+ * raw (workchain:hash in lower-case hex, from the user-friendly form when its
+ * checksum holds), anything else as given. An address that is not well formed
+ * for its network is returned unchanged, as the provider does.
+ */
+export function canonicalAddress(network, address) {
+    if (network.startsWith("ton:"))
+        return canonicalTONAddress(network, address);
+    if (!network.startsWith("eip155:") || !/^0[xX][0-9a-fA-F]{40}$/.test(address))
+        return address;
+    return "0x" + address.slice(2).toLowerCase();
+}
+function canonicalTONAddress(network, address) {
+    const raw = /^(0|-1):([0-9a-fA-F]{64})$/.exec(address);
+    if (raw)
+        return `${raw[1]}:${raw[2].toLowerCase()}`;
+    if (address.includes(":") || address.length !== 48 || !/^[A-Za-z0-9+/_-]{48}$/.test(address))
+        return address;
+    const bytes = Uint8Array.from(atob(address.replace(/-/g, "+").replace(/_/g, "/")), (c) => c.charCodeAt(0));
+    if (bytes.length !== 36 || (network === "ton:mainnet" && (bytes[0] & 0x80) !== 0) || ((bytes[0] & 0x7f) !== 0x11 && (bytes[0] & 0x7f) !== 0x51))
+        return address;
+    let crc = 0;
+    for (const byte of bytes.subarray(0, 34)) {
+        crc ^= byte << 8;
+        for (let bit = 0; bit < 8; bit++)
+            crc = crc & 0x8000 ? ((crc << 1) ^ 0x1021) & 0xffff : (crc << 1) & 0xffff;
+    }
+    if (((bytes[34] << 8) | bytes[35]) !== crc)
+        return address;
+    const workchain = bytes[1] > 127 ? bytes[1] - 256 : bytes[1];
+    return `${workchain}:${Array.from(bytes.subarray(2, 34), (b) => b.toString(16).padStart(2, "0")).join("")}`;
+}
+/** sameAddress compares two recipients as the network compares addresses. */
+export function sameAddress(network, a, b) {
+    return canonicalAddress(network, a) === canonicalAddress(network, b);
+}
+function assets(value, code) {
+    if (!Array.isArray(value) || value.length < 1 || value.length > LinkedModeCAssets.length)
+        fault(code);
+    const out = [];
+    for (const item of value) {
+        const r = record(item, ["asset", "max_amount_raw"]);
+        if (!LinkedModeCAssets.includes(r.asset) || !quantity(r.max_amount_raw, true) || out.some((a) => a.asset === r.asset))
+            fault(code);
+        out.push(Object.freeze({ asset: r.asset, maxAmountRaw: r.max_amount_raw }));
+    }
+    return out;
+}
+function recipients(network, value, code) {
+    if (!Array.isArray(value) || value.length > MaxRequestGrantRecipients)
+        fault(code);
+    const out = [];
+    for (const item of value) {
+        if (typeof item !== "string" || !printable.test(item) || out.some((seen) => sameAddress(network, seen, item)))
+            fault(code);
+        out.push(canonicalAddress(network, item));
+    }
+    return out;
+}
+/** buildLinkedRequestGrantEnrollment checks every bound locally and returns the closed create body. */
+export function buildLinkedRequestGrantEnrollment(key, enrollment) {
+    const code = "invalid_request_grant_enrollment";
+    const e = record(enrollment, ["ownerId", "servicePrincipalId", "linkedWalletId", "network", "assets", "recipientAllowlist", "maxFeeRaw"]);
+    if (!opaqueId(e.ownerId) || !opaqueId(e.servicePrincipalId) || typeof e.linkedWalletId !== "string" || !uuid.test(e.linkedWalletId) ||
+        typeof e.network !== "string" || !linkedNetwork.test(e.network) || !quantity(e.maxFeeRaw, false) || !key?.publicJwk)
+        fault(code);
+    const network = e.network;
+    const ceilings = assets(e.assets?.map((a) => ({ asset: a?.asset, max_amount_raw: a?.maxAmountRaw })), code);
+    return {
+        kind: "session.authorize_requests", owner_type: "account", owner_id: e.ownerId,
+        payload: {
+            public_jwk: { kty: key.publicJwk.kty, crv: key.publicJwk.crv, x: key.publicJwk.x, y: key.publicJwk.y },
+            service_principal_id: e.servicePrincipalId, linked_wallet_id: e.linkedWalletId, network,
+            assets: ceilings.map((a) => ({ asset: a.asset, max_amount_raw: a.maxAmountRaw })),
+            recipient_allowlist: recipients(network, e.recipientAllowlist, code), max_fee_raw: e.maxFeeRaw,
+        },
+    };
+}
+/** validateLinkedEnrollmentCreate is the client's createOperation check of the body above. */
+export function validateLinkedEnrollmentCreate(value, expectedOwnerId) {
+    const code = "invalid_operation_create";
+    const create = record(value, ["kind", "owner_type", "owner_id", "payload"], ["result_recipient"]);
+    const p = record(create.payload, ["public_jwk", "service_principal_id", "linked_wallet_id", "network", "assets", "recipient_allowlist", "max_fee_raw"]);
+    const jwk = record(p.public_jwk, ["kty", "crv", "x", "y"]);
+    if (create.kind !== "session.authorize_requests" || create.owner_type !== "account" || create.owner_id !== expectedOwnerId || !opaqueId(create.owner_id) ||
+        jwk.kty !== "EC" || jwk.crv !== "P-256" || typeof jwk.x !== "string" || !grantToken.test(jwk.x) || typeof jwk.y !== "string" || !grantToken.test(jwk.y) ||
+        !opaqueId(p.service_principal_id) || typeof p.linked_wallet_id !== "string" || !uuid.test(p.linked_wallet_id) || typeof p.network !== "string" ||
+        !linkedNetwork.test(p.network) || !quantity(p.max_fee_raw, false))
+        fault(code);
+    assets(p.assets, code);
+    recipients(p.network, p.recipient_allowlist, code);
+}
+/** parseLinkedEnrollmentDisplay reads the enrollment display of a linked wallet. */
+export function parseLinkedEnrollmentDisplay(value) {
+    const code = "invalid_server_response";
+    const d = record(value, ["address", "assets", "kind", "linked_wallet_id", "max_fee_raw", "network", "owner_id", "public_key_thumbprint", "recipient_allowlist", "requester_id", "service_principal_id"]);
+    if (d.kind !== "session.authorize_requests" || !opaqueId(d.owner_id) || !opaqueId(d.requester_id) || !opaqueId(d.service_principal_id) ||
+        typeof d.linked_wallet_id !== "string" || !uuid.test(d.linked_wallet_id) || typeof d.address !== "string" || !printable.test(d.address) ||
+        typeof d.network !== "string" || !linkedNetwork.test(d.network) || !quantity(d.max_fee_raw, false) || typeof d.public_key_thumbprint !== "string" || !grantToken.test(d.public_key_thumbprint))
+        fault(code);
+    return {
+        kind: "session.authorize_requests", ownerId: d.owner_id, requesterId: d.requester_id, servicePrincipalId: d.service_principal_id,
+        linkedWalletId: d.linked_wallet_id, address: d.address, network: d.network, assets: assets(d.assets, code),
+        recipientAllowlist: recipients(d.network, d.recipient_allowlist, code), maxFeeRaw: d.max_fee_raw, publicKeyThumbprint: d.public_key_thumbprint,
+    };
+}
+/** parseLinkedRequestGrantResult accepts exactly the protected result of a linked grant. */
+export function parseLinkedRequestGrantResult(payload) {
+    const code = "invalid_request_grant_result";
+    const root = record(payload, ["request_grant_id", "public_key_thumbprint", "server_time", "expires_at", "binding", "bounds"]);
+    if (typeof root.request_grant_id !== "string" || !grantToken.test(root.request_grant_id) || typeof root.public_key_thumbprint !== "string" ||
+        !grantToken.test(root.public_key_thumbprint) || !integer(root.server_time) || !integer(root.expires_at) || root.expires_at <= root.server_time ||
+        root.expires_at - root.server_time > MaxRequestGrantLifetimeSeconds)
+        fault(code);
+    const b = record(root.binding, ["tenant_id", "application_id", "environment_id", "client_id", "account_id", "session_id", "service_principal_id", "linked_wallet_id", "binding_revision"]);
+    if (![b.tenant_id, b.application_id, b.environment_id, b.client_id, b.account_id, b.session_id, b.service_principal_id].every(opaqueId) ||
+        typeof b.linked_wallet_id !== "string" || !uuid.test(b.linked_wallet_id) || !canonicalDecimal(b.binding_revision) || b.binding_revision === "0")
+        fault(code);
+    const bounds = record(root.bounds, ["network", "recipient_allowlist", "assets", "max_fee_raw"]);
+    if (typeof bounds.network !== "string" || !linkedNetwork.test(bounds.network) || !quantity(bounds.max_fee_raw, false))
+        fault(code);
+    return Object.freeze({
+        requestGrantId: root.request_grant_id, publicKeyThumbprint: root.public_key_thumbprint,
+        serverTime: root.server_time, expiresAt: root.expires_at,
+        binding: Object.freeze({ tenantId: b.tenant_id, applicationId: b.application_id, environmentId: b.environment_id,
+            clientId: b.client_id, accountId: b.account_id, sessionId: b.session_id, servicePrincipalId: b.service_principal_id,
+            linkedWalletId: b.linked_wallet_id, bindingRevision: b.binding_revision }),
+        bounds: Object.freeze({ network: bounds.network, recipientAllowlist: Object.freeze(recipients(bounds.network, bounds.recipient_allowlist, code)),
+            assets: Object.freeze(assets(bounds.assets, code)), maxFeeRaw: bounds.max_fee_raw }),
+    });
+}
+/**
+ * pairLinkedRequestGrant keeps a grant beside the key that enrolled it, and
+ * refuses one that is not this key's grant on these bounds: another key, owner,
+ * service, wallet, network, asset ceiling, fee ceiling or recipient list.
+ */
+export function pairLinkedRequestGrant(key, grant, enrollment) {
+    const mismatch = () => fault("request_grant_mismatch");
+    const b = grant.binding, n = grant.bounds;
+    if (grant.publicKeyThumbprint !== key.thumbprint || b.accountId !== enrollment.ownerId || b.servicePrincipalId !== enrollment.servicePrincipalId ||
+        b.linkedWalletId !== enrollment.linkedWalletId || n.network !== enrollment.network || n.maxFeeRaw !== enrollment.maxFeeRaw ||
+        n.assets.length !== enrollment.assets.length || n.assets.some((a, i) => a.asset !== enrollment.assets[i].asset || a.maxAmountRaw !== enrollment.assets[i].maxAmountRaw) ||
+        n.recipientAllowlist.length !== enrollment.recipientAllowlist.length ||
+        n.recipientAllowlist.some((r, i) => !sameAddress(n.network, r, enrollment.recipientAllowlist[i])))
+        mismatch();
+    return Object.freeze({ grant, key });
+}
+/**
+ * prepareLinkedMediatedTransfer derives the display and the closed body from
+ * the grant and the person's choice, and refuses before any signature what the
+ * grant does not cover: another asset, an amount over its ceiling, a recipient
+ * off a non-empty list, a comment off TON.
+ */
+export function prepareLinkedMediatedTransfer(paired, intent) {
+    const code = "invalid_transfer_intent";
+    const i = record(intent, ["asset", "recipient", "amountRaw"], ["comment"]);
+    const { grant } = paired;
+    const network = grant.bounds.network;
+    const ceiling = grant.bounds.assets.find((a) => a.asset === i.asset);
+    if (!ceiling || typeof i.recipient !== "string" || !printable.test(i.recipient) || !quantity(i.amountRaw, true) || BigInt(i.amountRaw) > BigInt(ceiling.maxAmountRaw))
+        fault(code);
+    const allowed = grant.bounds.recipientAllowlist;
+    if (allowed.length !== 0 && !allowed.some((r) => sameAddress(network, r, i.recipient)))
+        fault(code);
+    if (i.comment !== undefined && (typeof i.comment !== "string" || i.comment === "" || new TextEncoder().encode(i.comment).length > 120 || !network.startsWith("ton:")))
+        fault(code);
+    const payload = { network, asset: ceiling.asset, recipient: i.recipient, amount_raw: i.amountRaw, ...(i.comment !== undefined ? { comment: i.comment } : {}) };
+    const b = grant.binding;
+    return Object.freeze({
+        display: Object.freeze({ ownerId: b.accountId, linkedWalletId: b.linkedWalletId, servicePrincipalId: b.servicePrincipalId, network, asset: payload.asset,
+            recipient: payload.recipient, amountRaw: payload.amount_raw, ...(payload.comment !== undefined ? { comment: payload.comment } : {}), maxFeeRaw: grant.bounds.maxFeeRaw }),
+        operation: Object.freeze({ kind: "wallet.send", owner_type: "account", owner_id: b.accountId, linked_wallet_id: b.linkedWalletId, payload: Object.freeze(payload) }),
+    });
+}
+/** canonicalLinkedMediatedRequest is the RFC 8785 serialization the request hash covers. */
+export function canonicalLinkedMediatedRequest(operation) {
+    const o = record(operation, ["kind", "owner_type", "owner_id", "linked_wallet_id", "payload"]);
+    const p = record(o.payload, ["network", "asset", "recipient", "amount_raw"], ["comment"]);
+    const payload = { network: p.network, asset: p.asset, recipient: p.recipient, amount_raw: p.amount_raw };
+    if (p.comment !== undefined)
+        payload.comment = p.comment;
+    return canonicalJSON({ kind: o.kind, owner_type: o.owner_type, owner_id: o.owner_id, linked_wallet_id: o.linked_wallet_id, payload });
+}
+export function wireDeviceShare(share) {
+    const s = record(share, ["ciphertext", "nonce", "ephemeralPublicKey", "encryptionAlgorithm", "encryptionContext"]);
+    if (![s.ciphertext, s.nonce, s.ephemeralPublicKey, s.encryptionAlgorithm, s.encryptionContext].every((v) => typeof v === "string" && v !== ""))
+        fault("device_share_unavailable");
+    return Object.freeze({ ciphertext: s.ciphertext, nonce: s.nonce, ephemeral_public_key: s.ephemeralPublicKey,
+        encryption_algorithm: s.encryptionAlgorithm, encryption_context: s.encryptionContext });
+}
+/** deviceShareDigest is the lowercase hex SHA-256 of the RFC 8785 JSON of the share as the request carries it. */
+export function deviceShareDigest(crypto, share) {
+    return sha256HexLower(crypto, canonicalJSONBytes({ ...share }));
+}
+/**
+ * signLinkedMediatedRequest signs the shown transfer and the device share with
+ * the enrolled key as the 2.0 proof. The share is the one sealed to the Wallet
+ * for this transfer (resealDeviceShare); its digest is signed, so the backend
+ * can neither swap it nor change the transfer. The request lives at most 60
+ * seconds and never past the grant.
+ */
+export async function signLinkedMediatedRequest(input) {
+    const { grant, prepared, crypto, serverNowSeconds } = record(input, ["grant", "prepared", "deviceShare", "crypto", "serverNowSeconds"]);
+    if (!grant?.grant || !grant.key?.privateKey || !prepared?.operation || !prepared.display)
+        fault("opaque_signing_input_refused");
+    if (!crypto?.subtle || typeof crypto.getRandomValues !== "function")
+        fault("runtime_capability_unavailable");
+    const again = prepareLinkedMediatedTransfer(grant, { asset: prepared.display.asset, recipient: prepared.display.recipient, amountRaw: prepared.display.amountRaw,
+        ...(prepared.display.comment !== undefined ? { comment: prepared.display.comment } : {}) });
+    // Everything the person was shown is what the grant names and what is signed.
+    const shown = record(prepared.display, ["ownerId", "linkedWalletId", "servicePrincipalId", "network", "asset", "recipient", "amountRaw", "maxFeeRaw"], ["comment"]);
+    const members = new Set([...Object.keys(shown), ...Object.keys(again.display)]);
+    if ([...members].some((m) => shown[m] !== again.display[m]) ||
+        canonicalLinkedMediatedRequest(again.operation) !== canonicalLinkedMediatedRequest(prepared.operation))
+        fault("display_intent_mismatch");
+    if (!integer(serverNowSeconds) || serverNowSeconds <= 0 || serverNowSeconds >= grant.grant.expiresAt)
+        fault("request_grant_reenrollment_required");
+    const share = wireDeviceShare(input.deviceShare);
+    const issuedAt = serverNowSeconds, expiresAt = Math.min(issuedAt + MaxModeCProofLifetimeSeconds, grant.grant.expiresAt);
+    const requestHash = await sha256HexLower(crypto, new TextEncoder().encode(canonicalLinkedMediatedRequest(prepared.operation)));
+    const jti = base64url(crypto.getRandomValues(new Uint8Array(ModeCJtiBytes)));
+    const b = grant.grant.binding;
+    const payload = canonicalJSONBytes({
+        version: ModeCLinkedProofVersion, aud: ModeCProofAudience, tenant_id: b.tenantId, application_id: b.applicationId, environment_id: b.environmentId,
+        client_id: b.clientId, account_id: b.accountId, session_id: b.sessionId, service_principal_id: b.servicePrincipalId,
+        linked_wallet_id: b.linkedWalletId, binding_revision: b.bindingRevision, device_share_digest: await deviceShareDigest(crypto, share),
+        kind: ModeCProofKind, request_hash: requestHash, jti, iat: issuedAt, exp: expiresAt,
+    });
+    const signingInput = `${base64url(new TextEncoder().encode(modeCProtectedHeader(grant.grant.requestGrantId)))}.${base64url(payload)}`;
+    const signature = new Uint8Array(await crypto.subtle.sign({ name: "ECDSA", hash: { name: "SHA-256" } }, grant.key.privateKey, new TextEncoder().encode(signingInput)));
+    if (signature.length !== 64)
+        fault("invalid_request_signature");
+    return Object.freeze({
+        display: prepared.display, idempotencyKey: jti, requestHash, issuedAt, expiresAt,
+        request: Object.freeze({ operation: prepared.operation, user_proof: `${signingInput}.${base64url(signature)}`, device_share: share }),
+    });
+}

package/dist/pages.d.ts

@@ -0,0 +1,22 @@
+export interface PageOptions {
+    limit?: number;
+    cursor?: string;
+    signal?: AbortSignal;
+}
+export type PageEnvelope = {
+    request_id: string;
+    items: unknown[];
+    has_more: boolean;
+    next_cursor?: string;
+};
+export declare function pageRequest(path: string, input?: AbortSignal | PageOptions): {
+    path: string;
+    signal?: AbortSignal;
+};
+export declare function pageEnvelope(payload: unknown): PageEnvelope;
+export declare function pageProjection<T>(requestId: string, items: T[], hasMore: boolean, nextCursor?: string): {
+    requestId: string;
+    items: T[];
+    hasMore: boolean;
+    nextCursor?: string;
+};

package/dist/pages.js

@@ -0,0 +1,45 @@
+// Paging of the account lists: the closed request options and the envelope
+// every page arrives in.
+import { ClientFlowError, integer, opaqueId, record } from "./auth.js";
+export function pageRequest(path, input) {
+    if (isAbortSignal(input))
+        return { path, signal: input };
+    const options = input ?? {};
+    if (options === null || typeof options !== "object" || Array.isArray(options) || Object.keys(options).some((key) => !["limit", "cursor", "signal"].includes(key))) {
+        throw new ClientFlowError("invalid_page_request");
+    }
+    if (options.signal !== undefined && !isAbortSignal(options.signal))
+        throw new ClientFlowError("invalid_page_request");
+    const query = new URLSearchParams();
+    if (options.limit !== undefined) {
+        if (!integer(options.limit) || options.limit < 1 || options.limit > 100)
+            throw new ClientFlowError("invalid_page_request");
+        query.set("limit", String(options.limit));
+    }
+    if (options.cursor !== undefined) {
+        if (typeof options.cursor !== "string" || options.cursor.length === 0)
+            throw new ClientFlowError("invalid_page_request");
+        query.set("cursor", options.cursor);
+    }
+    return { path: query.size === 0 ? path : `${path}?${query.toString()}`, signal: options.signal };
+}
+function isAbortSignal(value) {
+    return value !== null && typeof value === "object" && typeof value.aborted === "boolean" && typeof value.addEventListener === "function";
+}
+export function pageEnvelope(payload) {
+    const root = record(payload, ["request_id", "items", "has_more"], ["next_cursor"]);
+    if (!opaqueId(root.request_id) || typeof root.has_more !== "boolean" || !Array.isArray(root.items))
+        throw new ClientFlowError("invalid_server_response");
+    const hasCursor = Object.prototype.hasOwnProperty.call(root, "next_cursor");
+    if (root.has_more) {
+        if (!hasCursor || typeof root.next_cursor !== "string" || root.next_cursor.length === 0)
+            throw new ClientFlowError("invalid_server_response");
+    }
+    else if (hasCursor) {
+        throw new ClientFlowError("invalid_server_response");
+    }
+    return root;
+}
+export function pageProjection(requestId, items, hasMore, nextCursor) {
+    return hasMore ? { requestId, items, hasMore, nextCursor } : { requestId, items, hasMore };
+}

package/dist/poll.d.ts

@@ -0,0 +1,15 @@
+export interface PollOptions<T> {
+    read: (signal: AbortSignal) => Promise<T>;
+    terminal: (value: T) => boolean;
+    signal?: AbortSignal;
+    intervalMs?: number;
+    timeoutMs?: number;
+    now?: () => number;
+    sleep?: (milliseconds: number, signal: AbortSignal) => Promise<void>;
+}
+export type PollDisposition = "server_terminal" | "local_timeout" | "local_canceled";
+export interface PollResult<T> {
+    lastKnown: T | undefined;
+    disposition: PollDisposition;
+}
+export declare function pollAuthoritative<T>(options: PollOptions<T>): Promise<PollResult<T>>;

package/dist/poll.js

@@ -0,0 +1,76 @@
+import { ClientFlowError } from "./auth.js";
+export async function pollAuthoritative(options) {
+    const intervalMs = options.intervalMs ?? 2_000;
+    const timeoutMs = options.timeoutMs ?? 60_000;
+    if (intervalMs < 2_000 || timeoutMs <= 0 || timeoutMs > 60_000)
+        throw new ClientFlowError("invalid_poll_bounds");
+    if (options.signal?.aborted)
+        return { lastKnown: undefined, disposition: "local_canceled" };
+    const now = options.now ?? Date.now;
+    const sleep = options.sleep ?? boundedSleep;
+    const deadline = now() + timeoutMs;
+    const boundary = new AbortController();
+    let timedOut = false;
+    const timeout = setTimeout(() => {
+        timedOut = true;
+        boundary.abort();
+    }, timeoutMs);
+    const cancel = () => boundary.abort();
+    options.signal?.addEventListener("abort", cancel, { once: true });
+    let lastKnown;
+    try {
+        while (true) {
+            if (options.signal?.aborted)
+                return { lastKnown, disposition: "local_canceled" };
+            if (timedOut || now() >= deadline)
+                return { lastKnown, disposition: "local_timeout" };
+            const observed = await raceBoundary(options.read(boundary.signal), boundary.signal);
+            if (!observed.completed)
+                return { lastKnown, disposition: timedOut ? "local_timeout" : "local_canceled" };
+            if (now() >= deadline)
+                return { lastKnown, disposition: "local_timeout" };
+            lastKnown = observed.value;
+            if (options.terminal(lastKnown))
+                return { lastKnown, disposition: "server_terminal" };
+            const remaining = deadline - now();
+            if (remaining <= 0)
+                return { lastKnown, disposition: "local_timeout" };
+            const waited = await raceBoundary(sleep(Math.min(intervalMs, remaining), boundary.signal), boundary.signal);
+            if (!waited.completed)
+                return { lastKnown, disposition: timedOut ? "local_timeout" : "local_canceled" };
+        }
+    }
+    finally {
+        clearTimeout(timeout);
+        options.signal?.removeEventListener("abort", cancel);
+    }
+}
+async function raceBoundary(operation, signal) {
+    if (signal.aborted)
+        return { completed: false };
+    return new Promise((resolve, reject) => {
+        const aborted = () => resolve({ completed: false });
+        signal.addEventListener("abort", aborted, { once: true });
+        operation.then((value) => {
+            signal.removeEventListener("abort", aborted);
+            resolve({ completed: true, value });
+        }, (error) => {
+            signal.removeEventListener("abort", aborted);
+            reject(error);
+        });
+    });
+}
+function boundedSleep(milliseconds, signal) {
+    return new Promise((resolve) => {
+        const timer = setTimeout(done, milliseconds);
+        const aborted = () => {
+            clearTimeout(timer);
+            done();
+        };
+        function done() {
+            signal.removeEventListener("abort", aborted);
+            resolve();
+        }
+        signal.addEventListener("abort", aborted, { once: true });
+    });
+}

package/dist/requestGrant.d.ts

@@ -0,0 +1,169 @@
+/** RequestPublicJwk is the closed enrollment key: no private member exists. */
+export interface RequestPublicJwk {
+    readonly kty: "EC";
+    readonly crv: "P-256";
+    readonly x: string;
+    readonly y: string;
+}
+/**
+ * RequestSigningKey is one client-held key. `privateKey` is non-extractable and
+ * usable only for local ES256 signing; it is never serialized and never leaves
+ * this object.
+ */
+export interface RequestSigningKey {
+    readonly handle: string;
+    readonly publicJwk: RequestPublicJwk;
+    readonly thumbprint: string;
+    readonly privateKey: CryptoKey;
+}
+/** RequestGrantBounds is the frozen finite transfer authority of one grant. */
+export interface RequestGrantBounds {
+    readonly network: string;
+    readonly recipientAllowlist: readonly string[];
+    readonly maxAmountRaw: string;
+    readonly maxFeeRaw: string;
+}
+/** RequestGrantBinding is the complete scoped identity the grant froze. */
+export interface RequestGrantBinding {
+    readonly tenantId: string;
+    readonly applicationId: string;
+    readonly environmentId: string;
+    readonly clientId: string;
+    readonly accountId: string;
+    readonly sessionId: string;
+    readonly servicePrincipalId: string;
+    readonly walletId: string;
+    readonly walletGeneration: string;
+    readonly mappingVersion: string;
+}
+/** RequestGrantResult is the protected `session.authorize_requests` result. */
+export interface RequestGrantResult {
+    readonly requestGrantId: string;
+    readonly publicKeyThumbprint: string;
+    /** Integer NumericDate seconds (source §2.2), not an RFC 3339 string. */
+    readonly serverTime: number;
+    /** Integer NumericDate seconds (source §2.2), not an RFC 3339 string. */
+    readonly expiresAt: number;
+    readonly binding: RequestGrantBinding;
+    readonly bounds: RequestGrantBounds;
+}
+/** RequestGrantEnrollment is the caller-declared enrollment intent. */
+export interface RequestGrantEnrollment {
+    readonly ownerId: string;
+    readonly servicePrincipalId: string;
+    readonly walletId: string;
+    readonly network: string;
+    readonly recipientAllowlist: readonly string[];
+    readonly maxAmountRaw: string;
+    readonly maxFeeRaw: string;
+}
+/** RequestGrantEnrollmentCreate is the closed OperationCreate of source §2.2. */
+export interface RequestGrantEnrollmentCreate {
+    readonly kind: "session.authorize_requests";
+    readonly owner_type: "account";
+    readonly owner_id: string;
+    readonly payload: {
+        readonly public_jwk: RequestPublicJwk;
+        readonly service_principal_id: string;
+        readonly wallet_id: string;
+        readonly network: string;
+        readonly recipient_allowlist: readonly string[];
+        readonly max_amount_raw: string;
+        readonly max_fee_raw: string;
+    };
+}
+/** PairedRequestGrant is one grant result bound to the exact key that owns it. */
+export interface PairedRequestGrant {
+    readonly grant: RequestGrantResult;
+    readonly key: RequestSigningKey;
+}
+/** MaxRequestGrantRecipients is the source §2.8 allowlist bound. */
+export declare const MaxRequestGrantRecipients = 10;
+/** MaxRequestGrantLifetimeSeconds is the source §2.5 ceiling of fifteen minutes. */
+export declare const MaxRequestGrantLifetimeSeconds: number;
+/**
+ * generateRequestSigningKey creates the non-extractable P-256 key of source
+ * §2.5. It refuses a runtime that returns an extractable private key or a
+ * public JWK carrying any private member, so a weakened WebCrypto cannot
+ * silently become custody of a user key.
+ */
+export declare function generateRequestSigningKey(crypto: Crypto): Promise<RequestSigningKey>;
+/**
+ * jwkThumbprint is the RFC 7638 SHA-256 thumbprint in unpadded base64url over
+ * exactly the required EC members. The canonicalizer already orders them
+ * lexicographically, which is the order RFC 7638 prescribes.
+ */
+export declare function jwkThumbprint(crypto: Crypto, key: RequestPublicJwk): Promise<string>;
+/**
+ * buildRequestGrantEnrollment returns the closed `session.authorize_requests`
+ * OperationCreate. Every bound is validated locally first, so an empty or
+ * over-length allowlist, a duplicate or wildcard recipient and a noncanonical
+ * or out-of-range ceiling never leave the client.
+ */
+export declare function buildRequestGrantEnrollment(key: RequestSigningKey, enrollment: RequestGrantEnrollment): RequestGrantEnrollmentCreate;
+/**
+ * RequestGrantEnrollmentHost is the operation contract `enrollRequestGrant`
+ * drives: creation, fresh provider-hosted passkey confirmation, explicit
+ * execution and the protected result read remain four separate calls, exactly
+ * as every other local operation in this SDK. The host is supplied by the
+ * caller so this one function can be pointed at the served route.
+ */
+export interface RequestGrantEnrollmentHost {
+    create(create: RequestGrantEnrollmentCreate, idempotencyKey: string): Promise<{
+        operationId: string;
+        version: string;
+    }>;
+    confirm(operationId: string): Promise<{
+        operationId: string;
+        version: string;
+    }>;
+    execute(operationId: string, version: string, idempotencyKey: string): Promise<void>;
+    result(operationId: string): Promise<unknown>;
+}
+/**
+ * enrollRequestGrant performs one explicit enrollment: it never runs from a
+ * refresh, reload or login callback, and it returns the protected grant result
+ * paired with the key that will sign under it. The caller must have obtained
+ * the hosted passkey confirmation through `confirm`; no proof is generated here
+ * and no mediated request is sent.
+ */
+export declare function enrollRequestGrant(host: RequestGrantEnrollmentHost, key: RequestSigningKey, enrollment: RequestGrantEnrollment, keys: {
+    readonly create: string;
+    readonly execute: string;
+}): Promise<RequestGrantResult>;
+/**
+ * parseRequestGrantResultEnvelope accepts the `{request_id,result}` protected
+ * result envelope and requires the grant to belong to this key and to the
+ * enrollment that was submitted.
+ */
+export declare function parseRequestGrantResultEnvelope(payload: unknown, key: RequestSigningKey, enrollment: RequestGrantEnrollment): {
+    requestId: string;
+    result: RequestGrantResult;
+};
+/** parseRequestGrantResult accepts exactly the closed grant result of source §2.2. */
+export declare function parseRequestGrantResult(payload: unknown): RequestGrantResult;
+/**
+ * RequestGrantStore keeps one grant result beside the exact key that owns it,
+ * in memory only. It never touches browser storage, never renews a grant and
+ * never re-enrolls: a released, absent or expired pairing reports
+ * `request_grant_reenrollment_required` so the caller performs an explicit
+ * fresh-UV enrollment instead.
+ */
+export declare class RequestGrantStore {
+    #private;
+    /** pair refuses any grant result that is not this key's own enrolled grant. */
+    pair(key: RequestSigningKey, grant: RequestGrantResult, enrollment: RequestGrantEnrollment): PairedRequestGrant;
+    /**
+     * current returns the live pairing. An absent pairing is a lost key, and an
+     * expired grant is over: neither is repaired locally.
+     */
+    current(serverNowSeconds: number): PairedRequestGrant;
+    /** release forgets the pairing, as logout or a lost key requires. */
+    release(): void;
+}
+/**
+ * assertGrantMatches is the local pairing check of source §1.4: the result must
+ * carry this key's RFC 7638 thumbprint and the exact bounds and owner the
+ * client enrolled. A mismatch is a refusal, never a renegotiated grant.
+ */
+export declare function assertGrantMatches(grant: RequestGrantResult, key: RequestSigningKey, enrollment: RequestGrantEnrollment): void;