@commonpub/layer 0.29.0 → 0.31.0

package/server/utils/permissions.ts

@@ -0,0 +1,97 @@
+/**
+ * Cached per-user permission resolver (Nitro util).
+ *
+ * Wraps the pure `resolveUserPermissions` core (@commonpub/server) with a short
+ * TTL + bounded LRU + explicit invalidation — modeled on `config.ts`'s DB-cache
+ * pattern and `layoutCache.ts`'s bounded map. Lives in the LAYER (not the app)
+ * so it ships to every consumer via @commonpub/layer: the auth middleware,
+ * `requireAdmin`, and `requirePermission` that consume it are all in the layer,
+ * and the layer already calls `useDB()`/`useConfig()` from layer code on every
+ * instance (see middleware/auth.ts). See docs/plans/rbac.md (Phase 0 location
+ * correction).
+ *
+ * The flag lives ONLY here (in the resolver), never in the guards —
+ * `requireFeature('rbac')` would 404 admin endpoints when off. With the flag
+ * off, the core returns the legacy mapping (admin→all, else→none) ⇒
+ * byte-identical to pre-RBAC (INV-1).
+ *
+ * Auth-critical → 30s TTL (favor freshness so a demote/revoke takes effect
+ * within the window, not on re-login — the set is never baked into the session
+ * token). Invalidate AFTER the DB commit; per-process so it clears the local
+ * node only (≤30s elsewhere — documented multi-pod staleness, acceptable v1).
+ */
+import { resolveUserPermissions, type ResolvedPermissions } from '@commonpub/server';
+
+export const PERMISSIONS_CACHE_TTL_MS = 30_000;
+
+/** Caps memory across adversarial/large user populations (bounded LRU). */
+export const MAX_PERMISSION_ENTRIES = 5000;
+
+interface CacheEntry {
+  value: ResolvedPermissions;
+  at: number;
+}
+
+const cache = new Map<string, CacheEntry>();
+
+function readFresh(userId: string, now: number): ResolvedPermissions | null {
+  const entry = cache.get(userId);
+  if (!entry) return null;
+  if (now - entry.at > PERMISSIONS_CACHE_TTL_MS) {
+    cache.delete(userId);
+    return null;
+  }
+  // LRU touch — move to newest end so eviction stays O(1) oldest-first.
+  cache.delete(userId);
+  cache.set(userId, entry);
+  return entry.value;
+}
+
+function store(userId: string, value: ResolvedPermissions, now: number): void {
+  if (cache.has(userId)) cache.delete(userId);
+  cache.set(userId, { value, at: now });
+  while (cache.size > MAX_PERMISSION_ENTRIES) {
+    const oldest = cache.keys().next().value;
+    if (oldest === undefined) break;
+    cache.delete(oldest);
+  }
+}
+
+/**
+ * Resolve (and cache) a user's effective permissions. Reads the `features.rbac`
+ * flag from the merged config; never throws (the core default-denies on error,
+ * and the admin floor is enforced downstream via `primaryRole`).
+ *
+ * @param primaryRole the already-enriched `users.role` (the auth middleware has
+ *   it). Passing it lets the core skip its own users query — so the admin and
+ *   flag-off hot paths do ZERO extra DB work — and keeps resolution consistent
+ *   with the enrich query.
+ */
+export async function resolvePermissions(
+  userId: string,
+  primaryRole?: string,
+): Promise<ResolvedPermissions> {
+  const now = Date.now();
+  const cached = readFresh(userId, now);
+  if (cached) return cached;
+
+  const rbacEnabled = useConfig().features.rbac === true;
+  const resolved = await resolveUserPermissions(useDB(), userId, { rbacEnabled, primaryRole });
+  store(userId, resolved, now);
+  return resolved;
+}
+
+/** Drop one user's cached permissions. Call AFTER a role/grant DB commit. */
+export function invalidatePermissions(userId: string): void {
+  cache.delete(userId);
+}
+
+/** Drop the whole cache — the RBAC kill-switch companion to flipping the flag off. */
+export function invalidateAllPermissions(): void {
+  cache.clear();
+}
+
+/** Cache size — test-only inspection. */
+export function _permissionsCacheSize(): number {
+  return cache.size;
+}

package/server/utils/requirePermission.ts

