@shuttle.technology/authorization 0.1.0 → 0.2.0

package/dist/walletOperations.d.ts

@@ -1,13 +1,16 @@
 import { type NextAction } from "./auth.ts";
-import type { ResultRecipient } from "./slice4.ts";
 import { type DisplayCommon } from "./walletDisplayParts.ts";
+import { type LinkedRecoverCreate, type LinkedRecoverDisplay } from "./linkedRecovery.ts";
+import { type WalletCreateGrant, type WalletCreateGrantOutcome, type WalletCreateGrantWire } from "./walletCreateGrant.ts";
+import { type ConsentDebitOutcome, type DebitTerms } from "./consentDebit.ts";
 import { type LinkedSendDisplay, type LinkedWalletIdentity } from "./linkedSendDisplay.ts";
 import { type MediatedDisplay, type MediatedPurgedDisplay } from "./mediatedOperation.ts";
 export { LinkedSendAssets, MaxTransferCommentBytes, ReplaceActions, linkedSendAsset, replaceAction, transferComment } from "./linkedSendDisplay.ts";
 export type { LinkedSendAsset, LinkedSendDisplay, LinkedWalletIdentity, ReplaceAction } from "./linkedSendDisplay.ts";
+export type { LinkedRecoverCreate, LinkedRecoverDisplay } from "./linkedRecovery.ts";
 export type { MediatedDisplay, MediatedLinkedSendDisplay, MediatedPurgedDisplay, MediatedSendDisplay } from "./mediatedOperation.ts";
 export type UserWalletOperationKind = "wallet.create" | "wallet.sign" | "wallet.send" | "wallet.export" | "wallet.recover";
-export type WalletResultKind = "signature" | "transfer_receipt" | "wallet_created";
+export type WalletResultKind = "signature" | "transfer_receipt" | "wallet_created" | "device_share_recovered";
 export type UserWalletState = "awaiting_confirmation" | "authorized" | "dispatching" | "outcome_unknown" | "succeeded" | "failed" | "denied" | "canceled" | "expired";
 export type UserWalletEffectState = "no_effect" | "possible" | "known";
 /**
@@ -20,10 +23,15 @@ export type UserWalletEffectState = "no_effect" | "possible" | "known";
  * MediatedDisplay, with no result recipient.
  */
 export type UserWalletAuthorizationBasis = "" | "user_confirmed" | "session_authorized" | "user_request_signed";
