@shuttle.technology/authorization 0.1.0 → 0.2.0

package/dist/errors.d.ts

@@ -0,0 +1,280 @@
+/**
+ * The provider's error codes: every code of the ErrorCode enum of the
+ * committed OpenAPI document, each with the HTTP status, `retryable` and
+ * `next_action` it is always answered with. An answer that disagrees with this
+ * table is refused as `invalid_error_response`, so a code an application
+ * switches on is always one of these.
+ */
+import type { NextAction } from "./auth.ts";
+export interface AuthorizationErrorContract {
+    readonly status: number;
+    readonly retryable: boolean;
+    readonly nextAction: NextAction;
+}
+declare const contracts: {
+    readonly INVALID_REQUEST: {
+        readonly status: 400;
+        readonly retryable: false;
+        readonly nextAction: "none";
+    };
+    readonly REGISTRATION_SCOPE_SELECTION_REQUIRED: {
+        readonly status: 409;
+        readonly retryable: false;
+        readonly nextAction: "none";
+    };
+    readonly CURSOR_INVALID: {
+        readonly status: 400;
+        readonly retryable: false;
+        readonly nextAction: "none";
+    };
+    readonly UNSUPPORTED_VERSION: {
+        readonly status: 400;
+        readonly retryable: false;
+        readonly nextAction: "none";
+    };
+    readonly UNAUTHORIZED: {
+        readonly status: 401;
+        readonly retryable: false;
+        readonly nextAction: "reauthenticate";
+    };
+    readonly SCOPE_DENIED: {
+        readonly status: 403;
+        readonly retryable: false;
+        readonly nextAction: "none";
+    };
+    readonly ORIGIN_NOT_ALLOWED: {
+        readonly status: 403;
+        readonly retryable: false;
+        readonly nextAction: "none";
+    };
+    readonly LIMIT_PER_TRANSFER_EXCEEDED: {
+        readonly status: 403;
+        readonly retryable: false;
+        readonly nextAction: "none";
+    };
+    readonly LIMIT_DAILY_EXCEEDED: {
+        readonly status: 403;
+        readonly retryable: false;
+        readonly nextAction: "none";
+    };
+    readonly RECIPIENT_NOT_ALLOWED: {
+        readonly status: 403;
+        readonly retryable: false;
+        readonly nextAction: "none";
+    };
+    readonly CONFIRMATION_METHOD_UNAVAILABLE: {
+        readonly status: 403;
+        readonly retryable: false;
+        readonly nextAction: "use_passkey";
+    };
+    readonly USER_PROOF_REQUIRED: {
+        readonly status: 403;
+        readonly retryable: false;
+        readonly nextAction: "sign_user_request";
+    };
+    readonly USER_PROOF_INVALID: {
+        readonly status: 403;
+        readonly retryable: false;
+        readonly nextAction: "sign_user_request";
+    };
+    readonly REQUEST_GRANT_INVALID: {
+        readonly status: 403;
+        readonly retryable: false;
+        readonly nextAction: "use_passkey";
+    };
+    readonly DEBIT_PERMISSION_INVALID: {
+        readonly status: 403;
+        readonly retryable: false;
+        readonly nextAction: "none";
+    };
+    readonly NOT_FOUND: {
+        readonly status: 404;
+        readonly retryable: false;
+        readonly nextAction: "none";
+    };
+    readonly IDENTITY_NOT_REGISTERED: {
+        readonly status: 409;
+        readonly retryable: false;
+        readonly nextAction: "start_signup";
+    };
+    readonly IDENTITY_ALREADY_REGISTERED: {
+        readonly status: 409;
+        readonly retryable: false;
+        readonly nextAction: "start_login";
+    };
+    readonly IDENTITY_ALREADY_LINKED: {
+        readonly status: 409;
+        readonly retryable: false;
+        readonly nextAction: "none";
+    };
+    readonly LAST_FACTOR: {
+        readonly status: 409;
+        readonly retryable: false;
+        readonly nextAction: "none";
+    };
+    readonly CONFIRMATION_REPLAYED: {
+        readonly status: 409;
+        readonly retryable: false;
+        readonly nextAction: "none";
+    };
+    readonly CANNOT_CANCEL: {
+        readonly status: 409;
+        readonly retryable: false;
+        readonly nextAction: "none";
+    };
+    readonly VERSION_CONFLICT: {
+        readonly status: 409;
+        readonly retryable: false;
+        readonly nextAction: "refresh_resource";
+    };
+    readonly AUTHORIZATION_STALE: {
+        readonly status: 409;
+        readonly retryable: false;
+        readonly nextAction: "refresh_resource";
+    };
+    readonly IDEMPOTENCY_CONFLICT: {
+        readonly status: 409;
+        readonly retryable: false;
+        readonly nextAction: "lookup_operation";
+    };
+    readonly USER_PROOF_REPLAYED: {
+        readonly status: 409;
+        readonly retryable: false;
+        readonly nextAction: "lookup_operation";
+    };
+    readonly OPERATION_NOT_AUTHORIZED: {
+        readonly status: 409;
+        readonly retryable: false;
+        readonly nextAction: "use_passkey";
+    };
+    readonly RESULT_NOT_READY: {
+        readonly status: 409;
+        readonly retryable: true;
+        readonly nextAction: "wait_for_result";
+    };
+    readonly TRANSFER_IN_FLIGHT: {
+        readonly status: 409;
+        readonly retryable: true;
+        readonly nextAction: "retry_same_request";
+    };
+    readonly ATTEMPT_EXPIRED: {
+        readonly status: 410;
+        readonly retryable: false;
+        readonly nextAction: "reauthenticate";
+    };
+    readonly OPERATION_EXPIRED: {
+        readonly status: 410;
+        readonly retryable: false;
+        readonly nextAction: "none";
+    };
+    readonly RESULT_EXPIRED: {
+        readonly status: 410;
+        readonly retryable: false;
+        readonly nextAction: "none";
+    };
+    readonly RESYNC_REQUIRED: {
+        readonly status: 410;
+        readonly retryable: false;
+        readonly nextAction: "resync_streams";
+    };
+    readonly USER_PROOF_EXPIRED: {
+        readonly status: 410;
+        readonly retryable: false;
+        readonly nextAction: "sign_user_request";
+    };
+    readonly CAPABILITY_UNAVAILABLE: {
+        readonly status: 422;
+        readonly retryable: false;
+        readonly nextAction: "none";
+    };
+    readonly RECOVERY_UNAVAILABLE: {
+        readonly status: 422;
+        readonly retryable: false;
+        readonly nextAction: "none";
+    };
+    readonly PAYLOAD_NOT_SUPPORTED: {
+        readonly status: 422;
+        readonly retryable: false;
+        readonly nextAction: "none";
+    };
+    readonly RATE_LIMITED: {
+        readonly status: 429;
+        readonly retryable: true;
+        readonly nextAction: "retry_same_request";
+    };
+    readonly DEPENDENCY_UNAVAILABLE: {
+        readonly status: 503;
+        readonly retryable: true;
+        readonly nextAction: "retry_same_request";
+    };
+    readonly NETWORK_FEE_TOO_HIGH: {
+        readonly status: 503;
+        readonly retryable: true;
+        readonly nextAction: "retry_same_request";
+    };
+    readonly INSUFFICIENT_BALANCE: {
+        readonly status: 422;
+        readonly retryable: false;
+        readonly nextAction: "none";
+    };
+    readonly WALLET_POLICY_DENIED: {
+        readonly status: 403;
+        readonly retryable: false;
+        readonly nextAction: "none";
+    };
+    readonly TENANT_AUTH_UNAVAILABLE: {
+        readonly status: 503;
+        readonly retryable: true;
+        readonly nextAction: "retry_same_request";
+    };
+    readonly AUDIT_UNAVAILABLE: {
+        readonly status: 503;
+        readonly retryable: true;
+        readonly nextAction: "retry_same_request";
+    };
+    readonly ADAPTER_INTEGRITY_CONFLICT: {
+        readonly status: 503;
+        readonly retryable: false;
+        readonly nextAction: "none";
+    };
+    readonly INTERNAL_ERROR: {
+        readonly status: 500;
+        readonly retryable: true;
+        readonly nextAction: "retry_same_request";
+    };
+};
+/** One code of the provider's ErrorCode enum. */
+export type AuthorizationErrorCode = keyof typeof contracts;
+/** Every code, with the status, `retryable` and `nextAction` it is answered with. */
+export declare const AuthorizationErrorContracts: Readonly<Record<AuthorizationErrorCode, AuthorizationErrorContract>>;
+/** Every code of the provider's ErrorCode enum. */
+export declare const AuthorizationErrorCodes: readonly AuthorizationErrorCode[];
+export declare function isAuthorizationErrorCode(value: unknown): value is AuthorizationErrorCode;
+/**
+ * The refusals of a Mode C transfer that the person's app signed and the
+ * service forwarded, besides the answers every request can get. The proof:
+ * `USER_PROOF_REQUIRED`, `USER_PROOF_INVALID`, `USER_PROOF_EXPIRED`, and
+ * `USER_PROOF_REPLAYED` or `IDEMPOTENCY_CONFLICT` for a reused one. The grant:
+ * `REQUEST_GRANT_INVALID` when it is not this service's, has ended or was
+ * enrolled on other bounds. The amount and the recipient, against the grant's
+ * bounds and the wallet's limits: `LIMIT_PER_TRANSFER_EXCEEDED`,
+ * `LIMIT_DAILY_EXCEEDED`, `RECIPIENT_NOT_ALLOWED`. The fee:
+ * `NETWORK_FEE_TOO_HIGH`. The balance, short of the amount and the fee's
+ * ceiling: `INSUFFICIENT_BALANCE`. The wallet system's own signing policy:
+ * `WALLET_POLICY_DENIED`. A refused transfer moved nothing.
+ */
+export declare const ModeCRefusals: readonly ["USER_PROOF_REQUIRED", "USER_PROOF_INVALID", "USER_PROOF_EXPIRED", "USER_PROOF_REPLAYED", "IDEMPOTENCY_CONFLICT", "REQUEST_GRANT_INVALID", "LIMIT_PER_TRANSFER_EXCEEDED", "LIMIT_DAILY_EXCEEDED", "RECIPIENT_NOT_ALLOWED", "NETWORK_FEE_TOO_HIGH", "INSUFFICIENT_BALANCE", "WALLET_POLICY_DENIED"];
+export type ModeCRefusal = (typeof ModeCRefusals)[number];
+export declare const isModeCRefusal: (code: unknown) => code is ModeCRefusal;
+/**
+ * The status of a write that possibly committed: it keeps its code and answers retryable false with
+ * lookup_operation and the operation to look up, at 500 for a code that is 500 and otherwise at 503
+ * (the server's error encoder).
+ */
+export declare const possibleCommitStatus: (code: AuthorizationErrorCode) => number;
+/**
+ * The codes the server names an operation with while keeping their own tuple: its WithOperationID call
+ * sites and the platform-custody result read. Every other operation_id is a possible commit.
+ */
+export declare const operationIdCodes: ReadonlySet<string>;
+export {};

