@oxy.so/core 4.0.0 → 4.2.0

package/dist/cjs/HttpService.js

@@ -27,6 +27,35 @@ const OxyServices_errors_1 = require("./OxyServices.errors");
 const edgeRegion_1 = require("./utils/edgeRegion");
 const activityId_1 = require("./utils/activityId");
 const slashes_1 = require("./utils/slashes");
+/** Comparison only fences local async work; it never validates token authority. */
+function sameTokenSession(left, right) {
+    if (left === right)
+        return true;
+    if (!left || !right)
+        return false;
+    const a = (0, tokenClaims_1.decodeTokenClaims)(left);
+    const b = (0, tokenClaims_1.decodeTokenClaims)(right);
+    if (!a || !b || !(a.userId || a.id || a.sub) || !(b.userId || b.id || b.sub))
+        return false;
+    // A refresh may rotate exp/iat/jti while preserving its account and session.
+    // Opaque/malformed context fields cannot establish that equivalence.
+    return ['userId', 'id', 'sub', 'sessionId', 'operatorId', 'clientId', 'appId', 'authMethodId'].every((key) => (a[key] === undefined || typeof a[key] === 'string') && a[key] === b[key]);
+}
+/** Cancel this wait only; the shared mint continues for other callers. */
+function awaitRequestSignal(pending, signal) {
+    if (!signal)
+        return pending;
+    return new Promise((resolve, reject) => {
+        const onAbort = () => { reject((0, errorUtils_1.createCancelledError)()); };
+        if (signal.aborted)
+            onAbort();
+        else
+            signal.addEventListener('abort', onAbort, { once: true });
+        // Both handlers remain attached even after cancellation, so a late shared
+        // failure is observed without reviving this request or becoming unhandled.
+        pending.then(resolve, reject).finally(() => signal.removeEventListener('abort', onAbort));
+    });
+}
 /** Methods whose calls concurrent callers may share (read-only). */
 const SAFE_METHODS = new Set(['GET']);
 /** Methods safe to re-send after a transient failure (RFC 9110 §9.2.2). */
