@shuttle.technology/authorization 0.0.0-stage → 0.2.0

package/dist/redirects.d.ts

@@ -0,0 +1,45 @@
+import { type AuthIntent } from "./auth.ts";
+import type { Session } from "./client.ts";
+/**
+ * HostedSignIn is a sign-in started on the provider's hosted page. The person
+ * picks the method there. On the web the state and the S256 verifier stay in
+ * this client's memory until `exchangeHandoff` receives the redirect back; on
+ * mobile the system browser hands the redirect back to the same call, which
+ * exchanges it and answers the session.
+ */
+export interface HostedSignIn {
+    intent: AuthIntent;
+    launchUrl: string;
+    session?: Session;
+}
+/** hostedSignInUrl is the provider's sign-in page for one client, intent, state and S256 challenge. */
+export declare function hostedSignInUrl(authorizationOrigin: string, input: {
+    clientId: string;
+    redirectUri: string;
+    state: string;
+    challenge: string;
+    intent: AuthIntent;
+}): string;
+/**
+ * handoffCallback reads the redirect back from a sign-in at the exact
+ * registered redirect. A sign-in begun on the hosted page returns the code and
+ * the state alone; one begun through the attempt API also names its attempt.
+ */
+export declare function handoffCallback(value: string, expected: string): {
+    attemptId?: string;
+    state: string;
+    code: string;
+};
+/** restoreCallback reads the redirect back from a web restore at the exact registered redirect. */
+export declare function restoreCallback(value: string, expected: string): {
+    restoreId: string;
+    state: string;
+    code: string;
+};
+/** The app's own exact origin: https on any host, or http on a loopback host. */
+export declare function exactAppOrigin(value: string): boolean;
+/** A redirect back to the app: https on any host, or http on a loopback host; no credentials, query or fragment. */
+export declare function exactAppRedirect(value: string): boolean;
+export declare function exactHttpsOrigin(value: string): boolean;
+export declare function exactHttpsRedirect(value: string): boolean;
+export declare function httpsURL(value: unknown): value is string;

package/dist/redirects.js

@@ -0,0 +1,108 @@
+// The provider's top-level sign-in page, the redirects that come back to the
+// application from a sign-in or a restore, and the exact HTTPS shapes the
+// configuration and the provider's answers are checked against.
+import { ClientFlowError, opaqueId } from "./auth.js";
+/** hostedSignInUrl is the provider's sign-in page for one client, intent, state and S256 challenge. */
+export function hostedSignInUrl(authorizationOrigin, input) {
+    const start = new URL("/v1/auth/start", authorizationOrigin);
+    start.searchParams.set("client_id", input.clientId);
+    start.searchParams.set("redirect_uri", input.redirectUri);
+    start.searchParams.set("state", input.state);
+    start.searchParams.set("code_challenge", input.challenge);
+    start.searchParams.set("code_challenge_method", "S256");
+    start.searchParams.set("intent", input.intent);
+    return start.toString();
+}
+/**
+ * handoffCallback reads the redirect back from a sign-in at the exact
+ * registered redirect. A sign-in begun on the hosted page returns the code and
+ * the state alone; one begun through the attempt API also names its attempt.
+ */
+export function handoffCallback(value, expected) {
+    const callback = exactRedirect(value, expected);
+    const code = callback.searchParams.getAll("code");
+    const state = callback.searchParams.getAll("state");
+    const attemptId = callback.searchParams.getAll("attempt_id");
+    const size = callback.searchParams.size;
+    if (code.length !== 1 || state.length !== 1 || code[0] === "" || state[0] === "" || !((size === 2 && attemptId.length === 0) || (size === 3 && attemptId.length === 1 && opaqueId(attemptId[0])))) {
+        throw new ClientFlowError("invalid_callback");
+    }
+    return attemptId.length === 1 ? { code: code[0], state: state[0], attemptId: attemptId[0] } : { code: code[0], state: state[0] };
+}
+/** restoreCallback reads the redirect back from a web restore at the exact registered redirect. */
+export function restoreCallback(value, expected) {
+    const callback = exactRedirect(value, expected);
+    const code = callback.searchParams.getAll("code");
+    const state = callback.searchParams.getAll("state");
+    const restoreId = callback.searchParams.getAll("restore_id");
+    if (callback.searchParams.size !== 3 || code.length !== 1 || state.length !== 1 || restoreId.length !== 1 || code[0] === "" || state[0] === "" || !opaqueId(restoreId[0]))
+        throw new ClientFlowError("invalid_callback");
+    return { code: code[0], state: state[0], restoreId: restoreId[0] };
+}
+function exactRedirect(value, expected) {
+    let callback;
+    try {
+        callback = new URL(value);
+    }
+    catch {
+        throw new ClientFlowError("invalid_callback");
+    }
+    const target = new URL(expected);
+    if (`${callback.origin}${callback.pathname}` !== `${target.origin}${target.pathname}` || callback.hash !== "")
+        throw new ClientFlowError("invalid_callback");
+    return callback;
+}
+/** A loopback host a browser treats as a secure context over plain http (local development). */
+function loopbackHost(hostname) {
+    return hostname === "localhost" || hostname === "127.0.0.1" || hostname === "[::1]";
+}
+/** The app's own exact origin: https on any host, or http on a loopback host. */
+export function exactAppOrigin(value) {
+    try {
+        const parsed = new URL(value);
+        const secure = parsed.protocol === "https:" || (parsed.protocol === "http:" && loopbackHost(parsed.hostname));
+        return secure && parsed.username === "" && parsed.password === "" && parsed.pathname === "/" && parsed.search === "" && parsed.hash === "" && parsed.origin === value;
+    }
+    catch {
+        return false;
+    }
+}
+/** A redirect back to the app: https on any host, or http on a loopback host; no credentials, query or fragment. */
+export function exactAppRedirect(value) {
+    try {
+        const parsed = new URL(value);
+        const secure = parsed.protocol === "https:" || (parsed.protocol === "http:" && loopbackHost(parsed.hostname));
+        return secure && parsed.username === "" && parsed.password === "" && parsed.search === "" && parsed.hash === "";
+    }
+    catch {
+        return false;
+    }
+}
+export function exactHttpsOrigin(value) {
+    try {
+        const parsed = new URL(value);
+        return parsed.protocol === "https:" && parsed.username === "" && parsed.password === "" && parsed.pathname === "/" && parsed.search === "" && parsed.hash === "" && parsed.origin === value;
+    }
+    catch {
+        return false;
+    }
+}
+export function exactHttpsRedirect(value) {
+    try {
+        const parsed = new URL(value);
+        return parsed.protocol === "https:" && parsed.username === "" && parsed.password === "" && parsed.search === "" && parsed.hash === "";
+    }
+    catch {
+        return false;
+    }
+}
+export function httpsURL(value) {
+    if (typeof value !== "string")
+        return false;
+    try {
+        return new URL(value).protocol === "https:";
+    }
+    catch {
+        return false;
+    }
+}

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;

