@shuttle.technology/authorization 0.0.0-stage → 0.1.0

package/dist/client.d.ts

@@ -0,0 +1,264 @@
+import { type ClientChannel, type IdentityMethod } from "./auth.ts";
+import { type AccountIdentity, type ConfirmationChallenge, type HostedIdentityFlow, type IdentityVerificationMethod, type LocalOperation, type LocalOperationCreate, type LocalOperationResult, type PasskeyBootstrapResult, type ServiceReadScope, type VerifiedIdentityResult } from "./slice4.ts";
+import { StreamsReads } from "./streams.ts";
+import { LinkedWallets } from "./linkedWallets.ts";
+export { LinkedWallets, eventOfTransaction, isWalletLimitRefusal, resumeCursor, sendEvents, transferFinal, WalletLimitRefusals } from "./linkedWallets.ts";
+export type { AssetBalance, LinkedWalletBalances, NetworkBalanceStatus, NetworkBalances, ListedSend, SendPage, TransferOutcome, TransferState, TransferStatus, WalletConnection, LinkedWallet, WalletLinkChallenge, WalletLinkAssertion, LinkedRegistrationCreate, LinkedRegistrationOperation, LinkedRegistrationDisplay, LinkedRegistrationPurgedDisplay, LinkedRegistrationResult, LinkedRegistrationListOptions, LinkedEventsOptions, LinkedStreamsRegistration, LinkedStreamsRegistrationList, LinkedSendInput, LinkedReplaceInput, LinkedSendDisplay, ReplaceAction, LinkedTransportKey, LimitAsset, WalletCeiling, WalletLimitRefusal, WalletLimits, WalletLimitsDisplay, WalletLimitsInput } from "./linkedWallets.ts";
+import { type UserWalletOperation, type UserWalletOperationCreate, type WalletResult } from "./walletOperations.ts";
+import { type PageOptions } from "./pages.ts";
+export type { PageOptions } from "./pages.ts";
+export { AuthorizationError, ClientFlowError } from "./auth.ts";
+export type { AuthIntent, ClientChannel, IdentityMethod, NextAction } from "./auth.ts";
+export { pollAuthoritative } from "./poll.ts";
+export type { PollDisposition, PollOptions, PollResult } from "./poll.ts";
+export type { AccountIdentity, ConfirmationChallenge, HostedIdentityFlow, IdentityVerificationMethod, LocalOperation, LocalOperationCreate, LocalOperationResult, PasskeyBootstrapResult, ResultRecipient, ServiceReadScope, VerifiedIdentityResult, } from "./slice4.ts";
+export { MaxTransferCommentBytes, MaxWalletMessageBytes, ReplaceActions, transferComment, walletMaterialPurged } from "./walletOperations.ts";
+export type { UserWalletAuthorizationBasis, UserWalletDisplay, UserWalletEffectState, UserWalletOperation, UserWalletOperationCreate, UserWalletOperationKind, UserWalletPurgedDisplay, UserWalletState, WalletResult, WalletResultKind, } from "./walletOperations.ts";
+export interface ClientConfiguration {
+    mode: "mode_b";
+    channel: ClientChannel;
+    authorizationOrigin: string;
+    applicationOrigin?: string;
+    redirectUri: string;
+    publishableClientId: string;
+    tenantId: string;
+    applicationId: string;
+    environmentId: string;
+    methods: readonly IdentityMethod[];
+    mobileApplicationIdentifier?: string;
+}
+export interface PublicClientConfiguration {
+    requestId: string;
+    id: string;
+    name: string;
+    environmentId: string;
+    methods: readonly IdentityMethod[];
+    providerOrigin: string;
+    rpId: string;
+    redirects: readonly string[];
+    platform: ClientChannel;
+}
+export interface FetchRequest {
+    url: string;
+    method?: string;
+    headers?: Record<string, string>;
+    body?: string;
+    credentials?: "include" | "omit";
+    cache?: "no-store";
+    signal?: AbortSignal;
+}
+export interface FetchResponse {
+    status: number;
+    ok: boolean;
+    json(): Promise<unknown>;
+    /** The answer as it arrives and its headers; only a signal stream reads them. */
+    body?: ReadableStream<Uint8Array> | null;
+    headers?: {
+        get(name: string): string | null;
+    };
+}
+export type FetchLike = (url: string, init?: Omit<FetchRequest, "url">) => Promise<FetchResponse>;
+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. This result is a
+ * port contract, not cryptographic proof produced by this TypeScript package.
+ */
+export interface MobileBrowserBridge {
+    verifyAssociatedRedirect(input: MobileAssociationInput): Promise<MobileAssociationVerification | null>;
+    openSystemBrowser(url: string): Promise<void> | void;
+}
+interface CommonDependencies {
+    fetch?: FetchLike;
+    crypto?: Crypto;
+    now?: () => number;
+}
+export interface WebDependencies extends CommonDependencies {
+    currentOrigin: () => string;
+    /**
+     * Opens a separate top-level browsing context. Restore requires the host to
+     * return the final registered app redirect while this caller stays alive so
+     * its state and PKCE verifier remain only in memory.
+     */
+    openHosted: (url: string) => Promise<string | void> | string | void;
+}
+export interface MobileDependencies extends CommonDependencies {
+    browserBridge: MobileBrowserBridge;
+    secureStorage: MobileSecureStorage;
+}
+export type ClientDependencies = WebDependencies | MobileDependencies;
+export interface AuthAttempt {
+    requestId: string;
+    attemptId: string;
+    launchUrl: string;
+    expiresAt: number;
+}
+export interface Session {
+    requestId: string;
+    accessExpiresAt: number;
+    accountId: string;
+    sessionId: string;
+    setupRequired?: boolean;
+}
+export interface MeProjection {
+    requestId: string;
+    account: {
+        accountId: string;
+        version: string;
+        setupRequired: boolean;
+    };
+    sessionId: string;
+    serverTime: number;
+}
+export interface SessionProjection {
+    requestId: string;
+    items: Array<{
+        sessionId: string;
+        clientId: string;
+        state: string;
+        createdAt: string;
+        expiresAt: string;
+        current: boolean;
+    }>;
+    hasMore: boolean;
+    nextCursor?: string;
+}
+export interface WalletProjection {
+    requestId: string;
+    items: Array<{
+        walletId: string;
+        network: string;
+        address: string;
+        state: string;
+        generation: string;
+        mappingVersion: string;
+    }>;
+    hasMore: boolean;
+    nextCursor?: string;
+}
+type NormalizedDependencies = {
+    fetch: FetchLike;
+    crypto: Crypto;
+    now: () => number;
+    launch: (url: string) => Promise<string | void>;
+    secureStorage?: MobileSecureStorage;
+};
+export declare function initializeAuthorizationClient(configuration: ClientConfiguration, dependencies: ClientDependencies): Promise<AuthorizationClient>;
+export declare class AuthorizationClient {
+    #private;
+    readonly capabilities: {
+        mode: "mode_b";
+        channel: ClientChannel;
+        methods: readonly IdentityMethod[];
+    };
+    readonly publicConfiguration?: PublicClientConfiguration;
+    constructor(configuration: ClientConfiguration, dependencies: NormalizedDependencies, publicConfiguration?: PublicClientConfiguration);
+    get hasSession(): boolean;
+    signup(method: IdentityMethod): Promise<AuthAttempt>;
+    login(method: IdentityMethod): Promise<AuthAttempt>;
+    bootstrapPasskey(signal?: AbortSignal): Promise<HostedIdentityFlow>;
+    verifyIdentity(method: IdentityVerificationMethod, signal?: AbortSignal): Promise<HostedIdentityFlow>;
+    completePasskeyBootstrap(callbackUri: string, signal?: AbortSignal): Promise<PasskeyBootstrapResult>;
+    /** identities lists the account's own active sign-in methods; a passkey names its credential. */
+    identities(signal?: AbortSignal): Promise<AccountIdentity[]>;
+    completeIdentityVerification(callbackUri: string, signal?: AbortSignal): Promise<VerifiedIdentityResult>;
+    createOperation(create: LocalOperationCreate, idempotencyKey: string, signal?: AbortSignal): Promise<LocalOperation>;
+    createIdentityLink(verifiedIdentityHandle: string, idempotencyKey: string, signal?: AbortSignal): Promise<LocalOperation>;
+    createIdentityUnlink(identityId: string, idempotencyKey: string, signal?: AbortSignal): Promise<LocalOperation>;
+    createSessionRevocation(sessionId: string, idempotencyKey: string, signal?: AbortSignal): Promise<LocalOperation>;
+    createServiceGrant(input: {
+        walletId: string;
+        servicePrincipalId: string;
+        enabled: boolean;
+        scopes: ServiceReadScope[];
+        externalRef?: string;
+    }, idempotencyKey: string, signal?: AbortSignal): Promise<LocalOperation>;
+    operation(operationId: string, signal?: AbortSignal): Promise<LocalOperation>;
+    challengeOperation(operationId: string, credentialId: string, signal?: AbortSignal): Promise<ConfirmationChallenge>;
+    completeOperationConfirmation(callbackUri: string, signal?: AbortSignal): Promise<LocalOperation>;
+    /**
+     * createWalletOperation admits one Mode B wallet intent on POST /v1/operations.
+     * The closed body is validated locally against the current session account
+     * before the request leaves the client (source §1.3, §2.2).
+     */
+    createWalletOperation(create: UserWalletOperationCreate, idempotencyKey: string, signal?: AbortSignal): Promise<UserWalletOperation>;
+    createWallet(input: {
+        network: string;
+        recipientPublicKey: string;
+    }, idempotencyKey: string, signal?: AbortSignal): Promise<UserWalletOperation>;
+    signWithWallet(input: {
+        walletId: string;
+        network: string;
+        messageBase64url: string;
+    }, idempotencyKey: string, signal?: AbortSignal): Promise<UserWalletOperation>;
+    sendFromWallet(input: {
+        walletId: string;
+        network: string;
+        recipient: string;
+        amountRaw: string;
+        maxFeeRaw: string;
+    }, idempotencyKey: string, signal?: AbortSignal): Promise<UserWalletOperation>;
+    exportWallet(input: {
+        walletId: string;
+        recipientPublicKey: string;
+    }, idempotencyKey: string, signal?: AbortSignal): Promise<UserWalletOperation>;
+    recoverWallet(input: {
+        walletId: string;
+        expectedGeneration: string;
+        recipientPublicKey: string;
+    }, idempotencyKey: string, signal?: AbortSignal): Promise<UserWalletOperation>;
+    /** walletOperation reads the safe wallet status on GET /v1/operations/{operation_id}. */
+    walletOperation(operationId: string, signal?: AbortSignal): Promise<UserWalletOperation>;
+    /**
+     * challengeWalletOperation reuses the shared confirmation challenge route and
+     * pending-state bookkeeping; the wallet and local challenge contracts are the
+     * same closed response.
+     */
+    challengeWalletOperation(operationId: string, credentialId: string, signal?: AbortSignal): Promise<ConfirmationChallenge>;
+    completeWalletOperationConfirmation(callbackUri: string, signal?: AbortSignal): Promise<UserWalletOperation>;
+    /**
+     * executeWalletOperation claims one confirmed wallet effect. The first claim
+     * answers 202 and an exact replay answers 200; both carry the same operation.
+     */
+    executeWalletOperation(operationId: string, version: string, idempotencyKey: string, signal?: AbortSignal): Promise<UserWalletOperation>;
+    /** walletOperationResult reads the protected wallet output for its frozen recipient. */
+    walletOperationResult(operationId: string, signal?: AbortSignal): Promise<WalletResult>;
+    executeOperation(operationId: string, version: string, idempotencyKey: string, signal?: AbortSignal): Promise<LocalOperation>;
+    /** HTTP-only Auth-owned links and session-authorized Streams registration. */
+    linkedWallets(): LinkedWallets;
+    /**
+     * streams binds the two authorized Streams reads of source §2.6 to this
+     * session's protected GET, so the account caller reuses the one access-token
+     * and refresh path. The read contract, its types and its bounds live in the
+     * `./streams` entry point, which this file deliberately does not re-export; a
+     * service caller constructs `StreamsReads` there with its own credentialed
+     * GET. The caller supplies the stable `idempotencyKey` in each read's options;
+     * it is forwarded unchanged on the original GET and any protected 401 retry.
+     */
+    streams(): StreamsReads;
+    operationResult(operationId: string, signal?: AbortSignal): Promise<LocalOperationResult>;
+    cancel(attemptId: string): "local_canceled";
+    exchangeHandoff(callbackUri: string, signal?: AbortSignal): Promise<Session>;
+    restoreSession(signal?: AbortSignal): Promise<Session>;
+    refreshSession(signal?: AbortSignal): Promise<Session>;
+    logout(signal?: AbortSignal): Promise<{
+        localCleared: true;
+        serverDisposition: "server_revoked" | "server_unconfirmed";
+    }>;
+    me(signal?: AbortSignal): Promise<MeProjection>;
+    sessions(input?: AbortSignal | PageOptions): Promise<SessionProjection>;
+    wallets(input?: AbortSignal | PageOptions): Promise<WalletProjection>;
+}