@shuttle.technology/authorization 0.1.0 → 0.2.0

package/dist/linkedWallets.d.ts

@@ -2,6 +2,7 @@ import { type NextAction } from './auth.ts';
 import { type WalletEventPage } from './streams.ts';
 export { resumeCursor } from './streams.ts';
 import { type LocalOperation, type ResultRecipient } from './slice4.ts';
+export { linkedEventsPath, linkedRegistrationsPath, parseLinkedRegistrationOperation, parseLinkedRegistrationOperationEnvelope, parseLinkedRegistrationResult, parseLinkedStreamsRegistrationList, validateLinkedRegistrationCreate } from './linkedRegistrations.ts';
 import { type LinkedWalletSignalEnd, type LinkedWalletSignalHandlers } from './linkedWalletSignals.ts';
 export { linkedSignalsPath, readLinkedWalletSignals, MaxSignalWallets, type LinkedWalletSignalEnd, type LinkedWalletSignalHandlers } from './linkedWalletSignals.ts';
 import { type TransferStatus } from './transferStatus.ts';
@@ -14,6 +15,9 @@ import type { PageOptions } from './pages.ts';
 export { parseTransferStatus, transferFinal, transferStatusPath, TransferStates, type TransferState, type TransferStatus } from './transferStatus.ts';
 import { type WalletLimits, type WalletLimitsInput } from './walletLimits.ts';
 export { WalletLimitRefusals, isWalletLimitRefusal, MaxLimitCeilings, MaxLimitRecipients, type LimitAsset, type WalletCeiling, type WalletLimitRefusal, type WalletLimits, type WalletLimitsDisplay, type WalletLimitsInput } from './walletLimits.ts';
+import { DebitPermissions } from './debitPermissions.ts';
+export { DebitPermissions, MaxDebitAssets, MaxDebitRecipients, type DebitAsset, type DebitAssetBound, type DebitPermission, type DebitPermissionDisplay, type DebitPermissionInput, type DebitPermissionList, type DebitPermissionRevokeDisplay, type DebitPermissionState, type DebitShareKeys } from './debitPermissions.ts';
+import type { DeviceRecoveryOptions, LinkedDeviceShares } from './deviceShares.ts';
 import { type LinkedSendAsset, type ReplaceAction, type DeviceSharePackage, type UserWalletOperation, type UserWalletState, type UserWalletEffectState, type UserWalletAuthorizationBasis } from './walletOperations.ts';
 /** session_authorized: the account's session registered its own linked wallet; no confirmation exists. */
 export type LinkedRegistrationAuthorizationBasis = UserWalletAuthorizationBasis;
@@ -76,7 +80,6 @@ export interface LinkedRegistrationCreate {
         assets?: string[];
         activity_types?: string[];
     };