package/dist/requestGrant.js

@@ -0,0 +1,243 @@
+// Mode C request-signing key and request grant (source §1.4, §2.2, §2.5).
+//
+// The private key is a non-extractable P-256 WebCrypto key held only in this
+// package's memory; only its public kty/crv/x/y JWK is ever enrolled. The
+// protected grant result is retained beside the exact key that produced it: a
+// result paired with another key, an altered thumbprint or a lost key all
+// refuse proof generation locally and require explicit re-enrollment with
+// fresh passkey UV. Nothing here reads or writes browser storage, and nothing
+// here re-enrolls on refresh, reload or login.
+import { ClientFlowError, base64url, canonicalDecimal, integer, opaqueId, record } from "./auth.js";
+import { canonicalJSONBytes } from "./canonicalize.js";
+/** MaxRequestGrantRecipients is the source §2.8 allowlist bound. */
+export const MaxRequestGrantRecipients = 10;
+/** MaxRequestGrantLifetimeSeconds is the source §2.5 ceiling of fifteen minutes. */
+export const MaxRequestGrantLifetimeSeconds = 15 * 60;
+const maxUint256 = (1n << 256n) - 1n;
+const coordinate = /^[A-Za-z0-9_-]{43}$/;
+const grantToken = /^[A-Za-z0-9_-]{43}$/;
+const grantNetwork = /^[A-Za-z0-9_.-]{1,64}$/;
+const grantRecipient = /^[\x21-\x7e]{1,256}$/;
+/**
+ * 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 async function generateRequestSigningKey(crypto) {
+    if (!crypto?.subtle || typeof crypto.subtle.generateKey !== "function" || typeof crypto.getRandomValues !== "function") {
+        throw new ClientFlowError("runtime_capability_unavailable");
+    }
+    const algorithm = { name: "ECDSA", namedCurve: "P-256" };
+    const pair = (await crypto.subtle.generateKey(algorithm, false, ["sign", "verify"]));
+    if (!pair?.privateKey || !pair.publicKey || pair.privateKey.extractable !== false)
+        throw new ClientFlowError("request_key_extractable");
+    const exported = await crypto.subtle.exportKey("jwk", pair.publicKey);
+    const publicJwk = exactPublicJwk(exported);
+    return {
+        handle: base64url(crypto.getRandomValues(new Uint8Array(16))),
+        publicJwk,
+        thumbprint: await jwkThumbprint(crypto, publicJwk),
+        privateKey: pair.privateKey,
+    };
+}
+/**
+ * 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 async function jwkThumbprint(crypto, key) {
+    if (!crypto?.subtle || typeof crypto.subtle.digest !== "function")
+        throw new ClientFlowError("runtime_capability_unavailable");
+    const canonical = canonicalJSONBytes({ crv: key.crv, kty: key.kty, x: key.x, y: key.y });
+    return base64url(new Uint8Array(await crypto.subtle.digest("SHA-256", canonical)));
+}
+/**
+ * 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 function buildRequestGrantEnrollment(key, enrollment) {
+    const declared = record(enrollment, ["ownerId", "servicePrincipalId", "walletId", "network", "recipientAllowlist", "maxAmountRaw", "maxFeeRaw"]);
+    if (!opaqueId(declared.ownerId) || !opaqueId(declared.servicePrincipalId) || !opaqueId(declared.walletId) ||
+        typeof declared.network !== "string" || !grantNetwork.test(declared.network) ||
+        !rawQuantity(declared.maxAmountRaw, true) || !rawQuantity(declared.maxFeeRaw, false)) {
+        throw new ClientFlowError("invalid_request_grant_enrollment");
+    }
+    const allowlist = exactAllowlist(declared.recipientAllowlist, "invalid_request_grant_enrollment");
+    return {
+        kind: "session.authorize_requests",
+        owner_type: "account",
+        owner_id: declared.ownerId,
+        payload: {
+            public_jwk: { kty: key.publicJwk.kty, crv: key.publicJwk.crv, x: key.publicJwk.x, y: key.publicJwk.y },
+            service_principal_id: declared.servicePrincipalId,
+            wallet_id: declared.walletId,
+            network: declared.network,
+            recipient_allowlist: allowlist,
+            max_amount_raw: declared.maxAmountRaw,
+            max_fee_raw: declared.maxFeeRaw,
+        },
+    };
+}
+/**
+ * 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 async function enrollRequestGrant(host, key, enrollment, keys) {
+    if (!opaqueId(keys?.create) || !opaqueId(keys?.execute))
+        throw new ClientFlowError("invalid_idempotency_key");
+    const create = buildRequestGrantEnrollment(key, enrollment);
+    const admitted = await host.create(create, keys.create);
+    if (!opaqueId(admitted?.operationId))
+        throw new ClientFlowError("invalid_server_response");
+    const confirmed = await host.confirm(admitted.operationId);
+    if (confirmed?.operationId !== admitted.operationId || !canonicalDecimal(confirmed.version))
+        throw new ClientFlowError("invalid_server_response");
+    await host.execute(admitted.operationId, confirmed.version, keys.execute);
+    return parseRequestGrantResultEnvelope(await host.result(admitted.operationId), key, enrollment).result;
+}
+/**
+ * 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 function parseRequestGrantResultEnvelope(payload, key, enrollment) {
+    const root = record(payload, ["request_id", "result"]);
+    if (!opaqueId(root.request_id))
+        throw new ClientFlowError("invalid_server_response");
+    const result = parseRequestGrantResult(root.result);
+    assertGrantMatches(result, key, enrollment);
+    return { requestId: root.request_id, result };
+}
+/** parseRequestGrantResult accepts exactly the closed grant result of source §2.2. */
+export function parseRequestGrantResult(payload) {
+    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) {
+        throw new ClientFlowError("invalid_request_grant_result");
+    }
+    const raw = record(root.binding, ["tenant_id", "application_id", "environment_id", "client_id", "account_id", "session_id", "service_principal_id", "wallet_id", "wallet_generation", "mapping_version"]);
+    const binding = {
+        tenantId: boundIdentifier(raw.tenant_id), applicationId: boundIdentifier(raw.application_id), environmentId: boundIdentifier(raw.environment_id),
+        clientId: boundIdentifier(raw.client_id), accountId: boundIdentifier(raw.account_id), sessionId: boundIdentifier(raw.session_id),
+        servicePrincipalId: boundIdentifier(raw.service_principal_id), walletId: boundIdentifier(raw.wallet_id),
+        walletGeneration: boundVersion(raw.wallet_generation), mappingVersion: boundVersion(raw.mapping_version),
+    };
+    const bounds = record(root.bounds, ["network", "recipient_allowlist", "max_amount_raw", "max_fee_raw"]);
+    if (typeof bounds.network !== "string" || !grantNetwork.test(bounds.network) ||
+        !rawQuantity(bounds.max_amount_raw, true) || !rawQuantity(bounds.max_fee_raw, false)) {
+        throw new ClientFlowError("invalid_request_grant_result");
+    }
+    return {
+        requestGrantId: root.request_grant_id,
+        publicKeyThumbprint: root.public_key_thumbprint,
+        serverTime: root.server_time,
+        expiresAt: root.expires_at,
+        binding,
+        bounds: {
+            network: bounds.network, recipientAllowlist: exactAllowlist(bounds.recipient_allowlist, "invalid_request_grant_result"),
+            maxAmountRaw: bounds.max_amount_raw, maxFeeRaw: bounds.max_fee_raw,
+        },
+    };
+}
+/**
+ * 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 class RequestGrantStore {
+    #paired;
+    /** pair refuses any grant result that is not this key's own enrolled grant. */
+    pair(key, grant, enrollment) {
+        assertGrantMatches(grant, key, enrollment);
+        const paired = Object.freeze({ grant, key });
+        this.#paired = paired;
+        return paired;
+    }
+    /**
+     * current returns the live pairing. An absent pairing is a lost key, and an
+     * expired grant is over: neither is repaired locally.
+     */
+    current(serverNowSeconds) {
+        const paired = this.#paired;
+        if (!paired)
+            throw new ClientFlowError("request_grant_reenrollment_required");
+        if (!integer(serverNowSeconds) || serverNowSeconds >= paired.grant.expiresAt)
+            throw new ClientFlowError("request_grant_reenrollment_required");
+        return paired;
+    }
+    /** release forgets the pairing, as logout or a lost key requires. */
+    release() {
+        this.#paired = undefined;
+    }
+}
+/**
+ * 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 function assertGrantMatches(grant, key, enrollment) {
+    if (grant.publicKeyThumbprint !== key.thumbprint)
+        throw new ClientFlowError("request_grant_mismatch");
+    if (grant.binding.accountId !== enrollment.ownerId || grant.binding.servicePrincipalId !== enrollment.servicePrincipalId ||
+        grant.binding.walletId !== enrollment.walletId || grant.bounds.network !== enrollment.network ||
+        grant.bounds.maxAmountRaw !== enrollment.maxAmountRaw || grant.bounds.maxFeeRaw !== enrollment.maxFeeRaw) {
+        throw new ClientFlowError("request_grant_mismatch");
+    }
+    if (grant.bounds.recipientAllowlist.length !== enrollment.recipientAllowlist.length ||
+        grant.bounds.recipientAllowlist.some((recipient, index) => recipient !== enrollment.recipientAllowlist[index])) {
+        throw new ClientFlowError("request_grant_mismatch");
+    }
+}
+function exactPublicJwk(value) {
+    if (value === null || typeof value !== "object" || Array.isArray(value))
+        throw new ClientFlowError("invalid_request_key");
+    const jwk = value;
+    // A WebCrypto export carries advertised usage metadata; every other member,
+    // and any private member, refuses the key outright.
+    const allowed = new Set(["kty", "crv", "x", "y", "ext", "key_ops"]);
+    if (Object.keys(jwk).some((member) => !allowed.has(member)))
+        throw new ClientFlowError("invalid_request_key");
+    if (jwk.kty !== "EC" || jwk.crv !== "P-256" || typeof jwk.x !== "string" || typeof jwk.y !== "string" ||
+        !coordinate.test(jwk.x) || !coordinate.test(jwk.y)) {
+        throw new ClientFlowError("invalid_request_key");
+    }
+    return Object.freeze({ kty: "EC", crv: "P-256", x: jwk.x, y: jwk.y });
+}
+function exactAllowlist(value, code) {
+    if (!Array.isArray(value) || value.length < 1 || value.length > MaxRequestGrantRecipients)
+        throw new ClientFlowError(code);
+    const allowlist = [];
+    for (const recipient of value) {
+        if (typeof recipient !== "string" || !grantRecipient.test(recipient) || allowlist.includes(recipient))
+            throw new ClientFlowError(code);
+        allowlist.push(recipient);
+    }
+    return Object.freeze(allowlist);
+}
+function rawQuantity(value, positive) {
+    if (!canonicalDecimal(value))
+        return false;
+    const quantity = BigInt(value);
+    return quantity <= maxUint256 && (!positive || quantity > 0n);
+}
+function boundIdentifier(value) {
+    if (!opaqueId(value))
+        throw new ClientFlowError("invalid_request_grant_result");
+    return value;
+}
+/** boundVersion accepts the canonical decimal versions of source §2.2; zero is never a live version. */
+function boundVersion(value) {
+    if (!canonicalDecimal(value) || value === "0")
+        throw new ClientFlowError("invalid_request_grant_result");
+    return value;
+}