package/dist/errors.js

@@ -0,0 +1,85 @@
+const contracts = {
+    INVALID_REQUEST: { status: 400, retryable: false, nextAction: "none" },
+    REGISTRATION_SCOPE_SELECTION_REQUIRED: { status: 409, retryable: false, nextAction: "none" },
+    CURSOR_INVALID: { status: 400, retryable: false, nextAction: "none" },
+    UNSUPPORTED_VERSION: { status: 400, retryable: false, nextAction: "none" },
+    UNAUTHORIZED: { status: 401, retryable: false, nextAction: "reauthenticate" },
+    SCOPE_DENIED: { status: 403, retryable: false, nextAction: "none" },
+    ORIGIN_NOT_ALLOWED: { status: 403, retryable: false, nextAction: "none" },
+    LIMIT_PER_TRANSFER_EXCEEDED: { status: 403, retryable: false, nextAction: "none" },
+    LIMIT_DAILY_EXCEEDED: { status: 403, retryable: false, nextAction: "none" },
+    RECIPIENT_NOT_ALLOWED: { status: 403, retryable: false, nextAction: "none" },
+    CONFIRMATION_METHOD_UNAVAILABLE: { status: 403, retryable: false, nextAction: "use_passkey" },
+    USER_PROOF_REQUIRED: { status: 403, retryable: false, nextAction: "sign_user_request" },
+    USER_PROOF_INVALID: { status: 403, retryable: false, nextAction: "sign_user_request" },
+    REQUEST_GRANT_INVALID: { status: 403, retryable: false, nextAction: "use_passkey" },
+    DEBIT_PERMISSION_INVALID: { status: 403, retryable: false, nextAction: "none" },
+    NOT_FOUND: { status: 404, retryable: false, nextAction: "none" },
+    IDENTITY_NOT_REGISTERED: { status: 409, retryable: false, nextAction: "start_signup" },
+    IDENTITY_ALREADY_REGISTERED: { status: 409, retryable: false, nextAction: "start_login" },
+    IDENTITY_ALREADY_LINKED: { status: 409, retryable: false, nextAction: "none" },
+    LAST_FACTOR: { status: 409, retryable: false, nextAction: "none" },
+    CONFIRMATION_REPLAYED: { status: 409, retryable: false, nextAction: "none" },
+    CANNOT_CANCEL: { status: 409, retryable: false, nextAction: "none" },
+    VERSION_CONFLICT: { status: 409, retryable: false, nextAction: "refresh_resource" },
+    AUTHORIZATION_STALE: { status: 409, retryable: false, nextAction: "refresh_resource" },
+    IDEMPOTENCY_CONFLICT: { status: 409, retryable: false, nextAction: "lookup_operation" },
+    USER_PROOF_REPLAYED: { status: 409, retryable: false, nextAction: "lookup_operation" },
+    OPERATION_NOT_AUTHORIZED: { status: 409, retryable: false, nextAction: "use_passkey" },
+    RESULT_NOT_READY: { status: 409, retryable: true, nextAction: "wait_for_result" },
+    TRANSFER_IN_FLIGHT: { status: 409, retryable: true, nextAction: "retry_same_request" },
+    ATTEMPT_EXPIRED: { status: 410, retryable: false, nextAction: "reauthenticate" },
+    OPERATION_EXPIRED: { status: 410, retryable: false, nextAction: "none" },
+    RESULT_EXPIRED: { status: 410, retryable: false, nextAction: "none" },
+    RESYNC_REQUIRED: { status: 410, retryable: false, nextAction: "resync_streams" },
+    USER_PROOF_EXPIRED: { status: 410, retryable: false, nextAction: "sign_user_request" },
+    CAPABILITY_UNAVAILABLE: { status: 422, retryable: false, nextAction: "none" },
+    RECOVERY_UNAVAILABLE: { status: 422, retryable: false, nextAction: "none" },
+    PAYLOAD_NOT_SUPPORTED: { status: 422, retryable: false, nextAction: "none" },
+    RATE_LIMITED: { status: 429, retryable: true, nextAction: "retry_same_request" },
+    DEPENDENCY_UNAVAILABLE: { status: 503, retryable: true, nextAction: "retry_same_request" },
+    NETWORK_FEE_TOO_HIGH: { status: 503, retryable: true, nextAction: "retry_same_request" },
+    INSUFFICIENT_BALANCE: { status: 422, retryable: false, nextAction: "none" },
+    WALLET_POLICY_DENIED: { status: 403, retryable: false, nextAction: "none" },
+    TENANT_AUTH_UNAVAILABLE: { status: 503, retryable: true, nextAction: "retry_same_request" },
+    AUDIT_UNAVAILABLE: { status: 503, retryable: true, nextAction: "retry_same_request" },
+    ADAPTER_INTEGRITY_CONFLICT: { status: 503, retryable: false, nextAction: "none" },
+    INTERNAL_ERROR: { status: 500, retryable: true, nextAction: "retry_same_request" },
+};
+/** Every code, with the status, `retryable` and `nextAction` it is answered with. */
+export const AuthorizationErrorContracts = Object.freeze(contracts);
+/** Every code of the provider's ErrorCode enum. */
+export const AuthorizationErrorCodes = Object.freeze(Object.keys(contracts));
+export function isAuthorizationErrorCode(value) {
+    return typeof value === "string" && Object.prototype.hasOwnProperty.call(contracts, value);
+}
+/**
+ * The refusals of a Mode C transfer that the person's app signed and the
+ * service forwarded, besides the answers every request can get. The proof:
+ * `USER_PROOF_REQUIRED`, `USER_PROOF_INVALID`, `USER_PROOF_EXPIRED`, and
+ * `USER_PROOF_REPLAYED` or `IDEMPOTENCY_CONFLICT` for a reused one. The grant:
+ * `REQUEST_GRANT_INVALID` when it is not this service's, has ended or was
+ * enrolled on other bounds. The amount and the recipient, against the grant's
+ * bounds and the wallet's limits: `LIMIT_PER_TRANSFER_EXCEEDED`,
+ * `LIMIT_DAILY_EXCEEDED`, `RECIPIENT_NOT_ALLOWED`. The fee:
+ * `NETWORK_FEE_TOO_HIGH`. The balance, short of the amount and the fee's
+ * ceiling: `INSUFFICIENT_BALANCE`. The wallet system's own signing policy:
+ * `WALLET_POLICY_DENIED`. A refused transfer moved nothing.
+ */
+export const ModeCRefusals = Object.freeze([
+    "USER_PROOF_REQUIRED", "USER_PROOF_INVALID", "USER_PROOF_EXPIRED", "USER_PROOF_REPLAYED", "IDEMPOTENCY_CONFLICT",
+    "REQUEST_GRANT_INVALID", "LIMIT_PER_TRANSFER_EXCEEDED", "LIMIT_DAILY_EXCEEDED", "RECIPIENT_NOT_ALLOWED", "NETWORK_FEE_TOO_HIGH", "INSUFFICIENT_BALANCE", "WALLET_POLICY_DENIED",
+]);
+export const isModeCRefusal = (code) => ModeCRefusals.includes(code);
+/**
+ * The status of a write that possibly committed: it keeps its code and answers retryable false with
+ * lookup_operation and the operation to look up, at 500 for a code that is 500 and otherwise at 503
+ * (the server's error encoder).
+ */
+export const possibleCommitStatus = (code) => AuthorizationErrorContracts[code].status === 500 ? 500 : 503;
+/**
+ * The codes the server names an operation with while keeping their own tuple: its WithOperationID call
+ * sites and the platform-custody result read. Every other operation_id is a possible commit.
+ */
+export const operationIdCodes = new Set(["AUTHORIZATION_STALE", "USER_PROOF_REQUIRED", "IDEMPOTENCY_CONFLICT", "RESULT_NOT_READY", "OPERATION_EXPIRED", "RESULT_EXPIRED",
+    "INVALID_REQUEST", "CAPABILITY_UNAVAILABLE", "ADAPTER_INTEGRITY_CONFLICT", "DEPENDENCY_UNAVAILABLE"]);

