@oxy.so/core 7.16.0 → 7.18.0

package/README.md

@@ -31,7 +31,7 @@ The package exposes two public entry points:
 - `@oxy.so/core/session` — `SessionClient`, the account dialog controller, auth-state stores, cold boot
 - `@oxy.so/core/crypto` — `KeyManager`, `SignatureService`, `RecoveryPhraseService` and the primitives under them
 - `@oxy.so/core/civic`, `@oxy.so/core/inference`, `@oxy.so/core/logger`
-- `@oxy.so/core/server` — `OxyServer` (service tokens, `middleware.*`) and the Express helpers (`createOxyRateLimit`, `createOxyAuthMiddleware`, `requireOxyAuth`, `getOxyUserId`, `getRequiredOxyUserId`, `createOxyCors`, `createOxySecurityHeaders`, `buildOxyCspDirectives`, `safeFetch`, `verifySecret`, and request types)
+- `@oxy.so/core/server` — `OxyServer` (workload service tokens, `middleware.*`, `withUser` / `asUser`, `appPermissionsFor`, `accountAccessFor`, `applicationAccessFor`) and the Express helpers (`createOxyRateLimit`, `createOxyAuthMiddleware`, `getOxyUserId`, `getRequiredOxyUserId`, `createOxyCors`, `createOxySocketCors`, `createOxySecurityHeaders`, `buildOxyCspDirectives`, `safeFetch`, `verifySecret`, and request types)
 
 Heavy pieces have their own entries so an app ships only what it uses; React Native and browser bundles never import Express. The full API map is [docs/api.mdx](./docs/api.mdx).
 
@@ -136,34 +136,45 @@ Caching is left to the consumer's own layer (React Query / stores). Pass
 `oxy.createLinkedClient({ baseURL, enableCache: true })` to opt back in when the
 consumer accepts responsibility for invalidation.
 
-## Backend Auth Middleware
+## Backends
 
-Backends should use the SDK server helpers instead of local auth request types
-or `requireAuth` copies.
+A backend uses ONE `OxyServer` per process. An Oxy-owned backend authenticates
+as its workload (ADR 0026/0049): no api key, no client secret.
 
 ```ts
-import { OxyServices } from '@oxy.so/core';
 import {
+  OxyServer,
+  createOxyAuthMiddleware,
   createOxyRateLimit,
-  requireOxyAuth,
   getRequiredOxyUserId,
   type OxyAuthRequest,
 } from '@oxy.so/core/server';
 
-const oxy = new OxyServices({ baseURL: 'https://api.oxy.so' });
+export const oxy = new OxyServer({
+  baseURL: 'https://api.oxy.so',
+  applicationId: process.env.OXY_APPLICATION_ID,
+  serviceIdentity: 'when-anonymous',
+});
 
 app.use(createOxyRateLimit(oxy, { store: redisStore }));
-router.use(requireOxyAuth);
+app.use('/api', createOxyAuthMiddleware(oxy));
 
 router.get('/me', (req: OxyAuthRequest, res) => {
-  const userId = getRequiredOxyUserId(req);
-  res.json({ userId });
+  res.json({ userId: getRequiredOxyUserId(req) });
+});
+
+// As the person behind the request — never on the shared client:
+router.get('/orgs/:accountId', async (req, res) => {
+  const access = await oxy.accountAccessFor(req, req.params.accountId);
+  res.json({ canEdit: access.has('account:update') });
 });
 ```
 
-For routers that are not mounted after `createOxyRateLimit`, use
-`createOxyAuthMiddleware(oxy)` to resolve the bearer session and require a user
-in one middleware.
+`createOxyAuthMiddleware(oxy)` resolves the bearer session and requires a user
+in one middleware; `createOptionalOxyAuth(oxy)` is the optional form. The
+permission questions (`appPermissionsFor`, `accountAccessFor`,
+`applicationAccessFor`), user clients (`withUser`), files and outbound HTTP are
+in [Building a backend](./docs/backend.mdx).
 
 ## Security Headers And CSP
 

package/dist/cjs/server/OxyServer.js

@@ -55,6 +55,8 @@ const workloadIdentity_1 = require("./workloadIdentity");
 const middleware_1 = require("./middleware");
 const appPermissions_1 = require("./appPermissions");
 const namespaces_1 = require("./namespaces");
+const callerAccess_1 = require("./callerAccess");
+const userClient_1 = require("./userClient");
 const safety_1 = require("./safety");
 const session_1 = require("./session");
 const serviceEvents_1 = require("./serviceEvents");
