@shuttle.technology/authorization 0.0.0-stage → 0.2.0

package/dist/canonicalize.js

@@ -0,0 +1,107 @@
+// RFC 8785 JSON Canonicalization Scheme (source §2.5). Mode C hashes the
+// normalized OperationCreate and signs the closed proof payload over exactly
+// these bytes, so the client canonicalizes locally and never accepts a
+// server-, backend- or library-supplied serialization of either value.
+//
+// The implementation is deliberately closed rather than general: only the JSON
+// value forms the two Mode C documents contain are accepted, and every other
+// input is a local fault instead of a best-effort approximation. In particular
+// a JSON number is accepted only as a safe integer, because the closed payload
+// carries integer NumericDate seconds and nothing else; a fractional or
+// out-of-range number would otherwise be canonicalized through a rounding rule
+// this package has no requirement to own.
+import { ClientFlowError } from "./auth.js";
+/**
+ * MaxCanonicalDepth bounds nesting. The Mode C request nests one object inside
+ * another and the proof payload is flat, so this bound is far above every
+ * accepted document and exists only to keep a hostile value from recursing.
+ */
+export const MaxCanonicalDepth = 8;
+/** canonicalJSON returns the RFC 8785 canonical serialization of value. */
+export function canonicalJSON(value) {
+    return serialize(value, 0);
+}
+/** canonicalJSONBytes returns the UTF-8 bytes canonicalJSON produces. */
+export function canonicalJSONBytes(value) {
+    return new TextEncoder().encode(canonicalJSON(value));
+}
+/**
+ * sha256HexLower is the lowercase hexadecimal SHA-256 digest Mode C uses for
+ * `request_hash`. Uppercase hexadecimal is a different value and the server
+ * rejects it, so the alphabet is fixed here.
+ */
+export async function sha256HexLower(crypto, bytes) {
+    if (!crypto?.subtle || typeof crypto.subtle.digest !== "function")
+        throw new ClientFlowError("runtime_capability_unavailable");
+    const digest = new Uint8Array(await crypto.subtle.digest("SHA-256", bytes));
+    let result = "";
+    for (const octet of digest)
+        result += lowerHex[octet >>> 4] + lowerHex[octet & 15];
+    return result;
+}
+const lowerHex = "0123456789abcdef";
+function serialize(value, depth) {
+    if (depth > MaxCanonicalDepth)
+        throw new ClientFlowError("noncanonical_value");
+    if (value === null)
+        return "null";
+    switch (typeof value) {
+        case "boolean":
+            return value ? "true" : "false";
+        case "number":
+            return serializeNumber(value);
+        case "string":
+            return serializeString(value);
+        case "object":
+            break;
+        default:
+            throw new ClientFlowError("noncanonical_value");
+    }
+    if (Array.isArray(value)) {
+        const items = value;
+        return "[" + items.map((item) => serialize(item, depth + 1)).join(",") + "]";
+    }
+    const object = value;
+    const members = Object.keys(object).sort(compareUTF16);
+    const encoded = members.map((member) => {
+        const child = object[member];
+        if (child === undefined)
+            throw new ClientFlowError("noncanonical_value");
+        return serializeString(member) + ":" + serialize(child, depth + 1);
+    });
+    return "{" + encoded.join(",") + "}";
+}
+/**
+ * serializeNumber accepts only a safe integer. RFC 8785 serializes numbers
+ * through the ECMAScript Number-to-String algorithm, which `String` performs
+ * exactly for this range, including -0 as "0".
+ */
+function serializeNumber(value) {
+    if (!Number.isSafeInteger(value))
+        throw new ClientFlowError("noncanonical_value");
+    return String(value);
+}
+/**
+ * serializeString uses the ECMAScript JSON string serialization RFC 8785
+ * §3.2.2.2 requires. A lone surrogate is not valid Unicode text, so it is
+ * refused here instead of being escaped into a document the server would then
+ * canonicalize differently.
+ */
+function serializeString(value) {
+    for (let index = 0; index < value.length; index += 1) {
+        const unit = value.charCodeAt(index);
+        if (unit < 0xd800 || unit > 0xdfff)
+            continue;
+        const next = index + 1 < value.length ? value.charCodeAt(index + 1) : 0;
+        if (unit >= 0xdc00 || next < 0xdc00 || next > 0xdfff)
+            throw new ClientFlowError("noncanonical_value");
+        index += 1;
+    }
+    return JSON.stringify(value);
+}
+/** compareUTF16 orders member names by UTF-16 code unit as RFC 8785 §3.2.3 requires. */
+function compareUTF16(left, right) {
+    if (left < right)
+        return -1;
+    return left > right ? 1 : 0;
+}