-    result_recipient?: ResultRecipient;
 }
 export interface LinkedRegistrationDisplay {
     kind: 'streams.register';
@@ -154,7 +157,6 @@ export interface LinkedSendInput {
     recipient: string;
     amountRaw: string;
     comment?: string;
-    resultRecipient?: ResultRecipient;
 }
 /**
  * The replacement of a send the network has not included. operationId is the
@@ -165,7 +167,6 @@ export interface LinkedReplaceInput {
     linkedWalletId: string;
     operationId: string;
     action: ReplaceAction;
-    resultRecipient?: ResultRecipient;
 }
 /** The own-wallet system's transport key, as that system publishes it. It carries no proof of where the key lives. */
 export interface LinkedTransportKey {
@@ -218,6 +219,8 @@ export interface LinkedWalletTransport {
     }>;
     accountId(): string;
     now(): number;
+    /** The device shares the client keeps (deviceShares.ts); absent, every call that asks the SDK for a share refuses with device_share_unavailable. */
+    devices?: LinkedDeviceShares;
 }
 export declare class LinkedWallets {
     #private;
@@ -275,7 +278,6 @@ export declare class LinkedWallets {
         network: string;
         assets?: string[];
         activityTypes?: string[];
-        resultRecipient?: ResultRecipient;
     }, idempotencyKey: string, signal?: AbortSignal): Promise<LinkedRegistrationOperation>;
     operation(operationId: string, signal?: AbortSignal): Promise<LinkedRegistrationOperation>;
     executeRegistration(operationId: string, version: string, idempotencyKey: string, signal?: AbortSignal): Promise<LinkedRegistrationOperation>;
@@ -323,11 +325,45 @@ export declare class LinkedWallets {
     transportKey(linkedWalletId: string, signal?: AbortSignal): Promise<LinkedTransportKey>;
     /**
      * Executes a prepared send, on the owner's confirm, with the device share
-     * resealed for the own-wallet system (resealDeviceShare). The provider
-     * cannot open the share. A send never prepared is refused with
-     * VERSION_CONFLICT, an expired one with OPERATION_EXPIRED.
+     * resealed for the own-wallet system. Without deviceShare the SDK supplies
+     * the share it keeps (deviceShareFor()), recovered first with one passkey
+     * confirmation when this browser holds none; an app that keeps its own share
+     * passes it resealed (resealDeviceShare). The provider cannot open the share.
+     * A send never prepared is refused with VERSION_CONFLICT, an expired one
+     * with OPERATION_EXPIRED.
      */
-    executeSend(operationId: string, version: string, idempotencyKey: string, deviceShare: DeviceSharePackage, signal?: AbortSignal): Promise<UserWalletOperation>;
+    executeSend(operationId: string, version: string, idempotencyKey: string, deviceShare?: DeviceSharePackage, signal?: AbortSignal): Promise<UserWalletOperation>;
+    /**
+     * The device share the SDK keeps for this wallet, resealed to the
+     * own-wallet system's transport key read right before: what executeSend()
+     * sends and what a Mode C request is signed with (signLinkedMediatedRequest).
+     * A browser that holds no share of the wallet (another domain, cleared site
+     * data, another browser or device) recovers it first: the person confirms
+     * once with the passkey on the provider's page, and the share the wallet had
+     * elsewhere stops working. Two tabs never recover the same wallet at once.
+     */
+    deviceShareFor(linkedWalletId: string, signal?: AbortSignal): Promise<DeviceSharePackage>;
+    /**
+     * The device key of the wallet's latest creation or recovery the provider
+     * made, as 33-byte compressed hex; absent when it knows none. A share kept
+     * here that is sealed to another key was replaced by a recovery elsewhere.
+     */
+    deviceKey(linkedWalletId: string, signal?: AbortSignal): Promise<{
+        requestId: string;
+        devicePublicKey?: string;
+    }>;
+    /** Whether this browser holds a current device share of the wallet; without one the next send recovers it with the passkey. */
+    hasDeviceShare(linkedWalletId: string, signal?: AbortSignal): Promise<boolean>;
+    /**
+     * Recovers the wallet's device share onto this browser when it holds no
+     * current one, as deviceShareFor() would, for an app that does it ahead of a
+     * transfer; force recovers even then. credentialId names the passkey that
+     * confirms it, by default the account's newest. Answers whether a recovery
+     * ran. Optional: sends recover by themselves.
+     */
+    recoverDevice(linkedWalletId: string, options?: DeviceRecoveryOptions & {
+        force?: boolean;
+    }): Promise<boolean>;
     /**
      * What became of the transfer a send prepared: on its way, confirmed by the
      * network, or failed and why. The send's operation succeeds when the
@@ -352,6 +388,8 @@ export declare class LinkedWallets {
      * executeOperation() apply it. A send the limits refuse answers one of WalletLimitRefusals.
      */
     setLimits(linkedWalletId: string, limits: WalletLimitsInput, idempotencyKey: string, signal?: AbortSignal): Promise<LocalOperation>;
+    /** The permissions the account lets services debit its linked wallets by, without the device (debitPermissions.ts). */
+    debitPermissions(): DebitPermissions;
 }
 export declare function parseWalletConnection(payload: unknown): WalletConnection;
 export declare function parseLinkedWallet(payload: unknown): LinkedWallet;
@@ -361,13 +399,3 @@ export declare function parseLinkedWalletList(payload: unknown): {
 };
 export declare function parseWalletLinkChallenge(payload: unknown, now: number): WalletLinkChallenge;
 export declare function validateWalletLinkAssertion(value: WalletLinkAssertion): WalletLinkAssertion;
-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/linkedWallets.js

@@ -8,10 +8,12 @@
 // shown, executeSend() sends it on the owner's confirm). No passkey is asked
 // for either (owner decisions of 8 and 14 October 2026); a passkey still
 // confirms creating a wallet.
-import { ClientFlowError, canonicalDecimal, deadlineAfter, integer, isNextAction, opaqueId, record, rfc3339UTC, unexpiredRFC3339 } from './auth.js';
-import { appendEventTypes, parseWalletEventPage, MaxStreamsActivityTypes, MaxStreamsCursorLength, MaxStreamsPageLimit } from './streams.js';
+import { ClientFlowError, canonicalDecimal, integer, opaqueId, record, rfc3339UTC, unexpiredRFC3339 } from './auth.js';
+import { parseWalletEventPage } from './streams.js';
 export { resumeCursor } from './streams.js';
 import { parseOperationEnvelope } from './slice4.js';
+import { linkedEventsPath, linkedRegistrationsPath, parseLinkedRegistrationOperationEnvelope, parseLinkedRegistrationResult, parseLinkedStreamsRegistrationList, validateLinkedRegistrationCreate } from './linkedRegistrations.js';
+export { linkedEventsPath, linkedRegistrationsPath, parseLinkedRegistrationOperation, parseLinkedRegistrationOperationEnvelope, parseLinkedRegistrationResult, parseLinkedStreamsRegistrationList, validateLinkedRegistrationCreate } from './linkedRegistrations.js';
 import { linkedSignalsPath, readLinkedWalletSignals } from './linkedWalletSignals.js';
 export { linkedSignalsPath, readLinkedWalletSignals, MaxSignalWallets } from './linkedWalletSignals.js';
 import { parseTransferStatus, transferStatusPath } from './transferStatus.js';
@@ -22,7 +24,9 @@ export { eventOfTransaction, parseSendPage, sendEvents, sendsPath } from './send
 export { parseTransferStatus, transferFinal, transferStatusPath, TransferStates } from './transferStatus.js';
 import { parseWalletLimits, walletLimitsCreate } from './walletLimits.js';
 export { WalletLimitRefusals, isWalletLimitRefusal, MaxLimitCeilings, MaxLimitRecipients } from './walletLimits.js';
-import { activityTypes, assets, b64, digest, fault, hex, https, network, publicKey, recipient, requestID, requestUUID, safeRevision, text, token, uuid } from './linkedChecks.js';
+import { DebitPermissions } from './debitPermissions.js';
+export { DebitPermissions, MaxDebitAssets, MaxDebitRecipients } from './debitPermissions.js';
+import { b64, fault, hex, network, publicKey, requestID, requestUUID, safeRevision, text, token, uuid } from './linkedChecks.js';
 import { linkedSendAsset, parseUserWalletOperationEnvelope, replaceAction, transferComment } from './walletOperations.js';
 export class LinkedWallets {
     #transport;
@@ -140,15 +144,13 @@ export class LinkedWallets {
      * executeRegistration() with its version dispatches it.
      */
     register(input, idempotencyKey, signal) {
-        record(input, ['linkedWalletId', 'network'], ['assets', 'activityTypes', 'resultRecipient']);
+        record(input, ['linkedWalletId', 'network'], ['assets', 'activityTypes']);
         const create = { kind: 'streams.register', owner_type: 'account', owner_id: this.#transport.accountId(), linked_wallet_id: input.linkedWalletId, payload: { network: input.network } };
         if (input.assets !== undefined)
             create.payload.assets = input.assets;
         // An empty selection means deposits only and is not sent; any other value is checked with the whole request.
         if (input.activityTypes !== undefined && !(Array.isArray(input.activityTypes) && input.activityTypes.length === 0))
             create.payload.activity_types = input.activityTypes;
-        if (input.resultRecipient !== undefined)
-            create.result_recipient = input.resultRecipient;
         return this.createRegistration(create, idempotencyKey, signal);
     }
     async operation(operationId, signal) {
@@ -181,7 +183,7 @@ export class LinkedWallets {
      * executeSend() with the device share.
      */
     async send(input, idempotencyKey, signal) {
-        const declared = record(input, ['linkedWalletId', 'network', 'asset', 'recipient', 'amountRaw'], ['comment', 'resultRecipient']);
+        const declared = record(input, ['linkedWalletId', 'network', 'asset', 'recipient', 'amountRaw'], ['comment']);
         requestID(idempotencyKey);
         if (!uuid(declared.linkedWalletId) || !network(declared.network) || !linkedSendAsset(declared.asset) || typeof declared.recipient !== 'string' || !/^[\x21-\x7e]{1,256}$/.test(declared.recipient) ||
             !canonicalDecimal(declared.amountRaw) || declared.amountRaw === '0' || declared.amountRaw.length > 78 ||
@@ -192,8 +194,6 @@ export class LinkedWallets {
         if (declared.comment !== undefined)
             sent.comment = declared.comment;
         const create = { kind: 'wallet.send', owner_type: 'account', owner_id: this.#transport.accountId(), linked_wallet_id: declared.linkedWalletId, payload: sent };
-        if (declared.resultRecipient !== undefined)
-            create.result_recipient = recipient(declared.resultRecipient);
         const { payload, accountId } = await this.#transport.write('/v1/operations', 'POST', create, signal, idempotencyKey);
         const operation = parseUserWalletOperationEnvelope(payload).operation;
         const shown = operation.display;
@@ -214,14 +214,12 @@ export class LinkedWallets {
      * transferStatus() of both.
      */
     async replaceSend(input, idempotencyKey, signal) {
-        const declared = record(input, ['linkedWalletId', 'operationId', 'action'], ['resultRecipient']);
+        const declared = record(input, ['linkedWalletId', 'operationId', 'action']);
         requestID(idempotencyKey);
         if (!uuid(declared.linkedWalletId) || !opaqueId(declared.operationId) || !replaceAction(declared.action))
             throw new ClientFlowError('invalid_operation_create');
         const create = { kind: 'wallet.send', owner_type: 'account', owner_id: this.#transport.accountId(), linked_wallet_id: declared.linkedWalletId,
             payload: { action: declared.action, replaces_operation_id: declared.operationId } };
-        if (declared.resultRecipient !== undefined)
-            create.result_recipient = recipient(declared.resultRecipient);
         const { payload, accountId } = await this.#transport.write('/v1/operations', 'POST', create, signal, idempotencyKey);
         const operation = parseUserWalletOperationEnvelope(payload).operation;
         const shown = operation.display;
@@ -267,15 +265,26 @@ export class LinkedWallets {
     }
     /**
      * Executes a prepared send, on the owner's confirm, with the device share
-     * resealed for the own-wallet system (resealDeviceShare). The provider
-     * cannot open the share. A send never prepared is refused with
-     * VERSION_CONFLICT, an expired one with OPERATION_EXPIRED.
+     * resealed for the own-wallet system. Without deviceShare the SDK supplies
+     * the share it keeps (deviceShareFor()), recovered first with one passkey
+     * confirmation when this browser holds none; an app that keeps its own share
+     * passes it resealed (resealDeviceShare). The provider cannot open the share.
+     * A send never prepared is refused with VERSION_CONFLICT, an expired one
+     * with OPERATION_EXPIRED.
      */
     async executeSend(operationId, version, idempotencyKey, deviceShare, signal) {
         requestID(operationId);
         requestID(idempotencyKey);
+        if (!canonicalDecimal(version))
+            throw new ClientFlowError('invalid_execute_request');
+        if (deviceShare === undefined) {
+            const linkedWalletId = parseUserWalletOperationEnvelope(await this.#transport.get(`/v1/operations/${operationId}`, signal)).operation.linkedWallet?.linkedWalletId;
+            if (linkedWalletId === undefined)
+                throw new ClientFlowError('invalid_execute_request');
+            deviceShare = await this.deviceShareFor(linkedWalletId, signal);
+        }
         const share = record(deviceShare, ['ciphertext', 'nonce', 'ephemeralPublicKey', 'encryptionAlgorithm', 'encryptionContext']);
-        if (!canonicalDecimal(version) || ![share.ciphertext, share.nonce, share.ephemeralPublicKey, share.encryptionContext].every(hex) || typeof share.encryptionAlgorithm !== 'string')
+        if (![share.ciphertext, share.nonce, share.ephemeralPublicKey, share.encryptionContext].every(hex) || typeof share.encryptionAlgorithm !== 'string')
             throw new ClientFlowError('invalid_execute_request');
         const body = { device_share: { ciphertext: share.ciphertext, nonce: share.nonce, ephemeral_public_key: share.ephemeralPublicKey, encryption_algorithm: share.encryptionAlgorithm, encryption_context: share.encryptionContext } };
         const operation = parseUserWalletOperationEnvelope((await this.#transport.write(`/v1/operations/${operationId}/execute`, 'POST', body, signal, idempotencyKey, version)).payload).operation;
@@ -283,6 +292,64 @@ export class LinkedWallets {
             fault();
         return operation;
     }
+    /**
+     * The device share the SDK keeps for this wallet, resealed to the
+     * own-wallet system's transport key read right before: what executeSend()
+     * sends and what a Mode C request is signed with (signLinkedMediatedRequest).
+     * A browser that holds no share of the wallet (another domain, cleared site
+     * data, another browser or device) recovers it first: the person confirms
+     * once with the passkey on the provider's page, and the share the wallet had
+     * elsewhere stops working. Two tabs never recover the same wallet at once.
+     */
+    async deviceShareFor(linkedWalletId, signal) {
+        return this.#sealedTo(linkedWalletId, async () => (await this.transportKey(linkedWalletId, signal)).publicKey, signal);
+    }
+    /** The kept share, recovered first when this browser holds none (with recover false: refused), resealed to the key read right before. */
+    async #sealedTo(linkedWalletId, publicKey, signal, recover = true) {
+        const devices = this.#devices();
+        const { wallet } = await this.wallet(linkedWalletId, signal);
+        if (recover)
+            await devices.ensure(wallet, this.#serverKey(linkedWalletId, signal), { signal });
+        else if (!(await devices.has(wallet, this.#serverKey(linkedWalletId, signal))))
+            throw new ClientFlowError('device_share_unavailable');
+        return devices.sealedFor(wallet, await publicKey());
+    }
+    /**
+     * The device key of the wallet's latest creation or recovery the provider
+     * made, as 33-byte compressed hex; absent when it knows none. A share kept
+     * here that is sealed to another key was replaced by a recovery elsewhere.
+     */
+    async deviceKey(linkedWalletId, signal) {
+        requestUUID(linkedWalletId);
+        const r = record(await this.#transport.get(`/v1/linked-wallets/${linkedWalletId}/device-key`, signal), ['request_id'], ['device_public_key']);
+        if (!opaqueId(r.request_id) || (r.device_public_key !== undefined && (typeof r.device_public_key !== 'string' || !/^0[23][0-9a-f]{64}$/.test(r.device_public_key))))
+            fault();
+        return r.device_public_key === undefined ? { requestId: r.request_id } : { requestId: r.request_id, devicePublicKey: r.device_public_key };
+    }
+    /** Whether this browser holds a current device share of the wallet; without one the next send recovers it with the passkey. */
+    async hasDeviceShare(linkedWalletId, signal) {
+        const devices = this.#devices();
+        return devices.has((await this.wallet(linkedWalletId, signal)).wallet, this.#serverKey(linkedWalletId, signal));
+    }
+    /**
+     * Recovers the wallet's device share onto this browser when it holds no
+     * current one, as deviceShareFor() would, for an app that does it ahead of a
+     * transfer; force recovers even then. credentialId names the passkey that
+     * confirms it, by default the account's newest. Answers whether a recovery
+     * ran. Optional: sends recover by themselves.
+     */
+    async recoverDevice(linkedWalletId, options = {}) {
+        const devices = this.#devices();
+        return devices.ensure((await this.wallet(linkedWalletId, options.signal)).wallet, this.#serverKey(linkedWalletId, options.signal), options);
+    }
+    #serverKey(linkedWalletId, signal) {
+        return async () => (await this.deviceKey(linkedWalletId, signal)).devicePublicKey;
+    }
+    #devices() {
+        if (!this.#transport.devices)
+            throw new ClientFlowError('device_share_unavailable');
+        return this.#transport.devices;
+    }
     /**
      * What became of the transfer a send prepared: on its way, confirmed by the
      * network, or failed and why. The send's operation succeeds when the
@@ -323,6 +390,8 @@ export class LinkedWallets {
             fault();
         return operation;
     }
+    /** The permissions the account lets services debit its linked wallets by, without the device (debitPermissions.ts). */
+    debitPermissions() { return new DebitPermissions(this.#transport, (linkedWalletId, keeperKey, signal, recover) => this.#sealedTo(linkedWalletId, async () => keeperKey, signal, recover)); }
 }
 export function parseWalletConnection(payload) {
     const r = record(payload, ['request_id', 'id', 'connector_id', 'state', 'created_at', 'last_synced_at'], ['revoked_at']);
@@ -365,107 +434,3 @@ export function validateWalletLinkAssertion(value) {
         throw new ClientFlowError('invalid_linked_wallet_request');
     return value;
 }
-export function validateLinkedRegistrationCreate(value, ownerId) {
-    const r = record(value, ['kind', 'owner_type', 'owner_id', 'linked_wallet_id', 'payload'], ['result_recipient']);
-    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');
-    if (r.result_recipient !== undefined)
-        recipient(r.result_recipient);
-    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));
-}

package/dist/me.d.ts

@@ -0,0 +1,27 @@
+/**
+ * One wallet of the account: "wallet" is a wallet the provider created,
+ * "linked_wallet" one its owner connected, and walletId is an identifier of
+ * that kind. A listed linked wallet is active; an own wallet is active or
+ * disabled.
+ */
+export interface MeWallet {
+    walletId: string;
+    kind: "wallet" | "linked_wallet";
+    network: string;
+    address: string;
+    state: "active" | "disabled";
+}
+export interface MeProjection {
+    requestId: string;
+    account: {
+        accountId: string;
+        version: string;
+        setupRequired: boolean;
+    };
+    sessionId: string;
+    serverTime: number;
+    /** Every wallet of the account, own then linked, at most 1000 of each kind. */
+    wallets: MeWallet[];
+}
+/** parseMeProjection reads exactly one `/v1/me` answer. */
+export declare function parseMeProjection(payload: unknown): MeProjection;

package/dist/me.js

@@ -0,0 +1,30 @@
+/**
+ * The live `/v1/me` projection: the current account, the session, the server
+ * time and every wallet of the account. It is read as strictly as every
+ * other answer: an unknown member, a missing one or a value outside its
+ * closed form refuses the whole answer.
+ */
+import { ClientFlowError, canonicalDecimal, integer, opaqueId, record } from "./auth.js";
+/** The most wallets of one kind an account lists; the answer holds two kinds. */
+const maxWalletsPerKind = 1000;
+/** parseMeProjection reads exactly one `/v1/me` answer. */
+export function parseMeProjection(payload) {
+    const root = record(payload, ["request_id", "account", "session_id", "server_time", "wallets"]);
+    const account = record(root.account, ["account_id", "version", "setup_required"]);
+    if (!opaqueId(root.request_id) || !opaqueId(account.account_id) || !canonicalDecimal(account.version) || typeof account.setup_required !== "boolean" || !opaqueId(root.session_id) || !integer(root.server_time) ||
+        !Array.isArray(root.wallets) || root.wallets.length > 2 * maxWalletsPerKind) {
+        throw new ClientFlowError("invalid_server_response");
+    }
+    const wallets = root.wallets.map((value) => {
+        const item = record(value, ["wallet_id", "kind", "network", "address", "state"]);
+        if (!opaqueId(item.wallet_id) || (item.kind !== "wallet" && item.kind !== "linked_wallet") || typeof item.network !== "string" || item.network === "" ||
+            typeof item.address !== "string" || item.address === "" || item.address.length > 256 || (item.state !== "active" && item.state !== "disabled")) {
+            throw new ClientFlowError("invalid_server_response");
+        }
+        return { walletId: item.wallet_id, kind: item.kind, network: item.network, address: item.address, state: item.state };
+    });
+    if (wallets.filter((wallet) => wallet.kind === "wallet").length > maxWalletsPerKind || wallets.filter((wallet) => wallet.kind === "linked_wallet").length > maxWalletsPerKind) {
+        throw new ClientFlowError("invalid_server_response");
+    }
+    return { requestId: root.request_id, account: { accountId: account.account_id, version: account.version, setupRequired: account.setup_required }, sessionId: root.session_id, serverTime: root.server_time, wallets };
+}

package/dist/mobile.d.ts

@@ -0,0 +1,64 @@
+export interface MobileSecureStorage {
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string): Promise<void>;
+    delete(key: string): Promise<void>;
+}
+export interface MobileAssociationInput {
+    redirectUri: string;
+    applicationIdentifier: string;
+}
+export interface MobileAssociationVerification {
+    source: "os_verified_https_association";
+    redirectUri: string;
+    applicationIdentifier: string;
+}
+/**
+ * Host/native trust boundary. Implementations must ask the operating system to
+ * verify the configured HTTPS app/universal-link association. On iOS, where no
+ * API reports that verification, the system makes it when an authentication
+ * session with an HTTPS callback starts, and refuses to start one for an app
+ * the domain does not name; a bridge whose openSystemBrowser opens exactly
+ * that session answers for it. This result is a port contract, not
+ * cryptographic proof produced by this TypeScript package.
+ */
+export interface MobileBrowserBridge {
+    verifyAssociatedRedirect(input: MobileAssociationInput): Promise<MobileAssociationVerification | null>;
+    /**
+     * Opens the URL in the system browser's authentication session
+     * (ASWebAuthenticationSession on iOS, a Custom Tab on Android), never an
+     * embedded web view, and resolves with the URL that session ended on: the
+     * registered app link the provider redirected back to. It resolves with
+     * nothing when no app link came back, for example when the person closed
+     * the browser. A sign-in needs that URL; the other hosted flows take it
+     * from the host through their `complete…` method.
+     */
+    openSystemBrowser(url: string): Promise<string | void> | string | void;
+}
+/**
+ * verifyMobileAssociation asks the host to have the operating system verify
+ * the app link of the exact configured redirect for the configured app, and
+ * accepts only the exact answer for both. It runs when the client is
+ * initialized and again before every sign-in opens the system browser.
+ */
+export declare function verifyMobileAssociation(bridge: MobileBrowserBridge, redirectUri: string, applicationIdentifier: string): Promise<void>;
+/** mobileBridgeComplete checks that the host supplied every mobile port. */
+export declare function mobileBridgeComplete(bridge: MobileBrowserBridge | undefined, storage: MobileSecureStorage | undefined): bridge is MobileBrowserBridge;
+/** mobileApplicationIdentifier is a bundle or package identifier as configuration names it. */
+export declare function mobileApplicationIdentifier(value: unknown): value is string;
+/**
+ * mobileSignInReturn reads what the system browser handed back from a hosted
+ * sign-in: the exact registered redirect with the one-use code and this
+ * sign-in's own state, and nothing else. No app link back, a redirect of
+ * another sign-in or an attempt's redirect is refused before any exchange.
+ */
+export declare function mobileSignInReturn(returned: string | void, redirectUri: string, state: string): {
+    code: string;
+    state: string;
+};
+/**
+ * mobileRefreshKey names the refresh token of one public client in the secure
+ * storage. Its parts are opaque identifiers, which hold no dot, so the key is
+ * unambiguous, and it uses only letters, digits, dots, hyphens and
+ * underscores, which every platform keystore takes as a key.
+ */
+export declare function mobileRefreshKey(tenantId: string, applicationId: string, environmentId: string, clientId: string): string;

package/dist/mobile.js

@@ -0,0 +1,69 @@
+// The mobile host boundary: the ports a native host supplies (the system
+// browser with its verified app link, and the OS secure storage that holds the
+// refresh token), the check of the app link the host reports, and the return
+// of a sign-in from the system browser's authentication session.
+//
+// A mobile app sends no browser Origin. The provider binds its sign-in to the
+// exact registered redirect, an HTTPS app link (iOS universal link, Android
+// app link) on one of the client's registered origins, and to the state and
+// the S256 verifier this client keeps in memory. The browser comes back to the
+// app with the one-use code and the state alone; the access token stays in
+// memory and the refresh token goes only to `MobileSecureStorage`.
+import { ClientFlowError } from "./auth.js";
+import { handoffCallback } from "./redirects.js";
+/**
+ * verifyMobileAssociation asks the host to have the operating system verify
+ * the app link of the exact configured redirect for the configured app, and
+ * accepts only the exact answer for both. It runs when the client is
+ * initialized and again before every sign-in opens the system browser.
+ */
+export async function verifyMobileAssociation(bridge, redirectUri, applicationIdentifier) {
+    let verification;
+    try {
+        verification = await bridge.verifyAssociatedRedirect({ redirectUri, applicationIdentifier });
+    }
+    catch {
+        throw new ClientFlowError("mobile_association_unverified");
+    }
+    if (!exactMobileAssociation(verification, redirectUri, applicationIdentifier))
+        throw new ClientFlowError("mobile_association_unverified");
+}
+/** mobileBridgeComplete checks that the host supplied every mobile port. */
+export function mobileBridgeComplete(bridge, storage) {
+    return Boolean(storage) && Boolean(bridge) && typeof bridge?.verifyAssociatedRedirect === "function" && typeof bridge?.openSystemBrowser === "function";
+}
+/** mobileApplicationIdentifier is a bundle or package identifier as configuration names it. */
+export function mobileApplicationIdentifier(value) {
+    return typeof value === "string" && /^[A-Za-z0-9._-]{1,255}$/.test(value);
+}
+/**
+ * mobileSignInReturn reads what the system browser handed back from a hosted
+ * sign-in: the exact registered redirect with the one-use code and this
+ * sign-in's own state, and nothing else. No app link back, a redirect of
+ * another sign-in or an attempt's redirect is refused before any exchange.
+ */
+export function mobileSignInReturn(returned, redirectUri, state) {
+    if (typeof returned !== "string")
+        throw new ClientFlowError("mobile_redirect_unavailable");
+    const callback = handoffCallback(returned, redirectUri);
+    if (callback.attemptId !== undefined)
+        throw new ClientFlowError("invalid_callback");
+    if (callback.state !== state)
+        throw new ClientFlowError("state_mismatch");
+    return { code: callback.code, state: callback.state };
+}
+/**
+ * mobileRefreshKey names the refresh token of one public client in the secure
+ * storage. Its parts are opaque identifiers, which hold no dot, so the key is
+ * unambiguous, and it uses only letters, digits, dots, hyphens and
+ * underscores, which every platform keystore takes as a key.
+ */
+export function mobileRefreshKey(tenantId, applicationId, environmentId, clientId) {
+    return ["authorization", tenantId, applicationId, environmentId, clientId, "refresh"].join(".");
+}
+function exactMobileAssociation(value, redirectUri, applicationIdentifier) {
+    if (value === null || typeof value !== "object" || Array.isArray(value))
+        return false;
+    const result = value;
+    return Object.keys(result).length === 3 && result.source === "os_verified_https_association" && result.redirectUri === redirectUri && result.applicationIdentifier === applicationIdentifier;
+}