@oxy.so/core 7.16.0 → 7.17.0

package/dist/cjs/server/safeFetch.js

@@ -29,6 +29,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.
@@ -46,6 +56,7 @@ const node_https_1 = __importDefault(require("node:https"));
 const promises_1 = require("node:dns/promises");
 const node_net_1 = require("node:net");
 const node_url_1 = require("node:url");
+const officialOrigins_1 = require("../utils/officialOrigins");
 const deadline_1 = require("./deadline");
 const ipCidr_1 = require("./ipCidr");
 /** Maximum accepted length of an input URL (DoS guard). */
@@ -255,6 +266,21 @@ async function assertSafePublicUrl(rawUrl, options = {}) {
         family: chosen.family === 4 ? 4 : 6,
     };
 }
+/** What a refusal of a first-party Oxy host adds to its reason. */
+const FIRST_PARTY_HOST_HINT = 'first-party Oxy host: inside the VPC it resolves to a private address, which safeFetch refuses by design; call it through OxyServer (its namespaces, serviceRequest, or createServiceClient().fetch), not safeFetch';
+/** `reason`, plus the first-party hint when `rawUrl` names an official Oxy host. */
+function rejectionReason(rawUrl, reason) {
+    let origin;
+    try {
+        origin = new node_url_1.URL(rawUrl).origin;
+    }
+    catch {
+        return reason;
+    }
+    return (0, officialOrigins_1.isOfficialWebOrigin)(origin) && !(0, officialOrigins_1.isLoopbackOrigin)(origin)
+        ? `${reason} (${FIRST_PARTY_HOST_HINT})`
+        : reason;
+}
 /** Marker error for a blocked SSRF target (map to 403 at the route layer). */
 class SsrfRejection extends Error {
     constructor(reason) {
@@ -353,7 +379,9 @@ async function safeFetch(rawUrl, options = {}) {
             signal,
         });
         if (!guard.ok) {
-            throw guard.incomplete ? new UpstreamError(guard.reason) : new SsrfRejection(guard.reason);
+            throw guard.incomplete
+                ? new UpstreamError(guard.reason)
+                : new SsrfRejection(rejectionReason(currentUrl, guard.reason));
         }
         const target = new node_url_1.URL(currentUrl);
         const requestOptions = buildRequestOptions(target, guard.ip, guard.family, method, baseHeaders, signal);

package/dist/cjs/server/userClient.js

@@ -0,0 +1,127 @@
+"use strict";
+/**
+ * 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`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OxyUserClient = void 0;
+exports.userClientConfig = userClientConfig;
+exports.userBearerOf = userBearerOf;
+const OxyServices_1 = require("../OxyServices");
+const callerAuthority_1 = require("./callerAuthority");
+/** The transport settings a user client inherits from its server; never auth, cache or app identity. */
+const INHERITED_TRANSPORT_KEYS = [
+    'baseURL',
+    'cloudURL',
+    'requestTimeout',
+    'enableRetry',
+    'maxRetries',
+    'retryDelay',
+    'maxConcurrentRequests',
+    'requestQueueSize',
+    'enableLogging',
+    'logLevel',
+    'onRequestStart',
+    'onRequestEnd',
+    'onRequestError',
+];
+/** The transport half of a server config, for a user client. */
+function userClientConfig(config) {
+    const transport = {};
+    for (const key of INHERITED_TRANSPORT_KEYS) {
+        if (config[key] !== undefined)
+            transport[key] = config[key];
+    }
+    return { ...transport, enableCache: false };
+}
+/**
+ * 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.
+ */
+function userBearerOf(source) {
+    if (typeof source === 'string') {
+        if (!(0, callerAuthority_1.isBearerToken)(source)) {
+            throw new callerAuthority_1.OxyAccessError('ACCESS_SESSION_REQUIRED', 'A user client needs a bearer token');
+        }
+        return source;
+    }
+    if (source.serviceApp) {
+        throw new callerAuthority_1.OxyAccessError('ACCESS_SESSION_REQUIRED', 'This request is authenticated by a service token; a user client needs a person’s session');
+    }
+    const token = source.accessToken;
+    if (typeof token !== 'string' || !(0, callerAuthority_1.isBearerToken)(token)) {
+        throw new callerAuthority_1.OxyAccessError('ACCESS_SESSION_REQUIRED', 'No verified user session on this request; mount middleware.auth() first');
+    }
+    return token;
+}
+/**
+ * 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.
+ */
+class OxyUserClient extends OxyServices_1.OxyServices {
+    /** @internal Use `OxyServer.asUser` / `OxyServer.withUser`. */
+    constructor(config, accessToken) {
+        super(config);
+        this.bearer = accessToken;
+        // For the namespaces that read the session's identity (`session.userId`).
+        this.http.setTokens(accessToken);
+    }
+    /**
+     * 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.
+     */
+    async request(method, url, data, options = {}) {
+        const bearer = this.bearer;
+        if (!bearer)
+            throw new Error('This Oxy user client has been disposed');
+        // This client speaks as its person only: no caller-supplied credential,
+        // in any letter case, rides along.
+        const headers = {};
+        for (const [name, value] of Object.entries(options.headers ?? {})) {
+            if (name.toLowerCase() !== 'authorization')
+                headers[name] = value;
+        }
+        headers.Authorization = `Bearer ${bearer}`;
+        return super.request(method, url, data, { ...options, headers });
+    }
+    /** Forget the bearer: every later call rejects. */
+    dispose() {
+        this.bearer = null;
+        super.dispose();
+    }
+}
+exports.OxyUserClient = OxyUserClient;

package/dist/cjs/utils/cache.js

@@ -11,6 +11,7 @@ exports.createCache = createCache;
 exports.registerCacheForCleanup = registerCacheForCleanup;
 exports.unregisterCacheFromCleanup = unregisterCacheFromCleanup;
 exports.stopAllCleanupIntervals = stopAllCleanupIntervals;
+exports.sweptCacheCount = sweptCacheCount;
 /**
  * TTL-based cache implementation
  *
@@ -48,6 +49,10 @@ class TTLCache {
         this.cache = new Map();
         this.hits = 0;
         this.misses = 0;
+        /** Registered for the shared expiry sweep (see {@link registerCacheForCleanup}). */
+        this.swept = false;
+        /** The sweep generation this cache registered in; {@link stopAllCleanupIntervals} ends it. */
+        this.sweptGeneration = -1;
         this.defaultTTL = defaultTTL;
         this.maxEntries = maxEntries;
     }
