@shuttle.technology/authorization 0.1.0 → 0.2.0

package/dist/clientTypes.d.ts

@@ -0,0 +1,56 @@
+import type { MobileBrowserBridge, MobileSecureStorage } from "./mobile.ts";
+import type { DeviceShareStore } from "./deviceShares.ts";
+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>;
+interface CommonDependencies {
+    fetch?: FetchLike;
+    crypto?: Crypto;
+    now?: () => number;
+    /**
+     * Where the SDK keeps the device key and the device share of each wallet it
+     * made the key for, and of each wallet it recovered onto this device. On the
+     * web it is the origin's IndexedDB when left out; on mobile there is none
+     * unless the app supplies one, and every call that asks the SDK for a share
+     * then refuses with device_share_unavailable.
+     */
+    deviceShares?: DeviceShareStore;
+}
+export interface WebDependencies extends CommonDependencies {
+    currentOrigin: () => string;
+    /**
+     * Opens a separate top-level browsing context; restore needs the final registered redirect back, the verifier staying in memory.
+     * A restore passes a signal that aborts once no caller waits for it any more: the host then closes the context it opened.
+     * A confirmation the SDK runs by itself (the recovery of a device share) needs the redirect back too.
+     */
+    openHosted: (url: string, signal?: AbortSignal) => 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 {};

package/dist/clientTypes.js

@@ -0,0 +1,5 @@
+// The ports the host hands initializeAuthorizationClient: its fetch, its
+// WebCrypto and clock, how a provider page is opened (a top-level window on
+// the web, the system browser on mobile), the mobile secure storage, and where
+// the device shares this SDK keeps live (deviceShares.ts).
+export {};

package/dist/configuration.d.ts

@@ -0,0 +1,48 @@
+/**
+ * The public configuration a client is initialized with, checked before any
+ * request, and the provider's public description of a web client, read and
+ * checked against it at initialization. Neither holds any authority.
+ */
+import { type ClientChannel, type IdentityMethod } from "./auth.ts";
+import type { FetchLike } from "./client.ts";
+export interface ClientConfiguration {
+    mode: "mode_b";
+    channel: ClientChannel;
+    /** The provider's API origin, such as https://demo.shuttle.technology; exact, HTTPS, no path. */
+    authorizationOrigin: string;
+    /** The web application's own exact origin; web only. */
+    applicationOrigin?: string;
+    /** Where the provider's pages return to: on the web, the page that starts the sign-in also completes it. */
+    redirectUri: string;
+    publishableClientId: string;
+    tenantId: string;
+    applicationId: string;
+    environmentId: string;
+    methods: readonly IdentityMethod[];
+    /** The app's bundle or package identifier; mobile only. */
+    mobileApplicationIdentifier?: string;
+}
+/**
+ * What an app passes. On the web, applicationOrigin and redirectUri may be left out: they are then
+ * the current page's origin and the current page (origin and path), so the page that starts a
+ * sign-in also completes it. Given, they are checked as they are. Mobile apps give both.
+ */
+export type ClientSettings = Omit<ClientConfiguration, "applicationOrigin" | "redirectUri"> & {
+    applicationOrigin?: string;
+    redirectUri?: string;
+};
+/** The settings with the web defaults filled from the current page; nothing is filled on mobile. */
+export declare function resolveConfiguration(settings: ClientSettings, currentOrigin: (() => string) | undefined): ClientConfiguration;
+export interface PublicClientConfiguration {
+    requestId: string;
+    id: string;
+    name: string;
+    environmentId: string;
+    methods: readonly IdentityMethod[];
+    providerOrigin: string;
+    rpId: string;
+    redirects: readonly string[];
+    platform: ClientChannel;
+}
+export declare function validateConfiguration(configuration: ClientConfiguration): void;
+export declare function readPublicConfiguration(configuration: ClientConfiguration, fetch: FetchLike): Promise<PublicClientConfiguration>;

package/dist/configuration.js

@@ -0,0 +1,72 @@
+/**
+ * The public configuration a client is initialized with, checked before any
+ * request, and the provider's public description of a web client, read and
+ * checked against it at initialization. Neither holds any authority.
+ */
+import { ClientFlowError, identityMethods, opaqueId, parseAuthorizationError, record } from "./auth.js";
+import { exactAppOrigin, exactAppRedirect, exactHttpsOrigin } from "./redirects.js";
+import { mobileApplicationIdentifier } from "./mobile.js";
+/** The settings with the web defaults filled from the current page; nothing is filled on mobile. */
+export function resolveConfiguration(settings, currentOrigin) {
+    if (settings.channel !== "web")
+        return { ...settings };
+    const origin = settings.applicationOrigin ?? (typeof currentOrigin === "function" ? currentOrigin() : undefined);
+    const page = globalThis.location;
+    const redirect = settings.redirectUri ?? (origin !== undefined && page?.origin === origin && typeof page.pathname === "string" ? origin + page.pathname : undefined);
+    return { ...settings, applicationOrigin: origin, redirectUri: redirect };
+}
+export function validateConfiguration(configuration) {
+    const allowedFields = ["applicationId", "applicationOrigin", "authorizationOrigin", "channel", "environmentId", "methods", "mobileApplicationIdentifier", "mode", "publishableClientId", "redirectUri", "tenantId"];
+    if (Object.keys(configuration).some((field) => !allowedFields.includes(field)))
+        throw new ClientFlowError("invalid_public_configuration");
+    if (configuration.mode !== "mode_b" || (configuration.channel !== "web" && configuration.channel !== "mobile") || !exactHttpsOrigin(configuration.authorizationOrigin) || typeof configuration.redirectUri !== "string" || !exactAppRedirect(configuration.redirectUri) || !opaqueId(configuration.publishableClientId) || !opaqueId(configuration.tenantId) || !opaqueId(configuration.applicationId) || !opaqueId(configuration.environmentId) || configuration.methods.length === 0 || new Set(configuration.methods).size !== configuration.methods.length || configuration.methods.some((method) => !identityMethods.includes(method))) {
+        throw new ClientFlowError("invalid_public_configuration");
+    }
+    if (configuration.channel === "web" && (!configuration.applicationOrigin || !exactAppOrigin(configuration.applicationOrigin) || configuration.mobileApplicationIdentifier !== undefined))
+        throw new ClientFlowError("invalid_public_configuration");
+    if (configuration.channel === "mobile" && (configuration.applicationOrigin !== undefined || !mobileApplicationIdentifier(configuration.mobileApplicationIdentifier)))
+        throw new ClientFlowError("invalid_public_configuration");
+}
+export async function readPublicConfiguration(configuration, fetch) {
+    const response = await fetch(`${configuration.authorizationOrigin}/v1/public/clients/${encodeURIComponent(configuration.publishableClientId)}`, {
+        method: "GET",
+        headers: { Accept: "application/json" },
+        credentials: "omit",
+        cache: "no-store",
+    });
+    const payload = await response.json();
+    if (!response.ok)
+        throw parseAuthorizationError(payload, response.status);
+    const root = record(payload, ["request_id", "client"]);
+    const client = record(root.client, ["id", "name", "environment_id", "methods", "provider_origin", "rp_id", "redirects", "platform"]);
+    if (!opaqueId(root.request_id) || client.id !== configuration.publishableClientId || typeof client.name !== "string" || client.name.length < 1 || client.name.length > 128 || client.environment_id !== configuration.environmentId || !Array.isArray(client.methods) || client.methods.length < 1 || client.methods.length > identityMethods.length || !client.methods.every((method) => typeof method === "string" && identityMethods.includes(method)) || new Set(client.methods).size !== client.methods.length || !sameStrings(client.methods, configuration.methods) || client.provider_origin !== configuration.authorizationOrigin || typeof client.rp_id !== "string" || client.rp_id.length === 0 || !knownRedirects(client.redirects, configuration.redirectUri) || client.platform !== "web") {
+        throw new ClientFlowError("invalid_public_configuration");
+    }
+    return Object.freeze({
+        requestId: root.request_id,
+        id: client.id,
+        name: client.name,
+        environmentId: client.environment_id,
+        methods: Object.freeze([...client.methods]),
+        providerOrigin: client.provider_origin,
+        rpId: client.rp_id,
+        redirects: Object.freeze([...client.redirects]),
+        platform: client.platform,
+    });
+}
+// A client registered for any origin lists its redirects as exactly ["*"]: any redirect the app's
+// own checks accept. Otherwise the app's redirect is one of the client's exact ones.
+function knownRedirects(redirects, redirectUri) {
+    if (!Array.isArray(redirects))
+        return false;
+    if (redirects.length === 1 && redirects[0] === "*")
+        return true;
+    return redirects.length >= 1 && redirects.length <= 20 && redirects.every((redirect) => typeof redirect === "string" && exactAppRedirect(redirect)) &&
+        new Set(redirects).size === redirects.length && redirects.includes(redirectUri);
+}
+function sameStrings(left, right) {
+    if (left.length !== right.length)
+        return false;
+    const expected = new Set(right);
+    return left.every((value) => typeof value === "string" && expected.has(value));
+}

package/dist/consentDebit.d.ts

@@ -0,0 +1,36 @@
+import { type DebitAssetBound } from './debitPermissionWire.ts';
+import type { DebitPermissions } from './debitPermissions.ts';
+import type { LocalOperation, LocalOperationResult } from './slice4.ts';
+import type { UserWalletOperation, WalletResult } from './walletOperations.ts';
+/** The debit terms a grant froze from its service: per asset the most one debit and 24 hours may move, and the recipients (empty: any). */
+export interface DebitTerms {
+    readonly assets: readonly DebitAssetBound[];
+    readonly recipients: readonly string[];
+}
+/**
+ * What became of the debit permission a consent creates. succeeded: the permission is active, operationId is the
+ * debit_permission.create operation and the permission's ID. not_set: it was not created, for the reason code says;
+ * the person then lets the service debit alone (createDebitPermission, with its own passkey) or opens the wallet to
+ * the service again. authorized is the provider's answer before the SDK executes it, and never reaches the app.
+ */
+export interface ConsentDebitOutcome {
+    state: 'succeeded' | 'not_set' | 'authorized';
+    operationId?: string;
+    code?: string;
+}
+/** parseDebitTerms reads the terms a display names, in their closed form. */
+export declare function parseDebitTerms(value: unknown): DebitTerms;
+/** parseConsentDebitOutcome reads the debit member of a creation's or a grant's result: a code exactly for not_set. */
+export declare function parseConsentDebitOutcome(value: unknown): ConsentDebitOutcome;
+/** What settling needs of the client: its reads and its linked-wallet facade. */
+export interface ConsentDebitClient {
+    walletOperation(operationId: string, signal?: AbortSignal): Promise<UserWalletOperation>;
+    operation(operationId: string, signal?: AbortSignal): Promise<LocalOperation>;
+    linkedWallets(): {
+        debitPermissions(): DebitPermissions;
+    };
+}
+/** settleCreationDebit settles the debit permission a creation's consent created beside its grant. */
+export declare function settleCreationDebit(client: ConsentDebitClient, released: WalletResult, signal?: AbortSignal): Promise<WalletResult>;
+/** settleGrantDebit settles the debit permission a grant's consent created. */
+export declare function settleGrantDebit(client: ConsentDebitClient, grantOperationId: string, released: LocalOperationResult, signal?: AbortSignal): Promise<LocalOperationResult>;

package/dist/consentDebit.js

@@ -0,0 +1,95 @@
+// The debit permission that rides on a grant (owner decision of 28 October
+// 2026). A service that holds wallet:debit:user carries the debit terms the
+// platform's operator set for it. Whenever the person opens a wallet to such a
+// service, by createWallet({ grant }) or by createServiceGrant(), the
+// provider's page names those terms and the one passkey confirmation also
+// creates the service's debit permission on the wallet. Nothing is for the app
+// to pass: once the creation's or the grant's result is read, the provider
+// has authorized the permission by that consent, and the SDK executes it at
+// once, handing the wallet's device share to the platform share keeper sealed
+// to the keeper's key, and only for the confirmed operation at its version.
+// The result then says succeeded, or not_set with the code.
+import { AuthorizationError, ClientFlowError, opaqueId, record } from './auth.js';
+import { isAuthorizationErrorCode } from './errors.js';
+import { recipients, wireBounds } from './debitPermissionWire.js';
+import { lowerUUID } from './walletDisplayParts.js';
+/** parseDebitTerms reads the terms a display names, in their closed form. */
+export function parseDebitTerms(value) {
+    let terms;
+    try {
+        terms = record(value, ['assets', 'recipients']);
+    }
+    catch {
+        throw new ClientFlowError('invalid_server_response');
+    }
+    if (!recipients(terms.recipients))
+        throw new ClientFlowError('invalid_server_response');
+    return Object.freeze({ assets: wireBounds(terms.assets), recipients: Object.freeze([...terms.recipients]) });
+}
+/** parseConsentDebitOutcome reads the debit member of a creation's or a grant's result: a code exactly for not_set. */
+export function parseConsentDebitOutcome(value) {
+    let outcome;
+    try {
+        outcome = record(value, ['state'], ['operation_id', 'code']);
+    }
+    catch {
+        throw new ClientFlowError('invalid_server_response');
+    }
+    const state = outcome.state;
+    if ((state !== 'authorized' && state !== 'succeeded' && state !== 'not_set') || (outcome.operation_id !== undefined && !lowerUUID(outcome.operation_id)) ||
+        (state === 'not_set') !== (outcome.code !== undefined) || (outcome.code !== undefined && !isAuthorizationErrorCode(outcome.code)) || (state !== 'not_set' && outcome.operation_id === undefined)) {
+        throw new ClientFlowError('invalid_server_response');
+    }
+    const parsed = { state };
+    if (outcome.operation_id !== undefined)
+        parsed.operationId = outcome.operation_id;
+    if (outcome.code !== undefined)
+        parsed.code = outcome.code;
+    return parsed;
+}
+/**
+ * settle executes a permission the consent authorized, for the wallet and service the consent was about, and answers
+ * succeeded or not_set. It hands the share this browser keeps and never recovers one: a browser without a current
+ * share answers not_set with device_share_unavailable. The execute's key is derived from the operation, so reading the
+ * result again repeats it safely.
+ */
+async function settle(client, outcome, linkedWalletId, servicePrincipalId, signal) {
+    if (outcome.state !== 'authorized' || outcome.operationId === undefined)
+        return outcome;
+    const operationId = outcome.operationId;
+    try {
+        const read = await client.operation(operationId, signal);
+        if (read.display.kind !== 'debit_permission.create' || linkedWalletId === undefined || read.display.linkedWalletId !== linkedWalletId ||
+            servicePrincipalId === undefined || read.display.servicePrincipalId !== servicePrincipalId) {
+            return { state: 'not_set', operationId, code: 'invalid_server_response' };
+        }
+        if (read.state === 'succeeded')
+            return { state: 'succeeded', operationId };
+        // Reading a result never asks for a passkey: without a current share kept here, nothing is recovered or sent.
+        const executed = await client.linkedWallets().debitPermissions().executeConsentDebitPermission(operationId, read.version, `consent-debit-${operationId}`, signal);
+        return executed.state === 'succeeded' ? { state: 'succeeded', operationId } : { state: 'not_set', operationId, code: 'AUTHORIZATION_STALE' };
+    }
+    catch (error) {
+        if (error instanceof AuthorizationError || error instanceof ClientFlowError)
+            return { state: 'not_set', operationId, code: error.code };
+        throw error;
+    }
+}
+/** settleCreationDebit settles the debit permission a creation's consent created beside its grant. */
+export async function settleCreationDebit(client, released, signal) {
+    const debit = released.result.debit;
+    if (debit === undefined || debit.state !== 'authorized')
+        return released;
+    const creation = await client.walletOperation(released.result.operationId, signal);
+    const service = creation.display.kind === 'wallet.create' && !('materialPurged' in creation.display) ? creation.display.grant?.servicePrincipalId : undefined;
+    return { ...released, result: { ...released.result, debit: await settle(client, debit, released.result.grant?.linkedWalletId, service, signal) } };
+}
+/** settleGrantDebit settles the debit permission a grant's consent created. */
+export async function settleGrantDebit(client, grantOperationId, released, signal) {
+    const debit = released.result.debit;
+    if (debit === undefined || debit.state !== 'authorized' || !opaqueId(grantOperationId))
+        return released;
+    const grant = await client.operation(grantOperationId, signal);
+    const display = grant.display.kind === 'service_grant.set' ? grant.display : undefined;
+    return { ...released, result: { ...released.result, debit: await settle(client, debit, display?.walletId, display?.servicePrincipalId, signal) } };
+}

package/dist/credentials.d.ts

@@ -0,0 +1,116 @@
+/**
+ * The session's credentials and every change to them, in one place.
+ *
+ * Every attempt takes a generation when it starts, before anything is
+ * awaited: a sign-in (code exchange), a renewal or restore, a logout. A
+ * session's lineage is the generation of the sign-in (or first restore) it
+ * comes from; its renewals carry it on, and one lineage is installed at a
+ * time. A sign-in installs while no newer sign-in or logout began. A renewal
+ * installs while the installed lineage did not change since it began (an
+ * epoch counts every change, to none included; a rotation within the lineage
+ * is no change) and it answers the same session of the same account: on the
+ * web the cookie is shared by every tab, and a sign-in in another tab puts its
+ * own session there. A renewal or restore of an installed session that
+ * answers another one installs nothing and ends the installed session
+ * (session_replaced); a client with no session takes up what the cookie holds.
+ * A definitive refusal ends the lineage of the token it refused, also after a
+ * rotation, and nothing else. A logout ends everything older.
+ *
+ * Every change of memory and of secure storage runs in one queue, one after
+ * another, failure cleanup included, and installs only while its attempt is
+ * current at that moment. A renewal reads the stored refresh token only in
+ * the queue and is checked again after the read and before it asks the
+ * provider. A superseded attempt undoes its own storage write and nothing
+ * else. A stored token whose cleanup failed stays marked ended, so no restore
+ * takes it up again. On the web nothing is stored: the refresh credential is
+ * the provider's cookie, and a web renewal or restore is checked against its
+ * attempt under the tabs' lock (webRenewal.ts).
+ */
+import { type ClientChannel } from "./auth.ts";
+import type { MobileSecureStorage } from "./mobile.ts";
+export interface Session {
+    requestId: string;
+    accessExpiresAt: number;
+    accountId: string;
+    sessionId: string;
+    setupRequired?: boolean;
+}
+/**
+ * One sign-in, renewal or restore: its generation, the epoch of the installed
+ * lineage when it began, whether it founds a lineage (a restore with no
+ * session), the lineage it installs into (a founding restore takes up the
+ * lineage of a stored token it reads), and for a renewal of an installed
+ * session the session and account it must answer.
+ */
+export interface Attempt {
+    readonly generation: number;
+    readonly kind: "sign_in" | "renewal";
+    readonly epoch: number;
+    readonly founds: boolean;
+    lineage: number;
+    readonly renews?: {
+        readonly sessionId: string;
+        readonly accountId: string;
+    };
+}
+/** The credentials held now. */
+export interface Held {
+    readonly token: string;
+    readonly csrf?: string;
+    readonly session: Session;
+    readonly lineage: number;
+}
+/** A renewal that changed hands before it asked the provider anything. */
+export declare class Superseded extends Error {
+    constructor();
+}
+export declare class Credentials {
+    #private;
+    constructor(channel: ClientChannel, storage: MobileSecureStorage | undefined, key: string);
+    /** current is the credentials held, while their lineage is the one installed. */
+    current(): Held | undefined;
+    get hasSession(): boolean;
+    /** usable is the token to send now: none while there is no session or a read was refused with it. */
+    usable(): string;
+    /** dispatchable says a request may still go out with token: of the lineage installed, and not refused by a read. */
+    dispatchable(token: string): boolean;
+    /** due says the token is to be renewed first: it lives less than marginSeconds more, or a read was refused with it. */
+    due(nowSeconds: number, marginSeconds: number): boolean;
+    /**
+     * markRefused marks a token a read was refused with, held now or rotated
+     * away, so no call waiting with it sends it; it says whether it is the
+     * token held now, which only a renewal replaces.
+     */
+    markRefused(token: string): boolean;
+    /** signIn starts a sign-in: no older sign-in installs after it. */
+    signIn(): Attempt;
+    /** renewal starts a renewal of the lineage installed now, or a restore that founds one when none is. */
+    renewal(): Attempt;
+    /** check throws Superseded once the renewal is no longer current, right before it asks the provider. */
+    check(attempt: Attempt): void;
+    /** superseded answers for an overtaken renewal: the session held now, or none. */
+    superseded(): Session;
+    /** refreshToken reads the stored refresh token for a mobile renewal, in the queue, and checks the renewal again after the read. */
+    refreshToken(attempt: Attempt): Promise<string>;
+    /**
+     * install keeps what an exchange or a renewal answered, in the queue, only
+     * while its attempt is current: in secure storage first on mobile, then in
+     * memory. A current attempt whose write fails ends its lineage and clears
+     * the held and stored credentials; an attempt overtaken during its write
+     * puts back what was stored before and installs nothing.
+     */
+    install(attempt: Attempt, payload: unknown, exchange: boolean): Promise<Session>;
+    /** refuse ends the lineage of a token the provider refused for good, whichever of its tokens it was. */
+    refuse(token: string): void;
+    /** renewalFailed answers for a failed renewal: overtaken, it is the session now; refused for good, its lineage ends. */
+    renewalFailed(attempt: Attempt, error: unknown): Session;
+    /** end ends one lineage at once, and clears its held and stored credentials in the queue. */
+    end(lineage: number): void;
+    /** logout ends the session held at once and every older attempt, clears memory and storage in the queue, and answers what it ended. */
+    logout(): {
+        token?: string;
+        csrf?: string;
+        sessionId?: string;
+        cleared: Promise<void>;
+    };
+}