@oxy.so/core 7.16.0 → 7.18.0

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

@@ -1,13 +1,16 @@
 /**
  * The Express and Socket.IO middleware `OxyServer` mounts
  * (`server.middleware.auth()`, `.socket()`, `.service()`, `.requireScope()`,
- * `.requireAppPermission()`),
+ * `.requireAppPermission()`, `.requireAccountAccess()`,
+ * `.requireApplicationAccess()`),
  * and the Ed25519 service-token and account-event verification they share.
  *
  * Node only; reachable solely from `@oxy.so/core/server`.
  */
 import type { OxyRequestUser } from './auth';
 import { type AppPermissionsOptions, type AppPermissionsRequest, type OxyAppPermissions, type RequireAppPermissionOptions } from './appPermissions';
+import { type OxyAccessDenyStatus } from './callerAuthority';
+import type { CallerAccessOptions, OxyAccountAccess, OxyApplicationAccess } from './callerAccess';
 import { type AccountActorChain, type SupervisedAction, type ServiceIntrospection } from '@oxy.so/contracts';
 import type { ApiError, User } from '../models/interfaces';
 import { type OxyServiceEnvironment } from '../utils/oxyServiceEnvironment';
@@ -221,7 +224,8 @@ export interface AuthMiddlewareOptions {
      * Own product receivers use their SDK's canonical `oxy-service:<appId>` audience.
      * First-party tokens must name that recipient exactly. External scoped tokens
      * also retain the legacy `oxy-api` audience. Other audience overrides remain exact.
-     * Oxy API defaults to `oxy-api`.
+     * Defaults to `OxyServerConfig.expectedAudience` when the server sets one,
+     * else `oxy-api`.
      */
     expectedAudience?: string;
 }
