authorize.ts · Source

authorize.tsapps/api/src/lib/authorize.tsraw ← lib23,934 B← Back to the app
1/**
2 * Server-side authorization — the single place where "may I?" is decided.
3 *
4 * Effective level resolution:
5 *   1. workspace role:  OWNER → FULL_ACCESS, ADMIN → FULL_ACCESS,
6 *                       MEMBER → EDIT, GUEST → VIEW (no membership → NONE)
7 *   2. `Permission` rows (grantee × resource × level) for this workspace:
8 *        - grantee: user (direct) or team (member of that team in this workspace)
9 *        - resource scope: workspace (applies to everything), teamspace,
10 *          page, database, record, file
11 *      The most specific applicable row wins (workspace < teamspace <
12 *      database < page < record < file); ties at one specificity take the
13 *      max level. The result is maxed with the workspace-role level.
14 *
15 * Levels: NONE < VIEW < COMMENT < EDIT < FULL_ACCESS.
16 *
17 * The `prisma` parameter is a structural interface (the three delegates
18 * used) so the resolution is unit-testable with a fixture object.
19 */
20 
21import { ApiError } from "../common/errors.js";
22import { ActorContext } from "../common/actor-context.js";
23// OAuth scope rules (TASK-0129): the domain lives in modules/oauth/scopes.ts
24// (catalog + cap + the "which scope was missing" helper) — it type-imports
25// `Level` from HERE, so this value import is one-directional at runtime
26// (no cycle). Reused here, never duplicated (AGENTS rule 4).
27import { oauthScopeCap, missingOAuthScope } from "../modules/oauth/scopes.js";
28 
29export type Level = "NONE" | "VIEW" | "COMMENT" | "EDIT" | "FULL_ACCESS";
30 
31/**
32 * API-key scope rules (TASK-0127, docs/api/authentication.md §7):
33 *   READ  key → may pass only VIEW-level assertions (reads);
34 *   WRITE key → may pass up to EDIT-level assertions (mutations; COMMENT
35 *               ops are covered since the level ladder is flat there);
36 *   ADMIN key → all levels (ADMIN implies WRITE implies READ).
37 * Anything beyond the key's cap yields 403 FORBIDDEN with
38 * `details: [{reason: "api_key_scope_write"}]` (the documented public
39 * alias: **SCOPE_DENIED** — `docs/api/authentication.md` §9.1).
40 *
41 * The cap is derived from the key's SCOPES (never from the asserted
42 * resource, never from the creator's membership).
43 */
44function apiKeyScopeCap(scopes: string[]): Level {
45  if (scopes.includes("ADMIN")) return "FULL_ACCESS";
46  if (scopes.includes("WRITE")) return "EDIT";
47  return "VIEW";
48}
49 
50/**
51 * The OAuth scope-cap, re-exported from modules/oauth/scopes.ts so callers
52 * (and tests) can import it from the authorize module too.
53 */
54export { oauthScopeCap };
55 
56/**
57 * OAuth branch of {@link assertCan} (TASK-0129, docs §8.2). Runs instead of
58 * the membership path when the in-flight actor is an OAuth token
59 * (`kind: "user"` + `oauthScopes`). The cap (`oauthScopeCap`) and the
60 * "which scope was missing" detail (`missingOAuthScope`) come from
61 * modules/oauth/scopes.ts — imported, never duplicated.
62 *
63 * The target workspace comes from the `X-Factory-Workspace` header (the
64 * OAuth JWT carries no workspace claim). Two gates, in order:
65 *   1. The token's user must be a MEMBER of the target workspace — not a
66 *      member → 401 (the workspace context is invalid for this user; never a
67 *      200 on another tenant, never a membership probe leak).
68 *   2. The scope CAP must cover the operation — otherwise 403 reusing the
69 *      documented `api_key_scope_write` reason (the public alias
70 *      SCOPE_DENIED), with the needed scope in `details[0].scope`.
71 */
72async function assertCanForOAuth(
73  prisma: AuthorizePrisma,
74  actor: { userId?: string; oauthScopes?: string[] },
75  workspaceId: string,
76  need: Level,
77  resource?: ResourceScope
78): Promise<Level> {
79  const membership =
80    actor.userId && workspaceId
81      ? await prisma.workspaceMember
82          .findUnique({ where: { workspaceId_userId: { workspaceId, userId: actor.userId } } })
83          .catch(() => null)
84      : null;
85  if (!membership) {
86    throw new ApiError("UNAUTHORIZED", 401, "You are not a member of the requested workspace.", [
87      { reason: "workspace_member_required" }
88    ]);
89  }
90  const scopes = actor.oauthScopes ?? [];
91  const cap = oauthScopeCap(scopes);
92  if (LEVEL_ORDER[cap] < LEVEL_ORDER[need]) {
93    throw new ApiError("FORBIDDEN", 403, `OAuth scope does not cover ${need} access.`, [
94      { reason: "api_key_scope_write", scope: missingOAuthScope(need, scopes, resource) }
95    ]);
96  }
97  return cap;
98}
99 
100export const LEVELS: Level[] = ["NONE", "VIEW", "COMMENT", "EDIT", "FULL_ACCESS"];
101 
102export const LEVEL_ORDER: Record<Level, number> = {
103  NONE: 0,
104  VIEW: 1,
105  COMMENT: 2,
106  EDIT: 3,
107  FULL_ACCESS: 4
108};
109 
110/** Workspace role → baseline permission level. */
111export const ROLE_LEVEL: Record<string, Level> = {
112  OWNER: "FULL_ACCESS",
113  ADMIN: "FULL_ACCESS",
114  MEMBER: "EDIT",
115  GUEST: "VIEW"
116};
117 
118/** Resource specificity: higher = more specific = wins over broader grants. */
119const RESOURCE_SPECIFICITY: Record<string, number> = {
120  workspace: 0,
121  teamspace: 1,
122  database: 2,
123  page: 3,
124  record: 4,
125  file: 5
126};
127 
128export interface ResourceScope {
129  pageId?: string;
130  databaseId?: string;
131  teamId?: string;
132  recordId?: string;
133  fileId?: string;
134}
135 
136export interface EffectiveLevelInput {
137  workspaceId: string;
138  userId: string;
139  resource?: ResourceScope;
140}
141 
142/** Minimal structural type of the Prisma delegates used here (testable).
143 *
144 * NOTE (2026-09-29, TASK-0101): the argument parameters are typed as
145 * `object` — the Prisma 5.22 generated delegates take their own
146 * `*FindManyArgs`/`*FindUniqueArgs` generics, which no single structural
147 * signature can satisfy without importing the generated client (the test
148 * fixture must stay import-free). The CALLER's `where` shape is still
149 * checked by the delegate at runtime; the caller-side literals are checked
150 * by the real client when `PrismaService` is passed (the only production
151 * implementation). This is the fix for the Prisma-5.22 drift that made
152 * `PrismaService` fail to satisfy this interface in ~15 services. */
153export interface AuthorizePrisma {
154  workspaceMember: {
155    findUnique(args: object): Promise<{ id: string; role: string } | null>;
156  };
157  teamMember: {
158    findMany(args: object): Promise<{ teamId: string }[]>;
159  };
160  permission: {
161    findMany(args: object): Promise<PermissionRow[]>;
162  };
163}
164 
165export interface PermissionRow {
166  id: string;
167  workspaceId: string;
168  granteeType: string; // "user" | "team" | "role"
169  granteeId: string;
170  resourceType: string; // workspace | teamspace | page | database | record | file
171  resourceId: string;
172  level: Level;
173  inheritsFrom?: string | null;
174}
175 
176function maxLevel(a: Level, b: Level): Level {
177  return LEVEL_ORDER[a] >= LEVEL_ORDER[b] ? a : b;
178}
179 
180/**
181 * TASK-0135: optional permission-decision cache. This lib is plain (no Nest
182 * DI), so the live `CacheService` is handed in ONCE at boot by the
183 * `PermissionCacheBridge` provider (CoreModule) via {@link setPermissionCache}.
184 * When unset (tests, or `PERF_CACHE` off) decisions go straight to Postgres —
185 * the cache is a transparent accelerator, never a change in the decision.
186 *
187 * The bound function's `loader` is the live resolution; the cache layer calls
188 * it on a miss and stores the level (zod-validated on read), busting the
189 * subject's entries on `permission.changed` (TTL 60 s as the safety net).
190 */
191type GetCachedLevel = (
192  workspaceId: string,
193  userId: string,
194  scope: ResourceScope | undefined,
195  loader: () => Promise<string>
196) => Promise<{ level: string; cached: boolean }>;
197 
198let permCacheFn: GetCachedLevel | null = null;
199 
200/** Hand the live (bound) permission-cache accessor in, or `null` to disable. */
201export function setPermissionCache(fn: GetCachedLevel | null): void {
202  permCacheFn = fn;
203}
204 
205/**
206 * Resolve the effective permission level of `userId` in `workspaceId` for an
207 * optional resource scope. Never throws — returns NONE when not a member
208 * and no grant applies.
209 */
210export async function effectiveLevel(
211  prisma: AuthorizePrisma,
212  input: EffectiveLevelInput
213): Promise<Level> {
214  const { workspaceId, userId, resource } = input;
215  // TASK-0135: the decision is cached (TTL 60 s + `permission.changed` bust)
216  // when the live accessor is bound; `loader` is the live resolution. When the
217  // cache is off/unbound, go straight to Postgres (loader runs inline).
218  if (permCacheFn) {
219    const { level } = await permCacheFn(workspaceId, userId, resource, () =>
220      rawEffectiveLevel(prisma, input)
221    );
222    return level as Level;
223  }
224  return rawEffectiveLevel(prisma, input);
225}
226 
227/** The live resolution (un-cached) — the loader the permission cache calls. */
228async function rawEffectiveLevel(
229  prisma: AuthorizePrisma,
230  input: EffectiveLevelInput
231): Promise<Level> {
232  const { workspaceId, userId, resource } = input;
233 
234  const membership = await prisma.workspaceMember.findUnique({
235    where: { workspaceId_userId: { workspaceId, userId } }
236  });
237  let level: Level = membership ? ROLE_LEVEL[membership.role] ?? "NONE" : "NONE";
238 
239  // Sequential (NOT Promise.all): the permission query's team-grant filter
240  // DEPENDS on `teams`, so it cannot run in parallel. (A prior sync commit
241  // inlined `teams.map(…)` inside the `Promise.all` argument — a temporal-dead-
242  // zone `ReferenceError` that threw on EVERY `effectiveLevel` call; fixed
243  // 2026-09-28, the two queries are semantically identical.)
244  const teams = await prisma.teamMember.findMany({ where: { userId }, select: { teamId: true } });
245  const grants = await prisma.permission.findMany({
246    where: {
247      workspaceId,
248      OR: [
249        { granteeType: "user", granteeId: userId },
250        { granteeType: "team", granteeId: { in: teams.map((t) => t.teamId) } }
251      ]
252    }
253  });
254 
255  let best: { specificity: number; level: Level } | undefined;
256  for (const grant of grants) {
257    const specificity = RESOURCE_SPECIFICITY[grant.resourceType];
258    if (specificity === undefined) continue;
259    if (!appliesToResource(grant, workspaceId, resource)) continue;
260    if (!best || specificity > best.specificity || (specificity === best.specificity && LEVEL_ORDER[grant.level] > LEVEL_ORDER[best.level])) {
261      best = { specificity, level: grant.level };
262    }
263  }
264 
265  // TASK-0104 §2/§Security — explicit NONE deny (a hard stop).
266  //
267  // A grant at level "NONE" is NOT "no grant" here: when ANY resource named
268  // in the requested scope (most specific first: file → record → page →
269  // database → teamspace) carries an explicit NONE grant for this user, the
270  // effective level is a hard NONE. It overrides the role baseline, broader
271  // inheritance, and even a HIGHER grant on the same resource — an explicit
272  // deny can never be bypassed by role (AGENTS.md §27, spec §Security "Explicit
273  // deny (NONE) is a hard stop"). `grants` is already filtered by the query to
274  // grants that apply to this user (user=userId or team∈teams), so a match on
275  // resourceType+resourceId+level is sufficient.
276  //
277  // Walking the whole named chain (not just the top resource) is what makes a
278  // NONE on the containing PAGE deny its files: a file inherits the page's
279  // access, so an explicit page deny is a cap the file cannot escape. A NONE
280  // grant on a resource NOT named in the scope (a different file, a different
281  // page) never fires — it is not part of this read's inheritance chain.
282  //
283  // NOTE: `maxLevel(level, "NONE")` in the loop above is a no-op, so without
284  // this branch an explicit NONE would be silently ignored (the pre-TASK-0104
285  // behavior) — the deny is what gives NONE its teeth. No NONE grant rows
286  // existed in production before TASK-0104 (share levels are VIEW/COMMENT/
287  // EDIT), so this is a pure capability addition, not a behavior break.
288  for (const named of namedResources(resource)) {
289    if (
290      grants.some(
291        (g) => g.resourceType === named.resourceType && g.resourceId === named.resourceId && g.level === "NONE"
292      )
293    ) {
294      return "NONE";
295    }
296  }
297 
298  if (best) level = maxLevel(level, best.level);
299  return level;
300}
301 
302/**
303 * The resources named in a `ResourceScope`, ordered most → least specific by
304 * `RESOURCE_SPECIFICITY` (file > record > page > database > teamspace). Empty
305 * when the scope names nothing. Used for the explicit-NONE deny walk.
306 */
307function namedResources(resource: ResourceScope | undefined): { resourceType: string; resourceId: string }[] {
308  if (!resource) return [];
309  const named: { resourceType: string; resourceId: string }[] = [];
310  if (resource.fileId) named.push({ resourceType: "file", resourceId: resource.fileId });
311  if (resource.recordId) named.push({ resourceType: "record", resourceId: resource.recordId });
312  if (resource.pageId) named.push({ resourceType: "page", resourceId: resource.pageId });
313  if (resource.databaseId) named.push({ resourceType: "database", resourceId: resource.databaseId });
314  if (resource.teamId) named.push({ resourceType: "teamspace", resourceId: resource.teamId });
315  return named;
316}
317 
318function appliesToResource(
319  grant: Pick<PermissionRow, "resourceType" | "resourceId">,
320  workspaceId: string,
321  resource: ResourceScope | undefined
322): boolean {
323  switch (grant.resourceType) {
324    case "workspace":
325      return grant.resourceId === workspaceId;
326    case "teamspace":
327      return resource?.teamId !== undefined && resource.teamId === grant.resourceId;
328    case "page":
329      return resource?.pageId !== undefined && resource.pageId === grant.resourceId;
330    case "database":
331      return resource?.databaseId !== undefined && resource.databaseId === grant.resourceId;
332    case "record":
333      return resource?.recordId !== undefined && resource.recordId === grant.resourceId;
334    case "file":
335      return resource?.fileId !== undefined && resource.fileId === grant.resourceId;
336    default:
337      return false;
338  }
339}
340 
341/**
342 * The actor of the in-flight request (undefined = no HTTP context: workers,
343 * tests calling services directly — the legacy path, unchanged).
344 */
345function currentActor() {
346  return ActorContext.get();
347}
348 
349/**
350 * API-key branch of {@link assertCan} (TASK-0127). Runs BEFORE the
351 * membership lookup so a key in workspace A can never inherit its creator's
352 * membership in workspace B. Returns the level the operation resolves to
353 * (EDIT for WRITE/ADMIN keys, VIEW for READ keys — the levels services may
354 * subsequently grant); throws 403 on a scope mismatch.
355 */
356function assertCanForApiKey(auth: {
357  workspaceId?: string;
358  scopes?: string[];
359  apiKeyId?: string;
360  userId?: string;
361}, workspaceId: string, need: Level): Level {
362  if (auth.workspaceId !== workspaceId) {
363    // The key is bound to its own workspace (docs §7); a cross-workspace
364    // call is a FORBIDDEN — never a 200 on someone else's tenant, and
365    // never a membership probe of the key creator.
366    throw new ApiError("FORBIDDEN", 403, "API key is bound to a different workspace.", [
367      { reason: "workspace_mismatch" }
368    ]);
369  }
370  const cap = apiKeyScopeCap(auth.scopes ?? []);
371  if (LEVEL_ORDER[cap] < LEVEL_ORDER[need]) {
372    throw new ApiError(
373      "FORBIDDEN",
374      403,
375      `API key scope does not cover ${need} access.`,
376      [{ reason: "api_key_scope_write" }]
377    );
378  }
379  // The level the key "has" for this workspace — the scope cap itself.
380  // Services that branch on the returned level (e.g. admin-view flags) see
381  // the key's real capability, not an inflated one.
382  return cap;
383}
384 
385/**
386 * The effective permission level for the ACTUAL actor (API key → its scope
387 * cap in its own workspace, never the creator's grants; user → the normal
388 * {@link effectiveLevel}). For the DIRECT `effectiveLevel` call sites that
389 * compare against a level threshold themselves (comment resolve/reopen,
390 * file purge, AI context assembly) instead of going through {@link assertCan}.
391 */
392export async function actorLevel(prisma: AuthorizePrisma, input: EffectiveLevelInput): Promise<Level> {
393  const actor = currentActor();
394  if (actor?.kind === "api") {
395    if (actor.workspaceId !== input.workspaceId) return "NONE";
396    const scopes = actor.scopes ?? [];
397    if (scopes.includes("ADMIN")) return "FULL_ACCESS";
398    if (scopes.includes("WRITE")) return "EDIT";
399    return "VIEW";
400  }
401  // TASK-0129: OAuth token → its SCOPE CAP (never the user's membership).
402  // The cap is already workspace-agnostic (VIEW/EDIT), so the membership
403  // gate lives in the membership lookups, not here.
404  if (actor?.kind === "user" && actor.oauthScopes) {
405    return oauthScopeCap(actor.oauthScopes);
406  }
407  return effectiveLevel(prisma, input);
408}
409 
410/** True when the in-flight actor is an ADMIN-scoped API key of `workspaceId`. */
411export function actorIsAdminKey(workspaceId: string): boolean {
412  const actor = currentActor();
413  return actor?.kind === "api" && actor.workspaceId === workspaceId && (actor.scopes ?? []).includes("ADMIN");
414}
415 
416/**
417 * Assert the caller has at least `need` on the resource.
418 * Throws `ApiError(FORBIDDEN, 403)` with `details: [{reason: "requires_…" }]`.
419 *
420 * TASK-0127: when the in-flight actor is an API key, the decision is the
421 * key's SCOPE (and its workspace binding), not the membership of the user
422 * the caller passed as `userId` — see {@link assertCanForApiKey}.
423 */
424export async function assertCan(
425  prisma: AuthorizePrisma,
426  input: EffectiveLevelInput,
427  need: Level
428): Promise<Level> {
429  const actor = currentActor();
430  if (actor?.kind === "api") {
431    return assertCanForApiKey(actor, input.workspaceId, need);
432  }
433  // TASK-0129: an OAuth token (kind "user" + oauthScopes) is gated by its
434  // SCOPE CAP in the X-Factory-Workspace workspace, never by the user's
435  // membership — see {@link assertCanForOAuth}.
436  if (actor?.kind === "user" && actor.oauthScopes) {
437    return assertCanForOAuth(prisma, actor, input.workspaceId, need, input.resource);
438  }
439  const have = await effectiveLevel(prisma, input);
440  if (LEVEL_ORDER[have] < LEVEL_ORDER[need]) {
441    throw new ApiError("FORBIDDEN", 403, `Requires ${need} access (you have ${have}).`, [
442      { reason: `requires_${need}`, have }
443    ]);
444  }
445  return have;
446}
447 
448/**
449 * Whether the in-flight actor is an API key bound to `workspaceId` (the key
450 * is a member-equivalent of its OWN workspace; cross-workspace → false).
451 * Used by the DIRECT membership lookups that bypass {@link assertCan}
452 * (services that 404 non-members instead of 403) so an API key never
453 * probes its creator's membership (TASK-0127, docs §7).
454 */
455export function actorIsWorkspaceKey(actor: { kind?: string; workspaceId?: string } | undefined, workspaceId: string): boolean {
456  return actor?.kind === "api" && actor.workspaceId === workspaceId;
457}
458 
459/**
460 * The permission level an API key exercises for `need` in `workspaceId` —
461 * the same scope rules as {@link assertCanForApiKey} but WITHOUT throwing
462 * (for the membership-shape lookups: the result is used as the caller's
463 * "role level", not as a grant). READ → VIEW, WRITE/ADMIN → EDIT, ADMIN →
464 * FULL_ACCESS (the max the key may pass); cross-workspace → NONE.
465 */
466export function apiKeyLevelFor(
467  actor: { kind?: string; workspaceId?: string; scopes?: string[] } | undefined,
468  workspaceId: string,
469  need: Level
470): Level {
471  if (actor?.kind !== "api" || actor.workspaceId !== workspaceId) return "NONE";
472  const scopes = actor.scopes ?? [];
473  let cap: Level = "VIEW";
474  if (scopes.includes("WRITE") || scopes.includes("ADMIN")) cap = "EDIT";
475  if (scopes.includes("ADMIN")) cap = "FULL_ACCESS";
476  return LEVEL_ORDER[cap] >= LEVEL_ORDER[need] ? need : "NONE";
477}
478 
479/**
480 * Resolve the workspace membership for the ACTUAL actor (user → the user's
481 * membership; API key → a SYNTHETIC membership whose role covers the key's
482 * scope level in `workspaceId`, never the creator's real row). This is the
483 * actor-aware stand-in for a direct `workspaceMember.findUnique` at the
484 * CALLER's-own-membership sites (list-members / usage / sidebar gates);
485 * target-user lookups (is `X` a member?) keep the raw query.
486 */
487export async function actorMembership(
488  prisma: AuthorizePrisma,
489  userId: string,
490  workspaceId: string,
491  need: Level = "VIEW"
492): Promise<{ id: string; role: string } | null> {
493  const actor = currentActor();
494  if (actor?.kind === "api") {
495    if (actor.workspaceId !== workspaceId) return null;
496    const scopes = actor.scopes ?? [];
497    const cap: Level = scopes.includes("ADMIN")
498      ? "FULL_ACCESS"
499      : scopes.includes("WRITE")
500        ? "EDIT"
501        : "VIEW";
502    if (LEVEL_ORDER[cap] < LEVEL_ORDER[need]) return null; // scope too small
503    // Synthesize a role from the key's CAP (its scope, never the creator's
504    // membership row): the key acts as the workspace at that level.
505    const role = cap === "FULL_ACCESS" ? "ADMIN" : cap === "EDIT" ? "MEMBER" : "GUEST";
506    return { id: `apikey-${actor.apiKeyId ?? "unknown"}`, role };
507  }
508  // TASK-0129: an OAuth token acts as its USER's membership (it carries the
509  // user's identity) but at most its SCOPE CAP — a member with a read-only
510  // token still resolves the membership, but `need` above the cap → null.
511  if (actor?.kind === "user" && actor.oauthScopes) {
512    if (!userId) return null;
513    if (LEVEL_ORDER[oauthScopeCap(actor.oauthScopes)] < LEVEL_ORDER[need]) return null; // scope too small
514    const m = await prisma.workspaceMember.findUnique({
515      where: { workspaceId_userId: { workspaceId, userId } },
516      select: { id: true, role: true }
517    });
518    return m;
519  }
520  if (!userId) return null;
521  const m = await prisma.workspaceMember.findUnique({
522    where: { workspaceId_userId: { workspaceId, userId } },
523    select: { id: true, role: true }
524  });
525  return m;
526}
527 
528/**
529 * Assert the caller has one of the workspace roles (owner/admin gating).
530 *
531 * TASK-0127: API keys — the key's ADMIN scope is the role gate (an ADMIN
532 * key acts as the workspace admin); a READ/WRITE key is rejected with the
533 * scope reason (docs §7: "member/permission/api-key management requires
534 * ADMIN"). The key's creator membership is never consulted.
535 */
536export async function assertRole(
537  prisma: AuthorizePrisma,
538  input: { workspaceId: string; userId: string },
539  roles: string[]
540): Promise<string> {
541  const actor = currentActor();
542  if (actor?.kind === "api") {
543    if (actor.workspaceId !== input.workspaceId) {
544      throw new ApiError("FORBIDDEN", 403, "API key is bound to a different workspace.", [
545        { reason: "workspace_mismatch" }
546      ]);
547    }
548    if (!actor.scopes?.includes("ADMIN")) {
549      throw new ApiError("FORBIDDEN", 403, "This operation requires the ADMIN scope.", [
550        { reason: "api_key_scope_write" }
551      ]);
552    }
553    // The ADMIN scope maps to the workspace ADMIN role — NOT the owner.
554    // OWNER-only gates (delete workspace, transfer ownership) stay closed
555    // to every API key: an API key can never own a workspace (docs §7).
556    if (!roles.includes("ADMIN")) {
557      throw new ApiError("FORBIDDEN", 403, `Requires workspace role ${roles.join(" or ")}.`, [
558        { reason: `requires_role_${roles.join("_")}` }
559      ]);
560    }
561    return "ADMIN";
562  }
563  // TASK-0129: an OAuth token carries NO workspace role — its scope cap tops
564  // out at EDIT (there is no FULL_ACCESS scope). Every OWNER/ADMIN role gate
565  // (app registration, member management, …) is therefore closed to it.
566  if (actor?.kind === "user" && actor.oauthScopes) {
567    if (oauthScopeCap(actor.oauthScopes) !== "FULL_ACCESS") {
568      throw new ApiError("FORBIDDEN", 403, `This operation requires workspace role ${roles.join(" or ")}.`, [
569        { reason: "oauth_role_denied" }
570      ]);
571    }
572  }
573  const membership = await prisma.workspaceMember.findUnique({
574    where: { workspaceId_userId: { workspaceId: input.workspaceId, userId: input.userId } }
575  });
576  if (!membership || !roles.includes(membership.role)) {
577    throw new ApiError("FORBIDDEN", 403, `Requires workspace role ${roles.join(" or ")}.`, [
578      { reason: `requires_role_${roles.join("_")}` }
579    ]);
580  }
581  return membership.role;
582}
583