package/dist/sends.d.ts

@@ -0,0 +1,89 @@
+import { type PageOptions } from './pages.ts';
+import { type ReplaceAction, type UserWalletEffectState, type UserWalletState } from './walletOperations.ts';
+import type { WalletEvent } from './walletEvents.ts';
+/** The recorded final fate of a send's transfer. It never changes. */
+export interface TransferOutcome {
+    readonly state: 'confirmed' | 'failed' | 'expired';
+    /** When the provider recorded the own-wallet system's report. */
+    readonly observedAt: string;
+    readonly transactionHash?: string;
+    readonly failureReason?: string;
+    /** The account's own send whose transaction the network included in this transfer's place; only with failureReason nonce_used. */
+    readonly replacedByOperationId?: string;
+}
+/**
+ * One send of the history. network, asset, recipient and amountRaw are absent
+ * once the operation's material retention expired (materialPurged): the send
+ * stays listed with its state and its transfer, and without details.
+ */
+export interface ListedSend {
+    readonly operationId: string;
+    readonly state: UserWalletState;
+    readonly effectState: UserWalletEffectState;
+    /**
+     * session_authorized: the account's session authorized a send from a linked
+     * wallet (no passkey, since 14 October 2026); user_confirmed: the passkey
+     * confirmed it; user_request_signed: a service sent it on the user's signed
+     * request; "" while it waits for a passkey.
+     */
+    readonly authorizationBasis: '' | 'user_confirmed' | 'session_authorized' | 'user_request_signed';
+    readonly createdAt: string;
+    readonly expiresAt: string;
+    readonly materialPurged: boolean;
+    /** Present for a send from a linked wallet. */
+    readonly linkedWalletId?: string;
+    /** Present for a send from a wallet bound in the provider. */
+    readonly walletId?: string;
+    readonly network?: string;
+    readonly asset?: string;
+    readonly recipient?: string;
+    readonly amountRaw?: string;
+    /** The sending address, once the own-wallet system prepared the transfer of a linked wallet. */
+    readonly address?: string;
+    /**
+     * Present for a send that replaces an earlier one the network had not
+     * included: that send's operation, and "speed_up" or "cancel". network,
+     * asset, recipient and amountRaw are then what the replacing transaction
+     * itself moves, for a cancel nothing ("0") to the wallet's own address.
+     */
+    readonly replacesOperationId?: string;
+    readonly replaceAction?: ReplaceAction;
+    /** The text the transfer carries to its recipient, on TON. */
+    readonly comment?: string;
+    /** The network's hash of a send from a linked wallet the own-wallet system accepted. */
+    readonly transactionHash?: string;
+    /** The final fate of that send's transfer; absent until transferStatus() read a final state. */
+    readonly transfer?: TransferOutcome;
+}
+export interface SendPage {
+    readonly requestId: string;
+    readonly items: readonly ListedSend[];
+    readonly hasMore: boolean;
+    readonly nextCursor?: string;
+}
+/** The path of one page of the send history. */
+export declare function sendsPath(options?: PageOptions): {
+    path: string;
+    signal?: AbortSignal;
+};
+/** Parses one closed page of the send history. */
+export declare function parseSendPage(payload: unknown): SendPage;
+/**
+ * Says whether a wallet event is the network's record of the transaction with
+ * this hash on this network: true or false where an event's sourceReference
+ * is the transaction hash, and undefined on every other network, where
+ * nothing ties an event to a hash yet. On the EVM networks and TRON the two
+ * are one hexadecimal hash and differ at most in a 0x prefix and letter case.
+ * On Solana both are the transaction's signature in base58, where case is
+ * part of the value. On TON the event names the transaction the network made
+ * and the own-wallet system names the message it sent; the two hashes differ.
+ */
+export declare function eventOfTransaction(event: WalletEvent, networkId: string, transactionHash: string): boolean | undefined;
+/**
+ * The wallet events that record one listed send on its network: the
+ * withdrawal from the sending wallet and any activity of the same
+ * transaction. It returns undefined where events cannot be tied to the send
+ * (no hash yet, details purged, or a network without that tie), and an empty
+ * list where they can and none of the given events is of this send.
+ */
+export declare function sendEvents(send: ListedSend, events: readonly WalletEvent[]): readonly WalletEvent[] | undefined;