@@ -232,6 +236,8 @@ export interface AuthMiddlewareOptions {
  */
 export interface OxyMiddlewareHost {
     readonly baseURL: string;
+    /** `OxyServerConfig.expectedAudience`: the audience `auth()` accepts when a mount names none. */
+    readonly defaultAudience?: string;
     readonly jwksCache: ServiceTokenJwksCache;
     validateSession(sessionId: string, options?: {
         deviceFingerprint?: string;
@@ -258,6 +264,27 @@ export interface OxyMiddlewareHost {
     introspectServiceToken?(token: string): Promise<ServiceIntrospection>;
     /** `OxyServer.appPermissionsFor` — what the person behind a request holds for this app. */
     appPermissionsFor(req: AppPermissionsRequest, options?: AppPermissionsOptions): Promise<OxyAppPermissions>;
+    /** `OxyServer.accountAccessFor`. */
+    accountAccessFor(req: AuthReq, accountId: string, options?: CallerAccessOptions): Promise<OxyAccountAccess>;
+    /** `OxyServer.applicationAccessFor`. */
+    applicationAccessFor(req: AuthReq, applicationId: string, options?: CallerAccessOptions): Promise<OxyApplicationAccess>;
+}
+/** Options of `middleware.requireAccountAccess` / `requireApplicationAccess`. */
+export interface RequireAccessOptions extends CallerAccessOptions {
+    /** The route parameter that names the account or application (`':appId'` → `'appId'`). */
+    param: string;
+    /**
+     * What a refusal is answered: `403` (default; `401` without a session) or
+     * `404` (`404` without a session too), for a surface that must not reveal
+     * what exists. Oxy unreachable is always `503`.
+     */
+    deny?: OxyAccessDenyStatus;
+    /**
+     * `false` hands the {@link OxyAccessError} to `next(error)` instead of
+     * answering; `accessErrorStatus(error, deny)` gives the status the
+     * middleware would have used.
+     */
+    respond?: boolean;
 }
 /** Build the middleware set for one server. See `OxyServer.middleware`. */
 export declare function createOxyMiddleware(host: OxyMiddlewareHost): {
@@ -276,6 +303,8 @@ export declare function createOxyMiddleware(host: OxyMiddlewareHost): {
     }) => (req: AuthReq, res: AuthRes, next: AuthNext) => Promise<void>;
     requireScope: (scope: string) => (req: AuthReq, res: AuthRes, next: AuthNext) => void;
     requireAppPermission: (permission: string, options?: RequireAppPermissionOptions) => (req: AuthReq, res: AuthRes, next: AuthNext) => Promise<void>;
+    requireAccountAccess: (permission: string, options: RequireAccessOptions) => (req: AuthReq, res: AuthRes, next: AuthNext) => Promise<void>;
+    requireApplicationAccess: (permission: string, options: RequireAccessOptions) => (req: AuthReq, res: AuthRes, next: AuthNext) => Promise<void>;
 };
 /** The middleware set `OxyServer.middleware` exposes. */
 export type OxyMiddleware = ReturnType<typeof createOxyMiddleware>;
@@ -318,6 +347,9 @@ interface AuthReq {
     oxyActor?: AccountActorChain | null;
     oxyAuthRefusal?: OxyAuthRefusal;
     oxyAppPermissions?: OxyAppPermissions;
+    oxyAccountAccess?: OxyAccountAccess;
+    oxyApplicationAccess?: OxyApplicationAccess;
+    params?: Record<string, string | string[] | undefined>;
 }
 interface AuthRes {
     status(code: number): AuthRes;

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

@@ -22,6 +22,19 @@ import { type BatchLookup } from '../utils/batchLookup';
 /** The bytes of a streamed service upload: sent as the whole request body. */
 export type ServiceUploadBody = Uint8Array | ArrayBuffer | Blob;
 /** What `uploadAppFile` and `uploadUserMedia` may say about the bytes besides their type. */
+/**
+ * Per-call transport options for a service call, overriding the server's
+ * `requestTimeout` / `enableRetry` for that one call — so one `OxyServer` can
+ * make a short, single-shot write and a patient read side by side.
+ */
+export interface ServiceCallOptions {
+    /** Abort the call. */
+    signal?: AbortSignal;
+    /** Per-attempt timeout in ms. */
+    timeout?: number;
+    /** `false` sends the call once; a transient failure is the caller's to retry (an outbox). */
+    retry?: boolean;
+}
 export interface ServiceUploadDescription {
     /**
      * Stored as the file's original name. Sent as a header, so only printable
@@ -62,10 +75,13 @@ export declare class ServerAssetsApi extends AssetsApi {
      *   changes the file's visibility.
      * - `remove`: only references this application holds. Never trashes or
      *   deletes the file.
+     *
+     * Both take {@link ServiceCallOptions} for each request they send — e.g.
+     * `{ retry: false, timeout: 5000 }` from an outbox that retries by itself.
      */
     readonly references: {
-        add: (references: ServiceFileReference[]) => Promise<ServiceFileReferenceResult[]>;
-        remove: (references: ServiceFileReference[]) => Promise<ServiceFileReferenceResult[]>;
+        add: (references: ServiceFileReference[], options?: ServiceCallOptions) => Promise<ServiceFileReferenceResult[]>;
+        remove: (references: ServiceFileReference[], options?: ServiceCallOptions) => Promise<ServiceFileReferenceResult[]>;
         /**
          * Reconcile this application's references of ONE entity type with its
          * real inventory (ADR 0043 D6) — the safety net for a reference a crash or

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

@@ -28,6 +28,16 @@
  *    response; without one, a server that sends its headers and stalls holds
  *    any other reader open.
  *
+ * NOT FOR OXY'S OWN HOSTS
+ * -----------------------
+ * `safeFetch` is for UNTRUSTED or caller-influenced URLs only. Never use it to
+ * reach a first-party host (`api.oxy.so`, any `*.oxy.so`, an Oxy product's
+ * API): inside the VPC those names resolve to the internal load balancer
+ * (split-horizon DNS), a private address this module refuses by design. Call
+ * Oxy through `OxyServer` — its namespaces, `serviceRequest`, or
+ * `createServiceClient({ baseURL, audience }).fetch` for another Oxy product.
+ * A refusal of such a host says so in its message.
+ *
  * Node-only: this module imports `node:http`/`node:https`/`node:dns` and is
  * exported solely from `@oxy.so/core/server`. It MUST NOT be reachable from the
  * browser `@oxy.so/core` entry.

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

@@ -0,0 +1,71 @@
+/**
+ * Calling Oxy AS the person behind a request.
+ *
+ * A backend's `OxyServer` is a process singleton authenticated as the backend
+ * itself; a user's bearer must never be planted on it (`setTokens`,
+ * `session.setAccessToken`), because every concurrent request would then speak
+ * as that user. A read that must be answered for the person — their own
+ * account graph, an application they manage, their profile — goes through an
+ * {@link OxyUserClient}: every namespace of `OxyServices`, bound to that one
+ * bearer, sharing no mutable state with the server.
+ *
+ * ```ts
+ * // Express, after oxy.middleware.auth():
+ * const node = await oxy.withUser(req, (user) => user.accounts.get(accountId));
+ * ```
+ *
+ * What makes it safe to create one per request:
+ *
+ * - **No response cache.** The client is built with `enableCache: false`, so
+ *   one person's answers are never served to anyone, including the same
+ *   person's next request, and nothing is registered with the module-wide
+ *   cache sweep.
+ * - **Exactly this bearer, every time.** Every request carries it as an
+ *   explicit `Authorization` header: never refreshed (that is the user's own
+ *   client's job), never dropped for an expired or opaque token, never
+ *   replaced by the server's service token. Oxy answers a revoked or expired
+ *   bearer 401, which the access readers map to `ACCESS_SESSION_REQUIRED`.
+ * - **Deterministic end.** `withUser` disposes the client when the callback
+ *   settles, so a reference that escapes the callback holds no bearer. A
+ *   client from `asUser` that is never disposed holds no global resource
+ *   either; it is collected with its last reference.
+ *
+ * Node only; reachable solely from `@oxy.so/core/server`.
+ */
+import { OxyServices, type OxyConfig } from '../OxyServices';
+import type { HttpMethod } from '../client/context';
+import type { RequestOptions, ResponsePayload } from '../HttpService';
+import { type OxyCallerRequest } from './callerAuthority';
+/**
+ * Whose bearer a user client carries: a request `middleware.auth()` resolved
+ * to a user session (its `req.accessToken`), or a bearer string the caller has
+ * already verified (a Socket.IO handshake's `socket.accessToken`, say).
+ */
+export type OxyUserSource = string | OxyCallerRequest;
+/** The transport half of a server config, for a user client. */
+export declare function userClientConfig(config: Readonly<OxyConfig>): OxyConfig;
+/**
+ * The user bearer `source` carries. Throws `OxyAccessError`
+ * (`ACCESS_SESSION_REQUIRED`) for a request with no user session — anonymous,
+ * or authenticated by a SERVICE token, whose bearer is the calling service's
+ * and never a person's.
+ */
+export declare function userBearerOf(source: OxyUserSource): string;
+/**
+ * Every `OxyServices` namespace, authenticated as one person. Create it with
+ * `OxyServer.withUser` (disposed for you) or `OxyServer.asUser` (dispose it
+ * yourself); the constructor is not part of the public contract.
+ */
+export declare class OxyUserClient extends OxyServices {
+    private bearer;
+    /** @internal Use `OxyServer.asUser` / `OxyServer.withUser`. */
+    constructor(config: OxyConfig, accessToken: string);
+    /**
+     * Every namespace call goes through here: it carries this client's bearer
+     * explicitly, which also keeps the response out of any cache and out of
+     * request de-duplication. Rejects once the client is disposed.
+     */
+    request<T>(method: HttpMethod, url: string, data?: unknown, options?: RequestOptions): Promise<ResponsePayload<T>>;
+    /** Forget the bearer: every later call rejects. */
+    dispose(): void;
+}

package/dist/types/utils/cache.d.ts

@@ -45,6 +45,10 @@ export declare class TTLCache<T> {
     private hits;
     private misses;
     private maxEntries;
+    /** Registered for the shared expiry sweep (see {@link registerCacheForCleanup}). */
+    private swept;
+    /** The sweep generation this cache registered in; {@link stopAllCleanupIntervals} ends it. */
+    private sweptGeneration;
     /**
      * Create a new TTL cache
      * @param defaultTTL Default TTL in milliseconds (default: 5 minutes)
@@ -99,6 +103,13 @@ export declare class TTLCache<T> {
      * @returns Number of entries removed
      */
     cleanup(): number;
+    /**
+     * Start or stop being swept: a registered cache is held by the shared sweep
+     * ONLY while it has entries to expire. An empty cache is referenced by
+     * nothing global, so a client nobody disposed is collected with its cache.
+     */
+    setSwept(swept: boolean): void;
+    private syncSweep;
     /**
      * Get cache size (number of entries)
      */
@@ -133,3 +144,5 @@ export declare function unregisterCacheFromCleanup(cache: TTLCache<unknown>): vo
  * This will clear the interval and unregister all caches
  */
 export declare function stopAllCleanupIntervals(): void;
+/** How many caches the shared sweep currently holds (tests). @internal */
+export declare function sweptCacheCount(): number;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oxy.so/core",
-  "version": "7.16.0",
+  "version": "7.18.0",
   "description": "OxyHQ SDK Foundation — API client, authentication, cryptographic identity, and shared utilities",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",

package/src/api/accounts.ts

@@ -1,4 +1,4 @@
-import type { OrganizationType } from '@oxy.so/contracts';
+import type { AccountAccessGrant, OrganizationType } from '@oxy.so/contracts';
 /**
  * `oxy.accounts` — the unified account graph (`/accounts`).
  *
@@ -163,6 +163,13 @@ export interface AccountNode {
    * ownership is implicit). Use `callerMembership.permissions` to gate UI.
    */
   callerMembership: AccountMember | null;
+  /**
+   * The caller's EFFECTIVE access to this account — role, permissions and
+   * where it comes from, `self` included (where `callerMembership` is `null`).
+   * Present on single-account reads (`accounts.get`); a backend asks
+   * `OxyServer.accountAccessFor`.
+   */
+  callerAccess?: AccountAccessGrant;
   /** Number of direct child accounts (present when the API computes it). */
   childCount?: number;
   /** Direct children, populated when the list is requested with `tree:true`. */

package/src/api/apps.ts

@@ -30,7 +30,7 @@ import {
   parseContract,
 } from '@oxy.so/contracts/client';
 import type { OxyContext } from '../client/context';
-import type { AccountMember, AccountSuccessResult } from './accounts';
+import type { AccountMember, AccountRole, AccountSuccessResult } from './accounts';
 
 const SHORT_TTL = 60 * 1000;
 const MEDIUM_TTL = 2 * 60 * 1000;
@@ -123,13 +123,32 @@ export interface Application {
   createdAt: string;
   updatedAt: string;
   /**
-   * The caller's effective membership in the OWNING account (direct or
-   * inherited), embedded by the API on list/detail responses, or `null` when the
-   * caller has no membership. Use `callerMembership.permissions` to gate UI.
+   * The caller's access to this application, derived from their effective
+   * role over the OWNING account (direct or inherited), embedded by the API on
+   * list/detail responses, or `null` when the caller has no membership. Use
+   * `callerMembership.permissions` to gate UI; a backend asks
+   * `OxyServer.applicationAccessFor`.
+   *
+   * The wire shape is {@link ApplicationCallerMembership} — only `role` and
+   * `permissions` of this `AccountMember` type are present. The type is
+   * corrected in 8.0 (ADR 0054); changing it in a minor would break compiles.
    */
   callerMembership?: AccountMember | null;
 }
 
+/**
+ * The caller's access to an application as the API actually embeds it: the role they
+ * hold over the owning account and the APPLICATION permissions it maps to
+ * (`app:read`, `app:update`, `webhooks:update`, …). There is no per-application
+ * member row, so this is not an `AccountMember`.
+ */
+export interface ApplicationCallerMembership {
+  role: AccountRole;
+  permissions: string[];
+  source: 'account';
+  ownerAccountId: string;
+}
+
 /**
  * Client-facing ApplicationCredential shape (an application's OAuth client
  * credentials). The raw secret is NEVER part of this shape — it is returned

package/src/index.ts

@@ -159,6 +159,7 @@ export type {
   AppsApi,
   AppAssertionsApi,
   Application,
+  ApplicationCallerMembership,
   ApplicationType,
   ApplicationStatus,
   ApplicationCredential,

package/src/server/OxyServer.ts

@@ -106,6 +106,14 @@ import {
   ServerNotificationsApi,
   ServerReputationApi,
 } from './namespaces';
+import {
+  OxyCallerAccessResolver,
+  type CallerAccessOptions,
+  type OxyAccountAccess,
+  type OxyApplicationAccess,
+} from './callerAccess';
+import type { OxyCallerRequest } from './callerAuthority';
+import { OxyUserClient, userBearerOf, userClientConfig, type OxyUserSource } from './userClient';
 import { ServerSafetyApi } from './safety';
 import { SESSION_VALIDATION_CACHE_TTL_MS, ServerSessionApi } from './session';
 import { OxyServiceEventFeed } from './serviceEvents';
@@ -145,12 +153,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
@@ -316,6 +333,7 @@ export class OxyServer extends OxyServices {
   private readonly configuredApplicationId: string | null;
   private readonly sessionValidationTtlMs: number;
   private readonly appPermissions: OxyAppPermissionsResolver;
+  private readonly callerAccess: OxyCallerAccessResolver;
   /** Opened the first time the validation cache would be used; see `./serviceEvents.ts`. */
   private serviceEventFeed: OxyServiceEventFeed | null = null;
   private disposed = false;
@@ -364,15 +382,27 @@ export class OxyServer extends OxyServices {
       defaultApplicationId: () => this.defaultApplicationId(),
       fetchRolesMe: (applicationId, accessToken) => this.fetchRolesMe(applicationId, accessToken),
     });
+    this.callerAccess = new OxyCallerAccessResolver({
+      ttlMs: ttl,
+      readAccount: (accountId, accessToken) =>
+        this.withUser(accessToken, (user) => user.accounts.get(accountId)),
+      readApplication: (applicationId, accessToken) =>
+        this.withUser(accessToken, (user) => user.apps.get(applicationId)),
+    });
+    const defaultAudience = config.expectedAudience?.trim() || undefined;
     this.middleware = createOxyMiddleware({
       get baseURL() {
         return server.baseURL;
       },
+      defaultAudience,
       jwksCache: this.jwksCache,
       validateSession: (sessionId, options) => this.session.validate(sessionId, options),
       verifyActingAs: (appId, userId, options) => this.verifyActingAs(appId, userId, options),
       introspectServiceToken: (token) => this.introspectServiceToken(token),
       appPermissionsFor: (req, options) => this.appPermissionsFor(req, options),
+      accountAccessFor: (req, accountId, options) => this.accountAccessFor(req, accountId, options),
+      applicationAccessFor: (req, applicationId, options) =>
+        this.applicationAccessFor(req, applicationId, options),
     });
   }
 
@@ -909,12 +939,101 @@ export class OxyServer extends OxyServices {
   }
 
   /**
-   * 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 {
     this.appPermissions.invalidate(filter);
+    this.callerAccess.invalidate(filter);
+  }
+
+  // ── The requesting person ────────────────────────────────────────────────
+
+  /**
+   * 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 {
+    const config = userClientConfig(this.config);
+    return new OxyUserClient(
+      { ...config, baseURL: this.baseURL, cloudURL: this.cloudURL },
+      userBearerOf(source),
+    );
+  }
+
+  /**
+   * 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());
+   * ```
+   */
+  async withUser<T>(
+    source: OxyUserSource,
+    use: (user: OxyUserClient) => T | Promise<T>,
+  ): Promise<T> {
+    const user = this.asUser(source);
+    try {
+      return await use(user);
+    } finally {
+      user.dispose();
+    }
+  }
+
+  /**
+   * 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> {
+    return this.callerAccess.account(req, accountId, options);
+  }
+
+  /**
+   * 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> {
+    return this.callerAccess.application(req, applicationId, options);
   }
 
   /**