@@ -305,8 +334,7 @@ class HttpService {
         const currentToken = this.tokenStore.getAccessToken();
         if (providedToken) {
             if (providedToken !== currentToken) {
-                this.tokenStore.setTokens(providedToken);
-                this.notifyTokenChange();
+                this.setTokens(providedToken);
             }
             return providedToken;
         }
@@ -1014,8 +1042,12 @@ class HttpService {
             this.tokenRefreshPromise = this.authRefreshHandler(reason)
                 .then((newToken) => {
                 if (epoch !== this.sessionEpoch) {
-                    // The session ended while this re-mint was in flight. Not a failure
-                    // (no cooldown), and nothing to plant.
+                    // A guarded refresh handler can itself adopt a new active context.
+                    // Acknowledge only an already-installed, exact result; never plant
+                    // a stale return value over a concurrent switch/logout.
+                    if (newToken && !this.sessionEnded && this.tokenStore.getAccessToken() === newToken) {
+                        return newToken;
+                    }
                     this.logger.debug('Discarded a token refresh that outlived its session');
                     return null;
                 }
@@ -1026,8 +1058,7 @@ class HttpService {
                 // A token is planted again, so there is a session again.
                 this.sessionEnded = false;
                 if (this.tokenStore.getAccessToken() !== newToken) {
-                    this.tokenStore.setTokens(newToken);
-                    this.notifyTokenChange();
+                    this.setTokens(newToken);
                 }
                 this.noFresherTokenThan = isInsideRefreshLeadWindow(newToken) ? newToken : null;
                 // A success clears the failure timestamp so the next refresh is never
@@ -1183,23 +1214,61 @@ class HttpService {
      * abort signal defines the lifetime of a healthy stream.
      */
     async requestAuthenticatedResponse(config) {
-        const authHeader = await this.getAuthHeader();
-        if (!authHeader) {
+        return this.requestRawResponse(config, true);
+    }
+    /**
+     * Raw response for public or authenticated app endpoints. The SDK supplies
+     * its current bearer when available; caller headers never supply authority.
+     * No caching, envelope transformation or transport-error retry is performed.
+     */
+    async requestResponse(config) {
+        return this.requestRawResponse(config, false);
+    }
+    async requestRawResponse(config, requireAuth) {
+        // Validate before obtaining a bearer: an unrelated origin must not trigger
+        // an auth mint, even when the trusted transport accepts absolute URLs.
+        const target = new URL(this.buildURL(config.url));
+        const base = new URL(this.baseURL);
+        if (target.origin !== base.origin || !['http:', 'https:'].includes(target.protocol)
+            || target.username || target.password) {
+            throw new Error('Raw response requests must target the configured API origin');
+        }
+        if (config.signal?.aborted)
+            throw (0, errorUtils_1.createCancelledError)();
+        // Snapshot caller-owned options once, including headers, before any await.
+        const request = { ...config, headers: new Headers(config.headers) };
+        const contextToken = this.syncAccessTokenFromProvider();
+        const beforeAuthEpoch = this.sessionEpoch;
+        const authHeader = await awaitRequestSignal(this.getAuthHeader(), config.signal);
+        if (beforeAuthEpoch !== this.sessionEpoch || !sameTokenSession(contextToken, this.tokenStore.getAccessToken())) {
+            throw new OxyServices_errors_1.OxyAuthenticationError('The request session changed', 'AUTH_SESSION_CHANGED');
+        }
+        if (config.signal?.aborted)
+            throw (0, errorUtils_1.createCancelledError)();
+        if (requireAuth && !authHeader) {
             throw new OxyServices_errors_1.OxyAuthenticationError('An active Oxy session is required for this request', 'AUTH_REQUIRED');
         }
-        return this.requestAuthenticatedResponseAttempt(config, authHeader, false);
+        return this.requestResponseAttempt(request, target.href, authHeader, false, this.sessionEpoch, contextToken);
     }
-    async requestAuthenticatedResponseAttempt(config, authHeader, isAuthRetry) {
+    async requestResponseAttempt(config, fullUrl, authHeader, isAuthRetry, epoch, contextToken) {
+        const assertCurrent = () => {
+            this.syncAccessTokenFromProvider();
+            if (epoch !== this.sessionEpoch || !sameTokenSession(contextToken, this.tokenStore.getAccessToken())) {
+                throw new OxyServices_errors_1.OxyAuthenticationError('The request session changed', 'AUTH_SESSION_CHANGED');
+            }
+        };
         const startTime = Date.now();
+        if (config.signal?.aborted)
+            throw (0, errorUtils_1.createCancelledError)();
+        assertCurrent();
         const headers = new Headers(config.headers);
-        if (!headers.has('Accept')) {
+        if (!headers.has('Accept'))
             headers.set('Accept', 'application/json');
-        }
-        // Authentication is owned by this SDK instance. A caller cannot replace
-        // the bearer with a different session or leak one across linked apps.
-        headers.set('Authorization', authHeader);
-        // Never awaited: the PoP is a hint, and waiting on its trace fetch put up
-        // to a second in front of requests.
+        // Never accept ambient credentials or another authority from a caller.
+        for (const name of ['Authorization', 'Cookie', 'Cookie2', 'Host', 'Proxy-Authorization'])
+            headers.delete(name);
+        if (authHeader)
+            headers.set('Authorization', authHeader);
         const edgeRegionHeader = (0, edgeRegion_1.peekBrowserEdgeRegionHeader)();
         for (const [name, value] of Object.entries(edgeRegionHeader))
             headers.set(name, value);
@@ -1207,22 +1276,51 @@ class HttpService {
         for (const [name, value] of Object.entries(activityIdHeader))
             headers.set(name, value);
         try {
-            const fullUrl = this.buildURL(config.url);
-            const response = await fetch(fullUrl, {
+            const body = config.method === 'GET' ? undefined : config.body;
+            const init = {
                 method: config.method,
                 headers,
-                body: config.method === 'GET' ? undefined : config.body,
+                body,
                 signal: config.signal,
-                credentials: this.getCredentialsMode(fullUrl),
-            });
-            if (response.status === 401 && !isAuthRetry) {
-                const refreshed = await this.refreshAccessToken('response-401');
+                credentials: 'omit',
+                redirect: 'error',
+            };
+            // Node fetch requires this flag for streaming uploads; ordinary and
+            // multipart bodies keep the platform's existing body serialization.
+            if (body && typeof body === 'object' && 'getReader' in body)
+                init.duplex = 'half';
+            const response = await (config.fetch ?? globalThis.fetch)(fullUrl, init);
+            try {
+                assertCurrent();
+            }
+            catch (error) {
+                await response.body?.cancel();
+                throw error;
+            }
+            const replayable = body === undefined || typeof body === 'string';
+            if (response.status === 401 && !isAuthRetry && authHeader && replayable && !config.signal?.aborted) {
+                let refreshed;
+                try {
+                    refreshed = await awaitRequestSignal(this.refreshAccessToken('response-401'), config.signal);
+                }
+                catch (error) {
+                    void response.body?.cancel().catch(() => undefined);
+                    throw error;
+                }
+                try {
+                    assertCurrent();
+                }
+                catch (error) {
+                    await response.body?.cancel();
+                    throw error;
+                }
                 if (refreshed) {
                     await response.body?.cancel();
-                    return this.requestAuthenticatedResponseAttempt(config, `Bearer ${refreshed}`, true);
+                    if (config.signal?.aborted)
+                        throw (0, errorUtils_1.createCancelledError)();
+                    return this.requestResponseAttempt(config, fullUrl, `Bearer ${refreshed}`, true, epoch, contextToken);
                 }
-                this.tokenStore.clearTokens();
-                this.notifyTokenChange();
+                this.clearTokens();
             }
             const duration = Date.now() - startTime;
             this.updateMetrics(response.ok, duration);
@@ -1233,8 +1331,12 @@ class HttpService {
             const duration = Date.now() - startTime;
             this.updateMetrics(false, duration);
             this.config.onRequestEnd?.(config.url, config.method, duration, false);
-            const normalizedError = error instanceof Error ? error : new Error(String(error));
+            const normalizedError = config.signal?.aborted || (0, errorUtils_1.isCancelledError)(error)
+                ? (0, errorUtils_1.createCancelledError)()
+                : error instanceof Error ? error : new Error(String(error));
             this.config.onRequestError?.(config.url, config.method, normalizedError);
+            if ((0, errorUtils_1.isCancelledError)(normalizedError) || normalizedError instanceof OxyServices_errors_1.OxyAuthenticationError)
+                throw normalizedError;
             throw (0, errorUtils_1.handleHttpError)(normalizedError);
         }
     }
@@ -1256,6 +1358,9 @@ class HttpService {
     }
     // Token management
     setTokens(accessToken) {
+        const current = this.tokenStore.getAccessToken();
+        if (current && !sameTokenSession(current, accessToken))
+            this.sessionEpoch += 1;
         this.sessionEnded = false;
         this.tokenStore.setTokens(accessToken);
         this.notifyTokenChange();
@@ -1264,17 +1369,19 @@ class HttpService {
      * End the local session: clear the bearer and abandon every re-mint already
      * in flight, so none of them can plant a token after the sign-out.
      *
-     * {@link clearTokens} alone only drops the bearer, which is right for a
-     * mirror (a linked client following its parent) but not for a sign-out: a
-     * refresh started a moment earlier would finish and plant a new one.
+     * Unlike {@link clearTokens}, this also marks the session as ended and
+     * invalidates pending re-mints even when no bearer is currently present.
      */
     endSession() {
-        this.sessionEpoch += 1;
+        if (!this.tokenStore.getAccessToken())
+            this.sessionEpoch += 1;
         this.sessionEnded = true;
         this.clearTokens();
     }
     /**
-     * The current session epoch — see {@link endSession}. A re-mint lane that
+     * The current context epoch: account/session switches and bearer removal
+     * invalidate pending work; rotation within the same context preserves it.
+     * A re-mint lane that
      * plants tokens itself (the device-secret arm) compares it across its awaits.
      */
     getSessionEpoch() {
@@ -1301,6 +1408,8 @@ class HttpService {
         this.anonymousAuthProvider = provider;
     }
     clearTokens() {
+        if (this.tokenStore.getAccessToken())
+            this.sessionEpoch += 1;
         this.tokenStore.clearTokens();
         // Drop the response cache on logout. The cache is identity-scoped, so a
         // different user could never read these entries, but a logged-out client

package/dist/cjs/api/accounts.js

@@ -1,21 +1,41 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.AccountsApi = exports.AccountMembersApi = exports.kindAcceptsAccountCategories = exports.isSelectableAccountCategoryId = exports.isOperatorSwitchTargetKind = exports.isDelegatedActAsEligibleKind = exports.SELECTABLE_ACCOUNT_CATEGORY_IDS = exports.MAX_ACCOUNT_CATEGORIES = exports.ACCOUNT_KINDS = exports.ACCOUNT_CATEGORY_IDS = void 0;
+exports.AccountsApi = exports.AccountAgentKeysApi = exports.AccountMembersApi = exports.kindAcceptsAccountCategories = exports.isSelectableAccountCategoryId = exports.isOperatorSwitchTargetKind = exports.isDelegatedActAsEligibleKind = exports.SELECTABLE_ACCOUNT_CATEGORY_IDS = exports.MAX_ACCOUNT_CATEGORIES = exports.ACCOUNT_KINDS = exports.ACCOUNT_CATEGORY_IDS = void 0;
+/**
+ * `oxy.accounts` — the unified account graph (`/accounts`).
+ *
+ * An account is a relational, tree-structured principal (the `User` document
+ * generalised): a `personal` account is a human login at the root of its tree;
+ * `organization` / `project` / `bot` / `channel` accounts are non-login
+ * principals operated through membership. Accounts form a tree
+ * (`parentAccountId`) and expose a single membership model (`AccountMember`)
+ * with a unified role set and an explicit-but-inheritable cascade down the
+ * subtree. The applications an account owns are `oxy.apps`.
+ *
+ * Reference accounts by their `_id` (`accountId`, the underlying `User._id`)
+ * and members by their member `_id` — never by name, slug, or handle.
+ *
+ * SWITCHING INTO AN ACCOUNT: `accounts.actAs(accountId)` mints a REAL
+ * session for the target account and plants it as the active session — there is
+ * no per-request "acting-as" header. Identity is carried by the session/token,
+ * so a switch propagates through reload and cross-domain exactly like a login.
+ */
+const contracts_1 = require("@oxy.so/contracts");
 const userIdentity_1 = require("../utils/userIdentity");
 const identityCacheSweep_1 = require("../utils/identityCacheSweep");
 const accountCacheSweep_1 = require("../utils/accountCacheSweep");
 const MEDIUM_TTL = 2 * 60 * 1000;
 const LONG_TTL = 5 * 60 * 1000;
 const enc = encodeURIComponent;
-var contracts_1 = require("@oxy.so/contracts");
-Object.defineProperty(exports, "ACCOUNT_CATEGORY_IDS", { enumerable: true, get: function () { return contracts_1.ACCOUNT_CATEGORY_IDS; } });
-Object.defineProperty(exports, "ACCOUNT_KINDS", { enumerable: true, get: function () { return contracts_1.ACCOUNT_KINDS; } });
-Object.defineProperty(exports, "MAX_ACCOUNT_CATEGORIES", { enumerable: true, get: function () { return contracts_1.MAX_ACCOUNT_CATEGORIES; } });
-Object.defineProperty(exports, "SELECTABLE_ACCOUNT_CATEGORY_IDS", { enumerable: true, get: function () { return contracts_1.SELECTABLE_ACCOUNT_CATEGORY_IDS; } });
-Object.defineProperty(exports, "isDelegatedActAsEligibleKind", { enumerable: true, get: function () { return contracts_1.isDelegatedActAsEligibleKind; } });
-Object.defineProperty(exports, "isOperatorSwitchTargetKind", { enumerable: true, get: function () { return contracts_1.isOperatorSwitchTargetKind; } });
-Object.defineProperty(exports, "isSelectableAccountCategoryId", { enumerable: true, get: function () { return contracts_1.isSelectableAccountCategoryId; } });
-Object.defineProperty(exports, "kindAcceptsAccountCategories", { enumerable: true, get: function () { return contracts_1.kindAcceptsAccountCategories; } });
+var contracts_2 = require("@oxy.so/contracts");
+Object.defineProperty(exports, "ACCOUNT_CATEGORY_IDS", { enumerable: true, get: function () { return contracts_2.ACCOUNT_CATEGORY_IDS; } });
+Object.defineProperty(exports, "ACCOUNT_KINDS", { enumerable: true, get: function () { return contracts_2.ACCOUNT_KINDS; } });
+Object.defineProperty(exports, "MAX_ACCOUNT_CATEGORIES", { enumerable: true, get: function () { return contracts_2.MAX_ACCOUNT_CATEGORIES; } });
+Object.defineProperty(exports, "SELECTABLE_ACCOUNT_CATEGORY_IDS", { enumerable: true, get: function () { return contracts_2.SELECTABLE_ACCOUNT_CATEGORY_IDS; } });
+Object.defineProperty(exports, "isDelegatedActAsEligibleKind", { enumerable: true, get: function () { return contracts_2.isDelegatedActAsEligibleKind; } });
+Object.defineProperty(exports, "isOperatorSwitchTargetKind", { enumerable: true, get: function () { return contracts_2.isOperatorSwitchTargetKind; } });
+Object.defineProperty(exports, "isSelectableAccountCategoryId", { enumerable: true, get: function () { return contracts_2.isSelectableAccountCategoryId; } });
+Object.defineProperty(exports, "kindAcceptsAccountCategories", { enumerable: true, get: function () { return contracts_2.kindAcceptsAccountCategories; } });
 /** `oxy.accounts.members` — who can act on an account, and with what role. */
 class AccountMembersApi {
     constructor(ctx) {
@@ -79,10 +99,29 @@ class AccountMembersApi {
     }
 }
 exports.AccountMembersApi = AccountMembersApi;
+/** Current account governors and autonomous rotation use action-bound proofs. */
+class AccountAgentKeysApi {
+    constructor(ctx) {
+        this.ctx = ctx;
+    }
+    async list(accountId) {
+        return contracts_1.agentKeyListResponseSchema.parse(await this.ctx.request('GET', `/accounts/${enc(accountId)}/agent-keys`, undefined, { cache: false }));
+    }
+    async requestChallenge(accountId, operation) {
+        const response = await this.ctx.request('POST', `/accounts/${enc(accountId)}/agent-keys/challenge`, contracts_1.agentKeyOperationSchema.parse(operation), { cache: false });
+        return contracts_1.agentKeyOperationChallengeSchema.parse(response);
+    }
+    async execute(accountId, operation, proof) {
+        const response = await this.ctx.request('POST', `/accounts/${enc(accountId)}/agent-keys/execute`, contracts_1.executeAgentKeyOperationSchema.parse({ operation, proof }), { cache: false });
+        return contracts_1.agentKeyOperationResultSchema.parse(response);
+    }
+}
+exports.AccountAgentKeysApi = AccountAgentKeysApi;
 class AccountsApi {
     constructor(ctx) {
         this.ctx = ctx;
         this.members = new AccountMembersApi(ctx);
+        this.agentKeys = new AccountAgentKeysApi(ctx);
     }
     /**
      * List the accounts the caller can access: their own personal (root)

package/dist/cjs/api/apps.js

@@ -172,10 +172,10 @@ class AppsApi {
      * consent, authorize, and device-flow approval screens before any session
      * exists.
      */
-    async getPublic(clientId) {
+    async getPublic(clientId, options = {}) {
         const res = await this.ctx.request('GET', `/auth/oauth/client/${enc(clientId)}`, undefined, 
         // Public client metadata (pre-session consent UI) — skip the bearer preflight.
-        { cache: true, cacheTTL: MEDIUM_TTL, skipAuth: true });
+        { cache: options.cache ?? true, cacheTTL: MEDIUM_TTL, skipAuth: true });
         return res.application;
     }
     /**

package/dist/cjs/api/auth.js

@@ -33,7 +33,7 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.AuthApi = exports.AuthCommonsApi = exports.AuthOAuthApi = exports.AuthTotpApi = exports.AuthPasswordApi = exports.AuthEmailApi = void 0;
+exports.AuthApi = exports.AuthAgentApi = exports.AuthCommonsApi = exports.AuthOAuthApi = exports.AuthTotpApi = exports.AuthPasswordApi = exports.AuthEmailApi = void 0;
 const contracts_1 = require("@oxy.so/contracts");
 const OxyServices_errors_1 = require("../OxyServices.errors");
 const logger_1 = require("../logger");
@@ -303,7 +303,8 @@ class AuthOAuthApi {
      * out, so the app can run the OAuth flow again. It never degrades into a
      * session that looks alive and cannot refresh.
      */
-    async exchangeCode(params) {
+    /** `plantTokens: false` defers bearer installation to a validated provider commit. */
+    async exchangeCode(params, options = {}) {
         const form = new URLSearchParams({
             grant_type: 'authorization_code',
             code: params.code,
@@ -334,7 +335,9 @@ class AuthOAuthApi {
         }
         const expiresInSec = typeof record.expires_in === 'number' ? record.expires_in : DEFAULT_ACCESS_TOKEN_TTL_SECONDS;
         const expiresAt = new Date(Date.now() + expiresInSec * 1000).toISOString();
-        if (accessToken) {
+        // Provider completion validates the expected subject before committing.
+        // Direct callers retain the historical token-planting default.
+        if (accessToken && options.plantTokens !== false) {
             this.ctx.oxy.session.setAccessToken(accessToken);
         }
         if (!deviceId || !deviceSecret) {
@@ -683,6 +686,23 @@ class AuthCommonsApi {
     }
 }
 exports.AuthCommonsApi = AuthCommonsApi;
+/** Bot entry uses caller-owned keys and the normal account session lane. */
+class AuthAgentApi {
+    constructor(ctx) {
+        this.ctx = ctx;
+    }
+    async requestChallenge(publicKey) {
+        const body = contracts_1.agentChallengeRequestSchema.parse({ publicKey });
+        const response = await this.ctx.request('POST', '/auth/agent/challenge', body, { cache: false, skipAuth: true });
+        return contracts_1.agentProofClaimsSchema.parse(response);
+    }
+    async verify(publicKey, proof) {
+        const body = contracts_1.agentVerifyRequestSchema.parse({ publicKey, ...proof });
+        const response = await this.ctx.request('POST', '/auth/agent/verify', body, { cache: false, skipAuth: true });
+        return plantSession(this.ctx, response, 'auth/agent/verify');
+    }
+}
+exports.AuthAgentApi = AuthAgentApi;
 class AuthApi {
     constructor(ctx) {
         this.ctx = ctx;
@@ -691,6 +711,7 @@ class AuthApi {
         this.totp = new AuthTotpApi(ctx);
         this.oauth = new AuthOAuthApi(ctx);
         this.commons = new AuthCommonsApi(ctx);
+        this.agent = new AuthAgentApi(ctx);
     }
     /**
      * Register a new identity with public key authentication

package/dist/cjs/api/billing.js

@@ -1,12 +1,47 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.BillingApi = void 0;
+/**
+ * `oxy.billing` — the signed-in user's subscription, wallet and payment history.
+ *
+ * Every call reads the SIGNED-IN user's data unless a `userId` is passed (the
+ * API refuses any other user's). Checkout, plan changes and cancellation live
+ * under `/billing` (Stripe) and are not wrapped here yet.
+ *
+ * The types model the JSON these routes actually return (`subscription.controller`,
+ * `payment.controller`, `wallet.routes` in `packages/api`); `Date` columns
+ * arrive as ISO-8601 strings.
+ */
+const contracts_1 = require("@oxy.so/contracts");
+const contracts_2 = require("@oxy.so/contracts");
 const SUBSCRIPTION_TTL = 2 * 60 * 1000;
 const WALLET_TTL = 60 * 1000;
 class BillingApi {
     constructor(ctx) {
         this.ctx = ctx;
     }
+    /** Product rights only; requires a production application-bound user session. Never cached. */
+    async productAccess(query) {
+        const parsed = contracts_1.subjectProductAccessQuerySchema.parse(query);
+        const response = await this.ctx.request('GET', `/v1/products/${encodeURIComponent(parsed.productId)}/access/${encodeURIComponent(parsed.subjectAccountId)}`, undefined, { cache: false });
+        return contracts_1.subjectProductAccessSchema.parse(response);
+    }
+    /** Named commercial sources for the current subject; no inferred plan collapse. */
+    async productSubscriptions() {
+        return contracts_2.productSubscriptionsResponseSchema.parse(await this.ctx.request("GET", "/billing/product-subscriptions", undefined, { cache: false })).subscriptions;
+    }
+    /** Per-grant credit provenance; no interpretation of the historical mixed balance. */
+    async creditGrants() {
+        return contracts_2.subscriptionCreditGrantsResponseSchema.parse(await this.ctx.request("GET", "/billing/credit-grants", undefined, { cache: false })).grants;
+    }
+    /** Payer-only named-source cancellation. Resolves on provider acceptance, including pending local reconciliation. Use cancelProductSubscriptionWithStatus for detailed completion state. */
+    async cancelProductSubscription(sourceId, expectedSubjectAccountId) {
+        await this.ctx.request("POST", "/billing/product-subscriptions/cancel", contracts_2.cancelProductSubscriptionSchema.parse({ sourceId, ...(expectedSubjectAccountId ? { expectedSubjectAccountId } : {}) }), { cache: false });
+    }
+    /** Provider acceptance versus completed local cancellation, for user-facing flows. */
+    async cancelProductSubscriptionWithStatus(sourceId, expectedSubjectAccountId) {
+        return contracts_2.productSubscriptionCancellationResultSchema.parse(await this.ctx.request('POST', '/billing/product-subscriptions/cancel', contracts_2.cancelProductSubscriptionSchema.parse({ sourceId, ...(expectedSubjectAccountId ? { expectedSubjectAccountId } : {}) }), { cache: false }));
+    }
     /** The signed-in user's payment history. Never cached. */
     async payments() {
         return this.ctx.request('GET', '/payments/user', undefined, { cache: false });

package/dist/cjs/boot/sessionColdBoot.js

@@ -49,7 +49,6 @@ const logger_1 = require("../logger");
 const cacheKey_1 = require("../utils/cacheKey");
 const refresh_1 = require("../session/refresh");
 const identitySession_1 = require("../session/identitySession");
-const sharedDeviceCredential_1 = require("../session/sharedDeviceCredential");
 /**
  * Run the device-first cold boot. Resolves to the `runColdBoot` outcome and, as
  * a side effect, invokes `onSession` (winning session, token already planted) or
@@ -73,6 +72,8 @@ async function runSessionColdBoot(opts) {
     // Boot-local (not module-level) so it cannot leak across boots or break under
     // bundler re-evaluation.
     let signedOutReason = 'no_session';
+    let rejectedLocalHolder = false;
+    let accountRecoverySuperseded = false;
     // Boot-local memo for the identity pin. Resolved lazily INSIDE a step so the
     // (local, but storage-backed) read is covered by `overallDeadlineMs`, and
     // resolved at most once per boot so two steps cannot disagree. Always `null`
@@ -104,6 +105,8 @@ async function runSessionColdBoot(opts) {
     steps.push({
         id: 'warm-token-plant',
         run: async () => {
+            if (identityBinding === null && isNative && await store.isAutomaticIdentitySignInSuppressed?.())
+                return { kind: 'skip' };
             const persisted = await store.load();
             if (!persisted?.accessToken || !persisted.sessionId || !persisted.userId || !persisted.expiresAt) {
                 return { kind: 'skip' };
@@ -176,6 +179,11 @@ async function runSessionColdBoot(opts) {
                         },
                     };
                 case 'invalid-secret': {
+                    if (identityBinding === null && store.setAutomaticIdentitySignInSuppressed && await store.isAutomaticIdentitySignInSuppressed?.()) {
+                        rejectedLocalHolder = true;
+                        signedOutReason = 'no_session';
+                        return { kind: 'skip' };
+                    }
                     // Stale/diverged secret — drop it so the mint lane stops firing. On
                     // native the Commons-proof step below can still recover; on web this ends
                     // signed out. Setting it undefined drops the key on the store's JSON
@@ -187,6 +195,7 @@ async function runSessionColdBoot(opts) {
                     return { kind: 'skip' };
                 }
                 case 'no-session':
+                    rejectedLocalHolder = identityBinding === null;
                     // Device known, no live session — authoritative signed-out. Keep the
                     // secret (the device may sign in again).
                     signedOutReason = 'no_session';
@@ -208,7 +217,10 @@ async function runSessionColdBoot(opts) {
                     logger_1.logger.debug('device-secret mint failed (transient) — keeping secret', { component: 'sessionColdBoot', method: 'device-secret-mint' });
                     return { kind: 'skip' };
                 case 'session-ended':
-                    // Signed out while the boot was minting; the arm planted nothing.
+                    // The prior holder/epoch was superseded. This boot must not turn a
+                    // late rejection into a fresh Commons sign-in; a new boot can reconcile.
+                    if (identityBinding === null)
+                        accountRecoverySuperseded = true;
                     return { kind: 'skip' };
                 case 'no-secret':
                     return { kind: 'skip' };
@@ -273,63 +285,16 @@ async function runSessionColdBoot(opts) {
             // The adoption itself is local, but it is only worth committing alongside
             // a mint that proves the credential — so the whole lane is online-gated
             // like every other network step.
-            enabled: () => isNative && !isOffline(),
+            enabled: () => isNative && !isOffline() && !accountRecoverySuperseded,
             run: async () => {
-                const before = await store.load();
-                const decision = (0, sharedDeviceCredential_1.decideSharedDeviceJoin)(before, await sharedSlot.read());
-                if (decision.action === 'skip') {
-                    logger_1.logger.debug(`shared device credential not adopted (${decision.reason})`, { component: 'sessionColdBoot', method: 'shared-device-adopt' });
-                    return { kind: 'skip' };
-                }
-                // Restore the store to exactly what it held before this lane touched it.
-                // A credential we adopted and could not prove must not be left behind for
-                // the next boot's mint lane to keep retrying.
-                const revert = async () => {
-                    if (before) {
-                        await store.save(before);
-                    }
-                    else {
-                        await store.clear();
-                    }
-                };
-                const adopted = {
-                    // The mint fills both in from the device's live state; carrying the
-                    // previous session's ids into a different device session would be a
-                    // lie for however long the mint takes.
-                    sessionId: '',
-                    userId: '',
-                    deviceId: decision.credential.deviceId,
-                    deviceSecret: decision.credential.deviceSecret,
-                };
-                if (!(await store.save(adopted))) {
-                    logger_1.logger.error('adopted the shared device credential but it could not be durably persisted — reverting', undefined, { component: 'sessionColdBoot', method: 'shared-device-adopt' });
-                    await revert();
-                    return { kind: 'skip' };
-                }
-                const result = await (0, refresh_1.refreshDeviceSecretArm)({ oxy, store, pin: null });
+                const result = await (0, refresh_1.refreshSharedDeviceArm)({ oxy, store, shared: sharedSlot, rejectedLocalHolder });
                 if (result.status === 'ok') {
-                    return {
-                        kind: 'session',
-                        session: {
-                            sessionId: result.sessionId,
-                            userId: result.userId,
-                            accessToken: result.token,
-                        },
-                    };
-                }
-                if (result.status === 'invalid-secret') {
-                    // The one place we hold POSITIVE proof that the exact bytes in the
-                    // shared slot are dead — the server rejected them by name. Clearing it
-                    // signs nobody out (a credential the server does not recognise cannot
-                    // be minting for anyone) and it is what stops a dead credential from
-                    // blocking every future install: a stale slot owned by a different
-                    // `deviceId` is otherwise never overwritten, by design.
-                    await sharedSlot.clear();
+                    return { kind: 'session', session: {
+                            sessionId: result.sessionId, userId: result.userId, accessToken: result.token, state: result.state,
+                        } };
                 }
-                else if (result.status === 'no-session') {
+                if (result.status === 'no-session')
                     signedOutReason = 'no_session';
-                }
-                await revert();
                 return { kind: 'skip' };
             },
         });
@@ -357,8 +322,11 @@ async function runSessionColdBoot(opts) {
             id: 'commons-proof-signin',
             enabled: () => isNative && !isOffline(),
             run: async () => {
-                const session = await oxy.auth.signInWithCommonsIdentity({ requestOptions: { retry: false } });
-                if (!session?.accessToken) {
+                if (accountRecoverySuperseded || await store.isAutomaticIdentitySignInSuppressed?.())
+                    return { kind: 'skip' };
+                const epoch = oxy.http.getSessionEpoch();
+                const session = await oxy.auth.signInWithCommonsIdentity({ plantTokens: false, requestOptions: { retry: false } });
+                if (!session?.accessToken || oxy.http.getSessionEpoch() !== epoch || await store.isAutomaticIdentitySignInSuppressed?.()) {
                     return { kind: 'skip' };
                 }
                 // `verifyChallenge` issues a deviceSecret; persist it so the next
@@ -374,6 +342,9 @@ async function runSessionColdBoot(opts) {
                         expiresAt: session.expiresAt,
                     });
                 }
+                if (oxy.http.getSessionEpoch() !== epoch || await store.isAutomaticIdentitySignInSuppressed?.())
+                    return { kind: 'skip' };
+                oxy.session.setAccessToken(session.accessToken);
                 return {
                     kind: 'session',
                     session: {