@oxy.so/core 4.1.0 → 4.2.0

package/dist/esm/api/accounts.js

@@ -1,3 +1,23 @@
+/**
+ * `oxy.accounts` — the unified account graph (`/accounts`).
+ *
+ * An account is a relational, tree-structured principal (the `User` document
+ * generalised): a `personal` account is a human login at the root of its tree;
+ * `organization` / `project` / `bot` / `channel` accounts are non-login
+ * principals operated through membership. Accounts form a tree
+ * (`parentAccountId`) and expose a single membership model (`AccountMember`)
+ * with a unified role set and an explicit-but-inheritable cascade down the
+ * subtree. The applications an account owns are `oxy.apps`.
+ *
+ * Reference accounts by their `_id` (`accountId`, the underlying `User._id`)
+ * and members by their member `_id` — never by name, slug, or handle.
+ *
+ * SWITCHING INTO AN ACCOUNT: `accounts.actAs(accountId)` mints a REAL
+ * session for the target account and plants it as the active session — there is
+ * no per-request "acting-as" header. Identity is carried by the session/token,
+ * so a switch propagates through reload and cross-domain exactly like a login.
+ */
+import { agentKeyOperationSchema, executeAgentKeyOperationSchema, agentKeyOperationChallengeSchema, agentKeyOperationResultSchema, agentKeyListResponseSchema } from '@oxy.so/contracts';
 import { normalizeUserIdentity } from '../utils/userIdentity.js';
 import { evictOxyIdentityCache } from '../utils/identityCacheSweep.js';
 import { evictOxyAccountForestCache, oxyAccountDetailCacheKey, OXY_ACCOUNT_PER_ACCOUNT_CACHE_PREFIX, } from '../utils/accountCacheSweep.js';
@@ -67,10 +87,28 @@ export class AccountMembersApi {
         return result;
     }
 }
