@shuttle.technology/authorization 0.0.0-stage → 0.2.0

package/dist/client.js

@@ -0,0 +1,781 @@
+import { AuthorizationError, ClientFlowError, abortable, canonicalDecimal, identityMethods, integer, newHandoffBinding, opaqueId, parseAuthorizationError, record, rfc3339Millis, } from "./auth.js";
+import { Credentials } from "./credentials.js";
+import { readPublicConfiguration, resolveConfiguration, validateConfiguration } from "./configuration.js";
+import { parseSessionPage, parseWalletPage } from "./accountLists.js";
+import { parseServiceGrantPage, serviceGrantCreate, serviceGrantRevocation } from "./serviceGrants.js";
+import { parseConfirmationChallenge, parseHostedIdentityFlow, parseIdentityFlowCallback, parseIdentityList, parseLocalOperationResult, parseOperationConfirmationCallback, parseOperationEnvelope, parsePasskeyBootstrapResult, parseVerifiedIdentityResult, validateLocalOperationCreate, } from "./slice4.js";
+import { parseMeProjection } from "./me.js";
+import { handoffCallback, hostedSignInUrl, httpsURL } from "./redirects.js";
+import { mobileBridgeComplete, mobileRefreshKey, mobileSignInReturn, verifyMobileAssociation } from "./mobile.js";
+import { StreamsReads } from "./streams.js";
+import { LinkedWallets } from "./linkedWallets.js";
+import { renewWebSession, restoreWebSession, revokedAnswer, revokeUnclaimedSession, revokeWithCurrentCredentials, staleCsrfRefusal, underRenewalLock } from "./webRenewal.js";
+export { DebitPermissions, LinkedWallets, MaxDebitAssets, MaxDebitRecipients, eventOfTransaction, isWalletLimitRefusal, resumeCursor, sendEvents, transferFinal, WalletLimitRefusals } from "./linkedWallets.js";
+import { parseUserWalletOperationEnvelope, parseWalletResult, validateUserWalletCreate } from "./walletOperations.js";
+import { createdAsAsked, walletCreateBody } from "./walletCreateGrant.js";
+import { settleCreationDebit, settleGrantDebit } from "./consentDebit.js";
+import { pageRequest } from "./pages.js";
+export { AuthorizationErrorCodes, AuthorizationErrorContracts, ModeCRefusals, isAuthorizationErrorCode, isModeCRefusal } from "./errors.js";
+export { AuthorizationError, ClientFlowError, isAuthorizationError } from "./auth.js";
+export { webRenewalRequiresNavigation } from "./webRenewal.js";
+export { pollAuthoritative } from "./poll.js";
+export { MaxTransferCommentBytes, MaxWalletMessageBytes, ReplaceActions, transferComment, walletMaterialPurged } from "./walletOperations.js";
+import { DeviceShareKeeper, defaultDeviceShareStore } from "./deviceShares.js";
+import { recoverDeviceShare, resumeDeviceRecovery } from "./deviceRecovery.js";
+/** accessToken renews a token with less than this many seconds to live, so the backend it is sent to still takes it. */
+const accessTokenRenewalSeconds = 30;
+export async function initializeAuthorizationClient(settings, dependencies) {
+    const configuration = resolveConfiguration(settings, dependencies.currentOrigin);
+    validateConfiguration(configuration);
+    const crypto = dependencies.crypto ?? globalThis.crypto;
+    // The platform fetch must be called on its global: stored on the dependencies
+    // object and called from there, a browser rejects it as an illegal invocation.
+    const platformFetch = globalThis.fetch;
+    const fetch = dependencies.fetch ?? (typeof platformFetch === "function" ? ((url, init) => platformFetch.call(globalThis, url, init)) : undefined);
+    if (!crypto?.subtle || typeof crypto.getRandomValues !== "function" || typeof fetch !== "function")
+        throw new ClientFlowError("runtime_capability_unavailable");
+    let publicConfiguration;
+    if (configuration.channel === "web") {
+        const web = dependencies;
+        if (typeof web.currentOrigin !== "function" || web.currentOrigin() !== configuration.applicationOrigin || typeof web.openHosted !== "function") {
+            throw new ClientFlowError("origin_mismatch");
+        }
+        publicConfiguration = await readPublicConfiguration(configuration, fetch);
+    }
+    else {
+        const mobile = dependencies;
+        if (!mobileBridgeComplete(mobile.browserBridge, mobile.secureStorage))
+            throw new ClientFlowError("mobile_association_unverified");
+        await verifyMobileAssociation(mobile.browserBridge, configuration.redirectUri, configuration.mobileApplicationIdentifier);
+    }
+    const normalized = {
+        fetch,
+        crypto,
+        now: dependencies.now ?? Date.now,
+        launch: configuration.channel === "web"
+            ? async (url, signal) => dependencies.openHosted(url, signal)
+            : async (url) => dependencies.browserBridge.openSystemBrowser(url),
+        secureStorage: configuration.channel === "mobile" ? dependencies.secureStorage : undefined,
+        deviceShares: dependencies.deviceShares,
+        browserBridge: configuration.channel === "mobile" ? dependencies.browserBridge : undefined,
+    };
+    return new AuthorizationClient(configuration, normalized, publicConfiguration);
+}
+export class AuthorizationClient {
+    capabilities;
+    publicConfiguration;
+    #configuration;
+    #dependencies;
+    #pending = new Map();
+    /** Sign-ins begun on the hosted page, by their state: the attempt is named only on the provider's side. */
+    #hostedPending = new Map();
+    #identityFlows = new Map();
+    #confirmations = new Map();
+    #refreshKey;
+    /** The session's credentials and every change to them (credentials.ts). */
+    #credentials;
+    /** The device shares this client keeps, and their recovery onto this device (deviceShares.ts, deviceRecovery.ts). */
+    #devices;
+    /** The one renewal or restore every caller waits for (#renewed). */
+    #flight;
+    /** The web sign-ins whose exchange went out, each settling false when it left a session in the cookie it could not confirm revoked (#exchange). */
+    #signingIn = new Set();
+    constructor(configuration, dependencies, publicConfiguration) {
+        this.#configuration = Object.freeze({ ...configuration, methods: Object.freeze([...configuration.methods]) });
+        this.#dependencies = dependencies;
+        this.publicConfiguration = publicConfiguration;
+        this.capabilities = Object.freeze({ mode: "mode_b", channel: configuration.channel, methods: Object.freeze([...configuration.methods]) });
+        this.#refreshKey = mobileRefreshKey(configuration.tenantId, configuration.applicationId, configuration.environmentId, configuration.publishableClientId);
+        this.#credentials = new Credentials(configuration.channel, dependencies.secureStorage, this.#refreshKey);
+        const { authorizationOrigin, publishableClientId: clientId } = configuration, store = dependencies.deviceShares ?? defaultDeviceShareStore(configuration.channel, this.#refreshKey);
+        this.#devices = new DeviceShareKeeper({ store, crypto: dependencies.crypto, lockPrefix: this.#refreshKey, lock: configuration.channel === "web" ? (lockName, work) => underRenewalLock({ authorizationOrigin, clientId, lockName }, work) : (_, work) => work(),
+            recover: (wallet, options, keepPending) => recoverDeviceShare(this, this.#accountId(), dependencies.crypto, wallet, options, keepPending),
+            resume: (wallet, pending, options) => resumeDeviceRecovery(this, dependencies.crypto, wallet, pending, options) });
+    }
+    get hasSession() { return this.#credentials.hasSession; }
+    #accountId() { return this.#credentials.current()?.session.accountId ?? ""; }
+    signup(method) { return method === undefined ? this.#beginHosted("signup") : this.#begin("signup", method); }
+    login(method) { return method === undefined ? this.#beginHosted("login") : this.#begin("login", method); }
+    bootstrapPasskey(signal) {
+        return this.#beginIdentityFlow("bootstrap", "/v1/identity/passkey-bootstrap", undefined, signal);
+    }
+    verifyIdentity(method, signal) {
+        return this.#beginIdentityFlow("verification", "/v1/identity-verifications", method, signal);
+    }
+    async completePasskeyBootstrap(callbackUri, signal) {
+        const { callback, pending } = this.#identityFlowCallback(callbackUri, "bootstrap");
+        const authority = await this.#accessForWrite(signal);
+        const payload = await this.#json("/v1/identity/passkey-bootstrap/complete", {
+            method: "POST",
+            body: JSON.stringify({ client_id: this.#configuration.publishableClientId, flow_id: callback.flowId, code: callback.code, verifier: pending.verifier, redirect_uri: this.#configuration.redirectUri }),
+            accessToken: authority.token,
+            signal,
+        });
+        const result = parsePasskeyBootstrapResult(payload);
+        this.#identityFlows.delete(callback.flowId);
+        return result;
+    }
+    /** identities lists the account's own active sign-in methods; a passkey names its credential. */
+    async identities(signal) {
+        return parseIdentityList(await this.#protectedGet("/v1/identities", signal));
+    }
+    async completeIdentityVerification(callbackUri, signal) {
+        const { callback, pending } = this.#identityFlowCallback(callbackUri, "verification");
+        const authority = await this.#accessForWrite(signal);
+        const payload = await this.#json("/v1/identity-verifications/complete", {
+            method: "POST",
+            body: JSON.stringify({ client_id: this.#configuration.publishableClientId, flow_id: callback.flowId, code: callback.code, verifier: pending.verifier, redirect_uri: this.#configuration.redirectUri }),
+            accessToken: authority.token,
+            signal,
+        });
+        const result = parseVerifiedIdentityResult(payload, this.#dependencies.now());
+        this.#identityFlows.delete(callback.flowId);
+        return result;
+    }
+    async createOperation(create, idempotencyKey, signal) {
+        const authority = await this.#accessForWrite(signal);
+        if (!opaqueId(idempotencyKey))
+            throw new ClientFlowError("invalid_idempotency_key");
+        validateLocalOperationCreate(create, authority.session.accountId);
+        const payload = await this.#json("/v1/operations", {
+            method: "POST", body: JSON.stringify(create), accessToken: authority.token, idempotencyKey, signal,
+        });
+        return parseOperationEnvelope(payload).operation;
+    }
+    createIdentityLink(verifiedIdentityHandle, idempotencyKey, signal) {
+        const ownerId = this.#accountId();
+        return this.createOperation({ kind: "identity.link", owner_type: "account", owner_id: ownerId, payload: { verified_identity_handle: verifiedIdentityHandle } }, idempotencyKey, signal);
+    }
+    createIdentityUnlink(identityId, idempotencyKey, signal) {
+        const ownerId = this.#accountId();
+        return this.createOperation({ kind: "identity.unlink", owner_type: "account", owner_id: ownerId, payload: { identity_id: identityId } }, idempotencyKey, signal);
+    }
+    createSessionRevocation(sessionId, idempotencyKey, signal) {
+        const ownerId = this.#accountId();
+        return this.createOperation({ kind: "session.revoke", owner_type: "account", owner_id: ownerId, payload: { session_id: sessionId } }, idempotencyKey, signal);
+    }
+    /** 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. */
+    async createServiceGrant(input, idempotencyKey, signal) {
+        return this.createOperation(serviceGrantCreate(this.#accountId(), input), idempotencyKey, signal);
+    }
+    /** revokeServiceGrant asks to withdraw the grant of one service on one wallet (`enabled: false`); the person confirms it with a passkey. */
+    async revokeServiceGrant(target, idempotencyKey, signal) {
+        return this.createOperation(serviceGrantRevocation(this.#accountId(), target), idempotencyKey, signal);
+    }
+    /** serviceGrants lists the grants the account gave services, in every state, newest first. */
+    async serviceGrants(input) {
+        const page = pageRequest("/v1/service-grants", input);
+        return parseServiceGrantPage(await this.#protectedGet(page.path, page.signal));
+    }
+    async operation(operationId, signal) {
+        if (!opaqueId(operationId))
+            throw new ClientFlowError("invalid_operation_id");
+        return parseOperationEnvelope(await this.#protectedGet(`/v1/operations/${encodeURIComponent(operationId)}`, signal)).operation;
+    }
+    async challengeOperation(operationId, credentialId, signal) {
+        if (!opaqueId(operationId) || !opaqueId(credentialId))
+            throw new ClientFlowError("invalid_confirmation_request");
+        const authority = await this.#accessForWrite(signal);
+        const binding = await newHandoffBinding(this.#dependencies.crypto);
+        const payload = await this.#json(`/v1/operations/${encodeURIComponent(operationId)}/challenge`, {
+            method: "POST",
+            body: JSON.stringify({ credential_id: credentialId, redirect_uri: this.#configuration.redirectUri, state: binding.state }),
+            accessToken: authority.token,
+            signal,
+        });
+        const challenge = parseConfirmationChallenge(payload, this.#dependencies.now());
+        const expiresAtMs = rfc3339Millis(challenge.expiresAt);
+        if (expiresAtMs === undefined)
+            throw new ClientFlowError("invalid_server_response");
+        this.#confirmations.set(operationId, { state: binding.state, operationId, expiresAtMs });
+        try {
+            const landed = await this.#dependencies.launch(challenge.confirmationLocation);
+            if (typeof landed === "string")
+                return { ...challenge, callbackUri: landed };
+        }
+        catch (error) {
+            this.#confirmations.delete(operationId);
+            throw error;
+        }
+        return challenge;
+    }
+    async completeOperationConfirmation(callbackUri, signal) {
+        const operationId = this.#acceptConfirmationCallback(callbackUri);
+        const operation = await this.operation(operationId, signal);
+        this.#confirmations.delete(operationId);
+        return operation;
+    }
+    /** createWalletOperation admits one Mode B wallet intent, its closed body checked locally first (source §1.3, §2.2). */
+    async createWalletOperation(create, idempotencyKey, signal) {
+        const authority = await this.#accessForWrite(signal);
+        if (!opaqueId(idempotencyKey))
+            throw new ClientFlowError("invalid_idempotency_key");
+        validateUserWalletCreate(create, authority.session.accountId);
+        const payload = await this.#json("/v1/operations", {
+            method: "POST", body: JSON.stringify(create), accessToken: authority.token, idempotencyKey, signal,
+        });
+        return parseUserWalletOperationEnvelope(payload).operation;
+    }
+    /** 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). */
+    async createWallet(input, idempotencyKey, signal) {
+        const device = input?.recipientPublicKey === undefined ? await this.#devices.creationKey(idempotencyKey) : undefined;
+        const create = walletCreateBody(this.#accountId(), input, device?.publicKeyHex);
+        const operation = createdAsAsked(await this.createWalletOperation(create, idempotencyKey, signal), create);
+        if (device)
+            this.#devices.holdCreation(operation.id, device);
+        return operation;
+    }
+    signWithWallet(input, idempotencyKey, signal) {
+        return this.createWalletOperation({
+            kind: "wallet.sign", owner_type: "account", owner_id: this.#accountId(), wallet_id: input.walletId,
+            payload: { network: input.network, message_base64url: input.messageBase64url },
+        }, idempotencyKey, signal);
+    }
+    sendFromWallet(input, idempotencyKey, signal) {
+        return this.createWalletOperation({
+            kind: "wallet.send", owner_type: "account", owner_id: this.#accountId(), wallet_id: input.walletId,
+            payload: { network: input.network, asset: "native", recipient: input.recipient, amount_raw: input.amountRaw, max_fee_raw: input.maxFeeRaw },
+        }, idempotencyKey, signal);
+    }
+    exportWallet(input, idempotencyKey, signal) {
+        return this.createWalletOperation({
+            kind: "wallet.export", owner_type: "account", owner_id: this.#accountId(), wallet_id: input.walletId,
+            payload: { recipient_public_key: input.recipientPublicKey },
+        }, idempotencyKey, signal);
+    }
+    recoverWallet(input, idempotencyKey, signal) {
+        return this.createWalletOperation({
+            kind: "wallet.recover", owner_type: "account", owner_id: this.#accountId(), wallet_id: input.walletId,
+            payload: { expected_generation: input.expectedGeneration, recipient_public_key: input.recipientPublicKey },
+        }, idempotencyKey, signal);
+    }
+    /** walletOperation reads the safe wallet status on GET /v1/operations/{operation_id}. */
+    async walletOperation(operationId, signal) {
+        if (!opaqueId(operationId))
+            throw new ClientFlowError("invalid_operation_id");
+        return parseUserWalletOperationEnvelope(await this.#protectedGet(`/v1/operations/${encodeURIComponent(operationId)}`, signal)).operation;
+    }
+    /** challengeWalletOperation is challengeOperation: the wallet and local challenges are one closed response. */
+    challengeWalletOperation(operationId, credentialId, signal) {
+        return this.challengeOperation(operationId, credentialId, signal);
+    }
+    async completeWalletOperationConfirmation(callbackUri, signal) {
+        const operationId = this.#acceptConfirmationCallback(callbackUri);
+        const operation = await this.walletOperation(operationId, signal);
+        this.#confirmations.delete(operationId);
+        return operation;
+    }
+    /** executeWalletOperation claims one confirmed wallet effect: 202, or 200 for an exact replay, with the same operation. */
+    async executeWalletOperation(operationId, version, idempotencyKey, signal) {
+        if (!opaqueId(operationId) || !canonicalDecimal(version) || !opaqueId(idempotencyKey))
+            throw new ClientFlowError("invalid_execute_request");
+        const authority = await this.#accessForWrite(signal);
+        const payload = await this.#json(`/v1/operations/${encodeURIComponent(operationId)}/execute`, {
+            method: "POST", accessToken: authority.token, idempotencyKey, ifMatch: version, signal,
+        });
+        return parseUserWalletOperationEnvelope(payload).operation;
+    }
+    /** walletOperationResult reads the protected wallet output for its frozen recipient. */
+    async walletOperationResult(operationId, signal) {
+        if (!opaqueId(operationId))
+            throw new ClientFlowError("invalid_operation_id");
+        const released = parseWalletResult(await this.#protectedGet(`/v1/operations/${encodeURIComponent(operationId)}/result`, signal), operationId);
+        await this.#devices.keepCreated(operationId, released.result);
+        return settleCreationDebit(this, released, signal);
+    }
+    async executeOperation(operationId, version, idempotencyKey, signal) {
+        if (!opaqueId(operationId) || !canonicalDecimal(version) || !opaqueId(idempotencyKey))
+            throw new ClientFlowError("invalid_execute_request");
+        const authority = await this.#accessForWrite(signal);
+        const payload = await this.#json(`/v1/operations/${encodeURIComponent(operationId)}/execute`, {
+            method: "POST", accessToken: authority.token, idempotencyKey, ifMatch: version, signal,
+        });
+        return parseOperationEnvelope(payload).operation;
+    }
+    /** HTTP-only Auth-owned links and session-authorized Streams registration. */
+    linkedWallets() {
+        return new LinkedWallets({
+            get: (path, signal) => this.#protectedGet(path, signal),
+            stream: (path, signal) => this.#protectedStream(path, signal),
+            write: async (path, method, body, signal, idempotencyKey, version) => {
+                const authority = await this.#accessForWrite(signal);
+                const payload = await this.#json(path, { method, body: body === undefined ? undefined : JSON.stringify(body), accessToken: authority.token, signal, idempotencyKey, ifMatch: version });
+                return { payload, accountId: authority.session.accountId };
+            },
+            accountId: () => this.#accountId(),
+            now: () => this.#dependencies.now(),
+            devices: this.#devices,
+        });
+    }
+    /**
+     * 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() {
+        return new StreamsReads({ scope: "account", get: (path, signal, idempotencyKey) => this.#protectedGet(path, signal, idempotencyKey) });
+    }
+    async operationResult(operationId, signal) {
+        if (!opaqueId(operationId))
+            throw new ClientFlowError("invalid_operation_id");
+        return settleGrantDebit(this, operationId, parseLocalOperationResult(await this.#protectedGet(`/v1/operations/${encodeURIComponent(operationId)}/result`, signal)), signal);
+    }
+    cancel(attemptId) {
+        this.#pending.delete(attemptId);
+        return "local_canceled";
+    }
+    /** exchangeHandoff exchanges the redirect back for the session; a signal ends only this caller's wait, never the exchange. */
+    exchangeHandoff(callbackUri, signal) {
+        try {
+            signal?.throwIfAborted();
+        }
+        catch (error) {
+            return Promise.reject(error);
+        }
+        return abortable(this.#exchangeHandoff(callbackUri), signal);
+    }
+    async #exchangeHandoff(callbackUri) {
+        const callback = handoffCallback(callbackUri, this.#configuration.redirectUri);
+        if (callback.attemptId === undefined)
+            return this.#exchangeHosted(callback);
+        const attempt = this.#pending.get(callback.attemptId);
+        if (!attempt)
+            throw new ClientFlowError("unknown_attempt");
+        if (attempt.state !== callback.state)
+            throw new ClientFlowError("state_mismatch");
+        if (this.#dependencies.now() / 1_000 >= attempt.expiresAt) {
+            this.#pending.delete(callback.attemptId);
+            throw new ClientFlowError("attempt_expired");
+        }
+        const session = await this.#exchange({
+            client_id: this.#configuration.publishableClientId,
+            attempt_id: callback.attemptId,
+            code: callback.code,
+            verifier: attempt.verifier,
+            redirect_uri: this.#configuration.redirectUri,
+        });
+        this.#pending.delete(callback.attemptId);
+        return session;
+    }
+    /** The redirect back from the hosted page names no attempt: the state finds this client's verifier. */
+    async #exchangeHosted(callback) {
+        const pending = this.#hostedPending.get(callback.state);
+        if (!pending)
+            throw new ClientFlowError("state_mismatch");
+        const session = await this.#exchangeCode(callback.code, pending.verifier);
+        this.#hostedPending.delete(callback.state);
+        return session;
+    }
+    #exchangeCode(code, verifier) {
+        return this.#exchange({ client_id: this.#configuration.publishableClientId, code, verifier, redirect_uri: this.#configuration.redirectUri });
+    }
+    /**
+     * #exchange spends a sign-in's one-use code with no caller's signal: once asked, the code is spent and its
+     * answer installed. On the web an answer a logout or a newer sign-in overtook set the cookie all the same,
+     * so its session is revoked (webRenewal.ts). On the web the exchange goes out under the tabs' lock, as a
+     * renewal and a restore do, so a renewal in another tab answered later never puts an older session back
+     * in the cookie; the answer is installed before the lock is given back, so a renewal that waited for it
+     * asks for the session the exchange installed, or nothing. A restore in another tab holds the lock while
+     * its window is open, and the exchange waits for it; one that a logout or a newer sign-in overtook
+     * meanwhile is not sent at all.
+     */
+    #exchange(body) {
+        const signIn = this.#credentials.signIn();
+        const ask = () => this.#json("/v1/auth/exchange", { method: "POST", body: JSON.stringify(body) });
+        if (this.#configuration.channel !== "web")
+            return ask().then((payload) => this.#acceptSession(payload, true, signIn));
+        const { authorizationOrigin, publishableClientId: clientId } = this.#configuration;
+        // A logout waits for the sign-ins it overtook whose exchange went out: each settles true only when it surely
+        // left no session behind. One still waiting for the lock is never sent once overtaken, so nobody waits for it.
+        let settle = () => { };
+        const clean = new Promise((resolve) => { settle = resolve; });
+        void clean.then(() => this.#signingIn.delete(clean));
+        return (async () => {
+            let payload, answered = false;
+            try {
+                const session = await underRenewalLock({ authorizationOrigin, clientId, lockName: this.#refreshKey }, async () => {
+                    try {
+                        this.#credentials.check(signIn);
+                    }
+                    catch {
+                        throw new ClientFlowError("session_unavailable");
+                    }
+                    this.#signingIn.add(clean);
+                    payload = await ask();
+                    answered = true;
+                    return this.#acceptSession(payload, true, signIn);
+                });
+                settle(true);
+                return session;
+            }
+            catch (error) {
+                // Not sent, or refused, it made no session; a lost or unread answer may have.
+                if (!this.#signingIn.has(clean))
+                    settle(true);
+                else if (!answered)
+                    settle(error instanceof AuthorizationError);
+                else if (!(error instanceof ClientFlowError && error.code === "session_unavailable"))
+                    settle(false);
+                else {
+                    const request = { authorizationOrigin, clientId, lockName: this.#refreshKey, fetch: this.#dependencies.fetch, whenWaiting: () => settle(false) };
+                    settle(await revokeUnclaimedSession(request, payload, (token, csrf) => this.#revoke(token, csrf)));
+                }
+                throw error;
+            }
+        })();
+    }
+    /** restoreSession is the top-level restore on the web (webRenewal.ts); on mobile it is refreshSession. */
+    restoreSession(signal) { return this.#renewed(signal, this.#configuration.channel === "web"); }
+    /** refreshSession renews in the background: on the web from the provider's cookie, on mobile with the stored refresh token. */
+    refreshSession(signal) { return this.#renewed(signal); }
+    /** 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) {
+        const ending = this.#credentials.logout();
+        const overtaken = [...this.#signingIn];
+        // Unconfirmed at the first overtaken sign-in that may have left a session; confirmed once every one surely left none.
+        const allClean = () => new Promise((resolve) => {
+            let left = overtaken.length;
+            if (left === 0)
+                resolve(true);
+            for (const one of overtaken)
+                void one.then((ok) => { if (!ok)
+                    resolve(false);
+                else if (--left === 0)
+                    resolve(true); });
+        });
+        const confirmed = async (result) => result.serverDisposition === "server_unconfirmed" || (await allClean()) ? result : { localCleared: true, serverDisposition: "server_unconfirmed" };
+        return abortable(this.#logout(ending).then(confirmed), signal);
+    }
+    async #logout({ token, csrf, sessionId, cleared }) {
+        try {
+            await cleared;
+            if (!token || (this.#configuration.channel === "web" && !csrf))
+                return { localCleared: true, serverDisposition: "server_unconfirmed" };
+            const revoke = (accessToken, csrfToken) => this.#revoke(accessToken, csrfToken);
+            // Another tab's renewal may have replaced the CSRF token: under the tabs' lock, revoke once more with
+            // the cookie's current one, only while the cookie still holds the session this logout ended.
+            const payload = await revoke(token, csrf).catch(async (error) => {
+                if (this.#configuration.channel !== "web" || !staleCsrfRefusal(error) || !sessionId)
+                    throw error;
+                const { authorizationOrigin, publishableClientId: clientId } = this.#configuration;
+                return revokeWithCurrentCredentials({ authorizationOrigin, clientId, lockName: this.#refreshKey, fetch: this.#dependencies.fetch, sessionId }, revoke);
+            });
+            if (!revokedAnswer(payload))
+                throw new ClientFlowError("invalid_server_response");
+            return { localCleared: true, serverDisposition: "server_revoked" };
+        }
+        catch {
+            return { localCleared: true, serverDisposition: "server_unconfirmed" };
+        }
+    }
+    /** #revoke is POST /v1/auth/logout with the tokens of the session it ends, held or only answered. */
+    #revoke(accessToken, csrfToken) {
+        return this.#json("/v1/auth/logout", { method: "POST", body: JSON.stringify({ client_id: this.#configuration.publishableClientId }), accessToken, csrfToken, ending: true });
+    }
+    /**
+     * 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.
+     */
+    async accessToken(signal) {
+        signal?.throwIfAborted();
+        if (!this.#credentials.hasSession)
+            throw new ClientFlowError("session_unavailable");
+        if (this.#credentials.due(this.#dependencies.now() / 1_000, accessTokenRenewalSeconds))
+            await this.#renewed(signal);
+        signal?.throwIfAborted();
+        return this.#credentials.usable();
+    }
+    async me(signal) {
+        return parseMeProjection(await this.#protectedGet("/v1/me", signal));
+    }
+    async sessions(input) {
+        const page = pageRequest("/v1/sessions", input);
+        return parseSessionPage(await this.#protectedGet(page.path, page.signal));
+    }
+    /** wallets pages the account's own wallets, kind "wallet" in me(), which lists them with the linked ones. */
+    async wallets(input) {
+        const page = pageRequest("/v1/wallets", input);
+        return parseWalletPage(await this.#protectedGet(page.path, page.signal));
+    }
+    async #begin(intent, method) {
+        if (!identityMethods.includes(method) || !this.#configuration.methods.includes(method))
+            throw new ClientFlowError("method_unavailable");
+        await this.#verifyMobileAssociation();
+        const binding = await newHandoffBinding(this.#dependencies.crypto);
+        const payload = await this.#json("/v1/auth/attempts", {
+            method: "POST",
+            body: JSON.stringify({
+                client_id: this.#configuration.publishableClientId,
+                intent,
+                method,
+                redirect_uri: this.#configuration.redirectUri,
+                state: binding.state,
+                code_challenge: binding.challenge,
+                code_challenge_method: "S256",
+            }),
+        });
+        const root = record(payload, ["request_id", "attempt_id", "launch_url", "expires_at"]);
+        if (!opaqueId(root.request_id) || !opaqueId(root.attempt_id) || !httpsURL(root.launch_url) || !integer(root.expires_at) || root.expires_at <= this.#dependencies.now() / 1_000) {
+            throw new ClientFlowError("invalid_server_response");
+        }
+        const attempt = { requestId: root.request_id, attemptId: root.attempt_id, launchUrl: root.launch_url, expiresAt: root.expires_at };
+        this.#pending.set(attempt.attemptId, { state: binding.state, verifier: binding.verifier, expiresAt: attempt.expiresAt });
+        await this.#dependencies.launch(attempt.launchUrl);
+        return attempt;
+    }
+    async #beginHosted(intent) {
+        const binding = await newHandoffBinding(this.#dependencies.crypto);
+        const launchUrl = hostedSignInUrl(this.#configuration.authorizationOrigin, { clientId: this.#configuration.publishableClientId, redirectUri: this.#configuration.redirectUri, state: binding.state, challenge: binding.challenge, intent });
+        if (this.#configuration.channel === "mobile") {
+            // One call: its state and verifier live only in it, so no other redirect can spend this sign-in.
+            await this.#verifyMobileAssociation();
+            const returned = await this.#dependencies.launch(launchUrl);
+            return { intent, launchUrl, session: await this.#exchangeCode(mobileSignInReturn(returned, this.#configuration.redirectUri, binding.state).code, binding.verifier) };
+        }
+        this.#hostedPending.set(binding.state, { verifier: binding.verifier });
+        try {
+            await this.#dependencies.launch(launchUrl);
+        }
+        catch (error) {
+            this.#hostedPending.delete(binding.state);
+            throw error;
+        }
+        return { intent, launchUrl };
+    }
+    /** On mobile, every sign-in has the OS verify the app link again before the system browser opens. */
+    async #verifyMobileAssociation() {
+        if (this.#dependencies.browserBridge)
+            await verifyMobileAssociation(this.#dependencies.browserBridge, this.#configuration.redirectUri, this.#configuration.mobileApplicationIdentifier);
+    }
+    async #beginIdentityFlow(kind, path, method, signal) {
+        if ((kind === "bootstrap" && !this.#configuration.methods.includes("passkey")) || (method !== undefined && (!identityMethods.includes(method) || !this.#configuration.methods.includes(method)))) {
+            throw new ClientFlowError("method_unavailable");
+        }
+        const authority = await this.#accessForWrite(signal);
+        const binding = await newHandoffBinding(this.#dependencies.crypto);
+        const body = {
+            client_id: this.#configuration.publishableClientId,
+            redirect_uri: this.#configuration.redirectUri,
+            state: binding.state,
+            code_challenge: binding.challenge,
+            code_challenge_method: "S256",
+        };
+        if (method !== undefined)
+            body.method = method;
+        const payload = await this.#json(path, { method: "POST", body: JSON.stringify(body), accessToken: authority.token, signal });
+        const flow = parseHostedIdentityFlow(payload, this.#dependencies.now());
+        this.#identityFlows.set(flow.flowId, { kind, state: binding.state, verifier: binding.verifier, expiresAt: flow.expiresAt });
+        try {
+            await this.#dependencies.launch(flow.launchUrl);
+        }
+        catch (error) {
+            this.#identityFlows.delete(flow.flowId);
+            throw error;
+        }
+        return flow;
+    }
+    #identityFlowCallback(callbackUri, expectedKind) {
+        const callback = parseIdentityFlowCallback(callbackUri, this.#configuration.redirectUri);
+        const pending = this.#identityFlows.get(callback.flowId);
+        if (!pending || pending.kind !== expectedKind)
+            throw new ClientFlowError("unknown_identity_flow");
+        if (pending.state !== callback.state)
+            throw new ClientFlowError("state_mismatch");
+        if (this.#dependencies.now() / 1_000 >= pending.expiresAt) {
+            this.#identityFlows.delete(callback.flowId);
+            throw new ClientFlowError("identity_flow_expired");
+        }
+        return { callback, pending };
+    }
+    /** #acceptConfirmationCallback checks the exact redirect, the operation's state and its deadline; never a server disposition. */
+    #acceptConfirmationCallback(callbackUri) {
+        const callback = parseOperationConfirmationCallback(callbackUri, this.#configuration.redirectUri);
+        const pending = this.#confirmations.get(callback.operationId);
+        if (!pending)
+            throw new ClientFlowError("unknown_confirmation");
+        if (pending.state !== callback.state)
+            throw new ClientFlowError("state_mismatch");
+        if (this.#dependencies.now() >= pending.expiresAtMs) {
+            this.#confirmations.delete(callback.operationId);
+            throw new ClientFlowError("confirmation_expired");
+        }
+        return callback.operationId;
+    }
+    async #accessForWrite(signal) {
+        if (!this.#credentials.hasSession)
+            throw new ClientFlowError("session_unavailable");
+        if (this.#credentials.due(this.#dependencies.now() / 1_000, 0))
+            await this.#renewed(signal);
+        const token = this.#credentials.usable();
+        return { token, session: { ...this.#credentials.current().session } };
+    }
+    /**
+     * #renewed waits for the renewal or restore under way, or starts one, its attempt taken before anything
+     * is awaited. A restore asked for during a background renewal starts once that settles, and later
+     * renewals join the restore. A background renewal runs without any caller's signal; a restore runs
+     * until no caller waits for it any more, and its host then closes its window. A signal ends only its
+     * caller's wait. A definitive refusal ends the session once, judged against the token it renews.
+     */
+    #renewed(signal, navigate = false) {
+        const ahead = this.#flight;
+        if (ahead && (ahead.navigate || !navigate))
+            return this.#wait(ahead, signal);
+        const attempt = this.#credentials.renewal();
+        const flight = { navigate, settled: false, ahead, waiting: 0, stop: new AbortController() };
+        const stop = navigate ? flight.stop.signal : undefined;
+        flight.operation = (ahead ? abortable(ahead.operation.catch(() => undefined), stop) : Promise.resolve())
+            .then(() => this.#performRefresh(attempt, navigate, stop))
+            .catch((error) => {
+            // A restore nobody waits for stops with its last caller's reason: no answer of the provider, it ends nothing.
+            if (stop?.aborted && error === stop.reason)
+                throw error;
+            return this.#credentials.renewalFailed(attempt, error);
+        })
+            .finally(() => { flight.settled = true; this.#release(flight); });
+        this.#flight = flight;
+        return this.#wait(flight, signal);
+    }
+    /** #release hands the slot of a flight that settled or that nobody waits for back to the one it waited behind. */
+    #release(flight) {
+        if (this.#flight === flight)
+            this.#flight = flight.ahead && !flight.ahead.settled ? flight.ahead : undefined;
+    }
+    /**
+     * #wait is one caller's wait for a flight. A restore stops once every caller waiting for it aborted:
+     * at that moment no later caller joins it, and the slot goes back to the flight it waited behind.
+     */
+    #wait(flight, signal) {
+        if (flight.navigate) {
+            flight.waiting++;
+            const leave = () => {
+                if (--flight.waiting > 0)
+                    return;
+                this.#release(flight);
+                flight.stop.abort(signal?.reason);
+            };
+            if (signal?.aborted)
+                leave();
+            else if (signal) {
+                signal.addEventListener("abort", leave, { once: true });
+                const forget = () => signal.removeEventListener("abort", leave);
+                flight.operation.then(forget, forget);
+            }
+        }
+        return abortable(flight.operation, signal);
+    }
+    /** #refused ends the session of a token the provider refused for good, while it is still the one held, and rethrows. */
+    #refused(error, token) {
+        if (error instanceof AuthorizationError && error.status === 401 && error.code === "UNAUTHORIZED")
+            this.#credentials.refuse(token);
+        throw error;
+    }
+    /**
+     * #performRefresh is the refresh seam: the web background renewal or top-level restore (webRenewal.ts),
+     * each checked against its attempt under the tabs' lock right before it asks the provider, or the
+     * mobile refresh. Whatever answers is installed only in the attempt's own generation.
+     */
+    async #performRefresh(attempt, navigate, signal) {
+        if (this.#configuration.channel === "web") {
+            const { authorizationOrigin, publishableClientId: clientId, redirectUri } = this.#configuration;
+            const web = { authorizationOrigin, clientId, lockName: this.#refreshKey, signal, current: () => this.#credentials.check(attempt) };
+            if (!navigate)
+                return this.#acceptSession(await renewWebSession({ ...web, fetch: this.#dependencies.fetch, csrfToken: this.#credentials.current()?.csrf }), false, attempt);
+            const exchange = (body) => this.#json("/v1/auth/restore", { method: "POST", body, signal });
+            return this.#acceptSession(await restoreWebSession({ ...web, redirectUri, crypto: this.#dependencies.crypto, launch: this.#dependencies.launch, exchange }), false, attempt);
+        }
+        const refreshToken = await this.#credentials.refreshToken(attempt);
+        this.#credentials.check(attempt);
+        const payload = await this.#json("/v1/auth/refresh", {
+            method: "POST",
+            body: JSON.stringify({ client_id: this.#configuration.publishableClientId, refresh_token: refreshToken }),
+            signal,
+        });
+        return this.#acceptSession(payload, false, attempt);
+    }
+    /** #acceptSession installs what an exchange or a renewal answered, generation-guarded (credentials.ts). */
+    #acceptSession(payload, exchange, attempt) {
+        return this.#credentials.install(attempt, payload, exchange);
+    }
+    async #protectedGet(path, signal, idempotencyKey) {
+        if (!this.#credentials.hasSession)
+            throw new ClientFlowError("session_unavailable");
+        if (this.#credentials.due(this.#dependencies.now() / 1_000, 0))
+            await this.#renewed(signal);
+        // Usable checked after any renewal, right before the request goes out.
+        const attemptedToken = this.#credentials.usable();
+        try {
+            return await this.#json(path, { method: "GET", accessToken: attemptedToken, idempotencyKey, signal });
+        }
+        catch (error) {
+            if (!(error instanceof AuthorizationError) || error.status !== 401 || error.code !== "UNAUTHORIZED")
+                throw error;
+            // The refused token, while it is still the session's, is used no more: only a renewal replaces it.
+            if (this.#credentials.markRefused(attemptedToken))
+                await this.#renewed(signal);
+            // A renewed token the provider refuses too: the session is over.
+            const renewedToken = this.#credentials.usable();
+            return this.#json(path, { method: "GET", accessToken: renewedToken, idempotencyKey, signal }).catch((refusal) => this.#refused(refusal, renewedToken));
+        }
+    }
+    /** Opens a long-lived answer with the session's access token, refreshed once if the server no longer takes it. */
+    async #protectedStream(path, signal) {
+        const open = (token) => {
+            if (!this.#credentials.dispatchable(token))
+                throw new ClientFlowError("session_unavailable");
+            return this.#dependencies.fetch(`${this.#configuration.authorizationOrigin}${path}`, {
+                method: "GET", headers: { Accept: "text/event-stream", Authorization: `Bearer ${token}` },
+                credentials: this.#configuration.channel === "web" ? "include" : "omit", cache: "no-store", signal,
+            });
+        };
+        const first = await this.#accessForWrite(signal);
+        let response = await open(first.token);
+        let renewed;
+        if (response.status === 401) {
+            if (this.#credentials.markRefused(first.token))
+                await this.#renewed(signal);
+            renewed = (await this.#accessForWrite(signal)).token;
+            response = await open(renewed);
+        }
+        if (!response.ok) {
+            const refusal = parseAuthorizationError(await response.json(), response.status);
+            if (renewed !== undefined)
+                this.#refused(refusal, renewed);
+            throw refusal;
+        }
+        if (!response.body || !(response.headers?.get("content-type") ?? "").startsWith("text/event-stream"))
+            throw new ClientFlowError("invalid_server_response");
+        return response.body;
+    }
+    async #json(path, options) {
+        // Right before it goes out, a request's token must still be of the session installed (a logout's own is not).
+        if (options.accessToken && !options.ending && !this.#credentials.dispatchable(options.accessToken))
+            throw new ClientFlowError("session_unavailable");
+        const headers = { Accept: "application/json" };
+        if (options.body !== undefined)
+            headers["Content-Type"] = "application/json";
+        if (options.accessToken)
+            headers.Authorization = `Bearer ${options.accessToken}`;
+        if (options.csrfToken)
+            headers["X-CSRF-Token"] = options.csrfToken;
+        if (options.idempotencyKey)
+            headers["Idempotency-Key"] = options.idempotencyKey;
+        if (options.ifMatch)
+            headers["If-Match"] = options.ifMatch;
+        const response = await this.#dependencies.fetch(`${this.#configuration.authorizationOrigin}${path}`, {
+            method: options.method,
+            headers,
+            body: options.body,
+            credentials: this.#configuration.channel === "web" ? "include" : "omit",
+            cache: "no-store",
+            signal: options.signal,
+        });
+        const payload = await response.json();
+        if (!response.ok) {
+            const refusal = parseAuthorizationError(payload, response.status);
+            // A refused write ends the session it was made with, as a refused read does; it is never repeated.
+            if (options.method !== "GET" && options.accessToken)
+                this.#refused(refusal, options.accessToken);
+            throw refusal;
+        }
+        return payload;
+    }
+}