@oxy.so/core 4.0.0 → 4.2.0

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 });
+}

package/src/server/auth.ts

@@ -1,5 +1,6 @@
 import type { NextFunction, Request, RequestHandler, Response } from 'express';
 import type { AuthMiddlewareOptions, OxyAuthRefusal, OxyMiddleware } from './middleware';
+import type { AccountActorChain } from '@oxy.so/contracts';
 import { logger } from '../logger';
 import { OXY_SERVICE_ENVIRONMENTS, type OxyServiceEnvironment } from '../utils/oxyServiceEnvironment';
 
@@ -43,6 +44,12 @@ export interface OxyAuthRequest extends Request {
   sessionId?: string | null;
   serviceApp?: OxyServiceAppContext;
   serviceActingAs?: OxyServiceActingAsContext;
+  /**
+   * Who acted, and as whom, on a USER session — read off the session row by the
+   * Oxy API, never off a header. `null`/absent when the request is not a user
+   * session or the API did not report it. Read it with {@link getOxyActor}.
+   */
+  oxyActor?: AccountActorChain | null;
   /**
    * Why the presented credential was refused, when one was and the request
    * still reached the handler (the optional path). Read it with
@@ -95,6 +102,24 @@ export function getOxyUserId(req: Request): string | null {
   );
 }
 
+/**
+ * Who acted, and as whom, on this user session (issue #1520), or `null` when
+ * the session authority did not report it.
+ *
+ * An audit records `actorAccountId` as the actor and `effectiveAccountId`
+ * (equal to {@link getOxyUserId}) as the account spoken as. A bot acting with
+ * nobody operating it is its own actor; a person acting as an organization or
+ * a bot is the actor of a `delegated` chain. Never substitute the effective
+ * account's owner for either: when this is `null`, record the actor as unknown.
+ */
+export function getOxyActor(req: Request): AccountActorChain | null {
+  const actor = (req as OxyAuthRequest).oxyActor;
+  if (!actor) return null;
+  // Defence in depth: a chain that does not describe the authenticated
+  // subject is not this request's chain.
+  return actor.effectiveAccountId === getOxyUserId(req) ? actor : null;
+}
+
 export function isOxyAuthenticated(req: Request): req is OxyAuthenticatedRequest {
   return getOxyUserId(req) !== null;
 }

package/src/server/capabilityTicket.ts

@@ -7,7 +7,6 @@ import {
 import {
   capabilityTicketClaimsSchema,
   type CapabilityTicketClaims,
-  type GrantLimit,
   type PolicyDecision,
 } from '@oxy.so/contracts';
 import type { NextFunction, Request, RequestHandler, Response } from 'express';
@@ -74,47 +73,6 @@ function decodeJsonSegment(segment: string): unknown {
   }
 }
 
-function valuesAtPath(input: Record<string, unknown>, path: string): unknown[] {
-  let current: unknown[] = [input];
-  for (const segment of path.split('.')) {
-    const next: unknown[] = [];
-    for (const value of current) {
-      const records = Array.isArray(value) ? value : [value];
-      for (const record of records) {
-        if (typeof record !== 'object' || record === null || Array.isArray(record)) continue;
-        if (Object.prototype.hasOwnProperty.call(record, segment)) {
-          next.push((record as Record<string, unknown>)[segment]);
-        }
-      }
-    }
-    if (next.length === 0) return [];
-    current = next;
-  }
-  return current.flatMap((value) => Array.isArray(value) ? value : [value]);
-}
-
-/** Enforces the signed per-action bounds before a domain handler runs. */
-export function inputSatisfiesCapabilityLimits(
-  tool: string,
-  input: Record<string, unknown>,
-  limits: readonly GrantLimit[],
-): boolean {
-  for (const limit of limits) {
-    if (limit.tool !== tool) return false;
-    const actualValues = valuesAtPath(input, limit.key);
-    if (actualValues.length === 0) return false;
-    if (typeof limit.value === 'number') {
-      const maximum = limit.value;
-      if (!actualValues.every((actual) => (
-        typeof actual === 'number' && Number.isFinite(actual) && actual <= maximum
-      ))) return false;
-      continue;
-    }
-    if (!actualValues.every((actual) => actual === limit.value)) return false;
-  }
-  return true;
-}
-
 export function issueCapabilityTicket(
   claims: UnsignedCapabilityTicketClaims,
   options: CapabilityTicketSigningOptions,
@@ -256,3 +214,5 @@ export function createCapabilityTicketMiddleware(
     }
   };
 }
