@shuttle.technology/authorization 0.0.0-stage → 0.2.0

package/dist/linkedWallets.d.ts

@@ -0,0 +1,401 @@
+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';
+import { type LinkedWalletBalances } from './balances.ts';
+export { parseLinkedWalletBalances, type AssetBalance, type LinkedWalletBalances, type NetworkBalanceStatus, type NetworkBalances } from './balances.ts';
+import { type SendPage } from './sends.ts';
+export { eventOfTransaction, parseSendPage, sendEvents, sendsPath, type ListedSend, type SendPage, type TransferOutcome } from './sends.ts';
+export type { LinkedSendDisplay, ReplaceAction } from './walletOperations.ts';
+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;
+export interface WalletConnection {
+    requestId: string;
+    id: string;
+    connectorId: string;
+    state: 'connected' | 'revoked' | 'reauth_required';
+    createdAt: string;
+    lastSyncedAt: string;
+    revokedAt?: string;
+}
+export interface LinkedWallet {
+    id: string;
+    connectionId: string;
+    externalWalletId: string;
+    externalKeyId: string;
+    network: string;
+    address: string;
+    algorithm: 'secp256k1' | 'ed25519';
+    publicKey: string;
+    bindingRevision: string;
+    status: 'active' | 'inactive';
+    observedAt: string;
+}
+export interface WalletLinkChallenge {
+    requestId: string;
+    challengeId: string;
+    expiresAt: string;
+    publicKey: {
+        challenge: string;
+        rpId: string;
+        timeoutMs: number;
+        userVerification: 'required';
+        allowCredentials: [{
+            type: 'public-key';
+            id: string;
+        }];
+    };
+}
+/** Assertion JSON from a credential ceremony on its server-approved RP/origin. */
+export interface WalletLinkAssertion {
+    id: string;
+    rawId: string;
+    type: 'public-key';
+    response: {
+        clientDataJSON: string;
+        authenticatorData: string;
+        signature: string;
+        userHandle: string;
+    };
+}
+export interface LinkedRegistrationCreate {
+    kind: 'streams.register';
+    owner_type: 'account';
+    owner_id: string;
+    linked_wallet_id: string;
+    payload: {
+        network: string;
+        assets?: string[];
+        activity_types?: string[];
+    };
+}
+export interface LinkedRegistrationDisplay {
+    kind: 'streams.register';
+    ownerId: string;
+    requesterId: string;
+    resultRecipient: ResultRecipient;
+    bindingSource: 'linked_wallet';
+    connectionId: string;
+    linkedWalletId: string;
+    bindingRevision: string;
+    assets: readonly string[];
+    network: string;
+    address: string;
+    streamsMappingId: string;
+    streamsMappingVersion: string;
+    targetCustomerId: string;
+    targetProjectId: string;
+    targetEnvironmentId: string;
+}
+export interface LinkedRegistrationPurgedDisplay {
+    kind: 'streams.register';
+    materialPurged: true;
+    ownerId: string;
+    requesterId: string;
+    resultRecipient: ResultRecipient;
+}
+export interface LinkedRegistrationOperation {
+    id: string;
+    version: string;
+    kind: 'streams.register';
+    state: UserWalletState;
+    effectState: UserWalletEffectState;
+    authorizationBasis: LinkedRegistrationAuthorizationBasis;
+    ownerType: 'account';
+    ownerId: string;
+    requesterId: string;
+    bindingSource: 'linked_wallet';
+    connectionId: string;
+    linkedWalletId: string;
+    bindingRevision: string;
+    requestFingerprint: string;
+    operationFingerprint: string;
+    display: LinkedRegistrationDisplay | LinkedRegistrationPurgedDisplay;
+    createdAt: string;
+    expiresAt: string;
+    nextAction: NextAction;
+    confirmationLocation?: string;
+}
+export interface LinkedRegistrationResult {
+    requestId: string;
+    result: {
+        kind: 'streams_registration';
+        operationId: string;
+        bindingSource: 'linked_wallet';
+        connectionId: string;
+        linkedWalletId: string;
+        bindingRevision: string;
+        sourceRegistrationId: string;
+        registrationDigest: string;
+        receiptId: string;
+    };
+}
+/**
+ * A send from a linked wallet. asset is the network's own coin ("native") or a
+ * token the own-wallet system sends on that network; amountRaw is in that
+ * asset's minimal units, and a token's decimals differ by network. comment
+ * is a text the transfer carries to its recipient, on a TON network only:
+ * the comment an exchange credits a deposit by (transferComment() is its
+ * rule). It is sent exactly as given.
+ */
+export interface LinkedSendInput {
+    linkedWalletId: string;
+    network: string;
+    asset: LinkedSendAsset;
+    recipient: string;
+    amountRaw: string;
+    comment?: string;
+}
+/**
+ * The replacement of a send the network has not included. operationId is the
+ * account's own send from the same wallet; what the replacement moves is
+ * that send's own and is not given here.
+ */
+export interface LinkedReplaceInput {
+    linkedWalletId: string;
+    operationId: string;
+    action: ReplaceAction;
+}
+/** The own-wallet system's transport key, as that system publishes it. It carries no proof of where the key lives. */
+export interface LinkedTransportKey {
+    requestId: string;
+    publicKey: string;
+    encryptionAlgorithm: string;
+}
+/** Metadata position is an Auth registration ID, never a deposit cursor. */
+export interface LinkedRegistrationListOptions {
+    afterRegistrationId?: string;
+    limit?: number;
+    signal?: AbortSignal;
+}
+/** eventTypes is the kinds of wallet event wanted: deposit, withdrawal, activity in any combination, or activity:<type>; left out, every kind. */
+export interface LinkedEventsOptions {
+    registrationId?: string;
+    cursor?: string;
+    limit?: number;
+    eventTypes?: readonly string[];
+    signal?: AbortSignal;
+}
+export interface LinkedStreamsRegistration {
+    readonly registrationId: string;
+    readonly bindingSource: 'linked_wallet';
+    readonly connectionId: string;
+    readonly linkedWalletId: string;
+    readonly bindingRevision: string;
+    readonly sourceRegistrationId: string;
+    readonly network: string;
+    readonly address: string;
+    readonly assets: readonly string[];
+    readonly status: 'pending' | 'active';
+    readonly effectiveFrom: string;
+    readonly revision: number;
+    readonly sourceVersion: string;
+}
+export interface LinkedStreamsRegistrationList {
+    readonly items: readonly LinkedStreamsRegistration[];
+    readonly hasMore: boolean;
+    readonly nextAfterRegistrationId?: string;
+}
+/** Consumer-owned ports reuse AuthorizationClient's existing session transport. */
+export interface LinkedWalletTransport {
+    get(path: string, signal?: AbortSignal): Promise<unknown>;
+    /** Opens a long-lived answer and returns it as it arrives. */
+    stream(path: string, signal?: AbortSignal): Promise<ReadableStream<Uint8Array>>;
+    write(path: string, method: 'POST' | 'DELETE', body: unknown | undefined, signal?: AbortSignal, idempotencyKey?: string, version?: string): Promise<{
+        payload: unknown;
+        accountId: string;
+    }>;
+    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;
+    constructor(transport: LinkedWalletTransport);
+    challenge(cognitoAccessToken: string, credentialId: string, signal?: AbortSignal): Promise<WalletLinkChallenge>;
+    connect(challengeId: string, cognitoAccessToken: string, assertion: WalletLinkAssertion, signal?: AbortSignal): Promise<WalletConnection>;
+    connection(connectionId: string, signal?: AbortSignal): Promise<WalletConnection>;
+    sync(connectionId: string, cognitoAccessToken: string, signal?: AbortSignal): Promise<WalletConnection>;
+    /**
+     * refresh binds the account to the Wallet identity the provider owns for it
+     * and synchronizes its public wallet inventory. It carries no Wallet token
+     * and no body; repeating it converges on the same connection. Call it after
+     * a wallet was created so the wallet appears in list().
+     */
+    refresh(signal?: AbortSignal): Promise<WalletConnection>;
+    disconnect(connectionId: string, signal?: AbortSignal): Promise<WalletConnection>;
+    list(signal?: AbortSignal): Promise<{
+        requestId: string;
+        items: readonly LinkedWallet[];
+    }>;
+    wallet(linkedWalletId: string, signal?: AbortSignal): Promise<{
+        requestId: string;
+        wallet: LinkedWallet;
+    }>;
+    /** Every metadata page is fresh; restart at the beginning to discover earlier insertions. */
+    registrations(linkedWalletId: string, options?: LinkedRegistrationListOptions): Promise<LinkedStreamsRegistrationList>;
+    /**
+     * One page of the linked wallet's retained events as wallet events 3.0:
+     * what came in, what went out and what else happened, each with kind,
+     * status and revision, those of the kinds eventTypes names. Continuations
+     * are sealed opaque cursors.
+     */
+    events(linkedWalletId: string, options?: LinkedEventsOptions): Promise<WalletEventPage>;
+    /**
+     * Opens one signal stream for these linked wallets and reads it to its end.
+     * onOpen says the stream is live: read every wallet once then. onWallets
+     * names wallets with new events: read them with events(). The promise
+     * resolves with the reason the stream ended; a stream lives no longer than
+     * an access token, so the caller opens the next one. It rejects with the
+     * server's refusal, with the abort reason, or when the connection fails;
+     * keep an ordinary timed read for those times.
+     */
+    signals(linkedWalletIds: readonly string[], handlers: LinkedWalletSignalHandlers): Promise<LinkedWalletSignalEnd>;
+    createRegistration(create: LinkedRegistrationCreate, idempotencyKey: string, signal?: AbortSignal): Promise<LinkedRegistrationOperation>;
+    /**
+     * Starts tracking a linked wallet on one network. An EVM wallet has one
+     * address on every EVM network, so it is registered on each of them with its
+     * own call. activityTypes names the kinds of activity events asked for beside
+     * deposits; omitted or empty means deposits only, and Streams refuses a kind
+     * the network does not have. The operation comes back authorized;
+     * executeRegistration() with its version dispatches it.
+     */
+    register(input: {
+        linkedWalletId: string;
+        network: string;
+        assets?: string[];
+        activityTypes?: string[];
+    }, idempotencyKey: string, signal?: AbortSignal): Promise<LinkedRegistrationOperation>;
+    operation(operationId: string, signal?: AbortSignal): Promise<LinkedRegistrationOperation>;
+    executeRegistration(operationId: string, version: string, idempotencyKey: string, signal?: AbortSignal): Promise<LinkedRegistrationOperation>;
+    registrationResult(operationId: string, signal?: AbortSignal): Promise<LinkedRegistrationResult>;
+    /**
+     * Starts a send from a linked wallet. The account's session authorizes it:
+     * the operation comes back authorized (authorizationBasis
+     * session_authorized), with no passkey and no confirmation window. Then
+     * prepare() has the own-wallet system prepare the transfer and name its
+     * fee; show the owner what was prepared and, on their confirm,
+     * executeSend() with the device share.
+     */
+    send(input: LinkedSendInput, idempotencyKey: string, signal?: AbortSignal): Promise<UserWalletOperation>;
+    /**
+     * Replaces a send the own-wallet system broadcast on an EVM network and the
+     * network has not included: "speed_up" sends the same transfer again with a
+     * higher fee, "cancel" sends nothing to the wallet's own address in its
+     * place. The answer is a send of its own, authorized by the session like
+     * send(): prepare() has the own-wallet system prepare the replacement (it
+     * may answer that the transfer no longer waits), show it with its new fee,
+     * and on the owner's confirm executeSend(). Whichever of the two
+     * transactions the network includes, the other fails; read
+     * transferStatus() of both.
+     */
+    replaceSend(input: LinkedReplaceInput, idempotencyKey: string, signal?: AbortSignal): Promise<UserWalletOperation>;
+    /**
+     * What the wallet holds on each of its networks: the coin and the tokens
+     * the stand names there, in minimal units with their decimals. The provider
+     * reads its own stand's nodes. A network whose node gave no amount is in
+     * the answer with its status and without amounts; it fails nothing.
+     */
+    balances(linkedWalletId: string, signal?: AbortSignal): Promise<LinkedWalletBalances>;
+    /**
+     * Has the own-wallet system prepare the transfer of a send or replacement
+     * the session authorized, and returns the send with what was prepared:
+     * display.preparedSummary, the sending address and the fee estimate. Show
+     * them to the owner; executeSend() sends exactly that transfer. The
+     * transfer is prepared once: calling again returns the same prepared send
+     * and asks the own-wallet system nothing. A prepared send expires within
+     * 150 seconds; one that expired is sent again from send(). The request
+     * carries no body, idempotency key or version.
+     */
+    prepare(operationId: string, signal?: AbortSignal): Promise<UserWalletOperation>;
+    /** The key the device seals its share to, read right before executeSend(). */
+    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. 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>;
+    /**
+     * 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
+     * own-wallet system accepted the transfer; this is what the network did
+     * with it. Read it until final is true. Before the send was prepared
+     * there is no transfer and the read is refused with NOT_FOUND.
+     */
+    transferStatus(operationId: string, signal?: AbortSignal): Promise<TransferStatus>;
+    /**
+     * One page of the account's send history, newest first: every wallet.send
+     * the account can read, with its transaction hash and the recorded final
+     * fate of its transfer. A send with a hash and no transfer has not been
+     * reported final yet: read transferStatus() for it, which records the fate.
+     * The cursor carries the first page's limit.
+     */
+    sends(options?: PageOptions): Promise<SendPage>;
+    /** The limits every send from the wallet obeys, read with the session (walletLimits.ts). Revision "0": never set. */
+    limits(linkedWalletId: string, signal?: AbortSignal): Promise<WalletLimits>;
+    /**
+     * Asks to replace the wallet's limits as a whole; empty ceilings and recipients remove them all. The operation
+     * awaits the owner's passkey: the client's challengeOperation(), completeOperationConfirmation() and
+     * 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;
+export declare function parseLinkedWalletList(payload: unknown): {
+    requestId: string;
+    items: readonly LinkedWallet[];
+};
+export declare function parseWalletLinkChallenge(payload: unknown, now: number): WalletLinkChallenge;
+export declare function validateWalletLinkAssertion(value: WalletLinkAssertion): WalletLinkAssertion;