@oxy.so/core 7.10.5 → 7.11.0

package/dist/cjs/api/session.js

@@ -10,6 +10,7 @@ exports.SessionApi = void 0;
  */
 const jwt_decode_1 = require("jwt-decode");
 const userIdentity_1 = require("../utils/userIdentity");
+const OxyServices_errors_1 = require("../OxyServices.errors");
 class SessionApi {
     constructor(ctx) {
         this.ctx = ctx;
@@ -144,13 +145,31 @@ class SessionApi {
      * validates the session it was issued for.
      */
     async validate(sessionId, options = {}) {
+        if ('liveSession' in options)
+            throw new OxyServices_errors_1.OxyApiError('Live session validation requires OxyServer', {
+                status: 503,
+                code: 'SESSION_AUTHORITY_UNAVAILABLE',
+            });
+        return this.validateRequest(sessionId, options);
+    }
+    /** Server implementations use this transport after enforcing their own contract. */
+    async validateRequest(sessionId, options) {
         try {
+            if (options.liveSession && !options.accessToken)
+                throw new OxyServices_errors_1.OxyApiError('Live session authority requires a bearer', {
+                    status: 503,
+                    code: 'SESSION_AUTHORITY_UNAVAILABLE',
+                });
             const validation = options.accessToken
                 ? await this.ctx.request('GET', `/session/validate-header/${encodeURIComponent(sessionId)}`, undefined, {
                     cache: false,
                     skipAuth: true,
+                    ...(options.liveSession ? { deduplicate: false, retry: false } : {}),
                     headers: {
                         Authorization: `Bearer ${options.accessToken}`,
+                        ...(options.liveSession
+                            ? { 'x-oxy-session-authority': 'live-v1', 'cache-control': 'no-store' }
+                            : {}),
                         ...(options.deviceFingerprint
                             ? { 'x-device-fingerprint': options.deviceFingerprint }
                             : {}),
@@ -162,9 +181,36 @@ class SessionApi {
                         : {}),
                     ...(options.useHeaderValidation ? { useHeaderValidation: 'true' } : {}),
                 }, { cache: false });
+            if (options.liveSession &&
+                (validation.liveSessionAuthority !== 'session-row-v1' ||
+                    validation.valid !== true ||
+                    validation.sessionId !== sessionId ||
+                    typeof validation.expiresAt !== 'string' ||
+                    !Number.isFinite(Date.parse(validation.expiresAt)) ||
+                    Date.parse(validation.expiresAt) <= Date.now() ||
+                    typeof validation.lastActivity !== 'string' ||
+                    !Number.isFinite(Date.parse(validation.lastActivity))))
+                throw new OxyServices_errors_1.OxyApiError('Live session authority is unavailable', {
+                    status: 503,
+                    code: 'SESSION_AUTHORITY_UNAVAILABLE',
+                });
             return { ...validation, user: (0, userIdentity_1.normalizeUserIdentity)(validation.user) };
         }
         catch (error) {
+            if (options.liveSession) {
+                const candidate = error;
+                const invalid = candidate?.status === 401 && candidate.code === 'OXY_LIVE_SESSION_INVALID_V1';
+                const denied = candidate?.status === 403 && candidate.code === 'OXY_LIVE_SESSION_POLICY_V1';
+                if (invalid)
+                    this.ctx.oxy.cache.delete(`GET:/session/user/${sessionId}`);
+                if (invalid || denied)
+                    throw error;
+                throw new OxyServices_errors_1.OxyApiError('Live session authority is unavailable', {
+                    status: 503,
+                    code: 'SESSION_AUTHORITY_UNAVAILABLE',
+                    cause: error,
+                });
+            }
             // The session is gone: drop any user cached for it (#196).
             this.ctx.oxy.cache.delete(`GET:/session/user/${sessionId}`);
             throw error;

package/dist/cjs/server/OxyServer.js

@@ -530,6 +530,29 @@ class OxyServer extends OxyServices_1.OxyServices {
             throw new Error('Product grant response attribution differs');
         return snapshot;
     }
+    /**
+     * Register accounts this deployment provisioned as its own users, so they count
+     * toward {@link applicationAccountTotal}. Workload identity only (the
+     * application is the workload's); idempotent; at most
+     * `APPLICATION_ACCOUNT_REGISTRATION_BATCH_MAX` ids per call. Ids that are
+     * unknown, federated, not personal or archived are skipped and not reported.
+     * Returns how many became newly registered.
+     */
+    async registerApplicationAccounts(accountIds) {
+        const body = contracts_1.applicationAccountRegistrationRequestSchema.parse({ accountIds });
+        const answer = await this.serviceRequest('POST', '/application-accounts/self/registrations', body, { cache: false });
+        return contracts_1.applicationAccountRegistrationResponseSchema.parse(answer).registered;
+    }
+    /**
+     * This deployment's eligible registered-account total (local, personal, active,
+     * not being closed), from a bounded server snapshot: read `computedAt`,
+     * `stale` and `exact` before presenting it. Rejects when no total is available
+     * (503 before the first snapshot) — never resolve an unknown total to `0`.
+     */
+    async applicationAccountTotal() {
+        const answer = await this.serviceRequest('GET', '/application-accounts/self/total', undefined, { cache: false });
+        return contracts_1.applicationAccountTotalSchema.parse(answer);
+    }
     async serviceRequest(method, url, data, options = {}) {
         const target = new URL(/^https?:\/\//i.test(url)
             ? url

package/dist/cjs/server/middleware.js

@@ -138,7 +138,7 @@ function createOxyMiddleware(host) {
      */
     function auth(options = {}) {
         const { debug = false, onError, onRefusal, loadUser = false, optional = false, serviceTokenJwksUrl = new URL('/.well-known/jwks.json', host.baseURL).toString(), expectedIssuer = exports.OXY_JWT_ISSUER, expectedAudience = OXY_JWT_AUDIENCE, } = options;
-        const strictPresentedBearer = Boolean(options.supervisedAction || options.strictOptionalBearer);
+        const strictPresentedBearer = Boolean(options.supervisedAction || options.strictOptionalBearer || options.liveSession);
         /**
          * Make a refusal observable to the HOST, without telling the client
          * anything it is not already told.
@@ -247,6 +247,17 @@ function createOxyMiddleware(host) {
                 // Handle service tokens (internal service-to-service auth)
                 // Service tokens are stateless JWTs with type: 'service' — requires signature verification
                 if (decoded.type === 'service') {
+                    if (options.liveSession) {
+                        const error = {
+                            error: 'SESSION_REQUIRED',
+                            message: 'A live user session is required',
+                            code: 'SESSION_REQUIRED',
+                            status: 403,
+                        };
+                        if (onError)
+                            return onError(error);
+                        return res.status(403).json(error);
+                    }
                     // Verify JWT signature, then audience / issuer / type / appId claims.
                     //
                     // Signature verification uses Node crypto rather than
@@ -659,6 +670,7 @@ function createOxyMiddleware(host) {
                         accessToken: token,
                         supervisedAction: options.supervisedAction,
                         fresh: options.freshSession,
+                        ...(options.liveSession ? { liveSession: true } : {}),
                     });
                     if (!validationResult || !validationResult.valid || !validationResult.user) {
                         recordRefusal(req, {

package/dist/cjs/server/session.js

@@ -19,10 +19,11 @@ exports.ServerSessionApi = exports.SESSION_VALIDATION_CACHE_TTL_MS = void 0;
  * bearer) — never the raw token — for {@link SESSION_VALIDATION_CACHE_TTL_MS}
  * (30 s) by default, and never past the token's own `exp`.
  *
- * THE SECURITY CONTRACT: the cache never keeps a revoked session alive. Oxy
- * announces every session it ends on its service-event feed
- * (`./serviceEvents.ts`; `@oxy.so/contracts` `sessionRevocation.ts`), and the
- * cache is used ONLY while that feed is live:
+ * Oxy announces ended sessions on its service-event feed (`./serviceEvents.ts`;
+ * `@oxy.so/contracts` `sessionRevocation.ts`), and the cache is used ONLY while
+ * that feed is live. Feed health alone cannot prove that every event was
+ * delivered. Routes requiring a fresh session-row read can opt in to
+ * `liveSession`; see `ServerSessionValidateOptions` for its scope.
  *
  * - no feed (this process has no service token: no credential and no attested
  *   workload, as in a test or a local checkout), a feed not yet connected, a
@@ -49,6 +50,7 @@ const node_crypto_1 = require("node:crypto");
 const contracts_1 = require("@oxy.so/contracts");
 const jwt_decode_1 = require("jwt-decode");
 const session_1 = require("../api/session");
+const OxyServices_errors_1 = require("../OxyServices.errors");
 const userIdentity_1 = require("../utils/userIdentity");
 /** Default lifetime of one cached validation. */
 exports.SESSION_VALIDATION_CACHE_TTL_MS = 30000;
@@ -81,7 +83,29 @@ class ServerSessionApi extends session_1.SessionApi {
         this.revoked = new Map();
     }
     async validate(sessionId, options = {}) {
-        const { supervisedAction, fresh, ...rest } = options;
+        const { supervisedAction, fresh, liveSession, ...rest } = options;
+        if (liveSession) {
+            if (supervisedAction)
+                throw new OxyServices_errors_1.OxyApiError('Live supervised session authority is unavailable', {
+                    status: 503,
+                    code: 'SESSION_AUTHORITY_UNAVAILABLE',
+                });
+            try {
+                const result = await this.validateRequest(sessionId, { ...rest, liveSession: true });
+                const actor = contracts_1.accountActorChainSchema.safeParse(result.actor);
+                if (!actor.success || actor.data.effectiveAccountId !== result.user.id)
+                    throw new OxyServices_errors_1.OxyApiError('Invalid live session authority response', {
+                        status: 503,
+                        code: 'SESSION_AUTHORITY_UNAVAILABLE',
+                    });
+                return result;
+            }
+            catch (error) {
+                if (error?.status === 401)
+                    this.refuse(sessionId);
+                throw error;
+            }
+        }
         if (supervisedAction)
             return this.validateSupervised(sessionId, supervisedAction, rest);
         if (!rest.accessToken || rest.deviceFingerprint || this.validationTtlMs <= 0) {

package/dist/esm/api/session.js

@@ -7,6 +7,7 @@
  */
 import { jwtDecode } from 'jwt-decode';
 import { normalizeUserIdentity } from '../utils/userIdentity.js';
+import { OxyApiError } from '../OxyServices.errors.js';
 export class SessionApi {
     constructor(ctx) {
         this.ctx = ctx;
@@ -141,13 +142,31 @@ export class SessionApi {
      * validates the session it was issued for.
      */
     async validate(sessionId, options = {}) {
+        if ('liveSession' in options)
+            throw new OxyApiError('Live session validation requires OxyServer', {
+                status: 503,
+                code: 'SESSION_AUTHORITY_UNAVAILABLE',
+            });
+        return this.validateRequest(sessionId, options);
+    }
+    /** Server implementations use this transport after enforcing their own contract. */
+    async validateRequest(sessionId, options) {
         try {
+            if (options.liveSession && !options.accessToken)
+                throw new OxyApiError('Live session authority requires a bearer', {
+                    status: 503,
+                    code: 'SESSION_AUTHORITY_UNAVAILABLE',
+                });
             const validation = options.accessToken
                 ? await this.ctx.request('GET', `/session/validate-header/${encodeURIComponent(sessionId)}`, undefined, {
                     cache: false,
                     skipAuth: true,
+                    ...(options.liveSession ? { deduplicate: false, retry: false } : {}),
                     headers: {
                         Authorization: `Bearer ${options.accessToken}`,
+                        ...(options.liveSession
+                            ? { 'x-oxy-session-authority': 'live-v1', 'cache-control': 'no-store' }
+                            : {}),
                         ...(options.deviceFingerprint
                             ? { 'x-device-fingerprint': options.deviceFingerprint }
                             : {}),
@@ -159,9 +178,36 @@ export class SessionApi {
                         : {}),
                     ...(options.useHeaderValidation ? { useHeaderValidation: 'true' } : {}),
                 }, { cache: false });
+            if (options.liveSession &&
+                (validation.liveSessionAuthority !== 'session-row-v1' ||
+                    validation.valid !== true ||
+                    validation.sessionId !== sessionId ||
+                    typeof validation.expiresAt !== 'string' ||
+                    !Number.isFinite(Date.parse(validation.expiresAt)) ||
+                    Date.parse(validation.expiresAt) <= Date.now() ||
+                    typeof validation.lastActivity !== 'string' ||
+                    !Number.isFinite(Date.parse(validation.lastActivity))))
+                throw new OxyApiError('Live session authority is unavailable', {
+                    status: 503,
+                    code: 'SESSION_AUTHORITY_UNAVAILABLE',
+                });
             return { ...validation, user: normalizeUserIdentity(validation.user) };
         }
         catch (error) {
+            if (options.liveSession) {
+                const candidate = error;
+                const invalid = candidate?.status === 401 && candidate.code === 'OXY_LIVE_SESSION_INVALID_V1';
+                const denied = candidate?.status === 403 && candidate.code === 'OXY_LIVE_SESSION_POLICY_V1';
+                if (invalid)
+                    this.ctx.oxy.cache.delete(`GET:/session/user/${sessionId}`);
+                if (invalid || denied)
+                    throw error;
+                throw new OxyApiError('Live session authority is unavailable', {
+                    status: 503,
+                    code: 'SESSION_AUTHORITY_UNAVAILABLE',
+                    cause: error,
+                });
+            }
             // The session is gone: drop any user cached for it (#196).
             this.ctx.oxy.cache.delete(`GET:/session/user/${sessionId}`);
             throw error;

package/dist/esm/server/OxyServer.js

@@ -1,5 +1,5 @@
 import { OxyRequesterClient } from './requesterClient.js';
-import { serviceIntrospectionSchema, resourceIntrospectionSchema, serviceTokenOptionsSchema, subjectProductAccessQuerySchema, subjectProductGrantSnapshotSchema, } from '@oxy.so/contracts';
+import { applicationAccountRegistrationRequestSchema, applicationAccountRegistrationResponseSchema, applicationAccountTotalSchema, serviceIntrospectionSchema, resourceIntrospectionSchema, serviceTokenOptionsSchema, subjectProductAccessQuerySchema, subjectProductGrantSnapshotSchema, } from '@oxy.so/contracts';
 /**
  * `OxyServer` — the Oxy client for a backend.
  *
@@ -526,6 +526,29 @@ export class OxyServer extends OxyServices {
             throw new Error('Product grant response attribution differs');
         return snapshot;
     }
+    /**
+     * Register accounts this deployment provisioned as its own users, so they count
+     * toward {@link applicationAccountTotal}. Workload identity only (the
+     * application is the workload's); idempotent; at most
+     * `APPLICATION_ACCOUNT_REGISTRATION_BATCH_MAX` ids per call. Ids that are
+     * unknown, federated, not personal or archived are skipped and not reported.
+     * Returns how many became newly registered.
+     */
+    async registerApplicationAccounts(accountIds) {
+        const body = applicationAccountRegistrationRequestSchema.parse({ accountIds });
+        const answer = await this.serviceRequest('POST', '/application-accounts/self/registrations', body, { cache: false });
+        return applicationAccountRegistrationResponseSchema.parse(answer).registered;
+    }
+    /**
+     * This deployment's eligible registered-account total (local, personal, active,
+     * not being closed), from a bounded server snapshot: read `computedAt`,
+     * `stale` and `exact` before presenting it. Rejects when no total is available
+     * (503 before the first snapshot) — never resolve an unknown total to `0`.
+     */
+    async applicationAccountTotal() {
+        const answer = await this.serviceRequest('GET', '/application-accounts/self/total', undefined, { cache: false });
+        return applicationAccountTotalSchema.parse(answer);
+    }
     async serviceRequest(method, url, data, options = {}) {
         const target = new URL(/^https?:\/\//i.test(url)
             ? url

package/dist/esm/server/middleware.js

@@ -131,7 +131,7 @@ export function createOxyMiddleware(host) {
      */
     function auth(options = {}) {
         const { debug = false, onError, onRefusal, loadUser = false, optional = false, serviceTokenJwksUrl = new URL('/.well-known/jwks.json', host.baseURL).toString(), expectedIssuer = OXY_JWT_ISSUER, expectedAudience = OXY_JWT_AUDIENCE, } = options;
-        const strictPresentedBearer = Boolean(options.supervisedAction || options.strictOptionalBearer);
+        const strictPresentedBearer = Boolean(options.supervisedAction || options.strictOptionalBearer || options.liveSession);
         /**
          * Make a refusal observable to the HOST, without telling the client
          * anything it is not already told.
@@ -240,6 +240,17 @@ export function createOxyMiddleware(host) {
                 // Handle service tokens (internal service-to-service auth)
                 // Service tokens are stateless JWTs with type: 'service' — requires signature verification
                 if (decoded.type === 'service') {
+                    if (options.liveSession) {
+                        const error = {
+                            error: 'SESSION_REQUIRED',
+                            message: 'A live user session is required',
+                            code: 'SESSION_REQUIRED',
+                            status: 403,
+                        };
+                        if (onError)
+                            return onError(error);
+                        return res.status(403).json(error);
+                    }
                     // Verify JWT signature, then audience / issuer / type / appId claims.
                     //
                     // Signature verification uses Node crypto rather than
@@ -652,6 +663,7 @@ export function createOxyMiddleware(host) {
                         accessToken: token,
                         supervisedAction: options.supervisedAction,
                         fresh: options.freshSession,
+                        ...(options.liveSession ? { liveSession: true } : {}),
                     });
                     if (!validationResult || !validationResult.valid || !validationResult.user) {
                         recordRefusal(req, {

package/dist/esm/server/session.js

@@ -16,10 +16,11 @@
  * bearer) — never the raw token — for {@link SESSION_VALIDATION_CACHE_TTL_MS}
  * (30 s) by default, and never past the token's own `exp`.
  *
- * THE SECURITY CONTRACT: the cache never keeps a revoked session alive. Oxy
- * announces every session it ends on its service-event feed
- * (`./serviceEvents.ts`; `@oxy.so/contracts` `sessionRevocation.ts`), and the
- * cache is used ONLY while that feed is live:
+ * Oxy announces ended sessions on its service-event feed (`./serviceEvents.ts`;
+ * `@oxy.so/contracts` `sessionRevocation.ts`), and the cache is used ONLY while
+ * that feed is live. Feed health alone cannot prove that every event was
+ * delivered. Routes requiring a fresh session-row read can opt in to
+ * `liveSession`; see `ServerSessionValidateOptions` for its scope.
  *
  * - no feed (this process has no service token: no credential and no attested
  *   workload, as in a test or a local checkout), a feed not yet connected, a
@@ -43,9 +44,10 @@
  * logout made through this client still drop entries too.
  */
 import { createHash } from 'node:crypto';
-import { safetySessionInputSchema, safetySessionValidationSchema, } from '@oxy.so/contracts';
+import { accountActorChainSchema, safetySessionInputSchema, safetySessionValidationSchema, } from '@oxy.so/contracts';
 import { jwtDecode } from 'jwt-decode';
 import { SessionApi } from '../api/session.js';
+import { OxyApiError } from '../OxyServices.errors.js';
 import { normalizeUserIdentity } from '../utils/userIdentity.js';
 /** Default lifetime of one cached validation. */
 export const SESSION_VALIDATION_CACHE_TTL_MS = 30000;
@@ -78,7 +80,29 @@ export class ServerSessionApi extends SessionApi {
         this.revoked = new Map();
     }
     async validate(sessionId, options = {}) {
-        const { supervisedAction, fresh, ...rest } = options;
+        const { supervisedAction, fresh, liveSession, ...rest } = options;
+        if (liveSession) {
+            if (supervisedAction)
+                throw new OxyApiError('Live supervised session authority is unavailable', {
+                    status: 503,
+                    code: 'SESSION_AUTHORITY_UNAVAILABLE',
+                });
+            try {
+                const result = await this.validateRequest(sessionId, { ...rest, liveSession: true });
+                const actor = accountActorChainSchema.safeParse(result.actor);
+                if (!actor.success || actor.data.effectiveAccountId !== result.user.id)
+                    throw new OxyApiError('Invalid live session authority response', {
+                        status: 503,
+                        code: 'SESSION_AUTHORITY_UNAVAILABLE',
+                    });
+                return result;
+            }
+            catch (error) {
+                if (error?.status === 401)
+                    this.refuse(sessionId);
+                throw error;
+            }
+        }
         if (supervisedAction)
             return this.validateSupervised(sessionId, supervisedAction, rest);
         if (!rest.accessToken || rest.deviceFingerprint || this.validationTtlMs <= 0) {

package/dist/types/api/session.d.ts

@@ -85,6 +85,10 @@ export declare class SessionApi {
      * validates the session it was issued for.
      */
     validate(sessionId: string, options?: SessionValidateOptions): Promise<SessionValidation>;
+    /** Server implementations use this transport after enforcing their own contract. */
+    protected validateRequest(sessionId: string, options: SessionValidateOptions & {
+        liveSession?: boolean;
+    }): Promise<SessionValidation>;
     /** The sessions that belong with `sessionId` (same account set). */
     list(sessionId: string): Promise<ClientSession[]>;
     /** Sign out `sessionId`, or — with `targetSessionId` — one of the sessions beside it. */

package/dist/types/server/OxyServer.d.ts

@@ -1,6 +1,6 @@
 import { OxyRequesterClient } from './requesterClient';
 import type { RequesterProof } from './requesterContext';
-import { type ResourceIntrospection, type ServiceIntrospection, type ServiceTokenOptions, type SubjectProductAccessQuery, type SubjectProductGrantSnapshot } from '@oxy.so/contracts';
+import { type ApplicationAccountTotal, type ResourceIntrospection, type ServiceIntrospection, type ServiceTokenOptions, type SubjectProductAccessQuery, type SubjectProductGrantSnapshot } from '@oxy.so/contracts';
 import { OxyServices, type OxyConfig } from '../OxyServices';
 import type { HttpMethod } from '../client/context';
 import type { RequestOptions, ResponsePayload } from '../HttpService';
@@ -267,6 +267,22 @@ export declare class OxyServer extends OxyServices {
     productGrantSnapshotForUser(query: SubjectProductAccessQuery, accessToken: string): Promise<SubjectProductGrantSnapshot>;
     /** Offline metering read: the API requires this app's live consent for this exact subject. */
     productGrantSnapshotForService(query: SubjectProductAccessQuery): Promise<SubjectProductGrantSnapshot>;
+    /**
+     * Register accounts this deployment provisioned as its own users, so they count
+     * toward {@link applicationAccountTotal}. Workload identity only (the
+     * application is the workload's); idempotent; at most
+     * `APPLICATION_ACCOUNT_REGISTRATION_BATCH_MAX` ids per call. Ids that are
+     * unknown, federated, not personal or archived are skipped and not reported.
+     * Returns how many became newly registered.
+     */
+    registerApplicationAccounts(accountIds: readonly string[]): Promise<number>;
+    /**
+     * This deployment's eligible registered-account total (local, personal, active,
+     * not being closed), from a bounded server snapshot: read `computedAt`,
+     * `stale` and `exact` before presenting it. Rejects when no total is available
+     * (503 before the first snapshot) — never resolve an unknown total to `0`.
+     */
+    applicationAccountTotal(): Promise<ApplicationAccountTotal>;
     serviceRequest<T>(method: HttpMethod, url: string, data?: unknown, options?: RequestOptions & {
         actAs?: string;
         requesterToken?: string;

package/dist/types/server/middleware.d.ts

@@ -189,11 +189,13 @@ export interface AuthMiddlewareOptions {
     /** Keep anonymous access, but reject every supplied invalid credential or authority outage. */
     strictOptionalBearer?: boolean;
     /**
-     * Ask Oxy about the session on every request instead of reusing a recent
-     * successful validation (`OxyServerConfig.sessionValidationCacheTtlMs`, 30 s).
-     * For routes where a just-revoked session must not act — deletion, payments.
+     * Ask Oxy instead of reusing this server's recent successful validation
+     * (`OxyServerConfig.sessionValidationCacheTtlMs`, 30 s). Oxy may itself
+     * serve a cached answer; use `liveSession` for a live session-row read.
      */
     freshSession?: boolean;
+    /** Require a live session-row read. Unsupported servers fail with 503. */
+    liveSession?: boolean;
     /**
      * Called whenever a PRESENTED credential is refused, on the optional path as
      * well as the blocking one. Runs before the response (if any) and after
@@ -237,6 +239,7 @@ export interface OxyMiddlewareHost {
         accessToken?: string;
         supervisedAction?: SupervisedAction;
         fresh?: boolean;
+        liveSession?: boolean;
     }): Promise<{
         valid: boolean;
         user?: User;

package/dist/types/server/session.d.ts

@@ -4,6 +4,17 @@ import { SessionApi, type SessionValidateOptions, type SessionValidation } from
 /** Default lifetime of one cached validation. */
 export declare const SESSION_VALIDATION_CACHE_TTL_MS = 30000;
 export interface ServerSessionValidateOptions extends SessionValidateOptions {
+    /**
+     * Require a session-row read on a PostgreSQL writer. Old servers and
+     * unavailable authority fail closed with 503. The read only reflects commits
+     * visible to its database snapshot; requests already authorized can finish.
+     * This does not make account, grant or supervision data fresh. An unconfirmed
+     * user, grant or policy negative returns 503 rather than invalidating a
+     * session. Expiry is checked against the consumer's clock; skew can cause
+     * unavailability. Each validation reaches Oxy and its activity bookkeeping;
+     * assess database and Redis load before enabling it on a route.
+     */
+    liveSession?: boolean;
     /**
      * A reviewed route category. Oxy then validates the bearer through this
      * service's live `safety:<action>:v1` authority, the only lane a supervised

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oxy.so/core",
-  "version": "7.10.5",
+  "version": "7.11.0",
   "description": "OxyHQ SDK Foundation — API client, authentication, cryptographic identity, and shared utilities",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",
@@ -181,7 +181,7 @@
   "dependencies": {
     "@noble/ciphers": "^1.3.0",
     "@noble/hashes": "^1.8.0",
-    "@oxy.so/contracts": "6.2.0",
+    "@oxy.so/contracts": "6.3.0",
     "@oxy.so/protocol": "^1.5.1",
     "@oxy.so/telemetry": "^2.1.0",
     "@scure/bip39": "^1.6.0",

package/src/api/session.ts

@@ -11,6 +11,7 @@ import type { OxyContext } from '../client/context';
 import type { ClientSession } from '../models/session';
 import type { User } from '../models/interfaces';
 import { normalizeUserIdentity } from '../utils/userIdentity';
+import { OxyApiError } from '../OxyServices.errors';
 
 /**
  * Reads the device credential this client holds, if any — `{ deviceId,
@@ -188,18 +189,40 @@ export class SessionApi {
   async validate(
     sessionId: string,
     options: SessionValidateOptions = {},
+  ): Promise<SessionValidation> {
+    if ('liveSession' in options)
+      throw new OxyApiError('Live session validation requires OxyServer', {
+        status: 503,
+        code: 'SESSION_AUTHORITY_UNAVAILABLE',
+      });
+    return this.validateRequest(sessionId, options);
+  }
+
+  /** Server implementations use this transport after enforcing their own contract. */
+  protected async validateRequest(
+    sessionId: string,
+    options: SessionValidateOptions & { liveSession?: boolean },
   ): Promise<SessionValidation> {
     try {
-      const validation = options.accessToken
-        ? await this.ctx.request<SessionValidation>(
+      if (options.liveSession && !options.accessToken)
+        throw new OxyApiError('Live session authority requires a bearer', {
+          status: 503,
+          code: 'SESSION_AUTHORITY_UNAVAILABLE',
+        });
+      const validation: SessionValidation & { liveSessionAuthority?: unknown } = options.accessToken
+        ? await this.ctx.request<SessionValidation & { liveSessionAuthority?: unknown }>(
             'GET',
             `/session/validate-header/${encodeURIComponent(sessionId)}`,
             undefined,
             {
               cache: false,
               skipAuth: true,
+              ...(options.liveSession ? { deduplicate: false, retry: false } : {}),
               headers: {
                 Authorization: `Bearer ${options.accessToken}`,
+                ...(options.liveSession
+                  ? { 'x-oxy-session-authority': 'live-v1', 'cache-control': 'no-store' }
+                  : {}),
                 ...(options.deviceFingerprint
                   ? { 'x-device-fingerprint': options.deviceFingerprint }
                   : {}),
@@ -217,8 +240,36 @@ export class SessionApi {
             },
             { cache: false },
           );
+      if (
+        options.liveSession &&
+        (validation.liveSessionAuthority !== 'session-row-v1' ||
+          validation.valid !== true ||
+          validation.sessionId !== sessionId ||
+          typeof validation.expiresAt !== 'string' ||
+          !Number.isFinite(Date.parse(validation.expiresAt)) ||
+          Date.parse(validation.expiresAt) <= Date.now() ||
+          typeof validation.lastActivity !== 'string' ||
+          !Number.isFinite(Date.parse(validation.lastActivity)))
+      )
+        throw new OxyApiError('Live session authority is unavailable', {
+          status: 503,
+          code: 'SESSION_AUTHORITY_UNAVAILABLE',
+        });
       return { ...validation, user: normalizeUserIdentity(validation.user) };
     } catch (error) {
+      if (options.liveSession) {
+        const candidate = error as { status?: unknown; code?: unknown } | null;
+        const invalid =
+          candidate?.status === 401 && candidate.code === 'OXY_LIVE_SESSION_INVALID_V1';
+        const denied = candidate?.status === 403 && candidate.code === 'OXY_LIVE_SESSION_POLICY_V1';
+        if (invalid) this.ctx.oxy.cache.delete(`GET:/session/user/${sessionId}`);
+        if (invalid || denied) throw error;
+        throw new OxyApiError('Live session authority is unavailable', {
+          status: 503,
+          code: 'SESSION_AUTHORITY_UNAVAILABLE',
+          cause: error,
+        });
+      }
       // The session is gone: drop any user cached for it (#196).
       this.ctx.oxy.cache.delete(`GET:/session/user/${sessionId}`);
       throw error;

package/src/server/OxyServer.ts

@@ -1,6 +1,10 @@
 import { OxyRequesterClient } from './requesterClient';
 import type { RequesterProof } from './requesterContext';
 import {
+  applicationAccountRegistrationRequestSchema,
+  applicationAccountRegistrationResponseSchema,
+  applicationAccountTotalSchema,
+  type ApplicationAccountTotal,
   type OxySessionRevocationEvent,
   serviceIntrospectionSchema,
   resourceIntrospectionSchema,
@@ -786,6 +790,41 @@ export class OxyServer extends OxyServices {
     return snapshot;
   }
 
+  /**
+   * Register accounts this deployment provisioned as its own users, so they count
+   * toward {@link applicationAccountTotal}. Workload identity only (the
+   * application is the workload's); idempotent; at most
+   * `APPLICATION_ACCOUNT_REGISTRATION_BATCH_MAX` ids per call. Ids that are
+   * unknown, federated, not personal or archived are skipped and not reported.
+   * Returns how many became newly registered.
+   */
+  async registerApplicationAccounts(accountIds: readonly string[]): Promise<number> {
+    const body = applicationAccountRegistrationRequestSchema.parse({ accountIds });
+    const answer = await this.serviceRequest<unknown>(
+      'POST',
+      '/application-accounts/self/registrations',
+      body,
+      { cache: false },
+    );
+    return applicationAccountRegistrationResponseSchema.parse(answer).registered;
+  }
+
+  /**
+   * This deployment's eligible registered-account total (local, personal, active,
+   * not being closed), from a bounded server snapshot: read `computedAt`,
+   * `stale` and `exact` before presenting it. Rejects when no total is available
+   * (503 before the first snapshot) — never resolve an unknown total to `0`.
+   */
+  async applicationAccountTotal(): Promise<ApplicationAccountTotal> {
+    const answer = await this.serviceRequest<unknown>(
+      'GET',
+      '/application-accounts/self/total',
+      undefined,
+      { cache: false },
+    );
+    return applicationAccountTotalSchema.parse(answer);
+  }
+
   async serviceRequest<T>(
     method: HttpMethod,
     url: string,

package/src/server/middleware.ts

@@ -278,11 +278,13 @@ export interface AuthMiddlewareOptions {
   /** Keep anonymous access, but reject every supplied invalid credential or authority outage. */
   strictOptionalBearer?: boolean;
   /**
-   * Ask Oxy about the session on every request instead of reusing a recent
-   * successful validation (`OxyServerConfig.sessionValidationCacheTtlMs`, 30 s).
-   * For routes where a just-revoked session must not act — deletion, payments.
+   * Ask Oxy instead of reusing this server's recent successful validation
+   * (`OxyServerConfig.sessionValidationCacheTtlMs`, 30 s). Oxy may itself
+   * serve a cached answer; use `liveSession` for a live session-row read.
    */
   freshSession?: boolean;
+  /** Require a live session-row read. Unsupported servers fail with 503. */
+  liveSession?: boolean;
   /**
    * Called whenever a PRESENTED credential is refused, on the optional path as
    * well as the blocking one. Runs before the response (if any) and after
@@ -329,6 +331,7 @@ export interface OxyMiddlewareHost {
       accessToken?: string;
       supervisedAction?: SupervisedAction;
       fresh?: boolean;
+      liveSession?: boolean;
     },
   ): Promise<{ valid: boolean; user?: User; actor?: unknown } | null>;
   verifyActingAs(
@@ -443,7 +446,9 @@ export function createOxyMiddleware(host: OxyMiddlewareHost) {
       expectedIssuer = OXY_JWT_ISSUER,
       expectedAudience = OXY_JWT_AUDIENCE,
     } = options;
-    const strictPresentedBearer = Boolean(options.supervisedAction || options.strictOptionalBearer);
+    const strictPresentedBearer = Boolean(
+      options.supervisedAction || options.strictOptionalBearer || options.liveSession,
+    );
 
     /**
      * Make a refusal observable to the HOST, without telling the client
@@ -567,6 +572,16 @@ export function createOxyMiddleware(host: OxyMiddlewareHost) {
         // Handle service tokens (internal service-to-service auth)
         // Service tokens are stateless JWTs with type: 'service' — requires signature verification
         if (decoded.type === 'service') {
+          if (options.liveSession) {
+            const error = {
+              error: 'SESSION_REQUIRED',
+              message: 'A live user session is required',
+              code: 'SESSION_REQUIRED',
+              status: 403,
+            };
+            if (onError) return onError(error);
+            return res.status(403).json(error);
+          }
           // Verify JWT signature, then audience / issuer / type / appId claims.
           //
           // Signature verification uses Node crypto rather than
@@ -1002,6 +1017,7 @@ export function createOxyMiddleware(host: OxyMiddlewareHost) {
             accessToken: token,
             supervisedAction: options.supervisedAction,
             fresh: options.freshSession,
+            ...(options.liveSession ? { liveSession: true } : {}),
           });
 
           if (!validationResult || !validationResult.valid || !validationResult.user) {

package/src/server/session.ts

@@ -16,10 +16,11 @@
  * bearer) — never the raw token — for {@link SESSION_VALIDATION_CACHE_TTL_MS}
  * (30 s) by default, and never past the token's own `exp`.
  *
- * THE SECURITY CONTRACT: the cache never keeps a revoked session alive. Oxy
- * announces every session it ends on its service-event feed
- * (`./serviceEvents.ts`; `@oxy.so/contracts` `sessionRevocation.ts`), and the
- * cache is used ONLY while that feed is live:
+ * Oxy announces ended sessions on its service-event feed (`./serviceEvents.ts`;
+ * `@oxy.so/contracts` `sessionRevocation.ts`), and the cache is used ONLY while
+ * that feed is live. Feed health alone cannot prove that every event was
+ * delivered. Routes requiring a fresh session-row read can opt in to
+ * `liveSession`; see `ServerSessionValidateOptions` for its scope.
  *
  * - no feed (this process has no service token: no credential and no attested
  *   workload, as in a test or a local checkout), a feed not yet connected, a
@@ -46,12 +47,14 @@ import { createHash } from 'node:crypto';
 import {
   type OxySessionRevocationEvent,
   type SupervisedAction,
+  accountActorChainSchema,
   safetySessionInputSchema,
   safetySessionValidationSchema,
 } from '@oxy.so/contracts';
 import { jwtDecode } from 'jwt-decode';
 import type { OxyContext } from '../client/context';
 import { SessionApi, type SessionValidateOptions, type SessionValidation } from '../api/session';
+import { OxyApiError } from '../OxyServices.errors';
 import type { User } from '../models/interfaces';
 import { normalizeUserIdentity } from '../utils/userIdentity';
 
@@ -61,6 +64,17 @@ export const SESSION_VALIDATION_CACHE_TTL_MS = 30_000;
 const SESSION_VALIDATION_CACHE_MAX = 5_000;
 
 export interface ServerSessionValidateOptions extends SessionValidateOptions {
+  /**
+   * Require a session-row read on a PostgreSQL writer. Old servers and
+   * unavailable authority fail closed with 503. The read only reflects commits
+   * visible to its database snapshot; requests already authorized can finish.
+   * This does not make account, grant or supervision data fresh. An unconfirmed
+   * user, grant or policy negative returns 503 rather than invalidating a
+   * session. Expiry is checked against the consumer's clock; skew can cause
+   * unavailability. Each validation reaches Oxy and its activity bookkeeping;
+   * assess database and Redis load before enabling it on a route.
+   */
+  liveSession?: boolean;
   /**
    * A reviewed route category. Oxy then validates the bearer through this
    * service's live `safety:<action>:v1` authority, the only lane a supervised
@@ -121,7 +135,27 @@ export class ServerSessionApi extends SessionApi {
     sessionId: string,
     options: ServerSessionValidateOptions = {},
   ): Promise<SessionValidation> {
-    const { supervisedAction, fresh, ...rest } = options;
+    const { supervisedAction, fresh, liveSession, ...rest } = options;
+    if (liveSession) {
+      if (supervisedAction)
+        throw new OxyApiError('Live supervised session authority is unavailable', {
+          status: 503,
+          code: 'SESSION_AUTHORITY_UNAVAILABLE',
+        });
+      try {
+        const result = await this.validateRequest(sessionId, { ...rest, liveSession: true });
+        const actor = accountActorChainSchema.safeParse(result.actor);
+        if (!actor.success || actor.data.effectiveAccountId !== result.user.id)
+          throw new OxyApiError('Invalid live session authority response', {
+            status: 503,
+            code: 'SESSION_AUTHORITY_UNAVAILABLE',
+          });
+        return result;
+      } catch (error) {
+        if ((error as { status?: unknown } | null)?.status === 401) this.refuse(sessionId);
+        throw error;
+      }
+    }
     if (supervisedAction) return this.validateSupervised(sessionId, supervisedAction, rest);
     if (!rest.accessToken || rest.deviceFingerprint || this.validationTtlMs <= 0) {
       return super.validate(sessionId, rest);