+
+export { inputSatisfiesCapabilityLimits } from '@oxy.so/contracts';

package/src/server/index.ts

@@ -26,6 +26,12 @@ export {
   ServerNotificationsApi,
   ServerReputationApi,
 } from './namespaces';
+export type {
+  CapabilityTicketGrant,
+  CapabilityTicketIntrospection,
+  CreateExecutionAuthorizationInput,
+  ServiceCapabilityCatalog,
+} from './namespaces';
 export { OxyAccountEventError, OXY_ACCOUNT_DELETED_EVENT_URI } from './middleware';
 export type {
   AuthMiddlewareOptions,
@@ -40,6 +46,7 @@ export type {
 export {
   createOptionalOxyAuth,
   createOxyAuthMiddleware,
+  getOxyActor,
   getOxyAuthRefusal,
   getOxyBillingPrincipal,
   getOxyDelegatedUserId,
@@ -163,6 +170,8 @@ export type {
 
 // Constant-time secret comparison.
 export { verifySecret } from './verifySecret';
+export { createLiveCapabilityTicketVerifier } from './liveCapabilityTicket';
+export type { LiveCapabilityTicketVerifierOptions } from './liveCapabilityTicket';
 
 // Cross-service user-invalidation signal: oxy-api publishes when identity
 // changes, every consuming backend sweeps its caches instead of waiting out a TTL.
@@ -200,3 +209,7 @@ export { observeNodeHttp, withoutNodeHttpObservation } from './trafficNodeHttp';
  */
 export { canAttestWorkloadIdentity, requestWorkloadServiceToken } from './workloadIdentity';
 export type { WorkloadServiceToken, WorkloadServiceTokenOptions } from './workloadIdentity';
+
+export { OXY_SERVICE_TOKEN_MAX_LIFETIME_SECONDS, hasBoundedServiceTokenLifetime } from './serviceTokenLifetime';
+export { signInAgentAccount } from './agentAccount';
+export type { AgentAccountSigner } from './agentAccount';

package/src/server/liveCapabilityTicket.ts

@@ -0,0 +1,47 @@
+import { canonicalCapabilityJson, capabilityTicketClaimsSchema, type CapabilityTicketClaims } from '@oxy.so/contracts';
+import { verifyCapabilityTicket, type CapabilityTicketVerificationOptions } from './capabilityTicket';
+import type { CapabilityTicketIntrospection } from './namespaces';
+
+export interface LiveCapabilityTicketVerifierOptions extends CapabilityTicketVerificationOptions {
+  issuer: string;
+  introspect: (ticket: string, options: { signal: AbortSignal }) => Promise<CapabilityTicketIntrospection>;
+  /** Network bound only; does not establish an authority freshness policy. */
+  timeoutMs?: number;
+}
+
+/** Local signature + live receiving-service introspection; no cache or retry. */
+export function createLiveCapabilityTicketVerifier(options: LiveCapabilityTicketVerifierOptions) {
+  if (typeof options.issuer !== 'string' || options.issuer.trim() === '') throw new Error('A trusted Capability issuer is required');
+  const timeoutMs = options.timeoutMs ?? 5000;
+  if (!Number.isInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 60000) {
+    throw new Error('Capability introspection timeout must be between 1 and 60000ms');
+  }
+  return async (ticket: string, input: { signal?: AbortSignal } = {}): Promise<CapabilityTicketClaims> => {
+    input.signal?.throwIfAborted();
+    const signed = verifyCapabilityTicket(ticket, options);
+    if (!signed.catalog) throw new Error('Internal MCP requires a signed catalogue binding');
+    const controller = new AbortController();
+    const abort = () => controller.abort(input.signal?.reason);
+    input.signal?.addEventListener('abort', abort, { once: true });
+    const timer = setTimeout(() => controller.abort(new Error('Capability introspection timed out')), timeoutMs);
+    let rejectAbort: (() => void) | undefined;
+    try {
+      const interrupted = new Promise<never>((_resolve, reject) => {
+        rejectAbort = () => reject(controller.signal.reason ?? new Error('Capability introspection aborted'));
+        controller.signal.addEventListener('abort', rejectAbort, { once: true });
+        if (controller.signal.aborted) rejectAbort();
+      });
+      const result = await Promise.race([options.introspect(ticket, { signal: controller.signal }), interrupted]);
+      controller.signal.throwIfAborted();
+      if (result.active !== true) throw new Error('Capability ticket is inactive');
+      const live = capabilityTicketClaimsSchema.parse(result.claims);
+      if (canonicalCapabilityJson(live) !== canonicalCapabilityJson(signed)) throw new Error('Capability introspection claims mismatch');
+      // An authority response delayed past expiry cannot extend the signed grant.
+      return verifyCapabilityTicket(ticket, options);
+    } finally {
+      clearTimeout(timer);
+      input.signal?.removeEventListener('abort', abort);
+      if (rejectAbort) controller.signal.removeEventListener('abort', rejectAbort);
+    }
+  };
+}

package/src/server/middleware.ts

@@ -1,3 +1,4 @@
+import { hasBoundedServiceTokenLifetime } from './serviceTokenLifetime';
 /**
  * The Express and Socket.IO middleware `OxyServer` mounts
  * (`server.middleware.auth()`, `.socket()`, `.service()`, `.requireScope()`),
@@ -6,6 +7,7 @@
  * Node only; reachable solely from `@oxy.so/core/server`.
  */
 import type { OxyRequestUser } from './auth';
+import { accountActorChainSchema, type AccountActorChain } from '@oxy.so/contracts';
 import { jwtDecode } from 'jwt-decode';
 import type { JsonWebKey } from 'node:crypto';
 import type { ApiError, User } from '../models/interfaces';
@@ -54,6 +56,8 @@ interface JwtPayload {
  * authoritative store stays server-side.
  */
 export interface ServiceActingAsVerification {
+  /** Decimal durable generation, never lossy JS number. */
+  epoch?: string;
   authorized: boolean;
   scopes: string[];
 }
@@ -148,11 +152,10 @@ export interface ServiceApp {
   appName: string;
   scopes: string[];
   /**
-   * `internal` when the caller is one of Oxy's own applications: app to app it
-   * is trusted outright — {@link requireScope} passes and it may act for a user
-   * without a delegation grant. `external` keeps every scope and grant rule.
-   * What the USER may do (their accounts, plan, limits) is still for the
-   * receiving service to decide. A token without the claim reads as `external`.
+   * Classification only. Both tiers obey scope ceilings and live offline
+   * delegation; neither a brand nor a header proves a user's authority.
+   * Resource authorization remains with the receiving service. A missing
+   * claim reads as external.
    */
   tier: 'internal' | 'external';
   /** The credentialId of the specific service credential that minted this token. */
@@ -299,8 +302,10 @@ export interface OxyMiddlewareHost {
   validateSession(
     sessionId: string,
     options?: { deviceFingerprint?: string; useHeaderValidation?: boolean },
-  ): Promise<{ valid: boolean; user?: User } | null>;
-  verifyActingAs(appId: string, userId: string): Promise<ServiceActingAsVerification | null>;
+  ): Promise<{ valid: boolean; user?: User; actor?: unknown } | null>;
+  verifyActingAs(appId: string, userId: string, options?: {
+    cache?: boolean; credentialId?: string; ownerAccountId?: string; environment?: string;
+  }): Promise<ServiceActingAsVerification | null>;
 }
 
 /** Build the middleware set for one server. See `OxyServer.middleware`. */
@@ -680,21 +685,18 @@ export function createOxyMiddleware(host: OxyMiddlewareHost) {
             return res.status(401).json(error);
           }
 
-          // One of Oxy's own applications acts for a user without a grant:
-          // inside the ecosystem that is trust, not consent. It still acts
-          // with the USER's authority only — what that user may do is for the
-          // receiving service to check.
-          if (oxyUserId && tier === 'internal') {
-            req.userId = oxyUserId;
-            req.user = { id: oxyUserId };
-            req.serviceActingAs = { userId: oxyUserId, scopes: [] };
-          } else if (oxyUserId) {
-            // C3: an EXTERNAL service may only act as a user when an explicit
+          // A service credential plus a user header is never a present user
+          // session, even for an internal tier. Offline delegation is explicit.
+          if (oxyUserId) {
+            // C3: every service may only act as a user when an explicit
             // ServiceActingAs grant exists for that (appId, userId) pair.
             // Without the grant we MUST refuse — silently attaching
             // `req.userId = oxyUserId` would let any service impersonate
             // any user simply by setting the header.
-            const grant = await host.verifyActingAs(appId, oxyUserId);
+            const grant = await host.verifyActingAs(appId, oxyUserId, {
+              cache: false, credentialId: decoded.credentialId as string,
+              ownerAccountId: decoded.ownerAccountId as string, environment: decoded.environment as string,
+            });
             if (!grant || !grant.authorized) {
               logger.warn('[oxy.auth] Service token rejected — no delegation grant', {
                 component: 'auth',
@@ -925,7 +927,44 @@ export function createOxyMiddleware(host: OxyMiddlewareHost) {
             return res.status(401).json(error);
           }
 
+          // Who acted, and as whom — from the session authority's answer
+          // (#1520), never from a header or this undecoded token. An API that
+          // predates the field answers without it, and that is `null` here:
+          // "not reported", never a guess that the subject acted for itself.
+          // A chain naming a DIFFERENT effective account than the session
+          // resolved to has no benign cause and is refused like a user
+          // mismatch.
+          const actor = readActorChain(validationResult.actor);
+          if (actor === 'invalid' || (actor && actor.effectiveAccountId !== validatedUserId)) {
+            logger.warn('[oxy.auth] Session rejected — actor chain does not describe the session', {
+              component: 'auth',
+              method: 'auth',
+              validatedUserId,
+            });
+            recordRefusal(req, {
+              code: 'SESSION_ACTOR_MISMATCH',
+              stage: 'session',
+              reason: 'Session actor chain does not describe the validated session',
+              status: 401,
+            });
+            if (optional) {
+              req.userId = null;
+              req.user = null;
+              return next();
+            }
+
+            const error = {
+              error: 'SESSION_ACTOR_MISMATCH',
+              message: 'Session actor does not match the session',
+              code: 'SESSION_ACTOR_MISMATCH',
+              status: 401
+            };
+            if (onError) return onError(error);
+            return res.status(401).json(error);
+          }
+
           req.userId = validatedUserId;
+          req.oxyActor = actor;
           req.accessToken = token;
           req.sessionId = sessionId;
           // Session validation already returned the full user, so `loadUser`
@@ -1216,13 +1255,6 @@ export function createOxyMiddleware(host: OxyMiddlewareHost) {
         return;
       }
 
-      // Oxy's own applications are trusted app to app; scopes are the
-      // external lane.
-      if (req.serviceApp.tier === 'internal') {
-        next();
-        return;
-      }
-
       const appHasScope = appScopes.includes(scope);
       const delegationHasScope = delegatedScopes.includes(scope);
       const hasRequiredScope = req.serviceActingAs
@@ -1468,6 +1500,9 @@ function verifyServiceTokenClaims(
   decoded: JwtPayload,
   expected: { audience: string; issuer: string },
 ): void {
+  if (!hasBoundedServiceTokenLifetime(decoded)) {
+    throw new ServiceTokenClaimError('Service token lifetime must be positive and at most 300 seconds');
+  }
   if (decoded.type !== 'service') {
     throw new ServiceTokenClaimError(`Service token has unexpected type '${String(decoded.type)}'`);
   }
@@ -1484,6 +1519,17 @@ function verifyServiceTokenClaims(
   }
 }
 
+/**
+ * Parse the session authority's actor chain. `null` when the API did not send
+ * one; `'invalid'` when it sent something that is not a chain, which the caller
+ * refuses rather than ignores.
+ */
+function readActorChain(raw: unknown): AccountActorChain | null | 'invalid' {
+  if (raw === undefined || raw === null) return null;
+  const parsed = accountActorChainSchema.safeParse(raw);
+  return parsed.success ? parsed.data : 'invalid';
+}
+
 // ---------------------------------------------------------------------------
 // Local request/response/socket typing
 //
@@ -1506,6 +1552,7 @@ interface AuthReq {
   sessionId?: string | null;
   serviceApp?: ServiceApp;
   serviceActingAs?: { userId: string; scopes: string[] };
+  oxyActor?: AccountActorChain | null;
   oxyAuthRefusal?: OxyAuthRefusal;
 }