@@ -66,6 +71,7 @@ class TTLCache {
         if (now >= entry.expiresAt) {
             this.cache.delete(key);
             this.misses++;
+            this.syncSweep();
             return null;
         }
         // Re-insert so Map order is recency order and eviction drops the LRU.
@@ -97,8 +103,7 @@ class TTLCache {
             if (oldest !== undefined)
                 this.cache.delete(oldest);
         }
-        if (!cleanupInterval && activeCaches.has(this))
-            updateCleanupInterval();
+        this.syncSweep();
     }
     /**
      * Delete a specific cache entry
@@ -107,10 +112,8 @@ class TTLCache {
      */
     delete(key) {
         const deleted = this.cache.delete(key);
-        // Only the delete that EMPTIES this cache can let the timer stop; checking
-        // on every delete made bulk invalidation O(deletes x caches).
-        if (deleted && this.cache.size === 0 && activeCaches.has(this))
-            updateCleanupInterval();
+        if (deleted)
+            this.syncSweep();
         return deleted;
     }
     /**
@@ -120,8 +123,7 @@ class TTLCache {
         this.cache.clear();
         this.hits = 0;
         this.misses = 0;
-        if (activeCaches.has(this))
-            updateCleanupInterval();
+        this.syncSweep();
     }
     /**
      * Delete every entry whose key matches, in ONE pass.
@@ -135,8 +137,8 @@ class TTLCache {
                 removed++;
             }
         }
-        if (removed > 0 && this.cache.size === 0 && activeCaches.has(this))
-            updateCleanupInterval();
+        if (removed > 0)
+            this.syncSweep();
         return removed;
     }
     /**
@@ -150,6 +152,7 @@ class TTLCache {
             return false;
         if (Date.now() >= entry.expiresAt) {
             this.cache.delete(key);
+            this.syncSweep();
             return false;
         }
         return true;
@@ -169,6 +172,7 @@ class TTLCache {
                 this.cache.delete(key);
             }
         }
+        this.syncSweep();
         return validKeys;
     }
     /**
@@ -184,8 +188,29 @@ class TTLCache {
                 removed++;
             }
         }
+        if (removed > 0)
+            this.syncSweep();
         return removed;
     }
+    /**
+     * 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) {
+        this.swept = swept;
+        this.sweptGeneration = sweepGeneration;
+        this.syncSweep();
+    }
+    syncSweep() {
+        if (this.swept && this.sweptGeneration === sweepGeneration && this.cache.size > 0) {
+            sweptCaches.add(this);
+        }
+        else {
+            sweptCaches.delete(this);
+        }
+        updateCleanupInterval();
+    }
     /**
      * Get cache size (number of entries)
      */