+/** Current account governors and autonomous rotation use action-bound proofs. */
+export class AccountAgentKeysApi {
+    constructor(ctx) {
+        this.ctx = ctx;
+    }
+    async list(accountId) {
+        return agentKeyListResponseSchema.parse(await this.ctx.request('GET', `/accounts/${enc(accountId)}/agent-keys`, undefined, { cache: false }));
+    }
+    async requestChallenge(accountId, operation) {
+        const response = await this.ctx.request('POST', `/accounts/${enc(accountId)}/agent-keys/challenge`, agentKeyOperationSchema.parse(operation), { cache: false });
+        return agentKeyOperationChallengeSchema.parse(response);
+    }
+    async execute(accountId, operation, proof) {
+        const response = await this.ctx.request('POST', `/accounts/${enc(accountId)}/agent-keys/execute`, executeAgentKeyOperationSchema.parse({ operation, proof }), { cache: false });
+        return agentKeyOperationResultSchema.parse(response);
+    }
+}
 export class AccountsApi {
     constructor(ctx) {
         this.ctx = ctx;
         this.members = new AccountMembersApi(ctx);
+        this.agentKeys = new AccountAgentKeysApi(ctx);
     }
     /**
      * List the accounts the caller can access: their own personal (root)

package/dist/esm/api/apps.js

@@ -167,10 +167,10 @@ export class AppsApi {
      * consent, authorize, and device-flow approval screens before any session
      * exists.
      */
-    async getPublic(clientId) {
+    async getPublic(clientId, options = {}) {
         const res = await this.ctx.request('GET', `/auth/oauth/client/${enc(clientId)}`, undefined, 
         // Public client metadata (pre-session consent UI) — skip the bearer preflight.
-        { cache: true, cacheTTL: MEDIUM_TTL, skipAuth: true });
+        { cache: options.cache ?? true, cacheTTL: MEDIUM_TTL, skipAuth: true });
         return res.application;
     }
     /**

package/dist/esm/api/auth.js

@@ -1,4 +1,4 @@
-import { emailSignInLinkResponseSchema, emailSignInPendingSchema, emailSignInStartResponseSchema, emailVerificationConfirmResponseSchema, emailVerificationStartResponseSchema, loginResultSchema, safeParseContract, secondFactorRequiredSchema, signInMethodsSchema, totpBackupCodesResponseSchema, totpEnrollResponseSchema, } from '@oxy.so/contracts';
+import { agentProofClaimsSchema, agentChallengeRequestSchema, agentVerifyRequestSchema, emailSignInLinkResponseSchema, emailSignInPendingSchema, emailSignInStartResponseSchema, emailVerificationConfirmResponseSchema, emailVerificationStartResponseSchema, loginResultSchema, safeParseContract, secondFactorRequiredSchema, signInMethodsSchema, totpBackupCodesResponseSchema, totpEnrollResponseSchema, } from '@oxy.so/contracts';
 import { OxyAuthenticationError } from '../OxyServices.errors.js';
 import { logger } from '../logger/index.js';
 import { normalizeUserIdentity } from '../utils/userIdentity.js';
@@ -264,7 +264,8 @@ export class AuthOAuthApi {
      * out, so the app can run the OAuth flow again. It never degrades into a
      * session that looks alive and cannot refresh.
      */
-    async exchangeCode(params) {
+    /** `plantTokens: false` defers bearer installation to a validated provider commit. */
+    async exchangeCode(params, options = {}) {
         const form = new URLSearchParams({
             grant_type: 'authorization_code',
             code: params.code,
@@ -295,7 +296,9 @@ export class AuthOAuthApi {
         }
         const expiresInSec = typeof record.expires_in === 'number' ? record.expires_in : DEFAULT_ACCESS_TOKEN_TTL_SECONDS;
         const expiresAt = new Date(Date.now() + expiresInSec * 1000).toISOString();
-        if (accessToken) {
+        // Provider completion validates the expected subject before committing.
+        // Direct callers retain the historical token-planting default.
+        if (accessToken && options.plantTokens !== false) {
             this.ctx.oxy.session.setAccessToken(accessToken);
         }
         if (!deviceId || !deviceSecret) {
@@ -642,6 +645,22 @@ export class AuthCommonsApi {
         { cache: false, skipAuth: true });
     }
 }
+/** Bot entry uses caller-owned keys and the normal account session lane. */
+export class AuthAgentApi {
+    constructor(ctx) {
+        this.ctx = ctx;
+    }
+    async requestChallenge(publicKey) {
+        const body = agentChallengeRequestSchema.parse({ publicKey });
+        const response = await this.ctx.request('POST', '/auth/agent/challenge', body, { cache: false, skipAuth: true });
+        return agentProofClaimsSchema.parse(response);
+    }
+    async verify(publicKey, proof) {
+        const body = agentVerifyRequestSchema.parse({ publicKey, ...proof });
+        const response = await this.ctx.request('POST', '/auth/agent/verify', body, { cache: false, skipAuth: true });
+        return plantSession(this.ctx, response, 'auth/agent/verify');
+    }
+}
 export class AuthApi {
     constructor(ctx) {
         this.ctx = ctx;
@@ -650,6 +669,7 @@ export class AuthApi {
         this.totp = new AuthTotpApi(ctx);
         this.oauth = new AuthOAuthApi(ctx);
         this.commons = new AuthCommonsApi(ctx);
+        this.agent = new AuthAgentApi(ctx);
     }
     /**
      * Register a new identity with public key authentication

package/dist/esm/api/billing.js

@@ -1,9 +1,44 @@
+/**
+ * `oxy.billing` — the signed-in user's subscription, wallet and payment history.
+ *
+ * Every call reads the SIGNED-IN user's data unless a `userId` is passed (the
+ * API refuses any other user's). Checkout, plan changes and cancellation live
+ * under `/billing` (Stripe) and are not wrapped here yet.
+ *
+ * The types model the JSON these routes actually return (`subscription.controller`,
+ * `payment.controller`, `wallet.routes` in `packages/api`); `Date` columns
+ * arrive as ISO-8601 strings.
+ */
+import { subjectProductAccessQuerySchema, subjectProductAccessSchema, } from '@oxy.so/contracts';
+import { productSubscriptionCancellationResultSchema, cancelProductSubscriptionSchema, productSubscriptionsResponseSchema, subscriptionCreditGrantsResponseSchema, } from '@oxy.so/contracts';
 const SUBSCRIPTION_TTL = 2 * 60 * 1000;
 const WALLET_TTL = 60 * 1000;
 export class BillingApi {
     constructor(ctx) {
         this.ctx = ctx;
     }
+    /** Product rights only; requires a production application-bound user session. Never cached. */
+    async productAccess(query) {
+        const parsed = subjectProductAccessQuerySchema.parse(query);
+        const response = await this.ctx.request('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() {
+        return productSubscriptionsResponseSchema.parse(await this.ctx.request("GET", "/billing/product-subscriptions", undefined, { cache: false })).subscriptions;
+    }
+    /** Per-grant credit provenance; no interpretation of the historical mixed balance. */
+    async creditGrants() {
+        return subscriptionCreditGrantsResponseSchema.parse(await this.ctx.request("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, expectedSubjectAccountId) {
+        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, expectedSubjectAccountId) {
+        return productSubscriptionCancellationResultSchema.parse(await this.ctx.request('POST', '/billing/product-subscriptions/cancel', cancelProductSubscriptionSchema.parse({ sourceId, ...(expectedSubjectAccountId ? { expectedSubjectAccountId } : {}) }), { cache: false }));
+    }
     /** The signed-in user's payment history. Never cached. */
     async payments() {
         return this.ctx.request('GET', '/payments/user', undefined, { cache: false });

package/dist/esm/boot/sessionColdBoot.js

@@ -44,9 +44,8 @@ import { runColdBoot } from '../utils/coldBoot.js';
 import { isNative as detectNative } from '../utils/platform.js';
 import { logger } from '../logger/index.js';
 import { computeIdentityTag } from '../utils/cacheKey.js';
-import { TOKEN_REFRESH_LEAD_MS, refreshDeviceSecretArm } from '../session/refresh.js';
+import { TOKEN_REFRESH_LEAD_MS, refreshDeviceSecretArm, refreshSharedDeviceArm } from '../session/refresh.js';
 import { establishIdentitySession, resolveIdentityPin, } from '../session/identitySession.js';
-import { decideSharedDeviceJoin, } from '../session/sharedDeviceCredential.js';
 /**
  * Run the device-first cold boot. Resolves to the `runColdBoot` outcome and, as
  * a side effect, invokes `onSession` (winning session, token already planted) or
@@ -70,6 +69,8 @@ export async function runSessionColdBoot(opts) {
     // Boot-local (not module-level) so it cannot leak across boots or break under
     // bundler re-evaluation.
     let 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
     // resolved at most once per boot so two steps cannot disagree. Always `null`
@@ -101,6 +102,8 @@ export async function runSessionColdBoot(opts) {
     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' };
@@ -173,6 +176,11 @@ export async function runSessionColdBoot(opts) {
                         },
                     };
                 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
@@ -184,6 +192,7 @@ export async function runSessionColdBoot(opts) {
                     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';
@@ -205,7 +214,10 @@ export async function runSessionColdBoot(opts) {
                     logger.debug('device-secret mint failed (transient) — keeping secret', { component: 'sessionColdBoot', method: 'device-secret-mint' });
                     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' };
@@ -270,63 +282,16 @@ export async function runSessionColdBoot(opts) {
             // 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 () => {
-                    if (before) {
-                        await store.save(before);
-                    }
-                    else {
-                        await store.clear();
-                    }
-                };
-                const adopted = {
-                    // 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,
-                        },
-                    };
-                }
-                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();
+                    return { kind: 'session', session: {
+                            sessionId: result.sessionId, userId: result.userId, accessToken: result.token, state: result.state,
+                        } };
                 }
-                else if (result.status === 'no-session') {
+                if (result.status === 'no-session')
                     signedOutReason = 'no_session';
-                }
-                await revert();
                 return { kind: 'skip' };
             },
         });
@@ -354,8 +319,11 @@ export async function runSessionColdBoot(opts) {
             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
@@ -371,6 +339,9 @@ export async function runSessionColdBoot(opts) {
                         expiresAt: session.expiresAt,
                     });
                 }
+                if (oxy.http.getSessionEpoch() !== epoch || await store.isAutomaticIdentitySignInSuppressed?.())
+                    return { kind: 'skip' };
+                oxy.session.setAccessToken(session.accessToken);
                 return {
                     kind: 'session',
                     session: {

package/dist/esm/inference/OxyInferenceClient.js

@@ -1,3 +1,15 @@
+var __classPrivateFieldSet = (this && this.__classPrivateFieldSet) || function (receiver, state, value, kind, f) {
+    if (kind === "m") throw new TypeError("Private method is not writable");
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a setter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot write private member to an object whose class did not declare it");
+    return (kind === "a" ? f.call(receiver, value) : f ? f.value = value : state.set(receiver, value)), value;
+};
+var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (receiver, state, kind, f) {
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a getter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
+    return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
+};
+var _OxyInferenceClient_instances, _OxyInferenceClient_baseURL, _OxyInferenceClient_credential, _OxyInferenceClient_fetch, _OxyInferenceClient_bearer, _OxyInferenceClient_headers, _OxyInferenceClient_request;
 /**
  * The Oxy inference client — one surface, two credential lanes (issue #972,
  * workstream 15).
@@ -49,18 +61,6 @@
  * schema, so a rename on either side fails a build rather than a customer's
  * request.
  */
-var __classPrivateFieldSet = (this && this.__classPrivateFieldSet) || function (receiver, state, value, kind, f) {
-    if (kind === "m") throw new TypeError("Private method is not writable");
-    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a setter");
-    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot write private member to an object whose class did not declare it");
-    return (kind === "a" ? f.call(receiver, value) : f ? f.value = value : state.set(receiver, value)), value;
-};
-var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (receiver, state, kind, f) {
-    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a getter");
-    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
-    return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
-};
-var _OxyInferenceClient_instances, _OxyInferenceClient_baseURL, _OxyInferenceClient_credential, _OxyInferenceClient_fetch, _OxyInferenceClient_bearer, _OxyInferenceClient_headers, _OxyInferenceClient_request;
 import { decisionRequestSchema, decisionSuccessSchema, decisionAnswersMatch } from '@oxy.so/contracts';
 import { INFERENCE_ERROR_CODES, MAX_INFERENCE_AUDIO_BYTES, inferenceAudioMediaTypeSchema, inferenceStreamEventSchema, modelIdSchema, } from '@oxy.so/contracts';
 /** The base URL of the Oxy API, when a caller names none. */
@@ -379,7 +379,15 @@ export class OxyInferenceClient {
      * somebody else.
      */
     async getGeneration(id, options = {}) {
-        const body = await __classPrivateFieldGet(this, _OxyInferenceClient_instances, "m", _OxyInferenceClient_request).call(this, '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, options = {}) {
+        const body = await __classPrivateFieldGet(this, _OxyInferenceClient_instances, "m", _OxyInferenceClient_request).call(this, 'GET', `/v1/generations/${encodeURIComponent(id)}`, options);
         return body.data;
     }
 }

package/dist/esm/server/OxyServer.js

@@ -26,6 +26,18 @@
  * Node only.
  */
 import { jwtDecode } from 'jwt-decode';
+import { hasBoundedServiceTokenLifetime } from './serviceTokenLifetime.js';
+/** Unverified cache metadata only: an old lifetime forces a new signed mint. */
+function reusableServiceToken(token) {
+    try {
+        const claims = jwtDecode(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 } from '../OxyServices.js';
 import { logger } from '../logger/index.js';
@@ -53,10 +65,10 @@ const WORKLOAD_CACHE_KEY = 'workload-identity';
 const TOKEN_REUSE_MARGIN_MS = 60000;
 /** 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 = 60000;
+/** Explicit authoritative read denials last ten seconds; failures are never cached. */
+const ACTING_AS_DENIAL_TTL_MS = 10000;
 export class OxyServer extends OxyServices {
     constructor(config) {
         super(config);
@@ -65,6 +77,7 @@ export class OxyServer extends OxyServices {
         this.serviceApiSecret = null;
         this.actingAs = new Map();
         this.actingAsPending = new Map();
+        this.actingAsGenerations = new Map();
         /** Public keys only; never private material. */
         this.jwksCache = { keys: new Map(), expiresAt: 0, lastAttemptAt: 0 };
         /**
@@ -118,7 +131,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),
         });
     }
     /** Files, plus the service-only metadata and linked-URL lookups. */
@@ -204,7 +217,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) {
@@ -266,32 +279,49 @@ 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, userId) {
-        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, userId, options = {}) {
+        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);
+        }
     }
     // ── Internals ────────────────────────────────────────────────────────────
     /**
@@ -347,7 +377,7 @@ export class OxyServer extends OxyServices {
     /** A token obtained by attestation, cached like a credential's (one identity per process). */
     async workloadServiceToken() {
         const entry = this.serviceTokens.get(WORKLOAD_CACHE_KEY);
-        if (entry?.token && entry.expiresAt > Date.now() + TOKEN_REUSE_MARGIN_MS)
+        if (entry?.token && reusableServiceToken(entry.token) && entry.expiresAt > Date.now() + TOKEN_REUSE_MARGIN_MS)
             return entry.token;
         if (entry?.pending)
             return entry.pending;
@@ -378,36 +408,62 @@ export class OxyServer extends OxyServices {
                 settled.pending = null;
         }
     }
-    async lookupActingAs(appId, userId) {
+    async lookupActingAs(appId, userId, options, pair, cacheKey, generation, serial, startedAt) {
         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('GET', '/internal/service-acting-as/verify', { appId, userId }, { cache: false, retry: false, timeout: 5000, headers: { Authorization: `Bearer ${serviceToken}` } });
-            const verified = result?.authorized
-                ? { authorized: true, scopes: Array.isArray(result.scopes) ? result.scopes : [] }
-                : null;
-            this.rememberActingAs(`${appId}:${userId}`, verified, ACTING_AS_GRANT_TTL_MS);
+            const result = await this.request('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}` } });
+            // 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 = 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;
         }
     }
-    rememberActingAs(cacheKey, result, ttlMs) {
+    clearActingAsPair(appId, userId) {
+        for (const key of this.actingAs.keys()) {
+            const [cachedApp, cachedUser] = JSON.parse(key);
+            if (cachedApp === appId && cachedUser === userId)
+                this.actingAs.delete(key);
+        }
+    }
+    rememberActingAs(cacheKey, result, expiresAt) {
         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)

package/dist/esm/server/agentAccount.js

@@ -0,0 +1,16 @@
+/** Autonomous entry helper. The signer owns its private key (for example in a KMS). */
+import { buildAgentProofMessage } from '@oxy.so/contracts';
+import { normalizeSecp256k1PublicKey } from '@oxy.so/protocol/secp256k1';
+/** Explicit sign-in; no timer, automatic escalation or service credential lane. */
+export async function signInAgentAccount(options) {
+    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 });
+}