@@ -170,15 +172,24 @@ class OxyServer extends OxyServices_1.OxyServices {
             defaultApplicationId: () => this.defaultApplicationId(),
             fetchRolesMe: (applicationId, accessToken) => this.fetchRolesMe(applicationId, accessToken),
         });
+        this.callerAccess = new callerAccess_1.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 = (0, middleware_1.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. */
@@ -605,12 +616,83 @@ class OxyServer extends OxyServices_1.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 = (0, userClient_1.userClientConfig)(this.config);
+        return new userClient_1.OxyUserClient({ ...config, baseURL: this.baseURL, cloudURL: this.cloudURL }, (0, userClient_1.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/cjs/server/appPermissions.js

@@ -45,16 +45,14 @@
  * Node only; reachable solely from `@oxy.so/core/server`.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.OxyAppPermissionsResolver = exports.OxyAppPermissionError = exports.APP_PERMISSIONS_CACHE_TTL_MS = void 0;
+exports.OxyAppPermissionsResolver = exports.appPermissionErrorBody = exports.OxyAppPermissionError = exports.APP_PERMISSIONS_CACHE_TTL_MS = void 0;
 exports.appPermissionErrorStatus = appPermissionErrorStatus;
-exports.appPermissionErrorBody = appPermissionErrorBody;
 exports.assertApplicationPermissionKey = assertApplicationPermissionKey;
 const contracts_1 = require("@oxy.so/contracts");
 const logger_1 = require("../logger");
+const callerAuthority_1 = require("./callerAuthority");
 /** Default cache lifetime of one answer. */
 exports.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. */
 class OxyAppPermissionError extends Error {
     constructor(code, message, options = {}) {
@@ -80,20 +78,7 @@ function appPermissionErrorStatus(error, deny = 404) {
     }
 }
 /** The response body for a status: the API error envelope (`docs/api-conventions.md`). */
-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' } };
-    }
-}
+exports.appPermissionErrorBody = callerAuthority_1.authorityErrorBody;
 /** Throws at MOUNT time on a key that could never be held — a typo is a deploy error. */
 function assertApplicationPermissionKey(permission) {
     if (!(0, contracts_1.isApplicationPermissionKey)(permission)) {
@@ -101,18 +86,7 @@ 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, ...(0, callerAuthority_1.permissionSet)(permissions) });
 }
 /**
  * The cache and the lookup behind `OxyServer.appPermissionsFor` and
@@ -121,22 +95,18 @@ function errorStatus(error) {
 class OxyAppPermissionsResolver {
     constructor(host) {
         this.host = host;
-        this.cache = new Map();
-        this.pending = new Map();
+        this.cache = new callerAuthority_1.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 = (0, callerAuthority_1.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) {
@@ -150,63 +120,15 @@ 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;
@@ -214,7 +136,7 @@ class OxyAppPermissionsResolver {
             answer = await this.host.fetchRolesMe(applicationId, accessToken);
         }
         catch (error) {
-            const status = errorStatus(error);
+            const status = (0, callerAuthority_1.errorStatus)(error);
             if (status === 401) {
                 throw new OxyAppPermissionError('APP_PERMISSION_SESSION_REQUIRED', 'Oxy refused the session while resolving application permissions', { cause: error });
             }

package/dist/cjs/server/callerAccess.js

@@ -0,0 +1,170 @@
+"use strict";
+/**
+ * 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`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OxyCallerAccessResolver = void 0;
+exports.parseAccountAccess = parseAccountAccess;
+exports.parseApplicationAccess = parseApplicationAccess;
+const contracts_1 = require("@oxy.so/contracts");
+const callerAuthority_1 = require("./callerAuthority");
+function callerSession(req) {
+    const caller = (0, callerAuthority_1.readCallerSession)(req);
+    if (caller.ok)
+        return caller.session;
+    throw new callerAuthority_1.OxyAccessError('ACCESS_SESSION_REQUIRED', caller.reason === 'service'
+        ? 'This request is authenticated by a service token; account and application access belong to a person in a session'
+        : 'No verified user session on this request; mount middleware.auth() first');
+}
+function requireId(id, what) {
+    if (typeof id !== 'string' || id.trim() === '') {
+        throw new TypeError(`${what} must be a non-empty string`);
+    }
+    return id;
+}
+function record(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value)
+        ? value
+        : null;
+}
+function stringArray(value) {
+    return Array.isArray(value) && value.every((entry) => typeof entry === 'string')
+        ? value
+        : null;
+}
+const RELATIONSHIPS = ['self', 'owner', 'member'];
+const APPLICATION_TYPES = [
+    'first_party',
+    'third_party',
+    'internal',
+    'system',
+];
+const OFFICIAL_TYPES = ['first_party', 'internal', 'system'];
+/** `deleted` is absent on purpose: Oxy answers a deleted application 404. */
+const APPLICATION_STATUSES = [
+    'active',
+    'suspended',
+    'pending_review',
+];
+/** `GET /accounts/:id` → the caller's effective access, or `null` for a malformed answer. */
+function parseAccountAccess(accountId, answer) {
+    const node = record(answer);
+    if (!node || node.accountId !== accountId)
+        return null;
+    const relationship = node.relationship;
+    if (!RELATIONSHIPS.includes(relationship) || typeof node.kind !== 'string')
+        return null;
+    const grant = contracts_1.accountAccessGrantSchema.safeParse(node.callerAccess);
+    if (!grant.success)
+        return null;
+    return Object.freeze({
+        accountId,
+        kind: node.kind,
+        relationship,
+        role: grant.data.role,
+        source: grant.data.source,
+        ...(0, callerAuthority_1.permissionSet)(grant.data.permissions),
+    });
+}
+/** `GET /applications/:id` → the caller's access over it, or `null` for a malformed answer. */
+function parseApplicationAccess(applicationId, answer) {
+    const application = record(answer);
+    if (!application || application._id !== applicationId)
+        return null;
+    const ownerAccountId = application.ownerAccountId;
+    const type = application.type;
+    const status = application.status;
+    const membership = record(application.callerMembership);
+    const permissions = stringArray(membership?.permissions);
+    if (typeof ownerAccountId !== 'string' ||
+        ownerAccountId === '' ||
+        typeof application.isOfficial !== 'boolean' ||
+        typeof application.isInternal !== 'boolean' ||
+        !APPLICATION_TYPES.includes(type) ||
+        !APPLICATION_STATUSES.includes(status) ||
+        !membership ||
+        typeof membership.role !== 'string' ||
+        membership.role === '' ||
+        membership.ownerAccountId !== ownerAccountId ||
+        !permissions) {
+        return null;
+    }
+    return Object.freeze({
+        applicationId,
+        ownerAccountId,
+        official: application.isOfficial || application.isInternal || OFFICIAL_TYPES.includes(type),
+        status,
+        role: membership.role,
+        ...(0, callerAuthority_1.permissionSet)(permissions),
+    });
+}
+/** The caches and lookups behind `accountAccessFor` / `applicationAccessFor`. One per server. */
+class OxyCallerAccessResolver {
+    constructor(host) {
+        this.host = host;
+        this.accounts = new callerAuthority_1.CallerAuthorityCache(host.ttlMs);
+        this.applications = new callerAuthority_1.CallerAuthorityCache(host.ttlMs);
+    }
+    async account(req, accountId, options = {}) {
+        const id = requireId(accountId, 'accountId');
+        const session = callerSession(req);
+        return this.accounts.read([id], session, options.fresh === true, async () => {
+            const answer = await this.host
+                .readAccount(id, session.accessToken)
+                .catch((error) => {
+                throw (0, callerAuthority_1.accessFailure)(error, `account ${id}`);
+            });
+            const access = parseAccountAccess(id, answer);
+            if (!access) {
+                throw new callerAuthority_1.OxyAccessError('ACCESS_UNAVAILABLE', `Oxy answered account ${id} without the caller's access`);
+            }
+            return access;
+        });
+    }
+    async application(req, applicationId, options = {}) {
+        const id = requireId(applicationId, 'applicationId');
+        const session = callerSession(req);
+        return this.applications.read([id], session, options.fresh === true, async () => {
+            const answer = await this.host
+                .readApplication(id, session.accessToken)
+                .catch((error) => {
+                throw (0, callerAuthority_1.accessFailure)(error, `application ${id}`);
+            });
+            const access = parseApplicationAccess(id, answer);
+            if (!access) {
+                throw new callerAuthority_1.OxyAccessError('ACCESS_UNAVAILABLE', `Oxy answered application ${id} without the caller's access`);
+            }
+            return access;
+        });
+    }
+    invalidate(filter = {}) {
+        this.accounts.invalidate(filter);
+        this.applications.invalidate(filter);
+    }
+}
+exports.OxyCallerAccessResolver = OxyCallerAccessResolver;