package/dist/client.d.ts

@@ -0,0 +1,152 @@
+import { type ClientChannel, type IdentityMethod } from "./auth.ts";
+import { type Session } from "./credentials.ts";
+import { type ClientConfiguration, type ClientSettings, type PublicClientConfiguration } from "./configuration.ts";
+import { type SessionProjection, type WalletProjection } from "./accountLists.ts";
+import { type ServiceGrantInput, type ServiceGrantPage, type ServiceGrantTarget } from "./serviceGrants.ts";
+import { type AccountIdentity, type ConfirmationChallenge, type HostedIdentityFlow, type IdentityVerificationMethod, type LocalOperation, type LocalOperationCreate, type LocalOperationResult, type PasskeyBootstrapResult, type VerifiedIdentityResult } from "./slice4.ts";
+import { type MeProjection } from "./me.ts";
+import { type HostedSignIn } from "./redirects.ts";
+import { type MobileBrowserBridge, type MobileSecureStorage } from "./mobile.ts";
+export type { MobileAssociationInput, MobileAssociationVerification, MobileBrowserBridge, MobileSecureStorage } from "./mobile.ts";
+import { StreamsReads } from "./streams.ts";
+import { LinkedWallets } from "./linkedWallets.ts";
+export { DebitPermissions, LinkedWallets, MaxDebitAssets, MaxDebitRecipients, 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, DebitAsset, DebitAssetBound, DebitPermission, DebitPermissionDisplay, DebitPermissionInput, DebitPermissionList, DebitPermissionRevokeDisplay, DebitPermissionState, DebitShareKeys } from "./linkedWallets.ts";
+import { type UserWalletOperation, type UserWalletOperationCreate, type WalletResult } from "./walletOperations.ts";
+import { type WalletCreateInput } from "./walletCreateGrant.ts";
+export type { ConsentDebitOutcome, DebitTerms } from "./consentDebit.ts";
+export type { WalletCreateGrant, WalletCreateGrantOutcome, WalletCreateInput } from "./walletCreateGrant.ts";
+import { type PageOptions } from "./pages.ts";
+export type { PageOptions } from "./pages.ts";
+export type { ClientConfiguration, ClientSettings, PublicClientConfiguration } from "./configuration.ts";
+export type { SessionProjection, WalletProjection } from "./accountLists.ts";
+export type { AccountServiceGrant, ServiceGrantInput, ServiceGrantPage, ServiceGrantState, ServiceGrantTarget } from "./serviceGrants.ts";
+export { AuthorizationErrorCodes, AuthorizationErrorContracts, ModeCRefusals, isAuthorizationErrorCode, isModeCRefusal } from "./errors.ts";
+export type { AuthorizationErrorCode, AuthorizationErrorContract, ModeCRefusal } from "./errors.ts";
+export type { MeProjection, MeWallet } from "./me.ts";
+export { AuthorizationError, ClientFlowError, isAuthorizationError } from "./auth.ts";
+export { webRenewalRequiresNavigation } from "./webRenewal.ts";
+export type { AuthIntent, ClientChannel, IdentityMethod, NextAction } from "./auth.ts";
+export type { HostedSignIn } from "./redirects.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, DeviceSharePackage, } from "./walletOperations.ts";
+export type { AuthAttempt, ClientDependencies, FetchLike, FetchRequest, FetchResponse, MobileDependencies, WebDependencies } from "./clientTypes.ts";
+import { type DeviceShareStore } from "./deviceShares.ts";
+export type { DeviceRecoveryOptions, DeviceShareRecord, DeviceShareStore } from "./deviceShares.ts";
+import type { ClientDependencies, FetchLike, AuthAttempt } from "./clientTypes.ts";
+export type { Session } from "./credentials.ts";
+type NormalizedDependencies = {
+    fetch: FetchLike;
+    crypto: Crypto;
+    now: () => number;
+    launch: (url: string, signal?: AbortSignal) => Promise<string | void>;
+    secureStorage?: MobileSecureStorage;
+    browserBridge?: MobileBrowserBridge;
+    deviceShares?: DeviceShareStore;
+};
+export declare function initializeAuthorizationClient(settings: ClientSettings, 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 and login open the hosted sign-in page (on mobile: verify the app link, open the system browser,
+     * exchange what it hands back and resolve with the session). Given a method, they begin that attempt.
+     */
+    signup(): Promise<HostedSignIn>;
+    signup(method: IdentityMethod): Promise<AuthAttempt>;
+    login(): Promise<HostedSignIn>;
+    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 asks to give one service read access to one of the account's wallets, or to change it; the person confirms it with a passkey. */
+    createServiceGrant(input: ServiceGrantInput, idempotencyKey: string, signal?: AbortSignal): Promise<LocalOperation>;
+    /** revokeServiceGrant asks to withdraw the grant of one service on one wallet (`enabled: false`); the person confirms it with a passkey. */
+    revokeServiceGrant(target: ServiceGrantTarget, idempotencyKey: string, signal?: AbortSignal): Promise<LocalOperation>;
+    /** serviceGrants lists the grants the account gave services, in every state, newest first. */
+    serviceGrants(input?: AbortSignal | PageOptions): Promise<ServiceGrantPage>;
+    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, its closed body checked locally first (source §1.3, §2.2). */
+    createWalletOperation(create: UserWalletOperationCreate, idempotencyKey: string, signal?: AbortSignal): Promise<UserWalletOperation>;
+    /** Without recipientPublicKey the SDK makes the device key and keeps the share (deviceShares.ts); grant opens the wallet to a service in the same confirmation (walletCreateGrant.ts). */
+    createWallet(input: WalletCreateInput, 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 is challengeOperation: the wallet and local challenges are one closed response. */
+    challengeWalletOperation(operationId: string, credentialId: string, signal?: AbortSignal): Promise<ConfirmationChallenge>;
+    completeWalletOperationConfirmation(callbackUri: string, signal?: AbortSignal): Promise<UserWalletOperation>;
+    /** executeWalletOperation claims one confirmed wallet effect: 202, or 200 for an exact replay, with 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 authorized Streams reads (source §2.6, `./streams`) to this session's protected GET;
+     * each read's `idempotencyKey` is forwarded unchanged on the GET and any 401 retry.
+     */
+    streams(): StreamsReads;
+    operationResult(operationId: string, signal?: AbortSignal): Promise<LocalOperationResult>;
+    cancel(attemptId: string): "local_canceled";
+    /** exchangeHandoff exchanges the redirect back for the session; a signal ends only this caller's wait, never the exchange. */
+    exchangeHandoff(callbackUri: string, signal?: AbortSignal): Promise<Session>;
+    /** restoreSession is the top-level restore on the web (webRenewal.ts); on mobile it is refreshSession. */
+    restoreSession(signal?: AbortSignal): Promise<Session>;
+    /** refreshSession renews in the background: on the web from the provider's cookie, on mobile with the stored refresh token. */
+    refreshSession(signal?: AbortSignal): Promise<Session>;
+    /** logout ends the session here at once and asks the provider to end it; a signal ends only this caller's wait, never the revocation. */
+    logout(signal?: AbortSignal): Promise<{
+        localCleared: true;
+        serverDisposition: "server_revoked" | "server_unconfirmed";
+    }>;
+    /**
+     * accessToken is the session's access token for the app's own backend, renewed first when it has
+     * less than 30 seconds to live or a read was refused with it. Never store it or put it in a URL.
+     */
+    accessToken(signal?: AbortSignal): Promise<string>;
+    me(signal?: AbortSignal): Promise<MeProjection>;
+    sessions(input?: AbortSignal | PageOptions): Promise<SessionProjection>;
+    /** wallets pages the account's own wallets, kind "wallet" in me(), which lists them with the linked ones. */
+    wallets(input?: AbortSignal | PageOptions): Promise<WalletProjection>;
+}