@commonpub/layer 0.28.1 → 0.30.0

package/server/api/contests/[slug]/entries.get.ts

@@ -1,4 +1,4 @@
-import { listContestEntries, getContestBySlug, isContestJudge, shouldRevealScores } from '@commonpub/server';
+import { listContestEntries, getContestBySlug, isContestJudge, shouldRevealScores, canViewContest } from '@commonpub/server';
 import type { ContestEntryItem } from '@commonpub/server';
 import { z } from 'zod';
 
@@ -6,6 +6,7 @@ const entriesQuerySchema = z.object({
   limit: z.coerce.number().int().min(1).max(100).optional(),
   offset: z.coerce.number().int().min(0).optional(),
   includeJudgeScores: z.coerce.boolean().optional(),
+  order: z.enum(['recent', 'rank']).optional(),
 });
 
 export default defineEventHandler(async (event): Promise<{ items: ContestEntryItem[]; total: number }> => {
@@ -21,17 +22,22 @@ export default defineEventHandler(async (event): Promise<{ items: ContestEntryIt
   // Aggregate score visibility additionally honours the contest's
   // judgingVisibility setting (public / judges-only / private).
   const user = getOptionalUser(event);
+  // Don't leak a private contest's entries to viewers who can't see the contest.
+  if (!(await canViewContest(db, contest, user))) {
+    throw createError({ statusCode: 404, statusMessage: 'Contest not found' });
+  }
   let privileged = false;
   if (user) {
     privileged =
       user.id === contest.createdById ||
-      user.role === 'admin' ||
+      hasPermission(event, 'contest.manage') ||
       (await isContestJudge(db, contest.id, user.id));
   }
 
   return listContestEntries(db, contest.id, {
     limit: query.limit,
     offset: query.offset,
+    orderBy: query.order,
     includeJudgeScores: privileged && query.includeJudgeScores,
     revealScores: shouldRevealScores(contest.judgingVisibility, contest.status, privileged),
   });

package/server/api/contests/[slug]/entries.post.ts

@@ -1,4 +1,4 @@
-import { submitContestEntry, getContestBySlug } from '@commonpub/server';
+import { submitContestEntry, getContestBySlug, canViewContest } from '@commonpub/server';
 import type { ContestEntryItem } from '@commonpub/server';
 import { z } from 'zod';
 
@@ -13,6 +13,10 @@ export default defineEventHandler(async (event): Promise<ContestEntryItem> => {
   const { slug } = parseParams(event, { slug: 'string' });
   const contest = await getContestBySlug(db, slug);
   if (!contest) throw createError({ statusCode: 404, statusMessage: 'Contest not found' });
+  // Can't enter a contest you can't see.
+  if (!(await canViewContest(db, contest, user))) {
+    throw createError({ statusCode: 404, statusMessage: 'Contest not found' });
+  }
   const input = await parseBody(event, submitEntrySchema);
 
   const entry = await submitContestEntry(db, contest.id, input.contentId, user.id);

package/server/api/contests/[slug]/index.delete.ts

@@ -12,7 +12,10 @@ export default defineEventHandler(async (event): Promise<{ deleted: boolean }> =
     throw createError({ statusCode: 404, statusMessage: 'Contest not found' });
   }
 
-  const deleted = await deleteContest(db, contest.id, user.id);
+  // Owner OR a contest.manage holder (RBAC Phase 1) may delete. Flag-off this is
+  // owner-or-admin, byte-identical to before; flag-on a custom managing role works.
+  const canManage = ownerOrPermission(event, contest.createdById, 'contest.manage');
+  const deleted = await deleteContest(db, contest.id, user.id, canManage);
   if (!deleted) {
     throw createError({ statusCode: 403, statusMessage: 'Not authorized to delete this contest' });
   }

package/server/api/contests/[slug]/index.get.ts

@@ -1,4 +1,4 @@
-import { getContestBySlug } from '@commonpub/server';
+import { getContestBySlug, canViewContest } from '@commonpub/server';
 import type { ContestDetail } from '@commonpub/server';
 
 export default defineEventHandler(async (event): Promise<ContestDetail> => {
@@ -7,5 +7,11 @@ export default defineEventHandler(async (event): Promise<ContestDetail> => {
   const { slug } = parseParams(event, { slug: 'string' });
   const contest = await getContestBySlug(db, slug);
   if (!contest) throw createError({ statusCode: 404, statusMessage: 'Contest not found' });
+  // Access control: private contests are only visible to owner/admin/stakeholders/
+  // judges/allowed-roles. 404 (not 403) so we don't leak that the contest exists.
+  const user = getOptionalUser(event);
+  if (!(await canViewContest(db, contest, user))) {
+    throw createError({ statusCode: 404, statusMessage: 'Contest not found' });
+  }
   return contest;
 });

package/server/api/contests/[slug]/judges/[userId].delete.ts

@@ -15,7 +15,7 @@ export default defineEventHandler(async (event) => {
   const contest = await getContestBySlug(db, slug);
   if (!contest) throw createError({ statusCode: 404, statusMessage: 'Contest not found' });
 
-  if (contest.createdById !== user.id && user.role !== 'admin') {
+  if (!ownerOrPermission(event, contest.createdById, 'contest.manage')) {
     throw createError({ statusCode: 403, statusMessage: 'Only contest owner or admin can manage judges' });
   }
 

package/server/api/contests/[slug]/judges/index.get.ts

@@ -1,4 +1,4 @@
-import { getContestBySlug, listContestJudges } from '@commonpub/server';
+import { getContestBySlug, listContestJudges, canViewContest } from '@commonpub/server';
 
 /**
  * GET /api/contests/:slug/judges
@@ -12,6 +12,9 @@ export default defineEventHandler(async (event) => {
 
   const contest = await getContestBySlug(db, slug);
   if (!contest) throw createError({ statusCode: 404, statusMessage: 'Contest not found' });
+  if (!(await canViewContest(db, contest, getOptionalUser(event)))) {
+    throw createError({ statusCode: 404, statusMessage: 'Contest not found' });
+  }
 
   return listContestJudges(db, contest.id);
 });

package/server/api/contests/[slug]/judges/index.post.ts

@@ -21,7 +21,7 @@ export default defineEventHandler(async (event) => {
   const contest = await getContestBySlug(db, slug);
   if (!contest) throw createError({ statusCode: 404, statusMessage: 'Contest not found' });
 
-  if (contest.createdById !== user.id && user.role !== 'admin') {
+  if (!ownerOrPermission(event, contest.createdById, 'contest.manage')) {
     throw createError({ statusCode: 403, statusMessage: 'Only contest owner or admin can manage judges' });
   }
 

package/server/api/contests/[slug]/stakeholders/[userId].delete.ts

@@ -0,0 +1,24 @@
+import { getContestBySlug, removeContestStakeholder } from '@commonpub/server';
+
+/**
+ * DELETE /api/contests/:slug/stakeholders/:userId
+ * Revoke a stakeholder's review access (contest owner or admin only).
+ */
+export default defineEventHandler(async (event) => {
+  requireFeature('contests');
+  const user = requireAuth(event);
+  const db = useDB();
+  const slug = getRouterParam(event, 'slug');
+  const userId = getRouterParam(event, 'userId');
+  if (!slug || !userId) throw createError({ statusCode: 400, statusMessage: 'Missing slug or userId' });
+
+  const contest = await getContestBySlug(db, slug);
+  if (!contest) throw createError({ statusCode: 404, statusMessage: 'Contest not found' });
+  if (!ownerOrPermission(event, contest.createdById, 'contest.manage')) {
+    throw createError({ statusCode: 403, statusMessage: 'Only the contest owner or admin can manage stakeholders' });
+  }
+
+  const removed = await removeContestStakeholder(db, contest.id, userId);
+  if (!removed) throw createError({ statusCode: 404, statusMessage: 'Stakeholder not found' });
+  return { removed: true };
+});

package/server/api/contests/[slug]/stakeholders/index.get.ts

@@ -0,0 +1,21 @@
+import { getContestBySlug, listContestStakeholders } from '@commonpub/server';
+
+/**
+ * GET /api/contests/:slug/stakeholders
+ * List view-only stakeholders (contest owner or admin only).
+ */
+export default defineEventHandler(async (event) => {
+  requireFeature('contests');
+  const user = requireAuth(event);
+  const db = useDB();
+  const slug = getRouterParam(event, 'slug');
+  if (!slug) throw createError({ statusCode: 400, statusMessage: 'Missing slug' });
+
+  const contest = await getContestBySlug(db, slug);
+  if (!contest) throw createError({ statusCode: 404, statusMessage: 'Contest not found' });
+  if (!ownerOrPermission(event, contest.createdById, 'contest.manage')) {
+    throw createError({ statusCode: 403, statusMessage: 'Only the contest owner or admin can view stakeholders' });
+  }
+
+  return listContestStakeholders(db, contest.id);
+});

package/server/api/contests/[slug]/stakeholders/index.post.ts

@@ -0,0 +1,33 @@
+import { getContestBySlug, addContestStakeholder } from '@commonpub/server';
+import { z } from 'zod';
+
+const addStakeholderSchema = z.object({ userId: z.string().uuid() });
+
+/**
+ * POST /api/contests/:slug/stakeholders
+ * Grant a user view-only review access (contest owner or admin only).
+ */
+export default defineEventHandler(async (event) => {
+  requireFeature('contests');
+  const user = requireAuth(event);
+  const db = useDB();
+  const slug = getRouterParam(event, 'slug');
+  if (!slug) throw createError({ statusCode: 400, statusMessage: 'Missing slug' });
+
+  const contest = await getContestBySlug(db, slug);
+  if (!contest) throw createError({ statusCode: 404, statusMessage: 'Contest not found' });
+  if (!ownerOrPermission(event, contest.createdById, 'contest.manage')) {
+    throw createError({ statusCode: 403, statusMessage: 'Only the contest owner or admin can manage stakeholders' });
+  }
+
+  const body = await parseBody(event, addStakeholderSchema);
+  const result = await addContestStakeholder(db, contest.id, body.userId, {
+    contestSlug: slug,
+    contestTitle: contest.title,
+    invitedBy: user.id,
+  });
+  if (!result.added) {
+    throw createError({ statusCode: 400, statusMessage: result.error ?? 'Failed to add stakeholder' });
+  }
+  return { added: true };
+});

package/server/api/contests/[slug]/votes.get.ts

@@ -1,4 +1,4 @@
-import { getContestBySlug, getContestEntryVotes } from '@commonpub/server';
+import { getContestBySlug, getContestEntryVotes, canViewContest } from '@commonpub/server';
 import type { ContestEntryVoteInfo } from '@commonpub/server';
 
 /**
@@ -13,6 +13,9 @@ export default defineEventHandler(async (event): Promise<ContestEntryVoteInfo[]>
 
   const contest = await getContestBySlug(db, slug);
   if (!contest) throw createError({ statusCode: 404, statusMessage: 'Contest not found' });
+  if (!(await canViewContest(db, contest, user))) {
+    throw createError({ statusCode: 404, statusMessage: 'Contest not found' });
+  }
   // Voting disabled, or contest not yet open (no entries) → empty array, not an error.
   if (!contest.communityVotingEnabled || contest.status === 'upcoming') return [];
 

package/server/api/contests/index.get.ts

@@ -6,5 +6,8 @@ export default defineEventHandler(async (event): Promise<PaginatedResponse<Conte
   requireFeature('contests');
   const db = useDB();
   const filters = parseQueryParams(event, contestFiltersSchema);
-  return listContests(db, filters);
+  // Pass the viewer so the list can include their own drafts/hidden contests
+  // (and everything for admins) while keeping the public list public-only.
+  const user = getOptionalUser(event);
+  return listContests(db, filters, user ? { userId: user.id, role: user.role } : null);
 });

package/server/api/docs/migrate-content.post.ts

@@ -16,7 +16,7 @@ import { docsPages } from '@commonpub/schema';
 import { eq } from 'drizzle-orm';
 
 export default defineEventHandler(async (event) => {
-  requireAdmin(event);
+  requirePermission(event, 'content.editorial');
   const db = useDB();
 
   // Fetch all pages

package/server/api/events/[slug].delete.ts

@@ -14,7 +14,7 @@ export default defineEventHandler(async (event) => {
   const existing = await getEventBySlug(db, slug);
   if (!existing) throw createError({ statusCode: 404, statusMessage: 'Event not found' });
 
-  const isAdmin = user.role === 'admin';
+  const isAdmin = hasPermission(event, 'event.manage');
   const deleted = await deleteEvent(db, existing.id, user.id, isAdmin);
   if (!deleted) throw createError({ statusCode: 403, statusMessage: 'Unauthorized' });
 

package/server/api/events/[slug].put.ts

@@ -29,7 +29,7 @@ export default defineEventHandler(async (event) => {
   if (!slug) throw createError({ statusCode: 400, statusMessage: 'Missing slug' });
 
   const body = await parseBody(event, updateEventSchema);
-  const isAdmin = user.role === 'admin';
+  const isAdmin = hasPermission(event, 'event.manage');
 
   const result = await updateEvent(db, slug, user.id, body, isAdmin);
   if (!result) throw createError({ statusCode: 404, statusMessage: 'Event not found or unauthorized' });

package/server/api/layouts/by-route.get.ts

@@ -71,7 +71,7 @@ export default defineEventHandler(async (event): Promise<PublicLayoutSlice | nul
   // requester's access tier so a layout served to a higher tier can't
   // leak via cache to a lower tier on the same path.
   const user = getOptionalUser(event);
-  const isAdmin = user?.role === 'admin';
+  const isAdmin = hasPermission(event, 'layout.manage');
   const tier: 'admin' | 'members' | 'anon' = isAdmin ? 'admin' : user ? 'members' : 'anon';
   const cacheKey = `${tier}:${path}`;
 

package/server/api/products/[id].delete.ts

@@ -2,7 +2,7 @@ import { deleteProduct } from '@commonpub/server';
 
 export default defineEventHandler(async (event): Promise<{ deleted: boolean }> => {
   const db = useDB();
-  requireAdmin(event);
+  requirePermission(event, 'content.moderate');
   const { id } = parseParams(event, { id: 'uuid' });
 
   const deleted = await deleteProduct(db, id);

package/server/api/videos/categories/[id].delete.ts

@@ -1,7 +1,7 @@
 import { deleteVideoCategory } from '@commonpub/server';
 
 export default defineEventHandler(async (event): Promise<{ success: boolean }> => {
-  requireAdmin(event);
+  requirePermission(event, 'categories.manage');
 
   const { id } = parseParams(event, { id: 'uuid' });
 

package/server/api/videos/categories/[id].put.ts

@@ -3,7 +3,7 @@ import type { VideoCategoryItem } from '@commonpub/server';
 import { createVideoCategorySchema } from '@commonpub/schema';
 
 export default defineEventHandler(async (event): Promise<VideoCategoryItem> => {
-  requireAdmin(event);
+  requirePermission(event, 'categories.manage');
   const { id } = parseParams(event, { id: 'uuid' });
   const input = await parseBody(event, createVideoCategorySchema.partial());
 

package/server/api/videos/categories.post.ts

@@ -3,7 +3,7 @@ import type { VideoCategoryItem } from '@commonpub/server';
 import { createVideoCategorySchema } from '@commonpub/schema';
 
 export default defineEventHandler(async (event): Promise<VideoCategoryItem> => {
-  requireAdmin(event);
+  requirePermission(event, 'categories.manage');
   const db = useDB();
   const input = await parseBody(event, createVideoCategorySchema);
 

package/server/middleware/auth.ts

@@ -55,6 +55,26 @@ declare module 'h3' {
   }
 }
 
+/**
+ * Attach the user's resolved permissions to the request context (RBAC Phase 0).
+ * One cached Map hit on the hot path (30s TTL), like feature-flags-prime. Reads
+ * the userId from the already-enriched auth user. Fail-closed: on any error the
+ * context stays unset and the guards default-deny — but the admin floor still
+ * holds because `requirePermission` falls back to the enriched `user.role`
+ * (INV-2). No-op for anon requests. `resolvePermissions` is a Nitro auto-import.
+ */
+async function attachPermissions(event: import('h3').H3Event, auth: AuthLocals): Promise<void> {
+  if (!auth?.user?.id) return;
+  try {
+    // Pass the enriched role so the resolver skips its own users query (admin +
+    // flag-off paths do zero extra DB work) and stays consistent with enrichUser.
+    const primaryRole = (auth.user as unknown as { role?: string }).role;
+    event.context.cpubPermissions = await resolvePermissions(auth.user.id, primaryRole);
+  } catch {
+    // Leave unset — guards default-deny; admin floor survives via user.role.
+  }
+}
+
 /**
  * Enrich the session user with custom DB columns (role, username, status)
  * that Better Auth doesn't include by default.
@@ -89,6 +109,7 @@ export default defineEventHandler(async (event) => {
       const webHeaders = new Headers(headers as Record<string, string>);
       event.context.auth = await middleware.resolveSession(webHeaders);
       await enrichUser(event.context.auth);
+      await attachPermissions(event, event.context.auth);
     } catch {
       event.context.auth = { user: null, session: null };
     }
@@ -143,6 +164,7 @@ export default defineEventHandler(async (event) => {
     const webHeaders = new Headers(headers as Record<string, string>);
     event.context.auth = await middleware.resolveSession(webHeaders);
     await enrichUser(event.context.auth);
+    await attachPermissions(event, event.context.auth);
   } catch (err: unknown) {
     // DB error during session resolution — don't silently eat it for API routes
     if (pathname.startsWith('/api/')) {

package/server/utils/auth.ts

@@ -22,12 +22,19 @@ export function requireAuth(event: H3Event): AuthUser {
   return auth.user as AuthUser;
 }
 
+/**
+ * Admin gate — the linchpin reimplemented (session 175, RBAC Phase 0) as
+ * `requirePermission(event, 'admin.access')`, routing all ~73 call sites through
+ * the permission machinery without changing any of them. `admin.access` is
+ * seeded ONLY to the admin role, and the resolver's admin-floor + flag-off
+ * legacy mapping make this bit-identical to the old `user.role === 'admin'`
+ * check (INV-1). The legacy 403 message is preserved verbatim.
+ *
+ * `requirePermission` is a Nitro auto-import (sibling util) — referenced without
+ * a static import so there's no import cycle with requirePermission.ts.
+ */
 export function requireAdmin(event: H3Event): AuthUser {
-  const user = requireAuth(event);
-  if (user.role !== 'admin') {
-    throw createError({ statusCode: 403, statusMessage: 'Admin access required' });
-  }
-  return user;
+  return requirePermission(event, 'admin.access', 'Admin access required');
 }
 
 export function getOptionalUser(event: H3Event): AuthUser | null {

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);
+}