@oxy.so/core 7.16.0 → 7.17.0

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

@@ -8,6 +8,9 @@ import { type WorkloadCredentialProvider } from './workloadIdentity';
 import { type OxyAccountEvent, type OxyAccountEventFeedPage, type OxyMiddleware, type ServiceActingAsVerification, type VerifyAccountEventOptions } from './middleware';
 import { type AppPermissionsOptions, type AppPermissionsRequest, type OxyAppPermissions } from './appPermissions';
 import { ServerAccountsApi, ServerAppsApi, ServerAgencyApi, ServerAssetsApi, ServerLinkedAccountsApi, ServerNotificationsApi, ServerReputationApi } from './namespaces';
+import { type CallerAccessOptions, type OxyAccountAccess, type OxyApplicationAccess } from './callerAccess';
+import type { OxyCallerRequest } from './callerAuthority';
+import { OxyUserClient, type OxyUserSource } from './userClient';
 import { ServerSafetyApi } from './safety';
 import { ServerSessionApi } from './session';
 export interface OxyServerConfig extends OxyConfig {
@@ -47,12 +50,21 @@ export interface OxyServerConfig extends OxyConfig {
      */
     applicationId?: string;
     /**
-     * How long one application-permissions answer is reused, per session
-     * (default 30 000 ms). This is the longest a revoked grant keeps working on
-     * this backend for a read that does not pass `fresh: true`. `0` disables the
-     * cache.
+     * How long one caller-authority answer — `appPermissionsFor`,
+     * `accountAccessFor`, `applicationAccessFor` and their middleware — is
+     * reused, per session (default 30 000 ms). This is the longest a revoked
+     * grant keeps working on this backend for a read that does not pass
+     * `fresh: true`. `0` disables the cache. Only positive answers are kept.
      */
     appPermissionsCacheTtlMs?: number;
+    /**
+     * The service-token audience this backend accepts when a mount names none:
+     * its own `oxy-service:<applicationId>`. Every `middleware.auth()` /
+     * `middleware.service()` mount — and so `createOxyAuthMiddleware`,
+     * `createOptionalOxyAuth` and `createOxyRateLimit` — uses it unless it
+     * passes `expectedAudience` itself. Unset, they accept `oxy-api` (unchanged).
+     */
+    expectedAudience?: string;
     /**
      * How long one successful user-bearer validation (`session.validate` with an
      * `accessToken`, which `middleware.auth()` runs on every request) is reused
@@ -168,6 +180,7 @@ export declare class OxyServer extends OxyServices {
     private readonly configuredApplicationId;
     private readonly sessionValidationTtlMs;
     private readonly appPermissions;
+    private readonly callerAccess;
     /** Opened the first time the validation cache would be used; see `./serviceEvents.ts`. */
     private serviceEventFeed;
     private disposed;
@@ -306,13 +319,67 @@ export declare class OxyServer extends OxyServices {
      */
     appPermissionsFor(req: AppPermissionsRequest, options?: AppPermissionsOptions): Promise<OxyAppPermissions>;
     /**
-     * Drop cached application-permission answers — all of them, or one
-     * person's (as the session user or the resolved operator). For a backend
-     * that learns of a revocation out of band and will not wait out the TTL.
+     * Drop cached caller-authority answers — application permissions and
+     * account / application access — all of them, or one person's (as the
+     * session user or the resolved operator). For a backend that learns of a
+     * revocation out of band and will not wait out the TTL.
      */
     invalidateAppPermissions(filter?: {
         userId?: string;
     }): void;
+    /**
+     * An isolated Oxy client authenticated as the person behind `source` — a
+     * request `middleware.auth()` resolved to a user session, or a bearer you
+     * already verified. Every `OxyServices` namespace, with no response cache,
+     * no token refresh and no fallback to this server's service identity; this
+     * server's own session is never touched.
+     *
+     * Prefer {@link withUser}, which disposes it for you. A client from here
+     * should be disposed when the request ends (`client.dispose()`) so a stray
+     * reference cannot keep using the bearer; one that is not holds no global
+     * resource and is collected normally.
+     *
+     * Throws `OxyAccessError` (`ACCESS_SESSION_REQUIRED`) for a request with no
+     * user session, including one authenticated by a service token.
+     */
+    asUser(source: OxyUserSource): OxyUserClient;
+    /**
+     * Run `use` with a client authenticated as the person behind `source`
+     * ({@link asUser}), and dispose it when `use` settles — success or failure.
+     *
+     * ```ts
+     * const accounts = await oxy.withUser(req, (user) => user.accounts.list());
+     * ```
+     */
+    withUser<T>(source: OxyUserSource, use: (user: OxyUserClient) => T | Promise<T>): Promise<T>;
+    /**
+     * What the person behind `req` may do in Oxy account `accountId` — an
+     * organization, store, channel or their own personal account: relationship,
+     * role, source and the EFFECTIVE permissions (inheritance, grants and
+     * revokes applied). Read with the request's own verified bearer.
+     *
+     * Cached per session for `appPermissionsCacheTtlMs` (30 s), positive
+     * answers only; pass `{ fresh: true }` before a write. Throws
+     * `OxyAccessError`: `ACCESS_SESSION_REQUIRED` (no session, a service token,
+     * or Oxy answered 401), `ACCESS_DENIED` (Oxy answered 403/404 — no access,
+     * or no such account), `ACCESS_UNAVAILABLE` (anything else; never a "no").
+     * Map it with `accessErrorStatus`. Gate on `has(permission)`, never on
+     * `role`.
+     */
+    accountAccessFor(req: OxyCallerRequest, accountId: string, options?: CallerAccessOptions): Promise<OxyAccountAccess>;
+    /**
+     * What the person behind `req` may do to Oxy application `applicationId`,
+     * through their membership of the account that owns it (developer RBAC:
+     * `app:read`, `app:update`, `webhooks:update`, `billing:manage`, …), plus
+     * its `ownerAccountId` and whether it is `official`. Read with the
+     * request's own verified bearer.
+     *
+     * Not {@link appPermissionsFor}: that one answers which of THIS backend's
+     * own declared operator keys the person holds. Same cache, options and
+     * errors as {@link accountAccessFor}; Oxy refuses (403) a caller with no
+     * `app:read`, so a successful answer always includes it.
+     */
+    applicationAccessFor(req: OxyCallerRequest, applicationId: string, options?: CallerAccessOptions): Promise<OxyApplicationAccess>;
     /**
      * Drop cached session validations — all of them, one user's or one
      * session's. Oxy's revocation feed does this by itself; a host may also call

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

@@ -43,6 +43,7 @@
  *
  * Node only; reachable solely from `@oxy.so/core/server`.
  */
+import { authorityErrorBody, type OxyCallerRequest } from './callerAuthority';
 /** Default cache lifetime of one answer. */
 export declare const APP_PERMISSIONS_CACHE_TTL_MS = 30000;
 /** What a refused request is answered with. */
@@ -105,22 +106,13 @@ export interface RequireAppPermissionOptions extends AppPermissionsOptions {
     respond?: boolean;
 }
 /** The request fields the resolver reads — all set by `middleware.auth()`. */
-export interface AppPermissionsRequest {
-    userId?: string | null;
-    sessionId?: string | null;
-    accessToken?: string;
-    serviceApp?: unknown;
+export interface AppPermissionsRequest extends OxyCallerRequest {
     oxyAppPermissions?: OxyAppPermissions;
 }
 /** The status the middleware answers an error with, under `deny`. */
 export declare function appPermissionErrorStatus(error: OxyAppPermissionError, deny?: OxyAppPermissionDenyStatus): number;
 /** The response body for a status: the API error envelope (`docs/api-conventions.md`). */
-export declare function appPermissionErrorBody(status: number): {
-    error: {
-        code: string;
-        message: string;
-    };
-};
+export declare const appPermissionErrorBody: typeof authorityErrorBody;
 /** Throws at MOUNT time on a key that could never be held — a typo is a deploy error. */
 export declare function assertApplicationPermissionKey(permission: unknown): asserts permission is string;
 /** What the resolver needs from the server it belongs to. */
@@ -138,7 +130,6 @@ export interface AppPermissionsHost {
 export declare class OxyAppPermissionsResolver {
     private readonly host;
     private readonly cache;
-    private readonly pending;
     constructor(host: AppPermissionsHost);
     /**
      * What the person behind `req` holds. Throws {@link OxyAppPermissionError};
@@ -152,6 +143,5 @@ export declare class OxyAppPermissionsResolver {
     invalidate(filter?: {
         userId?: string;
     }): void;
-    private remember;
     private lookup;
 }

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

@@ -2,6 +2,7 @@ import type { NextFunction, Request, RequestHandler, Response } from 'express';
 import type { AuthMiddlewareOptions, OxyAuthRefusal, OxyMiddleware, ServiceApp } from './middleware';
 import type { AccountActorChain } from '@oxy.so/contracts';
 import type { OxyAppPermissions } from './appPermissions';
+import type { OxyAccountAccess, OxyApplicationAccess } from './callerAccess';
 import { OXY_SERVICE_ENVIRONMENTS, type OxyServiceEnvironment } from '../utils/oxyServiceEnvironment';
 export { OXY_SERVICE_ENVIRONMENTS };
 export type { OxyServiceEnvironment, OxyAuthRefusal };
@@ -49,6 +50,10 @@ export interface OxyAuthRequest extends Request {
      * request. Its `operatorId` is the human to record as the actor.
      */
     oxyAppPermissions?: OxyAppPermissions;
+    /** Set by `middleware.requireAccountAccess` once it admits the request. */
+    oxyAccountAccess?: OxyAccountAccess;
+    /** Set by `middleware.requireApplicationAccess` once it admits the request. */
+    oxyApplicationAccess?: OxyApplicationAccess;
 }
 export interface OxyAuthenticatedRequest extends OxyAuthRequest {
     userId: string;

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

@@ -0,0 +1,86 @@
+/**
+ * The person behind a request, in an Oxy account and over an Oxy application:
+ * `OxyServer.accountAccessFor` and `OxyServer.applicationAccessFor`.
+ *
+ * Both read Oxy with the request's OWN verified bearer (an `OxyUserClient`),
+ * so Oxy resolves the HUMAN operator from the session — a person acting as
+ * their organization is answered for themselves — with inheritance, per-member
+ * grants and revokes applied. Nothing else the client sends is consulted.
+ *
+ * ```ts
+ * // Can the caller update this store (an Oxy account) in my app?
+ * const access = await oxy.accountAccessFor(req, storeAccountId, { fresh: true });
+ * if (!access.has('account:update')) throw new OxyAccessError('ACCESS_DENIED', '…');
+ *
+ * // Can the caller manage webhooks of application A (developer RBAC)?
+ * const app = await oxy.applicationAccessFor(req, applicationId);
+ * if (!app.has('webhooks:update')) …
+ * ```
+ *
+ * Which reader answers which question is in `./callerAuthority`; the short
+ * version: `appPermissionsFor` is about THIS backend's own declared operator
+ * keys, `applicationAccessFor` about any application through the account that
+ * owns it, `accountAccessFor` about an account. For work with no person
+ * present (a background import), `oxy.accounts.accessFor(accountId, userId)`
+ * asks with the service's own token instead.
+ *
+ * Node only; reachable solely from `@oxy.so/core/server`.
+ */
+import { type AccountAccessSource, type AccountKind } from '@oxy.so/contracts';
+import type { AccountRelationship } from '../api/accounts';
+import { type OxyCallerRequest } from './callerAuthority';
+/** What the person behind a request may do in one Oxy account. */
+export interface OxyAccountAccess {
+    readonly accountId: string;
+    readonly kind: AccountKind;
+    /** `self` for their own personal account, `owner`, or `member` (direct or inherited). */
+    readonly relationship: AccountRelationship;
+    /** Informational; gate on `permissions` / `has`, never on the role name. */
+    readonly role: string;
+    /** Where the access comes from: `self`, a `direct` membership, or one `inherited` from an ancestor. */
+    readonly source: AccountAccessSource;
+    /** The EFFECTIVE account permissions (role baseline, grants, revokes), sorted. */
+    readonly permissions: readonly string[];
+    has(permission: string): boolean;
+}
+/** What the person behind a request may do to one Oxy application, through its owning account. */
+export interface OxyApplicationAccess {
+    readonly applicationId: string;
+    /** The account that owns the application; the access derives from the caller's membership there. */
+    readonly ownerAccountId: string;
+    /** Whether the application is an official Oxy application. */
+    readonly official: boolean;
+    /** Informational; gate on `permissions` / `has`, never on the role name. */
+    readonly role: string;
+    /** The application permissions (`app:read`, `app:update`, `webhooks:update`, …), sorted. */
+    readonly permissions: readonly string[];
+    has(permission: string): boolean;
+}
+export interface CallerAccessOptions {
+    /** Skip the cache and ask Oxy (the answer still refreshes the cache). Use before a write. */
+    fresh?: boolean;
+}
+/** What the readers need from the server they belong to. */
+export interface CallerAccessHost {
+    /** `GET /accounts/:id` with this bearer, uncached. Rejects with the API error. */
+    readAccount(accountId: string, accessToken: string): Promise<unknown>;
+    /** `GET /applications/:id` with this bearer, uncached. Rejects with the API error. */
+    readApplication(applicationId: string, accessToken: string): Promise<unknown>;
+    readonly ttlMs: number;
+}
+/** `GET /accounts/:id` → the caller's effective access, or `null` for a malformed answer. */
+export declare function parseAccountAccess(accountId: string, answer: unknown): OxyAccountAccess | null;
+/** `GET /applications/:id` → the caller's access over it, or `null` for a malformed answer. */
+export declare function parseApplicationAccess(applicationId: string, answer: unknown): OxyApplicationAccess | null;
+/** The caches and lookups behind `accountAccessFor` / `applicationAccessFor`. One per server. */
+export declare class OxyCallerAccessResolver {
+    private readonly host;
+    private readonly accounts;
+    private readonly applications;
+    constructor(host: CallerAccessHost);
+    account(req: OxyCallerRequest, accountId: string, options?: CallerAccessOptions): Promise<OxyAccountAccess>;
+    application(req: OxyCallerRequest, applicationId: string, options?: CallerAccessOptions): Promise<OxyApplicationAccess>;
+    invalidate(filter?: {
+        userId?: string;
+    }): void;
+}

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

@@ -0,0 +1,127 @@
+/**
+ * What every "may the person behind this request …?" read on `OxyServer`
+ * shares: which requests carry a person at all, the one failure type and its
+ * status mapping, the response envelope, and the positive-only answer cache.
+ *
+ * The readers built on it answer different questions — keep them apart:
+ *
+ * | Question | Reader |
+ * |---|---|
+ * | Does this person hold one of MY application's declared operator keys (`payments.operate`)? | `appPermissionsFor` (`./appPermissions`) |
+ * | What may this person do in Oxy account X (an organization, store, channel)? | `accountAccessFor` (`./callerAccess`) |
+ * | What may this person do to application A, through the account that owns it (`app:read`, `app:update`)? | `applicationAccessFor` (`./callerAccess`) |
+ *
+ * ## The outcome mapping, and why an outage is never a "no"
+ *
+ * Every reader asks Oxy with the request's OWN verified bearer and maps the
+ * answer the same way: a 401 means the session is gone (sign in again); a 403
+ * or 404 is Oxy's definitive refusal; anything else — a 5xx, a timeout, a
+ * malformed body — is UNAVAILABLE, answered 503. Only a positive answer is
+ * cached, so a blip can never be remembered as a refusal, and a refusal is
+ * never remembered at all (the next request asks again).
+ *
+ * Node only; reachable solely from `@oxy.so/core/server`.
+ */
+/** The request fields a caller-authority read uses — all set by `middleware.auth()`. */
+export interface OxyCallerRequest {
+    userId?: string | null;
+    sessionId?: string | null;
+    accessToken?: string;
+    /** Set when the request is authenticated by a SERVICE token; such a request carries no person. */
+    serviceApp?: unknown;
+}
+/** The verified person behind a request. */
+export interface OxyCallerSession {
+    readonly userId: string;
+    readonly sessionId: string;
+    readonly accessToken: string;
+}
+/**
+ * The person behind `req`, or why there is none: `service` for a request
+ * authenticated by a service token (delegated or not — its bearer is the
+ * service's, never the person's), `missing` when `middleware.auth()` resolved
+ * no user session.
+ */
+export declare function readCallerSession(req: OxyCallerRequest): {
+    ok: true;
+    session: OxyCallerSession;
+} | {
+    ok: false;
+    reason: 'service' | 'missing';
+};
+/** A bearer that can be put in an `Authorization` header unchanged. */
+export declare function isBearerToken(token: string): boolean;
+/**
+ * - `ACCESS_SESSION_REQUIRED` — no person on the request (anonymous, or a
+ *   service token), or Oxy refused the session (401). Ask them to sign in.
+ * - `ACCESS_DENIED` — Oxy answered "no" (403, 404), or the answer lacks the
+ *   permission a gate required. Definitive.
+ * - `ACCESS_UNAVAILABLE` — Oxy could not be asked or gave no usable answer.
+ *   Fails closed, answered 503, never cached, never a "no".
+ */
+export type OxyAccessErrorCode = 'ACCESS_SESSION_REQUIRED' | 'ACCESS_DENIED' | 'ACCESS_UNAVAILABLE';
+/** The typed failure of `asUser`, `accountAccessFor`, `applicationAccessFor` and their middleware. */
+export declare class OxyAccessError extends Error {
+    readonly code: OxyAccessErrorCode;
+    /** The permission a gate required, when a gate refused. */
+    readonly permission: string | undefined;
+    /** The underlying failure (an `OxyApiError`), if any. Never sent to a client. */
+    readonly cause: unknown;
+    constructor(code: OxyAccessErrorCode, message: string, options?: {
+        permission?: string;
+        cause?: unknown;
+    });
+}
+/** What a refused request is answered with. */
+export type OxyAccessDenyStatus = 403 | 404;
+/**
+ * The status for an {@link OxyAccessError}: `deny` (default `403`) for a
+ * refusal; `401` for no session (`404` when `deny` is `404`, so a hidden
+ * surface stays hidden from the signed-out too); `503` when Oxy could not say.
+ */
+export declare function accessErrorStatus(error: OxyAccessError, deny?: OxyAccessDenyStatus): 401 | 403 | 404 | 503;
+/** The response body for a status: the API error envelope (`docs/api-conventions.md`). */
+export declare function authorityErrorBody(status: number): {
+    error: {
+        code: string;
+        message: string;
+    };
+};
+/** The HTTP status an `OxyApiError` (or anything shaped like one) carries. */
+export declare function errorStatus(error: unknown): number | undefined;
+/**
+ * Map a failed caller-bearer read of Oxy to its outcome: 401 → session
+ * required, 403/404 → denied, everything else → unavailable.
+ */
+export declare function accessFailure(error: unknown, what: string): OxyAccessError;
+/**
+ * The positive-only answer cache one caller-authority reader keeps, keyed by
+ * (resource, session, person). Concurrent identical reads share one lookup; a
+ * `fresh` read skips the cache and refreshes it; a slower, OLDER answer never
+ * overwrites a newer one (the newer may be the fresh read that saw a
+ * revocation); a failure is never stored.
+ */
+export declare class CallerAuthorityCache<T> {
+    private readonly ttlMs;
+    private readonly isAbout;
+    private readonly entries;
+    private readonly pending;
+    /**
+     * @param ttlMs How long an answer is reused; `0` disables the cache.
+     * @param isAbout Whether a cached answer concerns `userId` beyond the
+     *   session's own user (an application-permissions answer names the
+     *   resolved operator), for {@link invalidate}.
+     */
+    constructor(ttlMs: number, isAbout?: (value: T, userId: string) => boolean);
+    read(resourceKey: readonly string[], session: OxyCallerSession, fresh: boolean, lookup: () => Promise<T>): Promise<T>;
+    /** Forget every answer, or those about one person. */
+    invalidate(filter?: {
+        userId?: string;
+    }): void;
+    private remember;
+}
+/** A frozen, sorted permission set with `has`. */
+export declare function permissionSet(permissions: readonly string[]): {
+    readonly permissions: readonly string[];
+    has(permission: string): boolean;
+};

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

@@ -17,10 +17,21 @@ export interface CapabilityTicketVerificationOptions {
     now?: Date;
     maximumTtlSeconds?: number;
 }
+/**
+ * A signing-key lookup that may be asynchronous — `createOxyJwksKeyResolver`
+ * is — for the verifiers that already run asynchronously (the middleware and
+ * `createLiveCapabilityTicketVerifier`). The ticket's own `kid` is passed; no
+ * caller needs to decode the header first.
+ */
+export type CapabilityTicketKeyResolver = (keyId: string) => KeyObject | undefined | Promise<KeyObject | undefined>;
+/** {@link CapabilityTicketVerificationOptions} with a key lookup that may be asynchronous. */
+export interface AsyncCapabilityTicketVerificationOptions extends Omit<CapabilityTicketVerificationOptions, 'resolvePublicKey'> {
+    resolvePublicKey: CapabilityTicketKeyResolver;
+}
 export interface CapabilityTicketRequest extends Request {
     capabilityTicket?: CapabilityTicketClaims;
 }
-export interface CapabilityTicketMiddlewareOptions extends CapabilityTicketVerificationOptions {
+export interface CapabilityTicketMiddlewareOptions extends AsyncCapabilityTicketVerificationOptions {
     authorize: (claims: CapabilityTicketClaims) => Promise<PolicyDecision>;
 }
 export declare class CapabilityTicketError extends Error {
@@ -29,6 +40,17 @@ export declare class CapabilityTicketError extends Error {
 }
 export declare function issueCapabilityTicket(claims: UnsignedCapabilityTicketClaims, options: CapabilityTicketSigningOptions): string;
 export declare function verifyCapabilityTicket(token: string, options: CapabilityTicketVerificationOptions): CapabilityTicketClaims;
+/**
+ * A verifier for one ticket whose key lookup may be asynchronous: the key is
+ * resolved once, and the returned `check` re-verifies signature and claims
+ * against it (the live verifier checks again after introspection, so a slow
+ * authority answer cannot outlive the ticket).
+ *
+ * @internal Shared by the middleware and `createLiveCapabilityTicketVerifier`.
+ */
+export declare function resolveCapabilityTicketKey(token: string, options: AsyncCapabilityTicketVerificationOptions): Promise<{
+    check: () => CapabilityTicketClaims;
+}>;
 export declare function readCapabilityAuthorization(authorization: string | undefined): string | null;
 /**
  * Verifies cryptographic scope first, then asks the authority service for a

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

@@ -87,6 +87,45 @@ export declare function normalizeAppOrigins(appOrigins: string[]): Set<string>;
  * from `server/index.ts`.
  */
 export declare function matchesAllowedOrigin(explicit: ReadonlySet<string>, origin: string): boolean;
+/**
+ * The origin predicate `createOxyCors` applies, for any other transport that
+ * must admit the same browsers: the built-in HTTPS Oxy apex family plus the
+ * exact `appOrigins`, never an opaque origin (`exp://`, `file:`, …).
+ *
+ * ```ts
+ * const allowed = createOxyOriginCheck(['https://app.example.com']);
+ * allowed('https://mention.oxy.so'); // true
+ * ```
+ */
+export declare function createOxyOriginCheck(appOrigins?: string[]): (origin: string) => boolean;
+/** Options of {@link createOxySocketCors}. */
+export interface OxySocketCorsOptions {
+    /** Explicit additional allowed origins, as {@link OxyCorsOptions.appOrigins}. */
+    appOrigins?: string[];
+    /** Whether the polling transport sends `Access-Control-Allow-Credentials: true`. Default `true`. */
+    allowCredentials?: boolean;
+}
+/**
+ * The Socket.IO server options that admit exactly the origins `createOxyCors`
+ * admits — spread them into `new Server(httpServer, { ...createOxySocketCors(…) })`.
+ *
+ * Two halves, because Socket.IO has two transports: `cors` answers the
+ * long-polling requests (which browsers check), and `allowRequest` refuses a
+ * handshake from any other browser origin, which is the only check a WebSocket
+ * upgrade gets — browsers apply no CORS to it. A request with no `Origin`
+ * header (a native app, a server) is not a browser cross-origin request and is
+ * admitted; authenticate it with `oxy.middleware.socket()` as every socket.
+ */
+export declare function createOxySocketCors(options?: OxySocketCorsOptions): {
+    cors: {
+        origin: (origin: string | undefined, callback: (error: Error | null, allow?: boolean) => void) => void;
+        credentials: boolean;
+        methods: string[];
+    };
+    allowRequest: (req: {
+        headers: Record<string, string | string[] | undefined>;
+    }, callback: (error: string | null | undefined, success: boolean) => void) => void;
+};
 /**
  * Create a strict Oxy CORS middleware. See module docs.
  *

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

@@ -4,29 +4,53 @@
  * This subpath export provides Express middleware and Node.js-specific
  * utilities that are not available in React Native or browser environments.
  *
+ * One `OxyServer` per process, authenticated as the backend's own workload
+ * (ADR 0026/0049 — no api key, no client secret):
+ *
  * @example
  * ```ts
- * import { OxyServer, createOxyAuthMiddleware, createOxyRateLimit } from '@oxy.so/core/server';
+ * import {
+ *   OxyServer,
+ *   createOxyAuthMiddleware,
+ *   createOxyCors,
+ *   createOxyRateLimit,
+ *   createOxySecurityHeaders,
+ *   oxyTrustProxy,
+ * } from '@oxy.so/core/server';
  *
- * const oxy = new OxyServer({ baseURL: 'https://api.oxy.so', serviceAuth: { apiKey, apiSecret } });
+ * export const oxy = new OxyServer({
+ *   baseURL: process.env.OXY_API_URL ?? 'https://api.oxy.so',
+ *   applicationId: process.env.OXY_APPLICATION_ID,
+ *   serviceIdentity: 'when-anonymous',
+ * });
  *
+ * app.set('trust proxy', oxyTrustProxy);
+ * app.use(createOxySecurityHeaders(), createOxyCors({ appOrigins }));
  * app.use(createOxyRateLimit(oxy, { store: redisStore }));
  * app.use('/api', createOxyAuthMiddleware(oxy));
+ *
+ * // As the person behind the request, never on the shared client:
+ * const node = await oxy.withUser(req, (user) => user.accounts.get(accountId));
  * ```
  */
 export { OxyServer, ServiceCredentialMismatchError, ANONYMOUS_SERVICE_TOKEN_RETRY_MS, DEFAULT_SERVICE_TOKEN_AUDIENCE, } from './OxyServer';
 export type { OxyServerConfig, ServiceTokenAudience, ServiceTokenResponse } from './OxyServer';
+export { OxyUserClient } from './userClient';
+export type { OxyUserSource } from './userClient';
+export { OxyAccessError, accessErrorStatus } from './callerAuthority';
+export type { OxyAccessDenyStatus, OxyAccessErrorCode, OxyCallerRequest } from './callerAuthority';
+export type { CallerAccessOptions, OxyAccountAccess, OxyApplicationAccess, } from './callerAccess';
 export { ServerAccountsApi, ServerAppsApi, ServerAgencyApi, ServerAssetsApi, ServerLinkedAccountsApi, ServerNotificationsApi, ServerReputationApi, } from './namespaces';
 export { ServerSafetyApi } from './safety';
 export { ServerSessionApi } from './session';
 export type { ServerSessionValidateOptions } from './session';
 export { createOxyAliaMachineCredentialAuth, getOxyAliaMachineCredentialBearer, isOxyAliaMachinePrincipal, OXY_ALIA_RESOURCE_APPLICATION_ID, OXY_ALIA_MACHINE_SCOPES, } from './aliaMachineCredential';
 export type { AliaMachineCredentialIntrospection, OxyAliaMachinePrincipal, OxyAliaMachineRequest, OxyAliaMachineCredentialHost, } from './aliaMachineCredential';
-export type { CapabilityTicketGrant, CapabilityTicketIntrospection, CreateExecutionAuthorizationInput, ServiceCapabilityCatalog, ServiceUploadBody, ServiceUploadDescription, } from './namespaces';
+export type { CapabilityTicketGrant, CapabilityTicketIntrospection, CreateExecutionAuthorizationInput, ServiceCallOptions, ServiceCapabilityCatalog, ServiceUploadBody, ServiceUploadDescription, } from './namespaces';
 export { OxyAccountEventError, OXY_ACCOUNT_DELETED_EVENT_URI } from './middleware';
 export { APP_PERMISSIONS_CACHE_TTL_MS, OxyAppPermissionError, appPermissionErrorStatus, } from './appPermissions';
 export type { AppPermissionsOptions, OxyAppPermissionDenyStatus, OxyAppPermissionErrorCode, OxyAppPermissions, RequireAppPermissionOptions, } from './appPermissions';
-export type { AuthMiddlewareOptions, OxyAccountEvent, OxyAccountEventFeedItem, OxyAccountEventFeedPage, OxyMiddleware, ServiceActingAsVerification, ServiceApp, VerifyAccountEventOptions, } from './middleware';
+export type { AuthMiddlewareOptions, OxyAccountEvent, OxyAccountEventFeedItem, OxyAccountEventFeedPage, OxyMiddleware, RequireAccessOptions, ServiceActingAsVerification, ServiceApp, VerifyAccountEventOptions, } from './middleware';
 export { createOptionalOxyAuth, createOxyAuthMiddleware, getOxyActor, getOxyAuthRefusal, getOxyBillingPrincipal, getOxyDelegatedUserId, getOxyRequestAttribution, getOxyUserId, getRequiredOxyBillingPrincipal, getRequiredOxyUserId, isOxyAuthenticated, requireOxyAuth, OXY_SERVICE_ENVIRONMENTS, } from './auth';
 export type { OxyAuthHost } from './auth';
 export type { OxyAuthenticatedRequest, OxyAuthRefusal, OxyAuthMiddlewareOptions, OxyAuthRequest, OxyBillingPrincipal, OxyRequestAttribution, OxyRequestUser, OxyServiceActingAsContext, OxyServiceAppContext, OxyServiceEnvironment, } from './auth';
@@ -45,12 +69,12 @@ export { STREAM_KEY_AUTHORIZATION_EVENT_TYPE, StreamKeyAuthorizationVerification
 export type { StreamKeyAuthorizationAnswer, StreamKeyAuthorizationRequest, } from './streamKeyAuthorization';
 export { LargeUploadFailedError } from './largeUpload';
 export type { LargeServiceUploadOptions, LargeServiceUploadResult, LargeUploadProgressEvent, LargeUploadSession, LargeUploadSource, } from './largeUpload';
-export { createOxyCors } from './cors';
-export type { OxyCorsOptions } from './cors';
+export { createOxyCors, createOxyOriginCheck, createOxySocketCors } from './cors';
+export type { OxyCorsOptions, OxySocketCorsOptions } from './cors';
 export { buildOxyCspDirectives, buildOxyPagesHeaders, createOxySecurityHeaders, cspSourcesFor, extractInlineScripts, formatOxyCspPolicy, inlineScriptCspHash, OXY_CSP_BASELINE, OXY_FILES_UPLOAD_ORIGIN, } from './securityHeaders';
 export type { OxyCspDirective, OxyCspExtensions, OxyPagesHeadersOptions, OxySecurityHeadersOptions, } from './securityHeaders';
 export { CapabilityTicketError, createCapabilityTicketMiddleware, inputSatisfiesCapabilityLimits, issueCapabilityTicket, readCapabilityAuthorization, verifyCapabilityTicket, } from './capabilityTicket';
-export type { CapabilityTicketMiddlewareOptions, CapabilityTicketRequest, CapabilityTicketSigningOptions, CapabilityTicketVerificationOptions, } from './capabilityTicket';
+export type { AsyncCapabilityTicketVerificationOptions, CapabilityTicketKeyResolver, CapabilityTicketMiddlewareOptions, CapabilityTicketRequest, CapabilityTicketSigningOptions, CapabilityTicketVerificationOptions, } from './capabilityTicket';
 export { createOxyJwksKeyResolver } from './jwks';
 export type { OxyJwksKeyResolverOptions } from './jwks';
 export { OXY_APP_ASSERTION_DEFAULT_ISSUER, OxyAppAssertionError, oxyAppAssertionClaimsSchema, readAppAssertionHeader, readOxyAppAssertionKeyId, signOxyAppAssertion, verifyAppAssertion, verifyOxyAppAssertion, } from './appAssertion';

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

@@ -1,7 +1,11 @@
 import { type CapabilityTicketClaims } from '@oxy.so/contracts';
-import { type CapabilityTicketVerificationOptions } from './capabilityTicket';
+import { type AsyncCapabilityTicketVerificationOptions } from './capabilityTicket';
 import type { CapabilityTicketIntrospection } from './namespaces';
-export interface LiveCapabilityTicketVerifierOptions extends CapabilityTicketVerificationOptions {
+/**
+ * `resolvePublicKey` may be asynchronous — pass `createOxyJwksKeyResolver({ jwksUrl })`
+ * as it is; the ticket's `kid` is looked up once per verification.
+ */
+export interface LiveCapabilityTicketVerifierOptions extends AsyncCapabilityTicketVerificationOptions {
     issuer: string;
     introspect: (ticket: string, options: {
         signal: AbortSignal;