@oxy.so/core 7.15.1 → 7.17.0

package/src/server/appPermissions.ts

@@ -46,11 +46,17 @@
 
 import { applicationRolesMeSchema, isApplicationPermissionKey } from '@oxy.so/contracts';
 import { logger } from '../logger';
+import {
+  authorityErrorBody,
+  CallerAuthorityCache,
+  errorStatus,
+  permissionSet,
+  readCallerSession,
+  type OxyCallerRequest,
+} from './callerAuthority';
 
 /** Default cache lifetime of one answer. */
 export const APP_PERMISSIONS_CACHE_TTL_MS = 30_000;
-/** Entries kept per server; the oldest goes first. */
-const APP_PERMISSIONS_CACHE_MAX = 1000;
 
 /** What a refused request is answered with. */
 export type OxyAppPermissionDenyStatus = 403 | 404;
@@ -130,11 +136,7 @@ export interface RequireAppPermissionOptions extends AppPermissionsOptions {
 }
 
 /** 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;
 }
 
@@ -156,22 +158,7 @@ export function appPermissionErrorStatus(
 }
 
 /** The response body for a status: the API error envelope (`docs/api-conventions.md`). */
-export function appPermissionErrorBody(status: number): {
-  error: { code: string; message: string };
-} {
-  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: unknown): asserts permission is string {
@@ -187,20 +174,7 @@ function heldPermissions(
   operatorId: string,
   permissions: readonly string[],
 ): OxyAppPermissions {
-  const sorted = Object.freeze([...new Set(permissions)].sort());
-  const set = new Set(sorted);
-  return Object.freeze({
-    applicationId,
-    operatorId,
-    permissions: sorted,
-    has: (permission: string) => set.has(permission),
-  });
-}
-
-interface CacheEntry {
-  value: OxyAppPermissions;
-  startedAt: number;
-  expiresAt: number;
+  return Object.freeze({ applicationId, operatorId, ...permissionSet(permissions) });
 }
 
 /** What the resolver needs from the server it belongs to. */
@@ -212,20 +186,19 @@ export interface AppPermissionsHost {
   readonly ttlMs: number;
 }
 
-function errorStatus(error: unknown): number | undefined {
-  const status = (error as { status?: unknown } | null)?.status;
-  return typeof status === 'number' ? status : undefined;
-}
-
 /**
  * The cache and the lookup behind `OxyServer.appPermissionsFor` and
  * `middleware.requireAppPermission`. One per server.
  */
 export class OxyAppPermissionsResolver {
-  private readonly cache = new Map<string, CacheEntry>();
-  private readonly pending = new Map<string, Promise<OxyAppPermissions>>();
+  private readonly cache: CallerAuthorityCache<OxyAppPermissions>;
 
-  constructor(private readonly host: AppPermissionsHost) {}
+  constructor(private readonly host: AppPermissionsHost) {
+    this.cache = new CallerAuthorityCache<OxyAppPermissions>(
+      host.ttlMs,
+      (value, userId) => value.operatorId === userId,
+    );
+  }
 
   /**
    * What the person behind `req` holds. Throws {@link OxyAppPermissionError};
@@ -235,21 +208,13 @@ export class OxyAppPermissionsResolver {
     req: AppPermissionsRequest,
     options: AppPermissionsOptions = {},
   ): Promise<OxyAppPermissions> {
-    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) {
+    const caller = readCallerSession(req);
+    if (!caller.ok) {
       throw new OxyAppPermissionError(
         'APP_PERMISSION_SESSION_REQUIRED',
-        'No verified user session on this request; mount middleware.auth() first',
+        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',
       );
     }
 
@@ -272,30 +237,10 @@ export class OxyAppPermissionsResolver {
       );
     }
 
-    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),
+    );
   }
 
   /**
@@ -303,29 +248,7 @@ export class OxyAppPermissionsResolver {
    * either the session's user or the resolved operator).
    */
   invalidate(filter: { userId?: string } = {}): void {
-    if (!filter.userId) {
-      this.cache.clear();
-      return;
-    }
-    for (const [key, entry] of this.cache) {
-      const [, , userId] = JSON.parse(key) as [string, string, string];
-      if (userId === filter.userId || entry.value.operatorId === filter.userId) {
-        this.cache.delete(key);
-      }
-    }
-  }
-
-  private remember(key: string, value: OxyAppPermissions, startedAt: number, ttl: number): void {
-    // 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);
   }
 
   private async lookup(applicationId: string, accessToken: string): Promise<OxyAppPermissions> {

package/src/server/auth.ts

@@ -7,6 +7,7 @@ import type {
 } from './middleware';
 import type { AccountActorChain } from '@oxy.so/contracts';
 import type { OxyAppPermissions } from './appPermissions';
+import type { OxyAccountAccess, OxyApplicationAccess } from './callerAccess';
 import { logger } from '../logger';
 import {
   OXY_SERVICE_ENVIRONMENTS,
@@ -56,6 +57,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 {

package/src/server/callerAccess.ts

@@ -0,0 +1,232 @@
+/**
+ * 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 {
+  accountAccessGrantSchema,
+  type AccountAccessSource,
+  type AccountKind,
+} from '@oxy.so/contracts';
+import type { AccountRelationship } from '../api/accounts';
+import {
+  accessFailure,
+  CallerAuthorityCache,
+  OxyAccessError,
+  permissionSet,
+  readCallerSession,
+  type OxyCallerRequest,
+  type OxyCallerSession,
+} 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;
+}
+
+function callerSession(req: OxyCallerRequest): OxyCallerSession {
+  const caller = readCallerSession(req);
+  if (caller.ok) return caller.session;
+  throw new 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: unknown, what: string): string {
+  if (typeof id !== 'string' || id.trim() === '') {
+    throw new TypeError(`${what} must be a non-empty string`);
+  }
+  return id;
+}
+
+function record(value: unknown): Record<string, unknown> | null {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : null;
+}
+
+function stringArray(value: unknown): string[] | null {
+  return Array.isArray(value) && value.every((entry) => typeof entry === 'string')
+    ? (value as string[])
+    : null;
+}
+
+const RELATIONSHIPS: readonly AccountRelationship[] = ['self', 'owner', 'member'];
+
+/** `GET /accounts/:id` → the caller's effective access, or `null` for a malformed answer. */
+export function parseAccountAccess(accountId: string, answer: unknown): OxyAccountAccess | null {
+  const node = record(answer);
+  if (!node || node.accountId !== accountId) return null;
+  const relationship = node.relationship as AccountRelationship;
+  if (!RELATIONSHIPS.includes(relationship) || typeof node.kind !== 'string') return null;
+  const grant = accountAccessGrantSchema.safeParse(node.callerAccess);
+  if (!grant.success) return null;
+  return Object.freeze({
+    accountId,
+    kind: node.kind as AccountKind,
+    relationship,
+    role: grant.data.role,
+    source: grant.data.source,
+    ...permissionSet(grant.data.permissions),
+  });
+}
+
+/** `GET /applications/:id` → the caller's access over it, or `null` for a malformed answer. */
+export function parseApplicationAccess(
+  applicationId: string,
+  answer: unknown,
+): OxyApplicationAccess | null {
+  const application = record(answer);
+  if (!application || application._id !== applicationId) return null;
+  const ownerAccountId = application.ownerAccountId;
+  const membership = record(application.callerMembership);
+  const permissions = stringArray(membership?.permissions);
+  if (
+    typeof ownerAccountId !== 'string' ||
+    ownerAccountId === '' ||
+    typeof application.isOfficial !== 'boolean' ||
+    !membership ||
+    typeof membership.role !== 'string' ||
+    membership.role === '' ||
+    membership.ownerAccountId !== ownerAccountId ||
+    !permissions
+  ) {
+    return null;
+  }
+  return Object.freeze({
+    applicationId,
+    ownerAccountId,
+    official: application.isOfficial,
+    role: membership.role,
+    ...permissionSet(permissions),
+  });
+}
+
+/** The caches and lookups behind `accountAccessFor` / `applicationAccessFor`. One per server. */
+export class OxyCallerAccessResolver {
+  private readonly accounts: CallerAuthorityCache<OxyAccountAccess>;
+  private readonly applications: CallerAuthorityCache<OxyApplicationAccess>;
+
+  constructor(private readonly host: CallerAccessHost) {
+    this.accounts = new CallerAuthorityCache<OxyAccountAccess>(host.ttlMs);
+    this.applications = new CallerAuthorityCache<OxyApplicationAccess>(host.ttlMs);
+  }
+
+  async account(
+    req: OxyCallerRequest,
+    accountId: string,
+    options: CallerAccessOptions = {},
+  ): Promise<OxyAccountAccess> {
+    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: unknown) => {
+          throw accessFailure(error, `account ${id}`);
+        });
+      const access = parseAccountAccess(id, answer);
+      if (!access) {
+        throw new OxyAccessError(
+          'ACCESS_UNAVAILABLE',
+          `Oxy answered account ${id} without the caller's access`,
+        );
+      }
+      return access;
+    });
+  }
+
+  async application(
+    req: OxyCallerRequest,
+    applicationId: string,
+    options: CallerAccessOptions = {},
+  ): Promise<OxyApplicationAccess> {
+    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: unknown) => {
+          throw accessFailure(error, `application ${id}`);
+        });
+      const access = parseApplicationAccess(id, answer);
+      if (!access) {
+        throw new OxyAccessError(
+          'ACCESS_UNAVAILABLE',
+          `Oxy answered application ${id} without the caller's access`,
+        );
+      }
+      return access;
+    });
+  }
+
+  invalidate(filter: { userId?: string } = {}): void {
+    this.accounts.invalidate(filter);
+    this.applications.invalidate(filter);
+  }
+}