scopes.ts · Source

scopes.tsapps/api/src/modules/oauth/scopes.tsraw ← oauth5,042 B← Back to the app
1import { createHash } from "node:crypto";
2import type { Level } from "../../lib/authorize.js";
3 
4/**
5 * TASK-0129 — OAuth2 scopes (docs/api/authentication.md §8.1).
6 *
7 * The OAuth scope CATALOG — six resource-qualified scopes
8 * (`<resource>:<action>`, resource ∈ pages|databases|files). Apps offer a
9 * subset; the token carries the granted subset; the enforcement cap is the
10 * MAX across them (`oauthScopeCap`).
11 *
12 * CONFLICT C-13.7 (recorded in docs/tasks/phase-13-api.md): the task
13 * requirements text and one example list FIVE scopes (omitting
14 * `files:write`), while the locked design decision names the scope family
15 * "`pages:read`→VIEW, `pages:write`→EDIT, `databases:read`→VIEW,
16 * `databases:write`→EDIT, `files:read`→VIEW, `files:write`→EDIT" — and the
17 * doc §8.1 example grants `databases:write`, which only exists in the
18 * 6-scope family. Resolution: the full 6-scope family (symmetric read/write
19 * per resource); test apps may offer fewer (the E2E app offers five, matching
20 * the "5 scope checkboxes" acceptance text).
21 *
22 * Human descriptions are STATIC server strings (security: the consent screen
23 * renders only these — no client-supplied text, so no XSS vector).
24 */
25export const OAUTH_SCOPES = [
26  "pages:read",
27  "pages:write",
28  "databases:read",
29  "databases:write",
30  "files:read",
31  "files:write"
32] as const;
33export type OAuthScope = (typeof OAUTH_SCOPES)[number];
34 
35/** Resources a scope can qualify. */
36export const OAUTH_SCOPE_RESOURCES = ["pages", "databases", "files"] as const;
37export type OAuthScopeResource = (typeof OAUTH_SCOPE_RESOURCES)[number];
38 
39/** The resource a scope targets (`pages:read` → `pages`); null for unknown. */
40export function scopeResource(scope: string): OAuthScopeResource | null {
41  const i = scope.indexOf(":");
42  if (i === -1) return null;
43  const r = scope.slice(0, i);
44  return (OAUTH_SCOPE_RESOURCES as readonly string[]).includes(r) ? (r as OAuthScopeResource) : null;
45}
46 
47/** Human descriptions for the consent screen (static strings only). */
48export const OAUTH_SCOPE_DESCRIPTIONS: Record<OAuthScope, string> = {
49  "pages:read": "View pages",
50  "pages:write": "Create and edit pages",
51  "databases:read": "View databases and records",
52  "databases:write": "Create and edit databases and records",
53  "files:read": "View and download files",
54  "files:write": "Upload and manage files"
55};
56 
57/**
58 * The permission LEVEL an OAuth token exercises, derived from its scopes —
59 * the OAuth counterpart of `apiKeyScopeCap` (lib/authorize.ts, TASK-0127):
60 *
61 *   - any `*:write` scope  → EDIT (mutations; COMMENT-level ops sit below)
62 *   - only `*:read` scopes → VIEW (reads)
63 *   - no scopes            → NONE
64 *
65 * There is deliberately NO scope that reaches FULL_ACCESS: a third-party app
66 * never gets admin (owner/admin-only gates stay closed to OAuth tokens —
67 * recorded in C-13.7).
68 */
69export function oauthScopeCap(scopes: string[]): Level {
70  if (scopes.some((s) => s.endsWith(":write"))) return "EDIT";
71  if (scopes.some((s) => s.endsWith(":read"))) return "VIEW";
72  return "NONE";
73}
74 
75/**
76 * The OAuth scope whose ABSENCE should be named in a 403 SCOPE_DENIED detail
77 * (`details[0].scope`) when a token's cap is below `need`:
78 *   - need ≥ EDIT (write ops) → `<resource>:write`
79 *   - need ≤ VIEW (read ops)  → `<resource>:read`
80 * The resource is inferred from the asserted resource scope (pageId → pages,
81 * databaseId → databases, fileId → files); with no resource named it falls
82 * back to the resource of the token's first recognized scope, else "pages".
83 */
84export function missingOAuthScope(
85  need: Level,
86  scopes: string[],
87  resource?: { pageId?: string; databaseId?: string; fileId?: string }
88): string {
89  const action: "read" | "write" = need === "VIEW" || need === "NONE" ? "read" : "write";
90  let r: OAuthScopeResource | null = null;
91  if (resource?.pageId) r = "pages";
92  else if (resource?.databaseId) r = "databases";
93  else if (resource?.fileId) r = "files";
94  else {
95    for (const s of scopes) {
96      const sr = scopeResource(s);
97      if (sr) {
98        r = sr;
99        break;
100      }
101    }
102    if (!r) r = "pages";
103  }
104  return `${r}:${action}`;
105}
106 
107/** Split a space-separated `scope` wire value into a clean, ordered list. */
108export function parseScopeList(scope?: string | null): string[] {
109  if (!scope) return [];
110  const seen = new Set<string>();
111  for (const part of scope.split(" ")) {
112    const s = part.trim();
113    if (s && !seen.has(s)) seen.add(s);
114  }
115  return [...seen];
116}
117 
118/** Serialize to the space-separated wire format (canonical catalog order). */
119export function serializeScopeList(scopes: string[]): string {
120  return OAUTH_SCOPES.filter((s) => scopes.includes(s as OAuthScope)).join(" ");
121}
122 
123/** PKCE S256 (RFC 7636): BASE64URL(SHA256(ASCII(verifier))). */
124export function pkceChallenge(verifier: string): string {
125  return createHash("sha256")
126    .update(verifier, "ascii")
127    .digest("base64")
128    .replace(/\+/g, "-")
129    .replace(/\//g, "_")
130    .replace(/=+$/, "");
131}
132