package/dist/linkedRecovery.d.ts

@@ -0,0 +1,40 @@
+import { type DisplayCommon } from "./walletDisplayParts.ts";
+import type { LinkedWalletIdentity } from "./linkedSendDisplay.ts";
+import type { DeviceSharePackage } from "./walletOperations.ts";
+/** The create body of a recovery: the account's own linked wallet and the new device key its share is sealed to. */
+export type LinkedRecoverCreate = {
+    owner_type: "account";
+    owner_id: string;
+    kind: "wallet.recover";
+    linked_wallet_id: string;
+    payload: {
+        recipient_public_key: string;
+    };
+};
+/**
+ * LinkedRecoverDisplay is what the person confirms: the wallet by its address
+ * and network, and the device key its share goes to. The summary is there from
+ * the admission on, since the recovery is frozen whole when it is admitted.
+ */
+export type LinkedRecoverDisplay = DisplayCommon & LinkedWalletIdentity & {
+    kind: "wallet.recover";
+    network: string;
+    address: string;
+    recipientPublicKey: string;
+    preparedSummary?: string;
+};
+export declare function linkedRecoverCreate(ownerId: string, linkedWalletId: string, recipientPublicKey: string): LinkedRecoverCreate;
+/** validLinkedRecoverCreate checks the members a recovery adds to the common ones validateUserWalletCreate checked. */
+export declare function validLinkedRecoverCreate(common: Record<string, unknown>): boolean;
+export declare function parseLinkedRecoverDisplay(value: unknown): LinkedRecoverDisplay;
+/** The released result of a recovery: the wallet it is of and its device share, sealed to the new device key. */
+export declare function parseRecoveredShareResult(requestId: unknown, value: unknown, expectedOperationId: string): {
+    requestId: string;
+    result: {
+        operationId: string;
+        kind: "device_share_recovered";
+        receiptId: string;
+        linkedWalletId: string;
+        deviceShare: DeviceSharePackage;
+    };
+};