+/**
+ * A wallet operation's result goes to its owner account only, so no create
+ * body names a result recipient: the device share of a created, exported or
+ * recovered wallet reaches this device alone, and the server refuses a
+ * service named as the recipient with INVALID_REQUEST.
+ */
 type UserWalletCommon = {
     owner_type: "account";
     owner_id: string;
-    result_recipient?: ResultRecipient;
 };
 /**
  * UserWalletOperationCreate is the closed request body of source §2.2: the
@@ -36,6 +44,7 @@ export type UserWalletOperationCreate = (UserWalletCommon & {
         network: string;
         recipient_public_key: string;
     };
+    grant?: WalletCreateGrantWire;
 }) | (UserWalletCommon & {
     kind: "wallet.sign";
     wallet_id: string;
@@ -66,7 +75,7 @@ export type UserWalletOperationCreate = (UserWalletCommon & {
         expected_generation: string;
         recipient_public_key: string;
     };
-});
+}) | LinkedRecoverCreate;
 /** UserWalletPurgedDisplay is the safe identity left after material retention expires. */
 export type UserWalletPurgedDisplay = DisplayCommon & {
     kind: UserWalletOperationKind;
@@ -83,6 +92,8 @@ export type UserWalletDisplay = UserWalletPurgedDisplay | (DisplayCommon & {
     network: string;
     recipientPublicKey: string;
     preparedSummary?: string;
+    grant?: WalletCreateGrant;
+    debit?: DebitTerms;
 }) | (DisplayCommon & {
     kind: "wallet.sign";
     network: string;
@@ -105,7 +116,7 @@ export type UserWalletDisplay = UserWalletPurgedDisplay | (DisplayCommon & {
     recipientPublicKey: string;
     expectedGeneration: string;
     preparedSummary?: string;
-}) | MediatedDisplay;
+}) | LinkedRecoverDisplay | MediatedDisplay;
 /** walletMaterialPurged separates the purged display from every material display. */
 export declare function walletMaterialPurged(display: UserWalletDisplay): display is UserWalletPurgedDisplay | MediatedPurgedDisplay;
 export interface UserWalletOperation {
@@ -163,8 +174,14 @@ export interface WalletResult {
         outputBase64url?: string;
         /** Present exactly for a wallet_created result. */
         wallet?: CreatedWallet;
-        /** Present exactly for a wallet_created result. */
+        /** Present exactly for a wallet_created and a device_share_recovered result. */
         deviceShare?: DeviceSharePackage;
+        /** Present exactly for a device_share_recovered result: the linked wallet whose share was recovered. */
+        linkedWalletId?: string;
+        /** Present for a wallet_created result whose creation named a grant (walletCreateGrant.ts). */
+        grant?: WalletCreateGrantOutcome;
+        /** Present when the grant's service holds wallet:debit:user: the debit permission the creation's passkey also created (consentDebit.ts). */
+        debit?: ConsentDebitOutcome;
     };
 }
 /** MaxWalletMessageBytes is the decoded wallet.sign payload bound of source §2.8. */

package/dist/walletOperations.js

@@ -5,7 +5,10 @@
 // authority. Local faults raise ClientFlowError; server denials stay
 // AuthorizationError and are produced by the caller's transport.
 import { ClientFlowError, canonicalDecimal, deadlineAfter, isNextAction, opaqueId, record, rfc3339UTC, } from "./auth.js";
-import { bindingRevision, displayCommon, lowerUUID, rawQuantity, summaryOf, walletRecipient } from "./walletDisplayParts.js";
+import { bindingRevision, displayCommon, lowerHexBytes, lowerUUID, rawQuantity, summaryOf, walletRecipient } from "./walletDisplayParts.js";
+import { parseLinkedRecoverDisplay, parseRecoveredShareResult, validLinkedRecoverCreate } from "./linkedRecovery.js";
+import { parseWalletCreateGrant, parseWalletCreateGrantOutcome, validWalletCreateGrant } from "./walletCreateGrant.js";
+import { parseConsentDebitOutcome, parseDebitTerms } from "./consentDebit.js";
 import { parseLinkedSendDisplay } from "./linkedSendDisplay.js";
 import { parseMediatedOperation } from "./mediatedOperation.js";
 export { LinkedSendAssets, MaxTransferCommentBytes, ReplaceActions, linkedSendAsset, replaceAction, transferComment } from "./linkedSendDisplay.js";
@@ -28,14 +31,17 @@ const base64urlValue = /^[A-Za-z0-9_-]+$/;
  * caller sends the same closed body it validated.
  */
 export function validateUserWalletCreate(value, expectedOwnerId) {
-    const common = record(value, ["kind", "owner_type", "owner_id", "payload"], ["wallet_id", "result_recipient"]);
-    if (common.owner_type !== "account" || !opaqueId(common.owner_id) || common.owner_id !== expectedOwnerId) {
+    const common = record(value, ["kind", "owner_type", "owner_id", "payload"], ["wallet_id", "linked_wallet_id", "grant"]);
+    // A grant is named beside a creation alone.
+    if (common.owner_type !== "account" || !opaqueId(common.owner_id) || common.owner_id !== expectedOwnerId ||
+        (common.grant !== undefined && (common.kind !== "wallet.create" || !validWalletCreateGrant(common.grant)))) {
         throw new ClientFlowError("invalid_operation_create");
     }
-    if (common.result_recipient !== undefined) {
-        const recipient = record(common.result_recipient, ["type", "id"]);
-        if ((recipient.type !== "account" && recipient.type !== "service") || !opaqueId(recipient.id))
+    // A linked wallet is named by a recovery of its device share alone (linkedRecovery.ts).
+    if (common.linked_wallet_id !== undefined) {
+        if (!validLinkedRecoverCreate(common))
             throw new ClientFlowError("invalid_operation_create");
+        return value;
     }
     const walletRequired = common.kind !== "wallet.create";
     if (walletRequired !== opaqueId(common.wallet_id))
@@ -101,17 +107,19 @@ export function parseUserWalletOperation(payload) {
         (root.result_kind !== undefined && !walletResultKind(root.result_kind)) || !isNextAction(root.next_action)) {
         throw new ClientFlowError("invalid_server_response");
     }
-    // A linked wallet is named by all three of its members, only for a send,
-    // and never beside an own wallet.
+    // A linked wallet is named by all three of its members, only for a send or
+    // the recovery of its device share, never beside an own wallet; only a send
+    // is authorized by the session alone.
     const linked = root.binding_source !== undefined;
-    if (linked && (root.binding_source !== "linked_wallet" || root.kind !== "wallet.send" || root.wallet_id !== undefined ||
-        !lowerUUID(root.connection_id) || !lowerUUID(root.linked_wallet_id) || !bindingRevision(root.binding_revision))) {
+    if (linked && (root.binding_source !== "linked_wallet" || (root.kind !== "wallet.send" && root.kind !== "wallet.recover") || root.wallet_id !== undefined ||
+        !lowerUUID(root.connection_id) || !lowerUUID(root.linked_wallet_id) || !bindingRevision(root.binding_revision) ||
+        (root.kind === "wallet.recover" && root.authorization_basis === "session_authorized"))) {
         throw new ClientFlowError("invalid_server_response");
     }
     if (!linked && (root.connection_id !== undefined || root.linked_wallet_id !== undefined || root.binding_revision !== undefined || root.authorization_basis === "session_authorized")) {
         throw new ClientFlowError("invalid_server_response");
     }
-    const display = linked && !purgedDisplay(root.display) ? parseLinkedSendDisplay(root.display) : parseUserWalletDisplay(root.display, root.kind);
+    const display = linked && !purgedDisplay(root.display) ? (root.kind === "wallet.recover" ? parseLinkedRecoverDisplay(root.display) : parseLinkedSendDisplay(root.display)) : parseUserWalletDisplay(root.display, root.kind);
     if (display.ownerId !== root.owner_id || display.requesterId !== root.requester_id || display.walletId !== root.wallet_id) {
         throw new ClientFlowError("invalid_server_response");
     }
@@ -153,12 +161,14 @@ export function parseUserWalletOperation(payload) {
  */
 export function parseWalletResult(payload, expectedOperationId) {
     const root = record(payload, ["request_id", "result"]);
-    if (root.result !== null && typeof root.result === "object" && root.result.kind === "wallet_created") {
+    const resultKind = root.result !== null && typeof root.result === "object" ? root.result.kind : undefined;
+    if (resultKind === "wallet_created")
         return parseCreatedWalletResult(root.request_id, root.result, expectedOperationId);
-    }
+    if (resultKind === "device_share_recovered")
+        return parseRecoveredShareResult(root.request_id, root.result, expectedOperationId);
     const result = record(root.result, ["operation_id", "kind", "receipt_id"], ["output_base64url"]);
     if (!opaqueId(root.request_id) || !opaqueId(result.operation_id) || result.operation_id !== expectedOperationId ||
-        !walletResultKind(result.kind) || result.kind === "wallet_created" || !opaqueId(result.receipt_id)) {
+        !walletResultKind(result.kind) || result.kind === "wallet_created" || result.kind === "device_share_recovered" || !opaqueId(result.receipt_id)) {
         throw new ClientFlowError("invalid_server_response");
     }
     if (result.kind === "signature") {
@@ -171,7 +181,7 @@ export function parseWalletResult(payload, expectedOperationId) {
     return { requestId: root.request_id, result: { operationId: result.operation_id, kind: result.kind, receiptId: result.receipt_id } };
 }
 function parseCreatedWalletResult(requestId, value, expectedOperationId) {
-    const result = record(value, ["operation_id", "kind", "receipt_id", "wallet", "device_share"]);
+    const result = record(value, ["operation_id", "kind", "receipt_id", "wallet", "device_share"], ["grant", "debit"]);
     const wallet = record(result.wallet, ["wallet_id", "key_id", "network", "address", "algorithm", "public_key"]);
     const share = record(result.device_share, ["ciphertext", "nonce", "ephemeral_public_key", "encryption_algorithm", "encryption_context"]);
     // The receipt of a creation is the created wallet ID; a result naming two
@@ -189,6 +199,8 @@ function parseCreatedWalletResult(requestId, value, expectedOperationId) {
             operationId: expectedOperationId, kind: "wallet_created", receiptId: wallet.wallet_id,
             wallet: { walletId: wallet.wallet_id, keyId: wallet.key_id, network: wallet.network, address: wallet.address, algorithm: wallet.algorithm, publicKey: wallet.public_key },
             deviceShare: { ciphertext: share.ciphertext, nonce: share.nonce, ephemeralPublicKey: share.ephemeral_public_key, encryptionAlgorithm: share.encryption_algorithm, encryptionContext: share.encryption_context },
+            ...(result.grant === undefined ? {} : { grant: parseWalletCreateGrantOutcome(result.grant) }),
+            ...(result.debit === undefined ? {} : { debit: parseConsentDebitOutcome(result.debit) }),
         },
     };
 }
@@ -206,10 +218,11 @@ function parseUserWalletDisplay(value, kind) {
     }
     switch (kind) {
         case "wallet.create": {
-            const display = record(value, ["kind", "owner_id", "requester_id", "result_recipient", "network", "recipient_public_key"], ["wallet_id", "prepared_summary"]);
+            const display = record(value, ["kind", "owner_id", "requester_id", "result_recipient", "network", "recipient_public_key"], ["wallet_id", "prepared_summary", "grant", "debit"]);
             if (display.kind !== kind || !network(display.network) || !recipientPublicKey(display.recipient_public_key))
                 throw new ClientFlowError("invalid_server_response");
-            return { ...displayCommon(display), kind, network: display.network, recipientPublicKey: display.recipient_public_key, ...summaryOf(display.prepared_summary) };
+            return { ...displayCommon(display), kind, network: display.network, recipientPublicKey: display.recipient_public_key, ...summaryOf(display.prepared_summary),
+                ...(display.grant === undefined ? {} : { grant: parseWalletCreateGrant(display.grant) }), ...(display.debit === undefined ? {} : { debit: parseDebitTerms(display.debit) }) };
         }
         case "wallet.sign": {
             const display = record(value, ["kind", "owner_id", "requester_id", "result_recipient", "network", "message_base64url"], ["wallet_id", "prepared_summary"]);
@@ -273,11 +286,7 @@ function userWalletKind(value) {
     return value === "wallet.create" || value === "wallet.sign" || value === "wallet.send" || value === "wallet.export" || value === "wallet.recover";
 }
 function walletResultKind(value) {
-    return value === "signature" || value === "transfer_receipt" || value === "wallet_created";
-}
-/** lowerHexBytes accepts 1..1024 bytes of lowercase hexadecimal. */
-function lowerHexBytes(value) {
-    return typeof value === "string" && value.length >= 2 && value.length <= 2048 && value.length % 2 === 0 && /^[0-9a-f]+$/.test(value);
+    return value === "signature" || value === "transfer_receipt" || value === "wallet_created" || value === "device_share_recovered";
 }
 function algorithmName(value) {
     return typeof value === "string" && /^[a-z0-9_-]{1,128}$/.test(value);

package/dist/webRenewal.d.ts

@@ -0,0 +1,92 @@
+import type { FetchLike } from "./client.ts";
+/** The code of the typed error that asks the application to start the top-level restore. */
+export declare const webRenewalRequiresNavigation = "web_renewal_requires_navigation";
+interface WebSessionTarget {
+    authorizationOrigin: string;
+    clientId: string;
+    /** The name the tabs of one application take turns under. */
+    lockName: string;
+    signal?: AbortSignal;
+    /** Throws once the renewal or restore was superseded; asked under the lock right before each step that asks the provider. */
+    current?: () => void;
+}
+export interface WebRenewalRequest extends WebSessionTarget {
+    fetch: FetchLike;
+    /** The session's CSRF token, held in memory only; without one the renewal starts from the cookie. */
+    csrfToken: string | undefined;
+}
+export interface WebRestoreRequest extends WebSessionTarget {
+    redirectUri: string;
+    crypto: Crypto;
+    /** The host's top-level launcher; it answers the registered redirect the restore came back to. */
+    launch: (url: string, signal?: AbortSignal) => Promise<string | void>;
+    /** POST /v1/auth/restore with this body, answering the session payload. */
+    exchange: (body: string) => Promise<unknown>;
+}
+/**
+ * The tabs of one application share the cookie, and the provider ends a
+ * session whose refresh value it is shown twice. Every renewal and every
+ * restore therefore runs under one Web Lock per client: each sends the value
+ * the previous one left. A restore holds it until the host's launcher
+ * settles or the restore's signal aborts it; the host gets the same signal
+ * and closes its window, so no abandoned navigation rotates the value later.
+ * A sign-in's exchange, which sets the cookie too, goes out under the same
+ * lock (client.ts), so a renewal's late answer never follows a newer
+ * sign-in's.
+ */
+export declare function underRenewalLock<T>(target: WebSessionTarget & {
+    whenWaiting?: () => void;
+}, work: () => Promise<T>): Promise<T>;
+/**
+ * renewWebSession is the background call: POST /v1/auth/renew with the cookie
+ * (credentials: "include"). A page that holds the session's CSRF token sends
+ * it; a page that holds none (a reload, a new tab), or whose token a renewal
+ * or restore in another tab replaced, renews from the cookie alone with the
+ * fixed X-Authorization-Renew header and gets a new token. It answers the
+ * session payload.
+ */
+export declare function renewWebSession(request: WebRenewalRequest): Promise<unknown>;
+/**
+ * staleCsrfRefusal is the answer a web lifecycle call gets when a renewal or
+ * restore in another tab replaced the session's CSRF token since this page
+ * last renewed.
+ */
+export declare function staleCsrfRefusal(error: unknown): boolean;
+/**
+ * revokeWithCurrentCredentials is logout's way past a CSRF token another tab
+ * replaced. Under the tabs' lock, held until the revocation answers, it
+ * renews from the cookie alone and revokes with the tokens that answer, but
+ * only when they belong to the session the logout was asked for: a cookie
+ * another sign-in replaced is left alone and the revocation is not confirmed.
+ */
+export declare function revokeWithCurrentCredentials(request: Omit<WebRenewalRequest, "csrfToken"> & {
+    sessionId: string;
+    whenWaiting?: () => void;
+}, revoke: (accessToken: string, csrfToken: string) => Promise<unknown>): Promise<unknown>;
+/** revokedAnswer says a logout answer confirms the revocation. */
+export declare function revokedAnswer(payload: unknown): boolean;
+/**
+ * revokeUnclaimedSession ends the session of a sign-in answer this page does
+ * not install, because a logout or a newer sign-in overtook it while it was
+ * asked for. The answer set the cookie, so without it a reload would take up
+ * a session nobody holds, one the person may have logged out of. The
+ * provider clears the cookie only while it holds that session. A CSRF token
+ * another tab replaced meanwhile (it renewed that session from the cookie) is
+ * followed by the logout's recovery: one renewal from the cookie under the
+ * tabs' lock, checked against the answer's session, and the revocation with
+ * its tokens. It answers true only for a confirmed revocation of exactly that
+ * session; a cookie that holds another session is left alone and answers
+ * false, as does any refusal or failure. whenWaiting is told when the
+ * recovery has to wait for the lock (a restore may hold it while its window
+ * is open): the revocation goes on, but nobody needs to wait for its verdict.
+ */
+export declare function revokeUnclaimedSession(request: Omit<WebRenewalRequest, "csrfToken"> & {
+    whenWaiting?: () => void;
+}, payload: unknown, revoke: (accessToken: string, csrfToken: string) => Promise<unknown>): Promise<boolean>;
+/**
+ * restoreWebSession is the top-level restore: a fresh state and S256 verifier
+ * in memory, the provider restore URL through the host's launcher, and the
+ * one-use handoff of the redirect it returns exchanged for the session.
+ */
+export declare function restoreWebSession(request: WebRestoreRequest): Promise<unknown>;
+export {};

package/dist/webRenewal.js

@@ -0,0 +1,179 @@
+// The web session's renewal (owner decision of 27 October 2026). The refresh
+// credential is the provider's HttpOnly cookie, partitioned to the site the
+// application runs on, so a background call from the application carries it
+// and no navigation is needed, also after a reload or in a new tab. When the
+// browser sends no cookie the call is refused and the SDK raises
+// web_renewal_requires_navigation: the application then starts the top-level
+// restore (restoreSession) itself. The SDK never navigates on its own. The
+// restore sequence is here too, under the same lock.
+import { abortable, ClientFlowError, newHandoffBinding, opaqueId, parseAuthorizationError, record } from "./auth.js";
+import { restoreCallback } from "./redirects.js";
+/** The code of the typed error that asks the application to start the top-level restore. */
+export const webRenewalRequiresNavigation = "web_renewal_requires_navigation";
+/**
+ * The tabs of one application share the cookie, and the provider ends a
+ * session whose refresh value it is shown twice. Every renewal and every
+ * restore therefore runs under one Web Lock per client: each sends the value
+ * the previous one left. A restore holds it until the host's launcher
+ * settles or the restore's signal aborts it; the host gets the same signal
+ * and closes its window, so no abandoned navigation rotates the value later.
+ * A sign-in's exchange, which sets the cookie too, goes out under the same
+ * lock (client.ts), so a renewal's late answer never follows a newer
+ * sign-in's.
+ */
+export function underRenewalLock(target, work) {
+    const locks = globalThis.navigator?.locks;
+    if (!locks || typeof locks.request !== "function")
+        throw new ClientFlowError("runtime_capability_unavailable");
+    const whenWaiting = target.whenWaiting;
+    if (!whenWaiting)
+        return locks.request(target.lockName, { signal: target.signal }, work);
+    // Told when the lock is not free at once, the caller learns it waits; the work still runs once it is.
+    return locks.request(target.lockName, { ifAvailable: true }, async (lock) => (lock ? { ran: await work() } : undefined)).then((done) => {
+        if (done)
+            return done.ran;
+        whenWaiting();
+        return locks.request(target.lockName, { signal: target.signal }, work);
+    });
+}
+/**
+ * renewWebSession is the background call: POST /v1/auth/renew with the cookie
+ * (credentials: "include"). A page that holds the session's CSRF token sends
+ * it; a page that holds none (a reload, a new tab), or whose token a renewal
+ * or restore in another tab replaced, renews from the cookie alone with the
+ * fixed X-Authorization-Renew header and gets a new token. It answers the
+ * session payload.
+ */
+export async function renewWebSession(request) {
+    return underRenewalLock(request, async () => {
+        if (request.csrfToken) {
+            request.current?.();
+            const renewed = await renewOnce(request, { "X-CSRF-Token": request.csrfToken });
+            if (renewed.ok)
+                return renewed.payload;
+            if (renewed.refusal.status !== 403 || renewed.refusal.code !== "ORIGIN_NOT_ALLOWED")
+                throw refusedRenewal(renewed.refusal);
+        }
+        request.current?.();
+        const renewed = await renewOnce(request, { "X-Authorization-Renew": "1" });
+        if (renewed.ok)
+            return renewed.payload;
+        throw refusedRenewal(renewed.refusal);
+    });
+}
+/**
+ * staleCsrfRefusal is the answer a web lifecycle call gets when a renewal or
+ * restore in another tab replaced the session's CSRF token since this page
+ * last renewed.
+ */
+export function staleCsrfRefusal(error) {
+    return error instanceof Error && error.status === 403 && error.code === "ORIGIN_NOT_ALLOWED";
+}
+/**
+ * revokeWithCurrentCredentials is logout's way past a CSRF token another tab
+ * replaced. Under the tabs' lock, held until the revocation answers, it
+ * renews from the cookie alone and revokes with the tokens that answer, but
+ * only when they belong to the session the logout was asked for: a cookie
+ * another sign-in replaced is left alone and the revocation is not confirmed.
+ */
+export async function revokeWithCurrentCredentials(request, revoke) {
+    return underRenewalLock(request, async () => {
+        const renewed = await renewOnce({ ...request, csrfToken: undefined }, { "X-Authorization-Renew": "1" });
+        if (!renewed.ok)
+            throw refusedRenewal(renewed.refusal);
+        const payload = renewed.payload;
+        if (!payload || typeof payload.access_token !== "string" || payload.access_token === "" || typeof payload.csrf_token !== "string" || payload.csrf_token === "") {
+            throw new ClientFlowError("invalid_server_response");
+        }
+        if (payload.session_id !== request.sessionId)
+            throw new ClientFlowError("session_unavailable");
+        return revoke(payload.access_token, payload.csrf_token);
+    });
+}
+/** revokedAnswer says a logout answer confirms the revocation. */
+export function revokedAnswer(payload) {
+    try {
+        const result = record(payload, ["request_id", "server_disposition"]);
+        return opaqueId(result.request_id) && result.server_disposition === "server_revoked";
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * revokeUnclaimedSession ends the session of a sign-in answer this page does
+ * not install, because a logout or a newer sign-in overtook it while it was
+ * asked for. The answer set the cookie, so without it a reload would take up
+ * a session nobody holds, one the person may have logged out of. The
+ * provider clears the cookie only while it holds that session. A CSRF token
+ * another tab replaced meanwhile (it renewed that session from the cookie) is
+ * followed by the logout's recovery: one renewal from the cookie under the
+ * tabs' lock, checked against the answer's session, and the revocation with
+ * its tokens. It answers true only for a confirmed revocation of exactly that
+ * session; a cookie that holds another session is left alone and answers
+ * false, as does any refusal or failure. whenWaiting is told when the
+ * recovery has to wait for the lock (a restore may hold it while its window
+ * is open): the revocation goes on, but nobody needs to wait for its verdict.
+ */
+export async function revokeUnclaimedSession(request, payload, revoke) {
+    const answer = payload;
+    if (!answer || typeof answer !== "object" || typeof answer.access_token !== "string" || answer.access_token === "" ||
+        typeof answer.csrf_token !== "string" || answer.csrf_token === "" || !opaqueId(answer.session_id))
+        return false;
+    const sessionId = answer.session_id;
+    try {
+        return revokedAnswer(await revoke(answer.access_token, answer.csrf_token));
+    }
+    catch (error) {
+        if (!staleCsrfRefusal(error))
+            return false;
+    }
+    try {
+        return revokedAnswer(await revokeWithCurrentCredentials({ ...request, sessionId }, revoke));
+    }
+    catch {
+        return false;
+    }
+}
+async function renewOnce(request, header) {
+    const response = await request.fetch(`${request.authorizationOrigin}/v1/auth/renew`, {
+        method: "POST",
+        headers: { Accept: "application/json", "Content-Type": "application/json", ...header },
+        body: JSON.stringify({ client_id: request.clientId }),
+        credentials: "include",
+        cache: "no-store",
+        signal: request.signal,
+    });
+    const payload = await response.json();
+    return response.ok ? { ok: true, payload } : { ok: false, refusal: parseAuthorizationError(payload, response.status) };
+}
+// 401: the browser sent no cookie (it keeps no partitioned cookie) or the
+// value is no longer live; the top-level restore is the way back. Any other
+// refusal is passed on as it came.
+function refusedRenewal(refusal) {
+    return refusal.status === 401 && refusal.code === "UNAUTHORIZED" ? new ClientFlowError(webRenewalRequiresNavigation) : refusal;
+}
+/**
+ * restoreWebSession is the top-level restore: a fresh state and S256 verifier
+ * in memory, the provider restore URL through the host's launcher, and the
+ * one-use handoff of the redirect it returns exchanged for the session.
+ */
+export async function restoreWebSession(request) {
+    return underRenewalLock(request, async () => {
+        const binding = await newHandoffBinding(request.crypto);
+        request.signal?.throwIfAborted();
+        const start = new URL("/v1/auth/restore", request.authorizationOrigin);
+        for (const [name, value] of [["client_id", request.clientId], ["redirect_uri", request.redirectUri], ["state", binding.state], ["code_challenge", binding.challenge], ["code_challenge_method", "S256"]]) {
+            start.searchParams.set(name, value);
+        }
+        request.current?.();
+        const returned = await abortable(request.launch(start.toString(), request.signal), request.signal);
+        if (typeof returned !== "string")
+            throw new ClientFlowError("restore_redirect_unavailable");
+        const handoff = restoreCallback(returned, request.redirectUri);
+        if (handoff.state !== binding.state)
+            throw new ClientFlowError("state_mismatch");
+        request.current?.();
+        return request.exchange(JSON.stringify({ client_id: request.clientId, restore_id: handoff.restoreId, code: handoff.code, verifier: binding.verifier, redirect_uri: request.redirectUri }));
+    });
+}

package/package.json

@@ -1,66 +1,68 @@
 {
   "name": "@shuttle.technology/authorization",
-  "version": "0.1.0",
-  "description": "TypeScript SDK for Streams Authorization and authorized wallet operations.",
-  "homepage": "https://www.npmjs.com/package/@shuttle.technology/authorization",
-  "packageManager": "pnpm@11.19.0",
+  "version": "0.2.0",
+  "description": "Browser and mobile client of the Streams Authorization API: hosted sign-in, the account's wallets, service grants, limits, Mode B sends and Mode C signed requests.",
   "type": "module",
+  "sideEffects": false,
   "files": [
     "dist/**/*.js",
     "dist/**/*.d.ts",
-    "README.md"
+    "README.md",
+    "CHANGELOG.md"
   ],
   "main": "./dist/client.js",
   "types": "./dist/client.d.ts",
   "exports": {
     ".": {
       "types": "./dist/client.d.ts",
-      "import": "./dist/client.js"
+      "default": "./dist/client.js"
     },
     "./mode-c": {
       "types": "./dist/modeC.d.ts",
-      "import": "./dist/modeC.js"
+      "default": "./dist/modeC.js"
     },
     "./mode-c-linked": {
       "types": "./dist/modeCLinked.d.ts",
-      "import": "./dist/modeCLinked.js"
+      "default": "./dist/modeCLinked.js"
     },
     "./streams": {
       "types": "./dist/streams.d.ts",
-      "import": "./dist/streams.js"
+      "default": "./dist/streams.js"
     },
     "./linked-wallets": {
       "types": "./dist/linkedWallets.d.ts",
-      "import": "./dist/linkedWallets.js"
+      "default": "./dist/linkedWallets.js"
+    },
+    "./debit-permissions": {
+      "types": "./dist/debitPermissions.d.ts",
+      "default": "./dist/debitPermissions.js"
     },
     "./device-key": {
       "types": "./dist/deviceKey.d.ts",
-      "import": "./dist/deviceKey.js"
+      "default": "./dist/deviceKey.js"
     },
     "./device-share": {
       "types": "./dist/deviceShare.d.ts",
-      "import": "./dist/deviceShare.js"
+      "default": "./dist/deviceShare.js"
     }
   },
+  "engines": {
+    "node": ">=20"
+  },
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org/"
   },
+  "devDependencies": {
+    "@types/node": "24.13.3",
+    "typescript": "7.0.2"
+  },
   "scripts": {
-    "check": "node --experimental-strip-types --check src/auth.ts && node --experimental-strip-types --check src/balances.ts && node --experimental-strip-types --check src/canonicalize.ts && node --experimental-strip-types --check src/client.ts && node --experimental-strip-types --check src/aesGcmSiv.ts && node --experimental-strip-types --check src/deviceKey.ts && node --experimental-strip-types --check src/deviceShare.ts && node --experimental-strip-types --check src/deviceShareEnvelope.ts && node --experimental-strip-types --check src/linkedSendDisplay.ts && node --experimental-strip-types --check src/linkedChecks.ts && node --experimental-strip-types --check src/linkedWallets.ts && node --experimental-strip-types --check src/linkedWalletSignals.ts && node --experimental-strip-types --check src/mediatedOperation.ts && node --experimental-strip-types --check src/pages.ts && node --experimental-strip-types --check src/modeC.ts && node --experimental-strip-types --check src/modeCLinked.ts && node --experimental-strip-types --check src/poll.ts && node --experimental-strip-types --check src/requestGrant.ts && node --experimental-strip-types --check src/sends.ts && node --experimental-strip-types --check src/slice4.ts && node --experimental-strip-types --check src/streams.ts && node --experimental-strip-types --check src/trackedWallets.ts && node --experimental-strip-types --check src/transferStatus.ts && node --experimental-strip-types --check src/walletDisplayParts.ts && node --experimental-strip-types --check src/walletEvents.ts && node --experimental-strip-types --check src/walletLimits.ts && node --experimental-strip-types --check src/walletOperations.ts && node --check test/http-integration.mjs && node --check test/http-integration-slice4.mjs && node --check test/http-integration-slice6.mjs && node --check test/http-integration-slice7.mjs && node --check test/http-integration-contract.mjs && node --check test/http-integration-linked-send.mjs && node --check test/http-integration-limits.mjs && node --check test/http-integration-modec-linked.mjs && node --check test/http-integration-mode-a.mjs && node --check test/http-integration-demo.mjs",
+    "check": "node --experimental-strip-types --check src/accountLists.ts && node --experimental-strip-types --check src/auth.ts && node --experimental-strip-types --check src/balances.ts && node --experimental-strip-types --check src/canonicalize.ts && node --experimental-strip-types --check src/client.ts && node --experimental-strip-types --check src/clientTypes.ts && node --experimental-strip-types --check src/deviceRecovery.ts && node --experimental-strip-types --check src/deviceShares.ts && node --experimental-strip-types --check src/linkedRecovery.ts && node --experimental-strip-types --check src/linkedRegistrations.ts && node --experimental-strip-types --check src/configuration.ts && node --experimental-strip-types --check src/consentDebit.ts && node --experimental-strip-types --check src/credentials.ts && node --experimental-strip-types --check src/debitPermissions.ts && node --experimental-strip-types --check src/debitPermissionWire.ts && node --experimental-strip-types --check src/aesGcmSiv.ts && node --experimental-strip-types --check src/deviceKey.ts && node --experimental-strip-types --check src/deviceShare.ts && node --experimental-strip-types --check src/deviceShareEnvelope.ts && node --experimental-strip-types --check src/errors.ts && node --experimental-strip-types --check src/linkedSendDisplay.ts && node --experimental-strip-types --check src/linkedChecks.ts && node --experimental-strip-types --check src/linkedWallets.ts && node --experimental-strip-types --check src/linkedWalletSignals.ts && node --experimental-strip-types --check src/me.ts && node --experimental-strip-types --check src/mediatedOperation.ts && node --experimental-strip-types --check src/mobile.ts && node --experimental-strip-types --check src/pages.ts && node --experimental-strip-types --check src/modeC.ts && node --experimental-strip-types --check src/modeCLinked.ts && node --experimental-strip-types --check src/poll.ts && node --experimental-strip-types --check src/redirects.ts && node --experimental-strip-types --check src/requestGrant.ts && node --experimental-strip-types --check src/sends.ts && node --experimental-strip-types --check src/serviceGrants.ts && node --experimental-strip-types --check src/slice4.ts && node --experimental-strip-types --check src/streams.ts && node --experimental-strip-types --check src/trackedWallets.ts && node --experimental-strip-types --check src/transferStatus.ts && node --experimental-strip-types --check src/walletCreateGrant.ts && node --experimental-strip-types --check src/walletDisplayParts.ts && node --experimental-strip-types --check src/walletEvents.ts && node --experimental-strip-types --check src/walletLimits.ts && node --experimental-strip-types --check src/walletOperations.ts && node --experimental-strip-types --check src/webRenewal.ts && node --check test/http-integration.mjs && node --check test/http-integration-slice4.mjs && node --check test/http-integration-slice6.mjs && node --check test/http-integration-slice7.mjs && node --check test/http-integration-contract.mjs && node --check test/http-integration-linked-send.mjs && node --check test/http-integration-limits.mjs && node --check test/http-integration-modec-linked.mjs && node --check test/http-integration-mode-a.mjs && node --check test/http-integration-mode-a-platform.mjs && node --check test/http-integration-demo.mjs && node --check test/http-integration-wallet-create.mjs && node --check test/http-integration-wallet-create-grant.mjs && node --check test/http-integration-wallet-create-debit.mjs",
     "typecheck": "tsc --noEmit",
     "build": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\" && tsc -p tsconfig.build.json",
-    "prepack": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\" && tsc -p tsconfig.build.json",
-    "package:smoke": "node test/package-smoke.mjs",
     "test": "node --experimental-strip-types --test test/*.test.ts",
     "integration:http": "node test/http-integration.mjs",
     "verify": "pnpm run check && pnpm run typecheck && pnpm run build && pnpm run test"
-  },
-  "engines": {
-    "node": "24.19.0"
-  },
-  "devDependencies": {
-    "@types/node": "24.13.3",
-    "typescript": "7.0.2"
   }
-}
+}