@@ -225,23 +250,30 @@ function createCache(ttl = 5 * 60 * 1000) {
     return new TTLCache(ttl);
 }
 /**
- * Global cache cleanup interval (runs every minute)
- * This helps prevent memory leaks from expired cache entries
+ * The shared expiry sweep: one unref'd interval, running only while some
+ * registered cache holds entries.
+ *
+ * `sweptCaches` holds exactly the registered caches that are NON-EMPTY. A
+ * cache joins when it gains its first entry and leaves when it is emptied — by
+ * the sweep itself once its entries expire — so the module never pins a cache
+ * that has nothing to expire. That is what keeps a short-lived client that was
+ * never disposed (one per request, say) collectable: the most it can be held
+ * for is its entries' TTL.
  */
 let cleanupInterval = null;
-const activeCaches = new Set();
+const sweptCaches = new Set();
+/** Bumped by {@link stopAllCleanupIntervals}, which ends every registration. */
+let sweepGeneration = 0;
 /**
  * Register a cache for automatic cleanup
  * @param cache Cache instance to register
  */
 function registerCacheForCleanup(cache) {
-    activeCaches.add(cache);
-    updateCleanupInterval();
+    cache.setSwept(true);
 }
 /** Empty registered caches need no timer; importing a client must stay inert. */
 function updateCleanupInterval() {
-    const hasEntries = [...activeCaches].some((cache) => cache.size() > 0);
-    if (!hasEntries) {
+    if (sweptCaches.size === 0) {
         if (cleanupInterval)
             clearInterval(cleanupInterval);
         cleanupInterval = null;
@@ -250,25 +282,29 @@ function updateCleanupInterval() {
     if (cleanupInterval)
         return;
     cleanupInterval = setInterval(() => {
-        for (const cache of activeCaches)
+        // `cleanup()` removes an emptied cache from the set as it goes.
+        for (const cache of [...sweptCaches])
             cache.cleanup();
-        updateCleanupInterval();
     }, 60000);
     cleanupInterval.unref?.();
 }
 /** Unregister a cache without changing its entries or TTL behavior. */
 function unregisterCacheFromCleanup(cache) {
-    activeCaches.delete(cache);
-    updateCleanupInterval();
+    cache.setSwept(false);
 }
 /**
  * Stop all cleanup intervals (useful for testing)
  * This will clear the interval and unregister all caches
  */
 function stopAllCleanupIntervals() {
+    sweepGeneration += 1;
+    sweptCaches.clear();
     if (cleanupInterval) {
         clearInterval(cleanupInterval);
         cleanupInterval = null;
     }
-    activeCaches.clear();
+}
+/** How many caches the shared sweep currently holds (tests). @internal */
+function sweptCacheCount() {
+    return sweptCaches.size;
 }

package/dist/esm/server/OxyServer.js

@@ -52,6 +52,8 @@ import { canAttestWorkloadIdentity, requestWorkloadServiceToken, } from './workl
 import { createOxyMiddleware, OXY_ACCOUNT_DELETED_EVENT_URI, OXY_JWT_ISSUER, OxyAccountEventError, parseJsonSegment, resolveServiceTokenPublicKey, } from './middleware.js';
 import { APP_PERMISSIONS_CACHE_TTL_MS, OxyAppPermissionsResolver, } from './appPermissions.js';
 import { ServerAccountsApi, ServerAppsApi, ServerAgencyApi, ServerAssetsApi, ServerLinkedAccountsApi, ServerNotificationsApi, ServerReputationApi, } from './namespaces.js';
+import { OxyCallerAccessResolver, } from './callerAccess.js';
+import { OxyUserClient, userBearerOf, userClientConfig } from './userClient.js';
 import { ServerSafetyApi } from './safety.js';
 import { SESSION_VALIDATION_CACHE_TTL_MS, ServerSessionApi } from './session.js';
 import { OxyServiceEventFeed } from './serviceEvents.js';
@@ -166,15 +168,24 @@ 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),
         });
     }
     /** A product SDK transport authenticated only by this process's workload. */
