@oxy.so/core 7.11.1 → 7.12.0

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/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';