@oxy.so/core 7.11.0 → 7.12.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();

package/src/api/holderEvidence.ts

@@ -0,0 +1,66 @@
+/**
+ * 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 function sameHolderIdentity(a: HolderEvidenceIdentity, b: HolderEvidenceIdentity): boolean {
+  return (
+    a.deviceId === b.deviceId &&
+    a.deviceSessionId === b.deviceSessionId &&
+    a.contextId === b.contextId &&
+    a.actorId === b.actorId &&
+    a.accountId === b.accountId &&
+    a.sessionId === b.sessionId
+  );
+}

package/src/api/session.ts

@@ -12,6 +12,20 @@ import type { ClientSession } from '../models/session';
 import type { User } from '../models/interfaces';
 import { normalizeUserIdentity } from '../utils/userIdentity';
 import { OxyApiError } from '../OxyServices.errors';
+import { checkContract, holderContextEvidenceV1ResponseCheck } from '@oxy.so/contracts/client';
+import type { CredentialGeneration } from '../HttpService';
+import type {
+  HolderEvidence,
+  HolderEvidenceResult,
+  HolderEvidenceUnavailableReason,
+} from './holderEvidence';
+
+/** How long a refusal (disabled, rate limited, unreachable) is remembered per installation. */
+const EVIDENCE_REFUSAL_MS = 5_000;
+const unavailable = (reason: HolderEvidenceUnavailableReason): HolderEvidenceResult => ({
+  status: 'unavailable',
+  reason,
+});
 
 /**
  * Reads the device credential this client holds, if any — `{ deviceId,
@@ -42,12 +56,21 @@ interface AccessTokenClaims {
   exp?: number;
   userId?: string;
   id?: string;
+  sessionId?: string;
+  deviceId?: string;
+  device_context_id?: string;
+  act?: { sub?: string };
 }
 
 export class SessionApi {
   private deviceCredentialProvider: DeviceCredentialProvider | null = null;
   private decodedFor: string | null = null;
   private decoded: AccessTokenClaims | null = null;
+  /** One server round trip per installed bearer; the key is the opaque generation. */
+  private readonly evidence = new WeakMap<
+    CredentialGeneration,
+    { result: Promise<HolderEvidenceResult>; settledAt?: number }
+  >();
 
   constructor(protected readonly ctx: OxyContext) {}
 
@@ -163,6 +186,128 @@ export class SessionApi {
     }
   }
 
+  // ── 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(): Promise<HolderEvidenceResult> {
+    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 as number) < 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: HolderEvidence): boolean {
+    return (
+      Date.now() < evidence.expiresAtMs &&
+      this.ctx.http.isCredentialGenerationCurrent(evidence.generation)
+    );
+  }
+
+  private refreshEvidence(
+    generation: CredentialGeneration,
+    token: string,
+  ): Promise<HolderEvidenceResult> {
+    const entry: { result: Promise<HolderEvidenceResult>; settledAt?: number } = {
+      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;
+  }
+
+  private async acquireEvidence(
+    generation: CredentialGeneration,
+    token: string,
+  ): Promise<HolderEvidenceResult> {
+    let claims: AccessTokenClaims;
+    try {
+      claims = jwtDecode<AccessTokenClaims>(token);
+    } catch {
+      return unavailable('unsupported');
+    }
+    const proof = await this.readDeviceProof();
+    if (!proof) return unavailable('no_holder');
+    let response: unknown;
+    try {
+      response = await this.ctx.request<unknown>(
+        'POST',
+        '/session/device/context-evidence-v1',
+        proof,
+        {
+          cache: false,
+          retry: false,
+          expectedCredentialGeneration: generation,
+        },
+      );
+    } catch (error) {
+      if ((error as { code?: unknown } | null)?.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: HolderEvidence = 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. */

package/src/aws/index.ts

@@ -10,8 +10,22 @@ import type { WorkloadCredentialProvider } from '../server/workloadIdentity';
 export function createAwsWorkloadCredentialProvider(
   options: { profile?: string } = {},
 ): WorkloadCredentialProvider {
-  const provider = defaultProvider(options);
+  // An explicitly selected profile is an authority boundary. defaultProvider
+  // falls through a missing profile to ambient ECS/IMDS credentials, which may
+  // name another application. fromIni resolves only the selected profile and
+  // its declared source chain, or rejects; there is no ambient fallback.
+  if (options.profile !== undefined && !options.profile.trim())
+    throw new Error('An explicit AWS workload profile must not be empty');
+  const ambient = options.profile === undefined ? defaultProvider(options) : undefined;
+  const resolveProfile = async () =>
+    (await import('@aws-sdk/credential-provider-ini')).fromIni(options);
+  let selectedProfile: ReturnType<typeof resolveProfile> | undefined;
   return async () => {
+    let provider = ambient;
+    if (!provider) {
+      selectedProfile ??= resolveProfile();
+      provider = await selectedProfile;
+    }
     const credentials = await provider();
     if (
       !credentials.sessionToken ||

package/src/index.ts

@@ -48,7 +48,15 @@ export type {
   AuthenticatedResponseRequest,
   AuthRefreshReason,
   AuthRefreshHandler,
+  CredentialGeneration,
 } from './HttpService';
+export { sameHolderIdentity } from './api/holderEvidence';
+export type {
+  HolderEvidence,
+  HolderEvidenceIdentity,
+  HolderEvidenceResult,
+  HolderEvidenceUnavailableReason,
+} from './api/holderEvidence';
 
 // The namespaces — their classes (for typing) and their input/output types.
 export type { SessionApi, DeviceCredentialProvider, SessionValidation } from './api/session';