@@ -601,12 +612,83 @@ export class OxyServer extends OxyServices {
         return this.appPermissions.resolve(req, options);
     }
     /**
-     * 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 = {}) {
         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) {
+        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(source, use) {
+        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, accountId, options = {}) {
+        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, applicationId, options = {}) {
+        return this.callerAccess.application(req, applicationId, options);
     }
     /**
      * Drop cached session validations — all of them, one user's or one

package/dist/esm/server/appPermissions.js

@@ -45,10 +45,9 @@
  */
 import { applicationRolesMeSchema, isApplicationPermissionKey } from '@oxy.so/contracts';
 import { logger } from '../logger/index.js';
+import { authorityErrorBody, CallerAuthorityCache, errorStatus, permissionSet, readCallerSession, } from './callerAuthority.js';
 /** Default cache lifetime of one answer. */
 export const APP_PERMISSIONS_CACHE_TTL_MS = 30000;
-/** Entries kept per server; the oldest goes first. */
-const APP_PERMISSIONS_CACHE_MAX = 1000;
 /** The typed failure of {@link OxyAppPermissionsResolver.resolve} and the middleware. */
 export class OxyAppPermissionError extends Error {
     constructor(code, message, options = {}) {
@@ -73,20 +72,7 @@ export function appPermissionErrorStatus(error, deny = 404) {
     }
 }
 /** The response body for a status: the API error envelope (`docs/api-conventions.md`). */
-export function appPermissionErrorBody(status) {
-    switch (status) {
-        case 401:
-            return { error: { code: 'unauthorized', message: 'Authentication required' } };
-        case 403:
-            return { error: { code: 'forbidden', message: 'Not permitted' } };
-        case 404:
-            return { error: { code: 'not_found', message: 'Not found' } };
-        case 503:
-            return { error: { code: 'service_unavailable', message: 'Temporarily unavailable' } };
-        default:
-            return { error: { code: 'internal_error', message: 'Internal error' } };
-    }
-}
+export const appPermissionErrorBody = authorityErrorBody;
 /** Throws at MOUNT time on a key that could never be held — a typo is a deploy error. */
 export function assertApplicationPermissionKey(permission) {
     if (!isApplicationPermissionKey(permission)) {
@@ -94,18 +80,7 @@ export function assertApplicationPermissionKey(permission) {
     }
 }
 function heldPermissions(applicationId, operatorId, permissions) {
-    const sorted = Object.freeze([...new Set(permissions)].sort());
-    const set = new Set(sorted);
-    return Object.freeze({
-        applicationId,
-        operatorId,
-        permissions: sorted,
-        has: (permission) => set.has(permission),
-    });
-}
-function errorStatus(error) {
-    const status = error?.status;
-    return typeof status === 'number' ? status : undefined;
+    return Object.freeze({ applicationId, operatorId, ...permissionSet(permissions) });
 }
 /**
  * The cache and the lookup behind `OxyServer.appPermissionsFor` and
@@ -114,22 +89,18 @@ function errorStatus(error) {
 export class OxyAppPermissionsResolver {
     constructor(host) {
         this.host = host;
-        this.cache = new Map();
-        this.pending = new Map();
+        this.cache = new CallerAuthorityCache(host.ttlMs, (value, userId) => value.operatorId === userId);
     }
     /**
      * What the person behind `req` holds. Throws {@link OxyAppPermissionError};
      * never answers "nothing held" for a failure.
      */
     async resolve(req, options = {}) {
-        if (req.serviceApp) {
-            throw new OxyAppPermissionError('APP_PERMISSION_SESSION_REQUIRED', 'Application permissions are held by a person in a session; this request is authenticated by a service token');
-        }
-        const userId = typeof req.userId === 'string' && req.userId.length > 0 ? req.userId : null;
-        const sessionId = typeof req.sessionId === 'string' && req.sessionId.length > 0 ? req.sessionId : null;
-        const accessToken = typeof req.accessToken === 'string' && req.accessToken.length > 0 ? req.accessToken : null;
-        if (!userId || !sessionId || !accessToken) {
-            throw new OxyAppPermissionError('APP_PERMISSION_SESSION_REQUIRED', 'No verified user session on this request; mount middleware.auth() first');
+        const caller = readCallerSession(req);
+        if (!caller.ok) {
+            throw new OxyAppPermissionError('APP_PERMISSION_SESSION_REQUIRED', caller.reason === 'service'
+                ? 'Application permissions are held by a person in a session; this request is authenticated by a service token'
+                : 'No verified user session on this request; mount middleware.auth() first');
         }
         let applicationId = options.applicationId ?? null;
         if (!applicationId) {
@@ -143,63 +114,15 @@ export class OxyAppPermissionsResolver {
         if (!applicationId) {
             throw new OxyAppPermissionError('APP_PERMISSION_NOT_CONFIGURED', 'No application id: set OxyServerConfig.applicationId, configure service auth, or pass { applicationId }');
         }
-        const key = JSON.stringify([applicationId, sessionId, userId]);
-        const ttl = this.host.ttlMs;
-        if (options.fresh !== true && ttl > 0) {
-            const cached = this.cache.get(key);
-            if (cached && cached.expiresAt > Date.now()) {
-                return cached.value;
-            }
-            const inFlight = this.pending.get(key);
-            if (inFlight)
-                return inFlight;
-        }
-        const startedAt = Date.now();
-        const lookup = this.lookup(applicationId, accessToken).then((value) => {
-            if (ttl > 0)
-                this.remember(key, value, startedAt, ttl);
-            return value;
-        });
-        if (options.fresh === true || ttl <= 0)
-            return lookup;
-        this.pending.set(key, lookup);
-        try {
-            return await lookup;
-        }
-        finally {
-            if (this.pending.get(key) === lookup)
-                this.pending.delete(key);
-        }
+        const appId = applicationId;
+        return this.cache.read([appId], caller.session, options.fresh === true, () => this.lookup(appId, caller.session.accessToken));
     }
     /**
      * Forget cached answers: every one, or those about one person (matched as
      * either the session's user or the resolved operator).
      */
     invalidate(filter = {}) {
-        if (!filter.userId) {
-            this.cache.clear();
-            return;
-        }
-        for (const [key, entry] of this.cache) {
-            const [, , userId] = JSON.parse(key);
-            if (userId === filter.userId || entry.value.operatorId === filter.userId) {
-                this.cache.delete(key);
-            }
-        }
-    }
-    remember(key, value, startedAt, ttl) {
-        // A slower, OLDER read must not overwrite a newer one — the newer one may
-        // be the fresh read that saw a revocation.
-        const existing = this.cache.get(key);
-        if (existing && existing.startedAt > startedAt)
-            return;
-        this.cache.delete(key);
-        this.cache.set(key, { value, startedAt, expiresAt: startedAt + ttl });
-        if (this.cache.size > APP_PERMISSIONS_CACHE_MAX) {
-            const oldest = this.cache.keys().next().value;
-            if (oldest !== undefined)
-                this.cache.delete(oldest);
-        }
+        this.cache.invalidate(filter);
     }
     async lookup(applicationId, accessToken) {
         let answer;