@oxy.so/core 7.11.1 → 7.12.0

package/dist/esm/api/session.js

@@ -8,12 +8,21 @@
 import { jwtDecode } from 'jwt-decode';
 import { normalizeUserIdentity } from '../utils/userIdentity.js';
 import { OxyApiError } from '../OxyServices.errors.js';
+import { checkContract, holderContextEvidenceV1ResponseCheck } from '@oxy.so/contracts/client';
+/** How long a refusal (disabled, rate limited, unreachable) is remembered per installation. */
+const EVIDENCE_REFUSAL_MS = 5000;
+const unavailable = (reason) => ({
+    status: 'unavailable',
+    reason,
+});
 export class SessionApi {
     constructor(ctx) {
         this.ctx = ctx;
         this.deviceCredentialProvider = null;
         this.decodedFor = null;
         this.decoded = null;
+        /** One server round trip per installed bearer; the key is the opaque generation. */
+        this.evidence = new WeakMap();
     }
     // ── Local state ──────────────────────────────────────────────────────────
     /** The current access token, or `null` when signed out. */
@@ -118,6 +127,115 @@ export class SessionApi {
             return null;
         }
     }
+    // ── Holder-context evidence (ADR 0053) ───────────────────────────────────
+    /**
+     * Ask the server which shared-device context the INSTALLED bearer belongs to,
+     * and bind the answer to that exact installation.
+     *
+     * The result is honored only if the credential generation captured before
+     * the request is still current when the answer is committed, so a refresh,
+     * setter, account or actor switch, cross-tab change, restore or A to B to A
+     * during the request yields `changed`. The answer must also agree with the
+     * claims of the bearer that was captured; a disagreement is
+     * `binding_unavailable`. Nothing here refreshes, clears or mints a credential,
+     * and no outcome is a revocation verdict: callers keep their existing checks.
+     * Concurrent callers share one request per installation.
+     */
+    observeHolderEvidence() {
+        const generation = this.ctx.http.captureCredentialGeneration();
+        const token = this.ctx.http.getAccessToken();
+        if (!generation || !token)
+            return Promise.resolve(unavailable('no_credential'));
+        const known = this.evidence.get(generation);
+        if (known) {
+            const refused = known.settledAt !== undefined;
+            if (!refused || Date.now() - known.settledAt < EVIDENCE_REFUSAL_MS) {
+                return known.result.then((result) => result.status === 'ok' && result.evidence.expiresAtMs <= Date.now()
+                    ? this.refreshEvidence(generation, token)
+                    : result);
+            }
+        }
+        return this.refreshEvidence(generation, token);
+    }
+    /** Whether evidence still names the installed bearer and has not expired. */
+    isHolderEvidenceCurrent(evidence) {
+        return (Date.now() < evidence.expiresAtMs &&
+            this.ctx.http.isCredentialGenerationCurrent(evidence.generation));
+    }
+    refreshEvidence(generation, token) {
+        const entry = {
+            result: this.acquireEvidence(generation, token).then((result) => {
+                if (result.status !== 'ok')
+                    entry.settledAt = Date.now();
+                return result;
+            }),
+        };
+        this.evidence.set(generation, entry);
+        return entry.result;
+    }
+    async acquireEvidence(generation, token) {
+        let claims;
+        try {
+            claims = jwtDecode(token);
+        }
+        catch {
+            return unavailable('unsupported');
+        }
+        const proof = await this.readDeviceProof();
+        if (!proof)
+            return unavailable('no_holder');
+        let response;
+        try {
+            response = await this.ctx.request('POST', '/session/device/context-evidence-v1', proof, {
+                cache: false,
+                retry: false,
+                expectedCredentialGeneration: generation,
+            });
+        }
+        catch (error) {
+            if (error?.code === 'AUTH_SESSION_CHANGED') {
+                return unavailable('changed');
+            }
+            const status = error instanceof OxyApiError ? error.status : 0;
+            if (status === 403)
+                return unavailable('unsupported');
+            if (status === 409)
+                return unavailable('binding_unavailable');
+            return unavailable('unavailable');
+        }
+        const parsed = checkContract(holderContextEvidenceV1ResponseCheck, response);
+        if (!parsed)
+            return unavailable('unavailable');
+        // Commit synchronously: nothing may replace the bearer between this check
+        // and the evidence becoming visible to its caller.
+        if (!this.ctx.http.isCredentialGenerationCurrent(generation))
+            return unavailable('changed');
+        const expiresAtMs = Date.parse(parsed.expiresAt);
+        if (parsed.deviceId !== proof.deviceId ||
+            parsed.accountId !== claims.userId ||
+            parsed.sessionId !== claims.sessionId ||
+            (claims.act?.sub !== undefined && parsed.actorId !== claims.act.sub) ||
+            (claims.device_context_id !== undefined && parsed.contextId !== claims.device_context_id)) {
+            return unavailable('binding_unavailable');
+        }
+        if (!Number.isFinite(expiresAtMs) || expiresAtMs <= Date.now()) {
+            return unavailable('unavailable');
+        }
+        const evidence = Object.freeze({
+            generation,
+            identity: Object.freeze({
+                deviceId: parsed.deviceId,
+                deviceSessionId: parsed.deviceSessionId,
+                contextId: parsed.contextId,
+                actorId: parsed.actorId,
+                accountId: parsed.accountId,
+                sessionId: parsed.sessionId,
+            }),
+            deviceRevision: parsed.revision,
+            expiresAtMs,
+        });
+        return { status: 'ok', evidence };
+    }
     // ── The server session ───────────────────────────────────────────────────
     /** Ask the server whether the current access token is valid. */
     async validateToken() {

package/dist/esm/index.js

@@ -30,6 +30,7 @@ import './crypto/polyfill.js';
 // ---------------------------------------------------------------------------
 export { OxyServices, OXY_API_URL, OXY_CLOUD_URL } from './OxyServices.js';
 export { OxyApiError, OxyAuthenticationError, OxyAuthenticationTimeoutError, AssetUrlResolutionError, ServiceAssetMetadataError, } from './OxyServices.errors.js';
+export { sameHolderIdentity } from './api/holderEvidence.js';
 export { ASSET_MULTIPART_UPLOAD_MAX_BYTES, assetUrlCacheTTL, MAX_UPLOAD_BYTES } from './api/assets.js';
 export { DirectUploadInterruptedError } from './api/directUpload.js';
 export { buildUserDid } from './api/identity.js';

package/dist/types/HttpService.d.ts

@@ -22,6 +22,18 @@ export type AccessTokenProvider = () => string | null;
  * — `null` to send it anonymous. See {@link HttpService.setAnonymousAuthProvider}.
  */
 export type AnonymousAuthProvider = () => Promise<string | null>;
+declare const credentialGenerationBrand: unique symbol;
+/**
+ * An opaque, immutable token for ONE installation of a bearer in a client.
+ *
+ * `TokenStore` swaps it on every write path (setter, refresh, account or actor
+ * switch, cross-tab or restored token, clear), so two installations of the same
+ * bytes (A, B, A) are different generations. It names a local sequence only: it
+ * is not evidence of an account, a scope or authorization.
+ */
+export type CredentialGeneration = {
+    readonly [credentialGenerationBrand]: true;
+};
 /** A trusted platform transport, for example Expo's streaming fetch. */
 export type ResponseTransport = (input: string, init: RequestInit) => Promise<Response>;
 /**
@@ -44,6 +56,13 @@ export interface ResponseRequest {
 /** Same response contract, but rejects locally when the SDK has no bearer. */
 export type AuthenticatedResponseRequest = ResponseRequest;
 export interface RequestOptions {
+    /**
+     * Bind a write to ONE installation of the source's bearer. The transport
+     * rejects (`AUTH_SESSION_CHANGED`) when the generation was replaced before
+     * dispatch, after queueing, or before the result is returned. Implies no cache,
+     * deduplication or retry, and a 401 neither refreshes nor clears the session.
+     */
+    expectedCredentialGeneration?: CredentialGeneration;
     cache?: boolean;
     cacheTTL?: number;
     deduplicate?: boolean;
@@ -228,6 +247,7 @@ export declare class HttpService {
      * bearer — and through the token listeners, the account — back.
      */
     private sessionEpoch;
+    private readonly credentialSource;
     /** Preserve a known device across legacy rotations which omit the claim. */
     private sessionDeviceId;
     /** Preserve known actor and context hints across rotations without those claims. */
@@ -258,7 +278,7 @@ export declare class HttpService {
      */
     private _tokenChangeListeners;
     private requestMetrics;
-    constructor(config: OxyConfig);
+    constructor(config: OxyConfig, credentialSource?: HttpService | null);
     private syncAccessTokenFromProvider;
     /**
      * Robust FormData detection that works in browser, React Native, and
@@ -521,6 +541,10 @@ export declare class HttpService {
      * plants tokens itself (the device-secret arm) compares it across its awaits.
      */
     getSessionEpoch(): number;
+    /** Capture only the local generation; the caller must separately bind authority. */
+    captureCredentialGeneration(): CredentialGeneration | null;
+    isCredentialGenerationCurrent(generation: CredentialGeneration): boolean;
+    private assertCredentialGeneration;
     /** Whether {@link endSession} ran and no token has been planted since. */
     hasSessionEnded(): boolean;
     setAuthRefreshHandler(handler: AuthRefreshHandler | null): void;

package/dist/types/api/holderEvidence.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Holder-context evidence: the server's point-in-time observation of which
+ * shared-device context a bearer is installed in, bound to ONE installation of
+ * that bearer in this client (ADR 0053).
+ *
+ * Evidence is never authorization. It lets a caller that already captured a
+ * viewer intent prove, before a write is dispatched, that the bearer the write
+ * will carry belongs to that viewer's account and actor, and then pin the write
+ * to the exact installation with `expectedCredentialGeneration`. Anything that
+ * cannot be proven is `unavailable`, and the caller keeps its existing checks.
+ */
+import type { HolderContextEvidenceV1Response } from '@oxy.so/contracts';
+import type { CredentialGeneration } from '../HttpService';
+/** The identifiers the server observed; none of them is a credential. */
+export type HolderEvidenceIdentity = Readonly<Pick<HolderContextEvidenceV1Response, 'deviceId' | 'deviceSessionId' | 'contextId' | 'actorId' | 'accountId' | 'sessionId'>>;
+export interface HolderEvidence {
+    /** The installation of the bearer this evidence was observed for. */
+    readonly generation: CredentialGeneration;
+    readonly identity: HolderEvidenceIdentity;
+    /** The device-session revision the server observed. */
+    readonly deviceRevision: number;
+    /** Epoch milliseconds: the earlier of the bearer and session expiry. */
+    readonly expiresAtMs: number;
+}
+/**
+ * Why no evidence exists. Every reason means "keep the existing checks": none of
+ * them says the session is revoked, and none may clear or refresh credentials.
+ *
+ * - `no_credential`: no bearer is installed, or it comes from a pull-only provider.
+ * - `no_holder`: this client holds no device credential to prove the holder with.
+ * - `changed`: the bearer was replaced while the evidence was being acquired.
+ * - `unsupported`: a delegated, OAuth or legacy bearer, or the endpoint is not offered.
+ * - `binding_unavailable`: the server could not match holder, context and bearer.
+ * - `unavailable`: the endpoint is off, rate limited, unreachable or answered wrongly.
+ */
+export type HolderEvidenceUnavailableReason = 'no_credential' | 'no_holder' | 'changed' | 'unsupported' | 'binding_unavailable' | 'unavailable';
+export type HolderEvidenceResult = {
+    readonly status: 'ok';
+    readonly evidence: HolderEvidence;
+} | {
+    readonly status: 'unavailable';
+    readonly reason: HolderEvidenceUnavailableReason;
+};
+/** The one comparison that decides whether two observations name the same viewer context. */
+export declare function sameHolderIdentity(a: HolderEvidenceIdentity, b: HolderEvidenceIdentity): boolean;

package/dist/types/api/session.d.ts

@@ -2,6 +2,7 @@ import type { AccountActorChain, DeviceProof } from '@oxy.so/contracts';
 import type { OxyContext } from '../client/context';
 import type { ClientSession } from '../models/session';
 import type { User } from '../models/interfaces';
+import type { HolderEvidence, HolderEvidenceResult } from './holderEvidence';
 /**
  * Reads the device credential this client holds, if any — `{ deviceId,
  * deviceSecret }` from the provider's auth store. See
@@ -29,6 +30,8 @@ export declare class SessionApi {
     private deviceCredentialProvider;
     private decodedFor;
     private decoded;
+    /** One server round trip per installed bearer; the key is the opaque generation. */
+    private readonly evidence;
     constructor(ctx: OxyContext);
     /** The current access token, or `null` when signed out. */
     get accessToken(): string | null;
@@ -75,6 +78,24 @@ export declare class SessionApi {
      * that cannot be read only means the sign-in gets its own device.
      */
     readDeviceProof(): Promise<DeviceProof | null>;
+    /**
+     * Ask the server which shared-device context the INSTALLED bearer belongs to,
+     * and bind the answer to that exact installation.
+     *
+     * The result is honored only if the credential generation captured before
+     * the request is still current when the answer is committed, so a refresh,
+     * setter, account or actor switch, cross-tab change, restore or A to B to A
+     * during the request yields `changed`. The answer must also agree with the
+     * claims of the bearer that was captured; a disagreement is
+     * `binding_unavailable`. Nothing here refreshes, clears or mints a credential,
+     * and no outcome is a revocation verdict: callers keep their existing checks.
+     * Concurrent callers share one request per installation.
+     */
+    observeHolderEvidence(): Promise<HolderEvidenceResult>;
+    /** Whether evidence still names the installed bearer and has not expired. */
+    isHolderEvidenceCurrent(evidence: HolderEvidence): boolean;
+    private refreshEvidence;
+    private acquireEvidence;
     /** Ask the server whether the current access token is valid. */
     validateToken(): Promise<boolean>;
     /**

package/dist/types/index.d.ts

@@ -24,7 +24,9 @@ export { OxyServices, OXY_API_URL, OXY_CLOUD_URL } from './OxyServices';
 export type { OxyConfig, LinkedHttpClient } from './OxyServices';
 export { OxyApiError, OxyAuthenticationError, OxyAuthenticationTimeoutError, AssetUrlResolutionError, ServiceAssetMetadataError, } from './OxyServices.errors';
 export type { HttpMethod } from './client/context';
-export type { RequestOptions, ResponsePayload, ResponseRequest, ResponseTransport, AuthenticatedResponseRequest, AuthRefreshReason, AuthRefreshHandler, } from './HttpService';
+export type { RequestOptions, ResponsePayload, ResponseRequest, ResponseTransport, AuthenticatedResponseRequest, AuthRefreshReason, AuthRefreshHandler, CredentialGeneration, } from './HttpService';
+export { sameHolderIdentity } from './api/holderEvidence';
+export type { HolderEvidence, HolderEvidenceIdentity, HolderEvidenceResult, HolderEvidenceUnavailableReason, } from './api/holderEvidence';
 export type { SessionApi, DeviceCredentialProvider, SessionValidation } from './api/session';
 export type { AuthApi, ChallengeResponse, RegistrationRequest, ChallengeVerifyRequest, PublicKeyCheckResponse, OAuthUserInfoResponse, OAuthTokenExchangeResult, CommonsSignInHandle, CommonsSignInStatus, CommonsSignInPurpose, CommonsOAuthContext, CommonsApprovalInfo, CommonsApprovalSubjectAccount, CommonsSignInActionResult, CommonsOAuthFinalizeResult, CommonsDeliveryResult, SignInDeviceOptions, ClaimedSession, } from './api/auth';
 export type { UsersApi, ResolveExternalUserInput, DeleteAccountProof } from './api/users';

package/dist/types/server/safety.d.ts

@@ -17,7 +17,7 @@ export declare class ServerSafetyApi extends SafetyApi {
     /** The original personal bearer, a verified MCP connection proof, or explicit anonymous access. */
     profileAccess(input: ProfileAccessInput, options?: SafetyRequester): Promise<{
         allowed: boolean;
-        reason: "blocked" | "private" | "public" | "owner" | "unavailable";
+        reason: "blocked" | "private" | "public" | "unavailable" | "owner";
         policyVersion: "1";
     }>;
     profileAccessBatch(input: ProfileAccessBatchInput, options: SafetyRequester): Promise<{
@@ -25,14 +25,14 @@ export declare class ServerSafetyApi extends SafetyApi {
             subjectAccountId: string;
             decision: {
                 allowed: boolean;
-                reason: "blocked" | "private" | "public" | "owner" | "unavailable" | "allowed" | "unsupported_consumer" | "contact_not_approved" | "mature_content" | "unrated_content" | "approval_required";
+                reason: "blocked" | "private" | "public" | "unavailable" | "owner" | "allowed" | "unsupported_consumer" | "contact_not_approved" | "mature_content" | "unrated_content" | "approval_required";
                 policyVersion: "2";
             };
         }[];
     }>;
     messageAccess(input: MessageAccessInput, options: SafetyRequester): Promise<{
         allowed: boolean;
-        reason: "blocked" | "private" | "public" | "owner" | "unavailable" | "allowed" | "unsupported_consumer" | "contact_not_approved" | "mature_content" | "unrated_content" | "approval_required";
+        reason: "blocked" | "private" | "public" | "unavailable" | "owner" | "allowed" | "unsupported_consumer" | "contact_not_approved" | "mature_content" | "unrated_content" | "approval_required";
         policyVersion: "2";
     }>;
     messageAccessBatch(input: MessageAccessBatchInput, options: SafetyRequester): Promise<{
@@ -40,7 +40,7 @@ export declare class ServerSafetyApi extends SafetyApi {
             resourceId: string;
             decision: {
                 allowed: boolean;
-                reason: "blocked" | "private" | "public" | "owner" | "unavailable" | "allowed" | "unsupported_consumer" | "contact_not_approved" | "mature_content" | "unrated_content" | "approval_required";
+                reason: "blocked" | "private" | "public" | "unavailable" | "owner" | "allowed" | "unsupported_consumer" | "contact_not_approved" | "mature_content" | "unrated_content" | "approval_required";
                 policyVersion: "2";
             };
         }[];
@@ -60,7 +60,7 @@ export declare class ServerSafetyApi extends SafetyApi {
             resourceId: string;
             decision: {
                 allowed: boolean;
-                reason: "blocked" | "private" | "public" | "owner" | "unavailable" | "allowed" | "unsupported_consumer" | "contact_not_approved" | "mature_content" | "unrated_content" | "approval_required";
+                reason: "blocked" | "private" | "public" | "unavailable" | "owner" | "allowed" | "unsupported_consumer" | "contact_not_approved" | "mature_content" | "unrated_content" | "approval_required";
                 policyVersion: "2";
             };
         }[];
@@ -70,7 +70,7 @@ export declare class ServerSafetyApi extends SafetyApi {
             targetAccountId: string;
             decision: {
                 allowed: boolean;
-                reason: "blocked" | "private" | "public" | "owner" | "unavailable" | "allowed" | "unsupported_consumer" | "contact_not_approved" | "mature_content" | "unrated_content" | "approval_required";
+                reason: "blocked" | "private" | "public" | "unavailable" | "owner" | "allowed" | "unsupported_consumer" | "contact_not_approved" | "mature_content" | "unrated_content" | "approval_required";
                 policyVersion: "2";
             };
         }[];
@@ -96,7 +96,7 @@ export declare class ServerSafetyApi extends SafetyApi {
     }>;
     contentAccess(input: ContentAccessInput, options: SafetyRequester): Promise<{
         allowed: boolean;
-        reason: "blocked" | "private" | "public" | "owner" | "unavailable" | "allowed" | "unsupported_consumer" | "contact_not_approved" | "mature_content" | "unrated_content" | "approval_required";
+        reason: "blocked" | "private" | "public" | "unavailable" | "owner" | "allowed" | "unsupported_consumer" | "contact_not_approved" | "mature_content" | "unrated_content" | "approval_required";
         policyVersion: "2";
     }>;
     contentAccessBatch(input: ContentAccessBatchInput, options: SafetyRequester): Promise<{
@@ -104,14 +104,14 @@ export declare class ServerSafetyApi extends SafetyApi {
             resourceId: string;
             decision: {
                 allowed: boolean;
-                reason: "blocked" | "private" | "public" | "owner" | "unavailable" | "allowed" | "unsupported_consumer" | "contact_not_approved" | "mature_content" | "unrated_content" | "approval_required";
+                reason: "blocked" | "private" | "public" | "unavailable" | "owner" | "allowed" | "unsupported_consumer" | "contact_not_approved" | "mature_content" | "unrated_content" | "approval_required";
                 policyVersion: "2";
             };
         }[];
     }>;
     deliveryAccess(input: DeliveryAccessInput): Promise<{
         allowed: boolean;
-        reason: "blocked" | "private" | "public" | "owner" | "unavailable" | "allowed" | "unsupported_consumer" | "contact_not_approved" | "mature_content" | "unrated_content" | "approval_required";
+        reason: "blocked" | "private" | "public" | "unavailable" | "owner" | "allowed" | "unsupported_consumer" | "contact_not_approved" | "mature_content" | "unrated_content" | "approval_required";
         policyVersion: "2";
     }>;
     requestPurchaseApproval(input: PurchaseEffects, options: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oxy.so/core",
-  "version": "7.11.1",
+  "version": "7.12.0",
   "description": "OxyHQ SDK Foundation — API client, authentication, cryptographic identity, and shared utilities",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",
@@ -181,7 +181,7 @@
   "dependencies": {
     "@noble/ciphers": "^1.3.0",
     "@noble/hashes": "^1.8.0",
-    "@oxy.so/contracts": "6.3.0",
+    "@oxy.so/contracts": "6.4.0",
     "@oxy.so/protocol": "^1.5.1",
     "@oxy.so/telemetry": "^2.1.0",
     "@scure/bip39": "^1.6.0",

package/src/HttpService.ts

@@ -56,6 +56,21 @@ export type AccessTokenProvider = () => string | null;
  */
 export type AnonymousAuthProvider = () => Promise<string | null>;
 
+declare const credentialGenerationBrand: unique symbol;
+/**
+ * An opaque, immutable token for ONE installation of a bearer in a client.
+ *
+ * `TokenStore` swaps it on every write path (setter, refresh, account or actor
+ * switch, cross-tab or restored token, clear), so two installations of the same
+ * bytes (A, B, A) are different generations. It names a local sequence only: it
+ * is not evidence of an account, a scope or authorization.
+ */
+export type CredentialGeneration = { readonly [credentialGenerationBrand]: true };
+
+function newCredentialGeneration(): CredentialGeneration {
+  return Object.freeze({}) as CredentialGeneration;
+}
+
 /** Comparison only fences local async work; it never validates token authority. */
 function sameTokenSession(left: string | null, right: string | null): boolean {
   if (left === right) return true;
@@ -190,6 +205,13 @@ interface FormDataLike {
 }
 
 export interface RequestOptions {
+  /**
+   * Bind a write to ONE installation of the source's bearer. The transport
+   * rejects (`AUTH_SESSION_CHANGED`) when the generation was replaced before
+   * dispatch, after queueing, or before the result is returned. Implies no cache,
+   * deduplication or retry, and a 401 neither refreshes nor clears the session.
+   */
+  expectedCredentialGeneration?: CredentialGeneration;
   cache?: boolean;
   cacheTTL?: number;
   deduplicate?: boolean;
@@ -434,16 +456,29 @@ const CACHE_SIZE_WARNING_THROTTLE_MS = 60000;
  */
 class TokenStore {
   private accessToken: string | null = null;
+  private generation: CredentialGeneration = newCredentialGeneration();
 
   setTokens(accessToken: string): void {
+    this.generation = newCredentialGeneration();
     this.accessToken = accessToken;
   }
 
+  /** The identity of the bearer's current installation, never of its bytes. */
+  getGeneration(): CredentialGeneration {
+    return this.generation;
+  }
+
+  /** Retire the current generation without touching the bearer (provider swaps). */
+  invalidateGeneration(): void {
+    this.generation = newCredentialGeneration();
+  }
+
   getAccessToken(): string | null {
     return this.accessToken;
   }
 
   clearTokens(): void {
+    this.generation = newCredentialGeneration();
     this.accessToken = null;
   }
 
@@ -576,6 +611,7 @@ export class HttpService {
    * bearer — and through the token listeners, the account — back.
    */
   private sessionEpoch = 0;
+  private readonly credentialSource: HttpService | null;
   /** Preserve a known device across legacy rotations which omit the claim. */
   private sessionDeviceId: string | null = null;
   /** Preserve known actor and context hints across rotations without those claims. */
@@ -618,8 +654,9 @@ export class HttpService {
     averageResponseTime: 0,
   };
 
-  constructor(config: OxyConfig) {
+  constructor(config: OxyConfig, credentialSource: HttpService | null = null) {
     this.config = config;
+    this.credentialSource = credentialSource;
     this.baseURL = config.baseURL;
     this.tokenStore = new TokenStore();
 
@@ -760,6 +797,21 @@ export class HttpService {
    */
   async request<T = unknown>(config: RequestConfig): Promise<ResponsePayload<T>> {
     if (config.signal?.aborted) throw createCancelledError('Request cancelled before it was sent');
+    if (config.expectedCredentialGeneration) {
+      // The prototype is deliberately limited to writes; it does not
+      // yet define leases for cached/deduplicated reads or raw response paths.
+      if (
+        !['POST', 'PUT', 'PATCH', 'DELETE'].includes(config.method) ||
+        config.skipAuth ||
+        Object.keys(config.headers ?? {}).some((key) => key.toLowerCase() === 'authorization')
+      ) {
+        throw new Error('A credential generation requires an implicitly authenticated write');
+      }
+      (this.credentialSource ?? this).assertCredentialGeneration(
+        config.expectedCredentialGeneration,
+      );
+      config = { ...config, cache: false, deduplicate: false, retry: false };
+    }
     // The provider can change independently of the last request. Synchronize
     // before deriving the cache and deduplication identity, including hits.
     const explicitAuthorization = Object.keys(config.headers ?? {}).some(
@@ -878,6 +930,15 @@ export class HttpService {
     const authHeader = usesSessionAuth
       ? await awaitRequestSignal(this.getAuthHeader(), signal)
       : null;
+    const assertExpectedCredential = () => {
+      if (config.expectedCredentialGeneration) {
+        (this.credentialSource ?? this).assertCredentialGeneration(
+          config.expectedCredentialGeneration,
+          authHeader,
+        );
+      }
+    };
+    assertExpectedCredential();
     const isOriginalSession = () => {
       if (this.sessionEpoch !== contextEpoch) return false;
       const currentToken = this.syncAccessTokenFromProvider();
@@ -929,6 +990,7 @@ export class HttpService {
       if (usesSessionAuth && !isOriginalSession()) {
         throw new OxyAuthenticationError('The request session changed', 'AUTH_SESSION_CHANGED');
       }
+      assertExpectedCredential();
 
       /**
        * Whether OUR timer fired, so a timeout can be told apart from a
@@ -1042,6 +1104,9 @@ export class HttpService {
           throw new Error('Requester proofs require a transport that rejects redirects');
         }
 
+        // Header and source generation are checked together in this synchronous
+        // dispatch segment, after the preflight and any queue wait.
+        assertExpectedCredential();
         const response = useXhrForUpload
           ? await this.uploadViaXHR(
               fullUrl,
@@ -1065,6 +1130,13 @@ export class HttpService {
         // it, including on every throw between here and there.
         if (timeoutId) clearTimeout(timeoutId);
 
+        try {
+          assertExpectedCredential();
+        } catch (error) {
+          void discardResponseBody(response);
+          throw error;
+        }
+
         if (usesSessionAuth && !isOriginalSession()) {
           void discardResponseBody(response);
           throw new OxyAuthenticationError('The request session changed', 'AUTH_SESSION_CHANGED');
@@ -1077,6 +1149,7 @@ export class HttpService {
           // session routes; the refresh handler owns session rotation.
           if (
             response.status === 401 &&
+            !config.expectedCredentialGeneration &&
             !config._isAuthRetry &&
             usesSessionAuth &&
             isOriginalSession()
@@ -1218,12 +1291,14 @@ export class HttpService {
         if (usesSessionAuth && !isOriginalSession()) {
           throw new OxyAuthenticationError('The request session changed', 'AUTH_SESSION_CHANGED');
         }
+        assertExpectedCredential();
         const duration = Date.now() - startTime;
         this.updateMetrics(true, duration);
         this.config.onRequestEnd?.(url, method, duration, true);
 
         return responseData as T;
       } catch (error: unknown) {
+        assertExpectedCredential();
         const duration = Date.now() - startTime;
         this.updateMetrics(false, duration);
         // A body reader can reject or finish parsing an error after the viewer
@@ -1348,6 +1423,7 @@ export class HttpService {
     if (usesSessionAuth && !isOriginalSession()) {
       throw new OxyAuthenticationError('The request session changed', 'AUTH_SESSION_CHANGED');
     }
+    assertExpectedCredential();
 
     // Cache the result if caching is enabled
     if (cache && cacheKey && lease.valid && result) {
@@ -2192,6 +2268,36 @@ export class HttpService {
     return this.sessionEpoch;
   }
 
+  /** Capture only the local generation; the caller must separately bind authority. */
+  captureCredentialGeneration(): CredentialGeneration | null {
+    // A pull-only provider can change A→B→A between reads without notifying us.
+    if (this.accessTokenProvider) return null;
+    return this.tokenStore.getAccessToken() ? this.tokenStore.getGeneration() : null;
+  }
+
+  isCredentialGenerationCurrent(generation: CredentialGeneration): boolean {
+    return (
+      !this.accessTokenProvider &&
+      this.tokenStore.getAccessToken() !== null &&
+      generation === this.tokenStore.getGeneration()
+    );
+  }
+
+  private assertCredentialGeneration(
+    generation: CredentialGeneration,
+    selectedHeader?: string | null,
+  ): void {
+    const token = this.tokenStore.getAccessToken();
+    if (
+      this.accessTokenProvider ||
+      !token ||
+      generation !== this.tokenStore.getGeneration() ||
+      (selectedHeader !== undefined && selectedHeader !== `Bearer ${token}`)
+    ) {
+      throw new OxyAuthenticationError('The request credential changed', 'AUTH_SESSION_CHANGED');
+    }
+  }
+
   /** Whether {@link endSession} ran and no token has been planted since. */
   hasSessionEnded(): boolean {
     return this.sessionEnded;
@@ -2202,6 +2308,7 @@ export class HttpService {
   }
 
   setAccessTokenProvider(provider: AccessTokenProvider | null): void {
+    this.tokenStore.invalidateGeneration();
     this.accessTokenProvider = provider;
   }
 

package/src/OxyServices.ts

@@ -159,7 +159,10 @@ export class OxyServices {
    * Query). Pass `enableCache: true` to opt in.
    */
   createLinkedClient(config: OxyConfig): LinkedHttpClient {
-    const client = new HttpService({ ...config, enableCache: config.enableCache ?? false });
+    const client = new HttpService(
+      { ...config, enableCache: config.enableCache ?? false },
+      this.http,
+    );
 
     const syncToken = (accessToken: string | null): void => {
       const current = client.getAccessToken();