@@ -0,0 +1,102 @@
+import { hasPermissionPure } from '@commonpub/auth';
+import type { PermissionKey } from '@commonpub/schema';
+import type { ResolvedPermissions } from '@commonpub/server';
+import type { H3Event } from 'h3';
+import type { AuthUser } from './auth';
+
+// `requireAuth`, `getOptionalUser`, and `createError` are Nitro/h3 auto-imports
+// (same as the rest of the layer's server utils) — referenced without a static
+// import so there's no import cycle with auth.ts (which calls requirePermission
+// to reimplement requireAdmin).
+
+declare module 'h3' {
+  interface H3EventContext {
+    /**
+     * Effective permissions for the request's user, attached by the auth
+     * middleware via `resolvePermissions()`. Absent for anon / unenriched
+     * requests — guards default-deny when missing (INV-3).
+     */
+    cpubPermissions?: ResolvedPermissions;
+  }
+}
+
+/**
+ * Server-side permission gate — the single choke-point all instance-wide
+ * authorization routes through. Mirrors `requireScope.ts`: reads the resolved
+ * set the middleware attached (`event.context.cpubPermissions`) and the primary
+ * role (admin floor), then defers the decision to the pure `hasPermissionPure`.
+ *
+ * 401 if anon, 403 if the user lacks `needed`. NOT wrapped in
+ * `requireFeature('rbac')` — the flag lives only in the resolver, so admin
+ * endpoints keep working with the flag off (a flag-gated guard would 404 them).
+ * With the flag off the resolver yields the legacy mapping ⇒ this is
+ * byte-identical to the old `requireAdmin` for `admin.access` (INV-1).
+ *
+ * @param statusMessage Optional 403 message override (lets `requireAdmin`
+ *   preserve its exact legacy "Admin access required" wording).
+ */
+export function requirePermission(
+  event: H3Event,
+  needed: PermissionKey,
+  statusMessage?: string,
+): AuthUser {
+  const user = requireAuth(event);
+  const resolved = event.context.cpubPermissions;
+  const granted = resolved?.permissions ?? new Set<string>();
+  // Admin floor (INV-2) reads the AUTHORITATIVE enriched `user.role` from
+  // requireAuth — never `resolved.primaryRole`. If the resolver default-denied
+  // on a DB error it returns an empty set with `primaryRole: ''`, and `?? `
+  // would NOT fall back from a defined empty string — locking out admins for a
+  // TTL window. `user.role` comes from the same enrich query the old
+  // requireAdmin trusted, so no DB state can lock out admin.
+  const primaryRole = user.role || resolved?.primaryRole;
+
+  if (!hasPermissionPure(granted, needed, primaryRole)) {
+    throw createError({
+      statusCode: 403,
+      statusMessage: statusMessage ?? `Missing permission: ${needed}`,
+    });
+  }
+  return user;
+}
+
+/**
+ * Non-throwing permission check — for owner-OR-permission cases (the ad-hoc
+ * `user.role === 'x'` sites migrated in Phase 1) and client-driving endpoints.
+ * Returns false for anon. Reads the same attached context as requirePermission.
+ */
+export function hasPermission(event: H3Event, needed: PermissionKey): boolean {
+  const user = getOptionalUser(event);
+  if (!user) return false;
+  const resolved = event.context.cpubPermissions;
+  const granted = resolved?.permissions ?? new Set<string>();
+  // Authoritative enriched role for the admin floor — see requirePermission.
+  const primaryRole = user.role || resolved?.primaryRole;
+  return hasPermissionPure(granted, needed, primaryRole);
+}
+
+/**
+ * Owner-OR-permission gate — the Phase 1 replacement for the ad-hoc
+ * `resource.ownerId === user.id || user.role === 'admin'` idiom on resource
+ * routes (contest judges/stakeholders, etc). Returns true if the caller owns the
+ * resource OR holds `needed`. Non-throwing (returns false for anon / neither).
+ *
+ * Flag-off this is byte-identical to the old idiom: `hasPermission` floors on the
+ * admin role, so `owner || hasPermission(…)` ≡ `owner || role==='admin'`. Flag-on,
+ * a custom/staff role granted `needed` also passes — the intended broadening.
+ *
+ * The plan filed this under `packages/server/src/rbac/`, but — like the resolver
+ * (session-175 location correction) — it operates on an H3 `event` + the
+ * middleware-attached context, so it lives in the layer beside its siblings
+ * `requirePermission`/`hasPermission`. The pure core is `hasPermissionPure`.
+ */
+export function ownerOrPermission(
+  event: H3Event,
+  ownerId: string | null | undefined,
+  needed: PermissionKey,
+): boolean {
+  const user = getOptionalUser(event);
+  if (!user) return false;
+  if (ownerId && user.id === ownerId) return true;
+  return hasPermission(event, needed);
+}