package/dist/linkedRecovery.js

@@ -0,0 +1,49 @@
+// The wire of a linked wallet's device-share recovery (wallet.recover naming
+// linked_wallet_id): the closed create body, the display the person confirms
+// with the passkey, and the result, the device share sealed to the new device
+// key. deviceRecovery.ts runs it; walletOperations.ts reads it among the
+// other wallet operations.
+import { ClientFlowError, opaqueId, record } from "./auth.js";
+import { bindingRevision, displayCommon, lowerHexBytes, lowerUUID, summaryOf, walletRecipient } from "./walletDisplayParts.js";
+const compressedP256Key = /^(02|03)[0-9a-f]{64}$/;
+const linkedNetwork = /^[-a-z0-9]{3,8}:[-_a-zA-Z0-9]{1,32}$/;
+export function linkedRecoverCreate(ownerId, linkedWalletId, recipientPublicKey) {
+    return { kind: "wallet.recover", owner_type: "account", owner_id: ownerId, linked_wallet_id: linkedWalletId, payload: { recipient_public_key: recipientPublicKey } };
+}
+/** validLinkedRecoverCreate checks the members a recovery adds to the common ones validateUserWalletCreate checked. */
+export function validLinkedRecoverCreate(common) {
+    if (common.kind !== "wallet.recover" || common.wallet_id !== undefined || !lowerUUID(common.linked_wallet_id))
+        return false;
+    const payload = common.payload;
+    return payload !== null && typeof payload === "object" && !Array.isArray(payload) && Object.keys(payload).length === 1 &&
+        typeof payload.recipient_public_key === "string" && compressedP256Key.test(payload.recipient_public_key);
+}
+export function parseLinkedRecoverDisplay(value) {
+    const display = record(value, ["kind", "owner_id", "requester_id", "result_recipient", "binding_source", "connection_id", "linked_wallet_id", "binding_revision", "network", "address", "recipient_public_key"], ["prepared_summary"]);
+    if (display.kind !== "wallet.recover" || display.binding_source !== "linked_wallet" || !lowerUUID(display.connection_id) || !lowerUUID(display.linked_wallet_id) ||
+        !bindingRevision(display.binding_revision) || typeof display.network !== "string" || !linkedNetwork.test(display.network) ||
+        typeof display.address !== "string" || !walletRecipient.test(display.address) || typeof display.recipient_public_key !== "string" || !compressedP256Key.test(display.recipient_public_key)) {
+        throw new ClientFlowError("invalid_server_response");
+    }
+    return {
+        ...displayCommon(display), kind: "wallet.recover", connectionId: display.connection_id, linkedWalletId: display.linked_wallet_id, bindingRevision: display.binding_revision,
+        network: display.network, address: display.address, recipientPublicKey: display.recipient_public_key, ...summaryOf(display.prepared_summary),
+    };
+}
+/** The released result of a recovery: the wallet it is of and its device share, sealed to the new device key. */
+export function parseRecoveredShareResult(requestId, value, expectedOperationId) {
+    const result = record(value, ["kind", "operation_id", "receipt_id", "linked_wallet_id", "device_share"]);
+    const share = record(result.device_share, ["ciphertext", "nonce", "ephemeral_public_key", "encryption_algorithm", "encryption_context"]);
+    if (!opaqueId(requestId) || result.kind !== "device_share_recovered" || result.operation_id !== expectedOperationId || !lowerUUID(result.receipt_id) || !lowerUUID(result.linked_wallet_id) ||
+        !lowerHexBytes(share.ciphertext) || !lowerHexBytes(share.nonce) || !lowerHexBytes(share.ephemeral_public_key) ||
+        typeof share.encryption_algorithm !== "string" || !/^[a-z0-9_-]{1,128}$/.test(share.encryption_algorithm) || !lowerHexBytes(share.encryption_context)) {
+        throw new ClientFlowError("invalid_server_response");
+    }
+    return {
+        requestId,
+        result: {
+            operationId: expectedOperationId, kind: "device_share_recovered", receiptId: result.receipt_id, linkedWalletId: result.linked_wallet_id,
+            deviceShare: { ciphertext: share.ciphertext, nonce: share.nonce, ephemeralPublicKey: share.ephemeral_public_key, encryptionAlgorithm: share.encryption_algorithm, encryptionContext: share.encryption_context },
+        },
+    };
+}

