@oxy.so/core 4.1.0 → 4.3.0

package/src/api/billing.ts

@@ -9,6 +9,16 @@
  * `payment.controller`, `wallet.routes` in `packages/api`); `Date` columns
  * arrive as ISO-8601 strings.
  */
+import { type SubjectProductAccess,
+	type SubjectProductAccessQuery,
+	subjectProductAccessQuerySchema, subjectProductAccessSchema, } from '@oxy.so/contracts';
+import {
+	type ProductSubscriptionSummary, type SubscriptionCreditGrant, type ProductSubscriptionCancellationResult,
+  productSubscriptionCancellationResultSchema,
+	cancelProductSubscriptionSchema,
+	productSubscriptionsResponseSchema,
+	subscriptionCreditGrantsResponseSchema,
+} from '@oxy.so/contracts';
 import type { OxyContext } from '../client/context';
 
 const SUBSCRIPTION_TTL = 2 * 60 * 1000;
@@ -105,13 +115,65 @@ export interface WalletTransactionsPage {
 export class BillingApi {
   constructor(protected readonly ctx: OxyContext) {}
 
-  /** The signed-in user's payment history. Never cached. */
-  async payments(): Promise<Payment[]> {
+  /** Product rights only; requires a production application-bound user session. Never cached. */
+  async productAccess(query: SubjectProductAccessQuery): Promise<SubjectProductAccess> {
+    const parsed = subjectProductAccessQuerySchema.parse(query);
+    const response = await this.ctx.request<unknown>('GET',
+      `/v1/products/${encodeURIComponent(parsed.productId)}/access/${encodeURIComponent(parsed.subjectAccountId)}`,
+      undefined, { cache: false });
+    return subjectProductAccessSchema.parse(response);
+  }
+
+	/** Named commercial sources for the current subject; no inferred plan collapse. */
+	async productSubscriptions(): Promise<ProductSubscriptionSummary[]> {
+		return productSubscriptionsResponseSchema.parse(
+			await this.ctx.request<unknown>(
+				"GET",
+				"/billing/product-subscriptions",
+				undefined,
+				{ cache: false },
+			),
+		).subscriptions;
+	}
+
+	/** Per-grant credit provenance; no interpretation of the historical mixed balance. */
+	async creditGrants(): Promise<SubscriptionCreditGrant[]> {
+		return subscriptionCreditGrantsResponseSchema.parse(
+			await this.ctx.request<unknown>(
+				"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: string, expectedSubjectAccountId?: string): Promise<void> {
+		await this.ctx.request(
+			"POST",
+			"/billing/product-subscriptions/cancel",
+			cancelProductSubscriptionSchema.parse({ sourceId, ...(expectedSubjectAccountId ? { expectedSubjectAccountId } : {}) }),
+			{ cache: false },
+		);
+	}
+
+  /** Provider acceptance versus completed local cancellation, for user-facing flows. */
+  async cancelProductSubscriptionWithStatus(sourceId: string, expectedSubjectAccountId?: string): Promise<ProductSubscriptionCancellationResult> {
+    return productSubscriptionCancellationResultSchema.parse(await this.ctx.request<unknown>(
+      'POST', '/billing/product-subscriptions/cancel',
+      cancelProductSubscriptionSchema.parse({ sourceId, ...(expectedSubjectAccountId ? { expectedSubjectAccountId } : {}) }),
+      { cache: false },
+    ));
+  }
+
+	/** The signed-in user's payment history. Never cached. */
+	async payments(): Promise<Payment[]> {
     return this.ctx.request<Payment[]>('GET', '/payments/user', undefined, { cache: false });
   }
 
-  /** A user's subscription (default: the signed-in user's). */
-  async subscription(userId?: string): Promise<Subscription> {
+	/** A user's subscription (default: the signed-in user's). */
+	async subscription(userId?: string): Promise<Subscription> {
     const id = this.resolveUserId(userId);
     return this.ctx.request<Subscription>('GET', `/subscription/${id}`, undefined, {
       cache: true,
@@ -119,14 +181,14 @@ export class BillingApi {
     });
   }
 
-  /** A user's wallet (default: the signed-in user's). Cached briefly: the balance moves. */
-  async wallet(userId?: string): Promise<Wallet> {
+	/** A user's wallet (default: the signed-in user's). Cached briefly: the balance moves. */
+	async wallet(userId?: string): Promise<Wallet> {
     const id = this.resolveUserId(userId);
     return this.ctx.request<Wallet>('GET', `/wallet/${id}`, undefined, { cache: true, cacheTTL: WALLET_TTL });
   }
 
-  /** A page of a user's wallet transactions (default: the signed-in user's). Never cached. */
-  async walletTransactions(
+	/** A page of a user's wallet transactions (default: the signed-in user's). Never cached. */
+	async walletTransactions(
     options: { userId?: string; limit?: number; offset?: number } = {},
   ): Promise<WalletTransactionsPage> {
     const id = this.resolveUserId(options.userId);
@@ -136,7 +198,7 @@ export class BillingApi {
     return this.ctx.request<WalletTransactionsPage>('GET', `/wallet/transactions/${id}`, params, { cache: false });
   }
 
-  private resolveUserId(userId?: string): string {
+	private resolveUserId(userId?: string): string {
     const id = userId || this.ctx.oxy.session.userId;
     if (!id) throw new Error('User not authenticated');
     return id;

package/src/api/session.ts

@@ -6,7 +6,7 @@
  * token belongs to: validating it, listing the sessions beside it, signing out.
  */
 import { jwtDecode } from 'jwt-decode';
-import type { DeviceProof } from '@oxy.so/contracts';
+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';
@@ -26,6 +26,8 @@ export interface SessionValidation {
   user: User;
   sessionId?: string;
   source?: string;
+  /** Who acted, and as whom, read off the session row (issue #1520). */
+  actor?: AccountActorChain;
 }
 
 interface AccessTokenClaims {

package/src/boot/sessionColdBoot.ts

@@ -44,17 +44,14 @@ import { runColdBoot, type ColdBootOutcome, type ColdBootStep } from '../utils/c
 import { isNative as detectNative } from '../utils/platform';
 import { logger } from '../logger';
 import { computeIdentityTag } from '../utils/cacheKey';
-import { TOKEN_REFRESH_LEAD_MS, refreshDeviceSecretArm } from '../session/refresh';
+import { TOKEN_REFRESH_LEAD_MS, refreshDeviceSecretArm, refreshSharedDeviceArm } from '../session/refresh';
 import {
   establishIdentitySession,
   resolveIdentityPin,
   type IdentityBinding,
 } from '../session/identitySession';
 import type { IdentityPin } from '../session/identityPin';
-import {
-  decideSharedDeviceJoin,
-  type SharedDeviceCredentialStore,
-} from '../session/sharedDeviceCredential';
+import type { SharedDeviceCredentialStore } from '../session/sharedDeviceCredential';
 import type { OxyServices } from '../OxyServices';
 import type { AuthStateStore, PersistedAuthState } from '../session/authStateStore';
 import type { DeviceSessionState } from '@oxy.so/contracts';
@@ -178,6 +175,8 @@ export async function runSessionColdBoot(
   // Boot-local (not module-level) so it cannot leak across boots or break under
   // bundler re-evaluation.
   let signedOutReason: 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
@@ -212,6 +211,7 @@ export async function runSessionColdBoot(
   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' };
@@ -287,6 +287,11 @@ export async function runSessionColdBoot(
             },
           };
         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
@@ -298,6 +303,7 @@ export async function runSessionColdBoot(
           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';
@@ -329,7 +335,9 @@ export async function runSessionColdBoot(
           );
           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' };
@@ -394,73 +402,16 @@ export async function runSessionColdBoot(
       // 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 = decideSharedDeviceJoin(before, await sharedSlot.read());
-        if (decision.action === 'skip') {
-          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 (): Promise<void> => {
-          if (before) {
-            await store.save(before);
-          } else {
-            await store.clear();
-          }
-        };
-
-        const adopted: PersistedAuthState = {
-          // 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.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 refreshDeviceSecretArm({ oxy, store, pin: null });
+        const result = await refreshSharedDeviceArm({oxy, store, shared: sharedSlot, rejectedLocalHolder});
         if (result.status === 'ok') {
-          return {
-            kind: 'session',
-            session: {
-              sessionId: result.sessionId,
-              userId: result.userId,
-              accessToken: result.token,
-            },
-          };
+          return {kind: 'session', session: {
+            sessionId: result.sessionId, userId: result.userId, accessToken: result.token, state: result.state,
+          }};
         }
-
-        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();
-        } else if (result.status === 'no-session') {
-          signedOutReason = 'no_session';
-        }
-        await revert();
-        return { kind: 'skip' };
+        if (result.status === 'no-session') signedOutReason = 'no_session';
+        return {kind: 'skip'};
       },
     });
   }
@@ -488,8 +439,10 @@ export async function runSessionColdBoot(
       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
@@ -505,6 +458,8 @@ export async function runSessionColdBoot(
             expiresAt: session.expiresAt,
           });
         }
+        if (oxy.http.getSessionEpoch() !== epoch || await store.isAutomaticIdentitySignInSuppressed?.()) return { kind: 'skip' };
+        oxy.session.setAccessToken(session.accessToken);
         return {
           kind: 'session',
           session: {

package/src/index.ts

@@ -40,7 +40,7 @@ export {
   ServiceAssetMetadataError,
 } from './OxyServices.errors';
 export type { HttpMethod } from './client/context';
-export type { RequestOptions, AuthenticatedResponseRequest, AuthRefreshReason, AuthRefreshHandler } from './HttpService';
+export type { RequestOptions, ResponseRequest, ResponseTransport, AuthenticatedResponseRequest, AuthRefreshReason, AuthRefreshHandler } from './HttpService';
 
 // The namespaces — their classes (for typing) and their input/output types.
 export type { SessionApi, DeviceCredentialProvider, SessionValidation } from './api/session';

package/src/inference/OxyInferenceClient.ts

@@ -1,3 +1,4 @@
+import type { MeteredGeneration } from '@oxy.so/contracts';
 /**
  * The Oxy inference client — one surface, two credential lanes (issue #972,
  * workstream 15).
@@ -263,6 +264,9 @@ export interface OxyGenerationReceipt {
     readonly settledAt: string;
 }
 
+/** The endpoint returns either a customer receipt or internal technical usage. */
+export type OxyGenerationRecord = OxyGenerationReceipt | MeteredGeneration;
+
 /**
  * Anything the inference API refused.
  *
@@ -688,12 +692,38 @@ export class OxyInferenceClient {
      */
     async getGeneration(
         id: string,
-        options: { signal?: AbortSignal } = {},
+        options: { signal?: AbortSignal; delegatedUserId?: string } = {},
     ): Promise<OxyGenerationReceipt> {
-        const body = await this.#request<{ data: OxyGenerationReceipt }>(
-            'GET',
-            `/v1/generations/${encodeURIComponent(id)}`,
-            { ...(options.signal === undefined ? {} : { signal: options.signal }) },
+        const record = await this.getGenerationRecord(id, options);
+        if (record.schemaVersion !== 1) {
+            throw new OxyInferenceProtocolError('Internal usage has no financial receipt. Use getGenerationRecord().', record.requestId);
+        }
+        return record;
+    }
+
+    /** Read a financial receipt (v1) or an internal technical record (v2). */
+    async getGenerationRecord(
+        id: string,
+        options: { signal?: AbortSignal; delegatedUserId?: string } = {},
+    ): Promise<OxyGenerationRecord> {
+        const body = await this.#request<{ data: OxyGenerationRecord }>(
+            'GET', `/v1/generations/${encodeURIComponent(id)}`, options,
+        );
+        return body.data;
+    }
+
+    /**
+     * Recover the existing record using the original credential and key. This
+     * performs only GET; 404 is unknown/pending, never proof of zero cost and
+     * never an instruction to repeat decide(). Lost answers are not retained.
+     */
+    async getGenerationRecordByIdempotencyKey(
+        key: string,
+        options: { signal?: AbortSignal; delegatedUserId?: string } = {},
+    ): Promise<OxyGenerationRecord> {
+        if (key.length === 0 || key.length > 128) throw new Error('Invalid original idempotency key.');
+        const body = await this.#request<{ data: OxyGenerationRecord }>(
+            'GET', '/v1/generations/by-idempotency-key', { ...options, idempotencyKey: key },
         );
         return body.data;
     }

package/src/inference/index.ts

@@ -22,6 +22,7 @@ export {
 } from './OxyInferenceClient';
 export type {
   OxyGenerationReceipt,
+  OxyGenerationRecord,
   OxyInferenceClientOptions,
   OxyInferenceCredential,
   OxyInferenceFetch,

package/src/server/OxyServer.ts

@@ -26,6 +26,17 @@
  * Node only.
  */
 import { jwtDecode } from 'jwt-decode';
+import { hasBoundedServiceTokenLifetime } from './serviceTokenLifetime';
+
+/** Unverified cache metadata only: an old lifetime forces a new signed mint. */
+function reusableServiceToken(token: string): boolean {
+  try {
+    const claims = jwtDecode<{ iat?: number; exp?: number }>(token);
+    return hasBoundedServiceTokenLifetime(claims) && typeof claims.exp === 'number'
+      && claims.exp > Math.floor(Date.now() / 1000);
+  } catch { return false; }
+}
+
 import { loadNodeCrypto } from '@oxy.so/protocol';
 import { OxyServices, type OxyConfig } from '../OxyServices';
 import type { HttpMethod, ServiceLane } from '../client/context';
@@ -87,6 +98,21 @@ export interface OxyServerConfig extends OxyConfig {
 export const ANONYMOUS_SERVICE_TOKEN_RETRY_MS = 30_000;
 
 /** `POST /auth/service-token`. */
+export interface ActingAsVerificationOptions {
+  /** Only explicit read-only callers may reuse authority; effects always pass false. */
+  cache?: boolean;
+  /** Taken from verified service claims by middleware, never from a user header. */
+  credentialId?: string;
+  ownerAccountId?: string;
+  environment?: string;
+}
+
+interface ActingAsGeneration {
+  epoch: bigint;
+  issued: number;
+  completed: number;
+}
+
 export interface ServiceTokenResponse {
   token: string;
   expiresIn: number;
@@ -127,10 +153,10 @@ const TOKEN_REUSE_MARGIN_MS = 60_000;
 
 /** Bound on remembered `appId:userId` delegation answers. */
 const ACTING_AS_CACHE_MAX = 1000;
-/** A positive grant is reused for 5 minutes — the revocation latency window. */
-const ACTING_AS_GRANT_TTL_MS = 5 * 60 * 1000;
-/** A negative answer (or a failed lookup) is reused for 1 minute. */
-const ACTING_AS_DENIAL_TTL_MS = 60 * 1000;
+/** Explicit read reuse only; effects always perform a fresh lookup. */
+const ACTING_AS_GRANT_TTL_MS = 60_000;
+/** Explicit authoritative read denials last ten seconds; failures are never cached. */
+const ACTING_AS_DENIAL_TTL_MS = 10_000;
 
 export class OxyServer extends OxyServices {
   private readonly serviceTokens = new Map<string, ServiceTokenCacheEntry>();
@@ -138,6 +164,7 @@ export class OxyServer extends OxyServices {
   private serviceApiSecret: string | null = null;
   private readonly actingAs = new Map<string, { result: ServiceActingAsVerification | null; expiresAt: number }>();
   private readonly actingAsPending = new Map<string, Promise<ServiceActingAsVerification | null>>();
+  private readonly actingAsGenerations = new Map<string, ActingAsGeneration>();
   /** Public keys only; never private material. */
   private readonly jwksCache: ServiceTokenJwksCache = { keys: new Map(), expiresAt: 0, lastAttemptAt: 0 };
   /**
@@ -180,7 +207,7 @@ export class OxyServer extends OxyServices {
       },
       jwksCache: this.jwksCache,
       validateSession: (sessionId, options) => this.session.validate(sessionId, options),
-      verifyActingAs: (appId, userId) => this.verifyActingAs(appId, userId),
+      verifyActingAs: (appId, userId, options) => this.verifyActingAs(appId, userId, options),
     });
   }
 
@@ -277,7 +304,7 @@ export class OxyServer extends OxyServices {
         });
         throw new ServiceCredentialMismatchError();
       }
-      if (entry.token && entry.expiresAt > now + TOKEN_REUSE_MARGIN_MS) {
+      if (entry.token && reusableServiceToken(entry.token) && entry.expiresAt > now + TOKEN_REUSE_MARGIN_MS) {
         return entry.token;
       }
       if (entry.pending) {
@@ -344,32 +371,45 @@ export class OxyServer extends OxyServices {
   // ── Delegation and account events ────────────────────────────────────────
 
   /**
-   * Whether service app `appId` holds an active delegation grant to act for
-   * `userId`; the grant's scopes, or `null`. Used by `middleware.auth()` for
-   * `X-Oxy-User-Id`.
-   *
-   * Answers are cached per `appId:userId` (a grant for 5 minutes — the
-   * revocation window; a denial or failed lookup for 1 minute), bounded to the
-   * 1000 most recent pairs, and concurrent lookups of one pair share a single
-   * request.
+   * Resolve authority live by default. Explicit read-only reuse lasts at most
+   * 60s positive / 10s negative, anchored to request start; errors never cache.
+   * Effects do not share an older in-flight read. Durable epoch plus local
+   * completion ordering prevents ABA and late positive replies overwriting a
+   * newer refusal even when app/credential revocation leaves epoch unchanged.
    */
-  async verifyActingAs(appId: string, userId: string): Promise<ServiceActingAsVerification | null> {
-    const cacheKey = `${appId}:${userId}`;
-    const cached = this.actingAs.get(cacheKey);
-    if (cached && cached.expiresAt > Date.now()) {
-      // Refresh recency for the LRU bound.
-      this.actingAs.delete(cacheKey);
-      this.actingAs.set(cacheKey, cached);
-      return cached.result;
-    }
-    const inflight = this.actingAsPending.get(cacheKey);
-    if (inflight) return inflight;
-
-    const lookup = this.lookupActingAs(appId, userId).finally(() => {
-      this.actingAsPending.delete(cacheKey);
-    });
+  async verifyActingAs(
+    appId: string, userId: string, options: ActingAsVerificationOptions = {},
+  ): Promise<ServiceActingAsVerification | null> {
+    const pair = JSON.stringify([appId, userId]);
+    const cacheKey = JSON.stringify([appId, userId, options.credentialId, options.ownerAccountId, options.environment]);
+    if (options.cache === true) {
+      const cached = this.actingAs.get(cacheKey);
+      if (cached && cached.expiresAt > Date.now()) {
+        this.actingAs.delete(cacheKey);
+        this.actingAs.set(cacheKey, cached);
+        return cached.result;
+      }
+      const pending = this.actingAsPending.get(cacheKey);
+      if (pending) return pending;
+    }
+    let generation = this.actingAsGenerations.get(pair);
+    if (!generation) {
+      generation = { epoch: 0n, issued: 0, completed: 0 };
+      this.actingAsGenerations.set(pair, generation);
+      if (this.actingAsGenerations.size > ACTING_AS_CACHE_MAX) {
+        const oldest = this.actingAsGenerations.keys().next().value;
+        if (oldest !== undefined) this.actingAsGenerations.delete(oldest);
+      }
+    }
+    const serial = ++generation.issued;
+    const startedAt = Date.now();
+    const lookup = this.lookupActingAs(appId, userId, options, pair, cacheKey, generation, serial, startedAt);
+    if (options.cache !== true) return lookup;
     this.actingAsPending.set(cacheKey, lookup);
-    return lookup;
+    try { return await lookup; }
+    finally {
+      if (this.actingAsPending.get(cacheKey) === lookup) this.actingAsPending.delete(cacheKey);
+    }
   }
 
   /**
@@ -457,7 +497,7 @@ export class OxyServer extends OxyServices {
   /** A token obtained by attestation, cached like a credential's (one identity per process). */
   private async workloadServiceToken(): Promise<string> {
     const entry = this.serviceTokens.get(WORKLOAD_CACHE_KEY);
-    if (entry?.token && entry.expiresAt > Date.now() + TOKEN_REUSE_MARGIN_MS) return entry.token;
+    if (entry?.token && reusableServiceToken(entry.token) && entry.expiresAt > Date.now() + TOKEN_REUSE_MARGIN_MS) return entry.token;
     if (entry?.pending) return entry.pending;
 
     const seeded = entry ?? { token: '', expiresAt: 0, secretBuf: Buffer.alloc(0), pending: null, apiKey: WORKLOAD_CACHE_KEY };
@@ -486,41 +526,62 @@ export class OxyServer extends OxyServices {
     }
   }
 
-  private async lookupActingAs(appId: string, userId: string): Promise<ServiceActingAsVerification | null> {
+  private async lookupActingAs(
+    appId: string, userId: string, options: ActingAsVerificationOptions,
+    pair: string, cacheKey: string, generation: ActingAsGeneration, serial: number, startedAt: number,
+  ): Promise<ServiceActingAsVerification | null> {
     try {
-      // The verify endpoint admits only a platform-trusted caller, so this
-      // carries the VERIFIER's own service token. No retry and a short timeout:
-      // it runs inside request-handling middleware, and a retry loop would
-      // multiply the latency of every delegated request. A verifier with no
-      // credential throws here and is refused below — a host that cannot prove
-      // who it is has no business learning who delegated to whom.
       const serviceToken = await this.serviceToken();
       const result = await this.request<ServiceActingAsVerification>(
-        'GET',
-        '/internal/service-acting-as/verify',
-        { appId, userId },
+        'GET', '/internal/service-acting-as/verify',
+        { appId, userId, ...(options.credentialId ? { credentialId: options.credentialId,
+          ownerAccountId: options.ownerAccountId, environment: options.environment } : {}) },
         { cache: false, retry: false, timeout: 5000, headers: { Authorization: `Bearer ${serviceToken}` } },
       );
-      const verified: ServiceActingAsVerification | null = result?.authorized
-        ? { authorized: true, scopes: Array.isArray(result.scopes) ? result.scopes : [] }
-        : null;
-      this.rememberActingAs(`${appId}:${userId}`, verified, ACTING_AS_GRANT_TTL_MS);
+      // A deadline bounds how long an already old response can authorize. It
+      // is not by itself a measurement of end-to-end revocation latency.
+      if (this.actingAsGenerations.get(pair) !== generation || serial < generation.completed) return null;
+      generation.completed = serial;
+      this.clearActingAsPair(appId, userId);
+      if (Date.now() - startedAt >= 5000) return null;
+      const rawEpoch = result?.epoch;
+      if (typeof rawEpoch !== 'string' || !/^(?:0|[1-9][0-9]{0,18})$/.test(rawEpoch)) return null;
+      const epoch = BigInt(rawEpoch);
+      if (epoch > 9223372036854775807n) return null;
+      if (typeof result.authorized !== 'boolean' || !Array.isArray(result.scopes)
+        || !result.scopes.every((scope) => typeof scope === 'string' && scope.length > 0 && scope.trim() === scope)
+        || new Set(result.scopes).size !== result.scopes.length
+        || (!result.authorized && result.scopes.length !== 0)) return null;
+      const older = epoch < generation.epoch;
+      if (epoch > generation.epoch) generation.epoch = epoch;
+      if (result.authorized && older) return null;
+      const verified: ServiceActingAsVerification | null = result.authorized === true
+        ? { authorized: true, scopes: result.scopes, epoch: rawEpoch } : null;
+      if (options.cache === true) this.rememberActingAs(cacheKey, verified,
+        startedAt + (verified ? ACTING_AS_GRANT_TTL_MS : ACTING_AS_DENIAL_TTL_MS));
       return verified;
     } catch (error) {
-      logger.warn('[oxy.auth] verifyActingAs lookup failed — caching negative result', {
-        component: 'auth',
-        method: 'verifyActingAs',
-        appId,
-        userId,
+      if (this.actingAsGenerations.get(pair) === generation && serial >= generation.completed) {
+        generation.completed = serial;
+        this.clearActingAsPair(appId, userId);
+      }
+      logger.warn('[oxy.auth] verifyActingAs lookup failed — not cached', {
+        component: 'auth', method: 'verifyActingAs', appId, userId,
       }, error);
-      this.rememberActingAs(`${appId}:${userId}`, null, ACTING_AS_DENIAL_TTL_MS);
       return null;
     }
   }
 
-  private rememberActingAs(cacheKey: string, result: ServiceActingAsVerification | null, ttlMs: number): void {
+  private clearActingAsPair(appId: string, userId: string): void {
+    for (const key of this.actingAs.keys()) {
+      const [cachedApp, cachedUser] = JSON.parse(key) as [string, string];
+      if (cachedApp === appId && cachedUser === userId) this.actingAs.delete(key);
+    }
+  }
+
+  private rememberActingAs(cacheKey: string, result: ServiceActingAsVerification | null, expiresAt: number): void {
     this.actingAs.delete(cacheKey);
-    this.actingAs.set(cacheKey, { result, expiresAt: Date.now() + ttlMs });
+    this.actingAs.set(cacheKey, { result, expiresAt });
     if (this.actingAs.size > ACTING_AS_CACHE_MAX) {
       const oldest = this.actingAs.keys().next().value;
       if (oldest !== undefined) this.actingAs.delete(oldest);

package/src/server/agentAccount.ts

@@ -0,0 +1,28 @@
+/** Autonomous entry helper. The signer owns its private key (for example in a KMS). */
+import { buildAgentProofMessage, type LoginResult } from '@oxy.so/contracts';
+import { normalizeSecp256k1PublicKey } from '@oxy.so/protocol/secp256k1';
+import type { OxyServices } from '../OxyServices';
+
+export interface AgentAccountSigner {
+  /** Compressed or uncompressed SEC1 secp256k1 public key; no private-key field exists. */
+  publicKey: string;
+  signMessage(message: string): Promise<string>;
+}
+
+/** Explicit sign-in; no timer, automatic escalation or service credential lane. */
+export async function signInAgentAccount(options: {
+  client: Pick<OxyServices, 'auth'>;
+  accountId: string;
+  signer: AgentAccountSigner;
+}): Promise<LoginResult> {
+  const { client, accountId, signer } = options;
+  const publicKey = normalizeSecp256k1PublicKey(signer.publicKey.trim());
+  const claims = await client.auth.agent.requestChallenge(publicKey);
+  const timestamp = Date.now();
+  if (claims.action !== 'agent_signin' || claims.accountId !== accountId || claims.actorId !== accountId
+    || normalizeSecp256k1PublicKey(claims.publicKey) !== publicKey || !claims.authMethodId || claims.expiresAt <= timestamp) {
+    throw new Error('Agent challenge does not match this account and signer');
+  }
+  const signature = await signer.signMessage(buildAgentProofMessage(claims, timestamp));
+  return client.auth.agent.verify(publicKey, { challenge: claims.challenge, timestamp, signature });
+}