package/dist/linkedRegistrations.d.ts

@@ -0,0 +1,11 @@
+import type { LinkedEventsOptions, LinkedRegistrationCreate, LinkedRegistrationListOptions, LinkedRegistrationOperation, LinkedRegistrationResult, LinkedStreamsRegistrationList } from './linkedWallets.ts';
+export declare function validateLinkedRegistrationCreate(value: LinkedRegistrationCreate, ownerId: string): LinkedRegistrationCreate;
+export declare function parseLinkedRegistrationOperationEnvelope(payload: unknown): {
+    requestId: string;
+    operation: LinkedRegistrationOperation;
+};
+export declare function parseLinkedRegistrationOperation(payload: unknown): LinkedRegistrationOperation;
+export declare function parseLinkedRegistrationResult(payload: unknown, operationId: string): LinkedRegistrationResult;
+export declare function linkedRegistrationsPath(linkedWalletId: string, options?: LinkedRegistrationListOptions): string;
+export declare function linkedEventsPath(linkedWalletId: string, options?: LinkedEventsOptions): string;
+export declare function parseLinkedStreamsRegistrationList(payload: unknown, linkedWalletId: string): LinkedStreamsRegistrationList;

package/dist/linkedRegistrations.js

@@ -0,0 +1,109 @@
+// The linked-wallet registrations for tracking, as Authorization frames them:
+// the closed create body, the operation and its result, and the paths and
+// pages of a linked wallet's registrations and events. linkedWallets.ts calls
+// them and re-exports them.
+import { ClientFlowError, canonicalDecimal, deadlineAfter, integer, isNextAction, opaqueId, record, rfc3339UTC } from './auth.js';
+import { appendEventTypes, MaxStreamsCursorLength, MaxStreamsPageLimit } from './streams.js';
+import { activityTypes, assets, digest, fault, https, network, recipient, requestUUID, safeRevision, text, uuid } from './linkedChecks.js';
+export function validateLinkedRegistrationCreate(value, ownerId) {
+    const r = record(value, ['kind', 'owner_type', 'owner_id', 'linked_wallet_id', 'payload']);
+    const p = record(r.payload, ['network'], ['assets', 'activity_types']);
+    if (r.kind !== 'streams.register' || r.owner_type !== 'account' || !opaqueId(r.owner_id) || r.owner_id !== ownerId || !uuid(r.linked_wallet_id) || !network(p.network) || (p.assets !== undefined && !assets(p.assets)) || (p.activity_types !== undefined && !activityTypes(p.activity_types)))
+        throw new ClientFlowError('invalid_operation_create');
+    return value;
+}
+export function parseLinkedRegistrationOperationEnvelope(payload) {
+    const r = record(payload, ['request_id', 'operation']);
+    if (!opaqueId(r.request_id))
+        fault();
+    return { requestId: r.request_id, operation: parseLinkedRegistrationOperation(r.operation) };
+}
+export function parseLinkedRegistrationOperation(payload) {
+    const r = record(payload, ['id', 'version', 'kind', 'state', 'effect_state', 'authorization_basis', 'owner_type', 'owner_id', 'requester_id', 'binding_source', 'connection_id', 'linked_wallet_id', 'binding_revision', 'request_fingerprint', 'operation_fingerprint', 'display', 'created_at', 'expires_at', 'next_action'], ['confirmation_location']);
+    if (!opaqueId(r.id) || !canonicalDecimal(r.version) || r.kind !== 'streams.register' || r.owner_type !== 'account' || !opaqueId(r.owner_id) || !opaqueId(r.requester_id) || r.binding_source !== 'linked_wallet' || !uuid(r.connection_id) || !uuid(r.linked_wallet_id) || !safeRevision(r.binding_revision) || !digest(r.request_fingerprint) || !digest(r.operation_fingerprint) || !rfc3339UTC(r.created_at) || !rfc3339UTC(r.expires_at) || !deadlineAfter(r.created_at, r.expires_at) || !isNextAction(r.next_action) || !['awaiting_confirmation', 'authorized', 'dispatching', 'outcome_unknown', 'succeeded', 'failed', 'denied', 'canceled', 'expired'].includes(r.state) || !['no_effect', 'possible', 'known'].includes(r.effect_state) || !['', 'user_confirmed', 'session_authorized'].includes(r.authorization_basis) || (r.confirmation_location !== undefined && !https(r.confirmation_location)))
+        fault();
+    const purged = typeof r.display === 'object' && r.display !== null && 'material_purged' in r.display;
+    const d = record(r.display, ['kind', 'owner_id', 'requester_id', 'result_recipient', ...(purged ? ['material_purged'] : ['binding_source', 'connection_id', 'linked_wallet_id', 'binding_revision', 'assets', 'network', 'address', 'streams_mapping_id', 'streams_mapping_version', 'target_customer_id', 'target_project_id', 'target_environment_id'])]);
+    if (d.kind !== r.kind || d.owner_id !== r.owner_id || d.requester_id !== r.requester_id)
+        fault();
+    const common = { kind: 'streams.register', ownerId: r.owner_id, requesterId: r.requester_id, resultRecipient: recipient(d.result_recipient) };
+    let display;
+    if (purged) {
+        if (d.material_purged !== true)
+            fault();
+        display = { ...common, materialPurged: true };
+    }
+    else {
+        if (d.binding_source !== r.binding_source || d.connection_id !== r.connection_id || d.linked_wallet_id !== r.linked_wallet_id || d.binding_revision !== r.binding_revision || !assets(d.assets) || !network(d.network) || !text(d.address, 256) || !safeRevision(d.streams_mapping_version) || ![d.streams_mapping_id, d.target_customer_id, d.target_project_id, d.target_environment_id].every(opaqueId))
+            fault();
+        display = { ...common, bindingSource: 'linked_wallet', connectionId: r.connection_id, linkedWalletId: r.linked_wallet_id, bindingRevision: r.binding_revision, assets: Object.freeze([...d.assets]), network: d.network, address: d.address, streamsMappingId: d.streams_mapping_id, streamsMappingVersion: d.streams_mapping_version, targetCustomerId: d.target_customer_id, targetProjectId: d.target_project_id, targetEnvironmentId: d.target_environment_id };
+    }
+    const operation = { id: r.id, version: r.version, kind: 'streams.register', state: r.state, effectState: r.effect_state, authorizationBasis: r.authorization_basis, ownerType: 'account', ownerId: r.owner_id, requesterId: r.requester_id, bindingSource: 'linked_wallet', connectionId: r.connection_id, linkedWalletId: r.linked_wallet_id, bindingRevision: r.binding_revision, requestFingerprint: r.request_fingerprint, operationFingerprint: r.operation_fingerprint, display, createdAt: r.created_at, expiresAt: r.expires_at, nextAction: r.next_action };
+    if (r.confirmation_location !== undefined)
+        operation.confirmationLocation = r.confirmation_location;
+    return operation;
+}
+export function parseLinkedRegistrationResult(payload, operationId) {
+    const r = record(payload, ['request_id', 'result']);
+    const v = record(r.result, ['kind', 'operation_id', 'binding_source', 'connection_id', 'linked_wallet_id', 'binding_revision', 'source_registration_id', 'registration_digest', 'receipt_id']);
+    if (!opaqueId(r.request_id) || !opaqueId(v.operation_id) || v.operation_id !== operationId || v.kind !== 'streams_registration' || v.binding_source !== 'linked_wallet' || !uuid(v.connection_id) || !uuid(v.linked_wallet_id) || !safeRevision(v.binding_revision) || !text(v.source_registration_id, 128) || !text(v.receipt_id, 128) || !digest(v.registration_digest))
+        fault();
+    return { requestId: r.request_id, result: { kind: 'streams_registration', operationId: v.operation_id, bindingSource: 'linked_wallet', connectionId: v.connection_id, linkedWalletId: v.linked_wallet_id, bindingRevision: v.binding_revision, sourceRegistrationId: v.source_registration_id, registrationDigest: v.registration_digest, receiptId: v.receipt_id } };
+}
+export function linkedRegistrationsPath(linkedWalletId, options = {}) {
+    requestUUID(linkedWalletId);
+    const declared = record(options, [], ['afterRegistrationId', 'limit', 'signal']);
+    const query = new URLSearchParams();
+    if (declared.afterRegistrationId !== undefined) {
+        requestUUID(declared.afterRegistrationId);
+        query.set('after_registration_id', declared.afterRegistrationId);
+    }
+    readLimit(query, declared.limit);
+    return linkedReadPath(linkedWalletId, 'registrations', query);
+}
+export function linkedEventsPath(linkedWalletId, options = {}) {
+    requestUUID(linkedWalletId);
+    const declared = record(options, [], ['registrationId', 'cursor', 'limit', 'eventTypes', 'signal']);
+    const query = new URLSearchParams();
+    if (declared.registrationId !== undefined) {
+        requestUUID(declared.registrationId);
+        query.set('registration_id', declared.registrationId);
+    }
+    if (declared.cursor !== undefined) {
+        if (typeof declared.cursor !== 'string' || declared.cursor.length < 1 || declared.cursor.length > MaxStreamsCursorLength)
+            throw new ClientFlowError('invalid_streams_request');
+        query.set('cursor', declared.cursor);
+    }
+    readLimit(query, declared.limit);
+    appendEventTypes(query, declared.eventTypes);
+    return linkedReadPath(linkedWalletId, 'events', query);
+}
+export function parseLinkedStreamsRegistrationList(payload, linkedWalletId) {
+    const root = record(payload, ['items', 'has_more'], ['next_after_registration_id']);
+    if (!Array.isArray(root.items) || root.items.length > MaxStreamsPageLimit || typeof root.has_more !== 'boolean' || root.has_more !== Object.hasOwn(root, 'next_after_registration_id'))
+        fault();
+    const items = root.items.map(item => parseLinkedStreamsRegistration(item, linkedWalletId));
+    if (items.some((item, index) => index > 0 && items[index - 1].registrationId >= item.registrationId))
+        fault();
+    if (root.has_more && (!uuid(root.next_after_registration_id) || items.length === 0 || root.next_after_registration_id !== items.at(-1).registrationId))
+        fault();
+    const page = { items: Object.freeze(items), hasMore: root.has_more };
+    return Object.freeze(root.has_more ? { ...page, nextAfterRegistrationId: root.next_after_registration_id } : page);
+}
+function parseLinkedStreamsRegistration(payload, linkedWalletId) {
+    const r = record(payload, ['registration_id', 'binding_source', 'connection_id', 'linked_wallet_id', 'binding_revision', 'source_registration_id', 'network', 'address', 'assets', 'status', 'effective_from', 'revision', 'source_version']);
+    if (!uuid(r.registration_id) || r.binding_source !== 'linked_wallet' || !uuid(r.connection_id) || !uuid(r.linked_wallet_id) || r.linked_wallet_id !== linkedWalletId || !safeRevision(r.binding_revision) || !opaqueId(r.source_registration_id) || !network(r.network) || typeof r.address !== 'string' || !/^[A-Za-z0-9_:-]{1,256}$/.test(r.address) || !assets(r.assets) || !['pending', 'active'].includes(r.status) || typeof r.effective_from !== 'string' || new TextEncoder().encode(r.effective_from).length < 1 || new TextEncoder().encode(r.effective_from).length > 256 || !integer(r.revision) || r.revision < 1 || typeof r.source_version !== 'string' || !/^[0-9]+\.[0-9]+$/.test(r.source_version))
+        fault();
+    return Object.freeze({ registrationId: r.registration_id, bindingSource: 'linked_wallet', connectionId: r.connection_id, linkedWalletId: r.linked_wallet_id, bindingRevision: r.binding_revision, sourceRegistrationId: r.source_registration_id, network: r.network, address: r.address, assets: Object.freeze([...r.assets]), status: r.status, effectiveFrom: r.effective_from, revision: r.revision, sourceVersion: r.source_version });
+}
+function linkedReadPath(id, kind, query) {
+    const path = `/v1/linked-wallets/${id}/${kind}`;
+    return query.size === 0 ? path : `${path}?${query.toString()}`;
+}
+function readLimit(query, value) {
+    if (value === undefined)
+        return;
+    if (!integer(value) || value < 1 || value > MaxStreamsPageLimit)
+        throw new ClientFlowError('invalid_streams_request');
+    query.set('limit', String(value));
+}