@agilesyndrome/cf-genai-base 0.1.5 → 0.2.5

package/CONTRACT.md

@@ -4,7 +4,7 @@ Every site built from this foundation follows the same edge contract.
 
 ## Worker entrypoint
 
-`createWorker({ fetch, features?, middleware?, auth?, scheduled?, security? })` owns the Worker lifecycle. Features run in declaration order and may call `next()` or return a response. The site router owns pages, APIs, D1 queries, and R2 object keys. `scheduled`
+`createWorker({ fetch, features?, middleware?, auth?, authorize?, scheduled?, security? })` owns the Worker lifecycle and reserved admin boundary. Features run in declaration order and may call `next()` or return a response. The site router owns pages, APIs, D1 queries, and R2 object keys. `scheduled`
 is optional and must use `ctx.waitUntil` for background work.
 
 ## Routes
@@ -12,7 +12,12 @@ is optional and must use `ctx.waitUntil` for background work.
 - `GET /health` returns `{ ok, version, build_number }` and is cache-disabled.
 - `GET /api/me` returns `{ user: null | { sub, email, name, ...roles } }`.
 - `/auth/login`, `/auth/callback`, and `/auth/logout` are reserved for auth.
-- Public APIs must be explicitly listed in auth configuration.
+- `/admin` and `/admin/*` are browser admin routes; `/api/admin` and `/api/admin/*` are admin API routes.
+- Admin routes use `AUTH_STRATEGY`; omitted or empty means `http_basic`. Basic auth accepts username `admin` and the value of `ADMIN_TOKEN` (with `admin_token` supported for compatibility). Missing token means all admin routes return 401.
+- `AUTH_STRATEGY=oauth` delegates identity establishment to the configured auth provider and uses `authorize` for admin policy.
+- `scopes` registers an application scope manifest. `scopeRoutes` associates route prefixes or match functions with required scopes.
+- Base provides `/api/admin/users`, `/api/admin/scopes`, and `/api/admin/users/:id/scopes` for platform administrators when the authorization migration is installed.
+- Public APIs must be explicitly listed in provider-specific auth configuration.
 - Mutating `/api/*` requests require a same-origin `Origin` header.
 
 ## Environment and bindings
@@ -32,6 +37,10 @@ Standard bindings:
 
 Build metadata is optional: `BUILD_SHA` and `BUILD_NUMBER`.
 
+The package includes `migrations/0001_authorization.sql`; each site must apply
+the equivalent migration to its own D1 database before enabling the generic
+user/scope APIs.
+
 D1 migrations are committed with the site, applied by Wrangler, and are the
 source of truth for schema changes. R2 stores binary data; metadata and access
 control remain in D1.

package/README.md

@@ -2,11 +2,17 @@
 
 Opinionated startup boilerplate for small Cloudflare Workers.
 
-The base is deliberately small: a site still owns its router, HTML, D1
-queries, R2 keys, and scheduled jobs. `createWorker` composes ordered feature middleware, normalizes uncaught failures, and applies baseline response headers.
+The base owns the shared security boundary as well as Worker lifecycle concerns. It reserves `/admin` and `/api/admin` routes, authenticates them using `AUTH_STRATEGY` (default `http_basic`, or `oauth` when an auth provider is supplied), and applies the optional `authorize` policy. Sites still own their router, HTML, D1 queries, R2 keys, and scheduled jobs.
 Use D1 bindings for durable application data and R2 bindings for binary assets;
 do not put either into module-level state.
 
+Base also provides provider-neutral authorization helpers and browser components
+through `@agilesyndrome/cf-genai-base/authorization` and
+`@agilesyndrome/cf-genai-base/ui`. Applications declare their scope manifest,
+while base owns the user, scope, and grant records plus the generic user-access
+API. The UI components are themeable with CSS custom properties and do not
+contain application-specific components.
+
 ```js
 import { createWorker, healthResponse } from "@agilesyndrome/cf-genai-base";
 

package/migrations/0001_authorization.sql

@@ -0,0 +1,32 @@
+CREATE TABLE IF NOT EXISTS auth_users (
+  id TEXT PRIMARY KEY,
+  provider TEXT NOT NULL,
+  subject TEXT NOT NULL,
+  email TEXT NOT NULL DEFAULT '',
+  display_name TEXT NOT NULL DEFAULT '',
+  is_admin INTEGER NOT NULL DEFAULT 0 CHECK (is_admin IN (0,1)),
+  created_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  updated_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  UNIQUE(provider, subject)
+);
+
+CREATE INDEX IF NOT EXISTS auth_users_email_idx ON auth_users(email COLLATE NOCASE);
+
+CREATE TABLE IF NOT EXISTS auth_scopes (
+  name TEXT PRIMARY KEY,
+  label TEXT NOT NULL,
+  description TEXT NOT NULL DEFAULT '',
+  system INTEGER NOT NULL DEFAULT 0 CHECK (system IN (0,1)),
+  created_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  updated_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP
+);
+
+CREATE TABLE IF NOT EXISTS auth_user_scopes (
+  user_id TEXT NOT NULL REFERENCES auth_users(id) ON DELETE CASCADE,
+  scope_name TEXT NOT NULL REFERENCES auth_scopes(name) ON DELETE CASCADE,
+  granted_by TEXT,
+  granted_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  PRIMARY KEY (user_id, scope_name)
+);
+
+CREATE INDEX IF NOT EXISTS auth_user_scopes_scope_idx ON auth_user_scopes(scope_name);

package/package.json

@@ -1,9 +1,12 @@
 {
   "name": "@agilesyndrome/cf-genai-base",
-  "version": "0.1.5",
+  "version": "0.2.5",
   "type": "module",
   "exports": {
-    ".": "./src/index.js"
+    ".": "./src/index.js",
+    "./authorization": "./src/authorization.js",
+    "./ui": "./src/ui/index.js",
+    "./ui/styles.css": "./src/ui/styles.css"
   },
   "description": "Lean Worker lifecycle and security helpers for Cloudflare sites.",
   "license": "MIT",
@@ -13,6 +16,7 @@
   },
   "files": [
     "src",
+    "migrations",
     "README.md",
     "CONTRACT.md",
     "LICENSE"
@@ -24,7 +28,7 @@
   "homepage": "https://github.com/agilesyndrome/cf-genai-base#readme",
   "scripts": {
     "check": "node --check src/index.js",
-    "test": "node --check src/index.js",
+    "test": "node --test tests/*.test.mjs",
     "build": "npm run check && npm test && npm pack --dry-run"
   }
 }

package/src/authorization.js

@@ -0,0 +1,70 @@
+export const AUTH_USER_TABLE = "auth_users";
+export const AUTH_SCOPE_TABLE = "auth_scopes";
+export const AUTH_GRANT_TABLE = "auth_user_scopes";
+
+export function normalizeScopes(scopes = []) {
+  return scopes.map((scope) => typeof scope === "string" ? { name: scope, label: scope, description: "", system: false } : scope)
+    .filter((scope) => scope && /^[a-z0-9]+(?::[a-z0-9-]+)+$/.test(String(scope.name || "")))
+    .map((scope) => ({ name: String(scope.name), label: String(scope.label || scope.name), description: String(scope.description || ""), system: Boolean(scope.system) }));
+}
+
+export async function ensureScopes(env, scopes = []) {
+  if (!env?.DB) return;
+  for (const scope of normalizeScopes(scopes)) {
+    await env.DB.prepare(`INSERT INTO ${AUTH_SCOPE_TABLE} (name,label,description,system) VALUES (?,?,?,?) ON CONFLICT(name) DO UPDATE SET label=excluded.label,description=excluded.description,system=excluded.system`).bind(scope.name, scope.label, scope.description, scope.system ? 1 : 0).run();
+  }
+}
+
+export async function ensureUser(env, user) {
+  if (!env?.DB || !user?.sub) return null;
+  const provider = String(user.auth_strategy || "oauth");
+  const subject = String(user.sub);
+  const email = String(user.email || "").trim().toLowerCase();
+  const existing = await env.DB.prepare(`SELECT * FROM ${AUTH_USER_TABLE} WHERE provider=? AND subject=?`).bind(provider, subject).first();
+  const bootstrap = new Set(String(env.AUTH_ADMIN_EMAILS || env.ADMIN_EMAILS || "").split(",").map((value) => value.trim().toLowerCase()).filter(Boolean));
+  if (existing) {
+    await env.DB.prepare(`UPDATE ${AUTH_USER_TABLE} SET email=?,display_name=?,is_admin=CASE WHEN is_admin=1 OR ? THEN 1 ELSE 0 END,updated_at=CURRENT_TIMESTAMP WHERE id=?`).bind(email, String(user.name || email || subject), bootstrap.has(email) ? 1 : 0, existing.id).run();
+    return { ...existing, email, display_name: String(user.name || email || subject), is_admin: Boolean(existing.is_admin || bootstrap.has(email)) };
+  }
+  const id = await stableId(`${provider}:${subject}`);
+  await env.DB.prepare(`INSERT INTO ${AUTH_USER_TABLE} (id,provider,subject,email,display_name,is_admin) VALUES (?,?,?,?,?,?) ON CONFLICT(provider,subject) DO NOTHING`).bind(id, provider, subject, email, String(user.name || email || subject), bootstrap.has(email) ? 1 : 0).run();
+  return await env.DB.prepare(`SELECT * FROM ${AUTH_USER_TABLE} WHERE id=?`).bind(id).first();
+}
+
+export async function hasScope(env, user, scope) {
+  if (user?.auth_strategy === "http_basic") return true;
+  const authUser = await ensureUser(env, user);
+  if (!authUser) return false;
+  if (Boolean(authUser.is_admin)) return true;
+  return Boolean(await env.DB.prepare(`SELECT 1 FROM ${AUTH_GRANT_TABLE} WHERE user_id=? AND scope_name=?`).bind(authUser.id, scope).first());
+}
+
+export async function listAuthorizationUsers(env) {
+  const { results } = await env.DB.prepare(`SELECT id,email,display_name,provider,subject,is_admin,created_at,updated_at FROM ${AUTH_USER_TABLE} ORDER BY email COLLATE NOCASE`).all();
+  return Promise.all(results.map(async (user) => ({ ...user, scopes: (await listUserGrants(env, user.id)).map((grant) => grant.scope_name) })));
+}
+
+export async function listAuthorizationScopes(env) {
+  const { results } = await env.DB.prepare(`SELECT name,label,description,system FROM ${AUTH_SCOPE_TABLE} ORDER BY name`).all();
+  return results;
+}
+
+export async function listUserGrants(env, userId) {
+  const { results } = await env.DB.prepare(`SELECT scope_name,granted_at FROM ${AUTH_GRANT_TABLE} WHERE user_id=? ORDER BY scope_name`).bind(userId).all();
+  return results;
+}
+
+export async function replaceUserGrants(env, userId, scopes, grantedBy) {
+  const valid = new Set((await listAuthorizationScopes(env)).map((scope) => scope.name));
+  const requested = [...new Set(scopes)].filter((scope) => valid.has(scope));
+  await env.DB.batch([
+    env.DB.prepare(`DELETE FROM ${AUTH_GRANT_TABLE} WHERE user_id=?`).bind(userId),
+    ...requested.map((scope) => env.DB.prepare(`INSERT INTO ${AUTH_GRANT_TABLE} (user_id,scope_name,granted_by) VALUES (?,?,?)`).bind(userId, scope, grantedBy || null))
+  ]);
+  return requested;
+}
+
+async function stableId(value) {
+  const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(value));
+  return [...new Uint8Array(digest)].map((byte) => byte.toString(16).padStart(2, "0")).join("").slice(0, 32);
+}

package/src/index.js

@@ -2,9 +2,12 @@
  * Lean, opinionated Worker composition for Cloudflare sites.
  * Site code owns domain routes and data; this owns lifecycle and edge concerns.
  */
-export function createWorker({ fetch, scheduled, auth, middleware = [], features = [], health, boot, metrics, security = true }) {
+import { ensureScopes, ensureUser, hasScope, listAuthorizationScopes, listAuthorizationUsers, listUserGrants, replaceUserGrants } from "./authorization.js";
+export function createWorker({ fetch, scheduled, auth, authorize, scopes = [], scopeRoutes = [], middleware = [], features = [], health, boot, metrics, security = true }) {
   if (typeof fetch !== "function") throw new TypeError("createWorker requires a fetch handler");
+  const provider = auth || features.find((feature) => typeof feature?.getUser === "function");
   const chain = [
+    (request, env, ctx, next, state) => adminBoundary(request, env, ctx, next, state, { provider, authorize, scopes, scopeRoutes }),
     ...features.flatMap((feature) => feature?.middleware ? [feature.middleware.bind(feature)] : []),
     ...middleware,
     ...(auth ? [(request, env, ctx, next) => auth(request, env, ctx, next)] : []),
@@ -39,6 +42,85 @@ export function createWorker({ fetch, scheduled, auth, middleware = [], features
   };
 }
 
+
+async function adminBoundary(request, env, ctx, next, state, { provider, authorize, scopes, scopeRoutes }) {
+  const url = new URL(request.url);
+  if (!isAdminPath(url.pathname)) return next(request);
+  const strategy = String(env?.AUTH_STRATEGY || "http_basic").trim().toLowerCase();
+  if (strategy === "http_basic") {
+    const user = basicUser(request, env);
+    if (!user) return adminUnauthorized(request);
+    state.user = user;
+  } else if (strategy === "oauth") {
+    const user = provider?.getUser ? await provider.getUser(request, env) : null;
+    if (!user) return oauthUnauthorized(request, url);
+    state.user = user;
+  } else {
+    return new Response("Unsupported AUTH_STRATEGY", { status: 500, headers: { "Cache-Control": "no-store" } });
+  }
+  await ensureScopes(env, scopes);
+  state.authUser = await ensureUser(env, state.user);
+  const requiredScope = requiredScopeFor(url.pathname, scopeRoutes);
+  const scopeAllowed = !requiredScope || await hasScope(env, state.user, requiredScope);
+  if (!scopeAllowed || (authorize && state.user.auth_strategy !== "http_basic" && !(await authorize({ request, url, user: state.user, env, ctx, state })))) {
+    return url.pathname.startsWith("/api/") ? Response.json({ error: "Administrator access is required." }, { status: 403, headers: { "Cache-Control": "no-store" } }) : new Response("Administrator access is required.", { status: 403, headers: { "Cache-Control": "no-store" } });
+  }
+  const platformResponse = await authorizationApi(request, env, url, state);
+  return platformResponse || next(request);
+}
+
+function requiredScopeFor(pathname, routes) {
+  const route = routes.find((entry) => typeof entry.match === "function" ? entry.match(pathname) : pathname === entry.path || pathname.startsWith(String(entry.path || "") + "/"));
+  return route && route.scope ? route.scope : null;
+}
+
+async function authorizationApi(request, env, url, state) {
+  const grantsMatch = url.pathname.match(/\/api\/admin\/users\/([^/]+)\/scopes$/);
+  const platformPath = url.pathname === "/api/admin/users" || url.pathname === "/api/admin/scopes" || Boolean(grantsMatch);
+  if (!platformPath) return null;
+  if (!(state.user.auth_strategy === "http_basic" || (state.authUser && state.authUser.is_admin))) return Response.json({ error: "Administrator access is required." }, { status: 403, headers: { "Cache-Control": "no-store" } });
+  if (url.pathname === "/api/admin/users" && request.method === "GET") return Response.json({ users: await listAuthorizationUsers(env) });
+  if (url.pathname === "/api/admin/scopes" && request.method === "GET") return Response.json({ scopes: await listAuthorizationScopes(env) });
+  if (grantsMatch && request.method === "GET") return Response.json({ grants: await listUserGrants(env, decodeURIComponent(grantsMatch[1])) });
+  if (grantsMatch && request.method === "PUT") {
+    const body = await request.json().catch(() => null);
+    if (!body || !Array.isArray(body.scopes)) return Response.json({ error: "scopes must be an array" }, { status: 400 });
+    const grants = await replaceUserGrants(env, decodeURIComponent(grantsMatch[1]), body.scopes, state.authUser && state.authUser.id);
+    return Response.json({ grants });
+  }
+  return null;
+}
+
+function isAdminPath(pathname) {
+  return pathname === "/admin" || pathname.startsWith("/admin/") || pathname === "/api/admin" || pathname.startsWith("/api/admin/");
+}
+
+function basicUser(request, env) {
+  const token = String(env?.ADMIN_TOKEN || env?.admin_token || "");
+  if (!token) return null;
+  const header = request.headers.get("Authorization") || "";
+  if (!header.toLowerCase().startsWith("basic ")) return null;
+  let decoded;
+  try { decoded = atob(header.slice(6).trim()); } catch { return null; }
+  const separator = decoded.indexOf(":");
+  if (separator < 0) return null;
+  if (!constantTimeEqual(decoded.slice(0, separator), "admin") || !constantTimeEqual(decoded.slice(separator + 1), token)) return null;
+  return { sub: "basic:admin", email: "", name: "admin", roles: ["admin"], auth_strategy: "http_basic" };
+}
+
+function adminUnauthorized(request) {
+  const headers = { "Cache-Control": "no-store", "WWW-Authenticate": "Basic realm=\"admin\", charset=\"UTF-8\"" };
+  return new URL(request.url).pathname.startsWith("/api/") ? Response.json({ error: "Authentication is required." }, { status: 401, headers }) : new Response("Authentication is required.", { status: 401, headers });
+}
+
+function oauthUnauthorized(request, url) {
+  if (url.pathname.startsWith("/api/")) return Response.json({ error: "Authentication is required." }, { status: 401, headers: { "Cache-Control": "no-store" } });
+  return Response.redirect(url.origin + "/auth/login?return_to=" + encodeURIComponent(safeReturnTo(url.pathname + url.search)), 302);
+}
+
+function safeReturnTo(value) { return value?.startsWith("/") && !value.startsWith("//") && !value.startsWith("/auth/") ? value : "/"; }
+function constantTimeEqual(a, b) { const aa = new TextEncoder().encode(a), bb = new TextEncoder().encode(b); let n = aa.length ^ bb.length; for (let i = 0; i < Math.max(aa.length, bb.length); i++) n |= (aa[i] || 0) ^ (bb[i] || 0); return n === 0; }
+
 export function validateBoot(env, { bindings = [], required = [] } = {}) {
   const missingBindings = bindings.filter((name) => !env?.[name]);
   const missingValues = required.filter((name) => !env?.[name] || String(env[name]).startsWith("replace-with-"));

package/src/ui/index.js

@@ -0,0 +1,51 @@
+const styles = `:host { --cf-ui-bg:#fff; --cf-ui-surface:#f7f7f5; --cf-ui-text:#20231f; --cf-ui-muted:#687067; --cf-ui-border:#d8ddd5; --cf-ui-primary:#2f6f52; color:var(--cf-ui-text); font:15px/1.45 system-ui,sans-serif } *,*::before,*::after{box-sizing:border-box}.shell{display:grid;gap:1rem}.nav{display:flex;flex-wrap:wrap;gap:.5rem;border-bottom:1px solid var(--cf-ui-border);padding-bottom:.75rem}.nav a{color:var(--cf-ui-text);padding:.45rem .7rem;border-radius:.4rem;text-decoration:none}.nav a:hover,.nav a[aria-current=page]{background:var(--cf-ui-surface);color:var(--cf-ui-primary)}.card{background:var(--cf-ui-bg);border:1px solid var(--cf-ui-border);border-radius:.6rem;padding:1rem;overflow:auto}table{width:100%;border-collapse:collapse}th,td{padding:.65rem;border-bottom:1px solid var(--cf-ui-border);text-align:left;vertical-align:top}th{color:var(--cf-ui-muted);font-size:.8rem;text-transform:uppercase;letter-spacing:.04em}button{border:1px solid var(--cf-ui-border);border-radius:.4rem;background:var(--cf-ui-bg);color:inherit;padding:.45rem .65rem;cursor:pointer}.scope-list{display:grid;gap:.3rem;min-width:14rem}.scope-list label{display:flex;gap:.4rem;align-items:center}.status{color:var(--cf-ui-muted);min-height:1.4em}`;
+
+export class CfAdminShell extends HTMLElement {
+  connectedCallback() {
+    const active = this.getAttribute("active") || "";
+    this.attachShadow({ mode: "open" }).innerHTML = `<style>${styles}</style><div class="shell"><nav class="nav" part="navigation"><a href="/admin" ${active === "home" ? 'aria-current="page"' : ""}>Admin</a><a href="/admin/users" ${active === "users" ? 'aria-current="page"' : ""}>Users</a><a href="/admin/scopes" ${active === "scopes" ? 'aria-current="page"' : ""}>Scopes</a></nav><slot></slot></div>`;
+  }
+}
+
+export class CfScopeBadge extends HTMLElement {
+  connectedCallback() { this.attachShadow({ mode: "open" }).innerHTML = `<style>${styles}.badge{display:inline-block;border:1px solid var(--cf-ui-border);border-radius:999px;padding:.15rem .5rem;color:var(--cf-ui-primary);background:var(--cf-ui-surface);font-size:.85rem}</style><span class="badge" part="badge"></span>`; this.shadowRoot.querySelector(".badge").textContent = this.getAttribute("scope") || this.textContent || ""; }
+}
+
+export class CfUserManagement extends HTMLElement {
+  async connectedCallback() { this.attachShadow({ mode: "open" }).innerHTML = `<style>${styles}</style><section class="card" part="panel"><h2>User access</h2><p class="status" part="status">Loading users and scopes…</p><table hidden part="table"><thead><tr><th>User</th><th>Scopes</th><th>Save</th></tr></thead><tbody></tbody></table></section>`; try { await this.load(); } catch (error) { this.status.textContent = error.message || "Unable to load access data."; } }
+  get status() { return this.shadowRoot.querySelector(".status"); }
+  async load() { const [usersResponse, scopesResponse] = await Promise.all([fetch("/api/admin/users", { credentials: "same-origin" }), fetch("/api/admin/scopes", { credentials: "same-origin" })]); if (!usersResponse.ok || !scopesResponse.ok) throw new Error("Unable to load user access."); const users = (await usersResponse.json()).users || []; const scopes = (await scopesResponse.json()).scopes || []; const body = this.shadowRoot.querySelector("tbody"); body.replaceChildren(...users.map((user) => this.row(user, scopes))); this.shadowRoot.querySelector("table").hidden = false; this.status.textContent = `${users.length} user${users.length === 1 ? "" : "s"}`; }
+  row(user, scopes) { const row = document.createElement("tr"); const identity = document.createElement("td"); identity.textContent = `${user.display_name || user.email || "Unnamed user"} (${user.email || "no email"})`; const grants = document.createElement("td"); const list = document.createElement("div"); list.className = "scope-list"; for (const scope of scopes) { const label = document.createElement("label"); const input = document.createElement("input"); input.type = "checkbox"; input.value = scope.name; input.checked = Boolean((user.scopes || []).includes(scope.name)); label.append(input, document.createTextNode(scope.label || scope.name)); list.append(label); } grants.append(list); const action = document.createElement("td"); const button = document.createElement("button"); button.textContent = "Save"; button.addEventListener("click", async () => { button.disabled = true; const selected = [...list.querySelectorAll("input:checked")].map((input) => input.value); const response = await fetch(`/api/admin/users/${encodeURIComponent(user.id)}/scopes`, { method: "PUT", credentials: "same-origin", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ scopes: selected }) }); button.disabled = false; this.status.textContent = response.ok ? "Access saved." : "Unable to save access."; }); action.append(button); row.append(identity, grants, action); return row; }
+}
+
+if (!customElements.get("cf-admin-shell")) customElements.define("cf-admin-shell", CfAdminShell);
+if (!customElements.get("cf-scope-badge")) customElements.define("cf-scope-badge", CfScopeBadge);
+if (!customElements.get("cf-user-management")) customElements.define("cf-user-management", CfUserManagement);
+
+export class CfScopeCatalog extends HTMLElement {
+  async connectedCallback() {
+    this.attachShadow({ mode: "open" }).innerHTML = `<style>${styles}</style><section class="card" part="panel"><h2>Available scopes</h2><p class="status" part="status">Loading scopes…</p><div class="scope-list" hidden part="list"></div></section>`;
+    try {
+      const response = await fetch("/api/admin/scopes", { credentials: "same-origin" });
+      if (!response.ok) throw new Error("Unable to load scopes.");
+      const scopes = (await response.json()).scopes || [];
+      const list = this.shadowRoot.querySelector(".scope-list");
+      list.replaceChildren(...scopes.map((scope) => {
+        const item = document.createElement("div");
+        const badge = document.createElement("cf-scope-badge");
+        badge.setAttribute("scope", scope.name);
+        const description = document.createElement("span");
+        description.textContent = scope.description || scope.label || scope.name;
+        item.append(badge, description);
+        return item;
+      }));
+      list.hidden = false;
+      this.shadowRoot.querySelector(".status").textContent = `${scopes.length} scope${scopes.length === 1 ? "" : "s"}`;
+    } catch (error) {
+      this.shadowRoot.querySelector(".status").textContent = error.message || "Unable to load scopes.";
+    }
+  }
+}
+
+if (!customElements.get("cf-scope-catalog")) customElements.define("cf-scope-catalog", CfScopeCatalog);
+if (!customElements.get("cf-scope-catalog")) customElements.define("cf-scope-catalog", CfScopeCatalog);

package/src/ui/styles.css

@@ -0,0 +1,9 @@
+:root {
+  --cf-ui-bg: #ffffff;
+  --cf-ui-surface: #f7f7f5;
+  --cf-ui-text: #20231f;
+  --cf-ui-muted: #687067;
+  --cf-ui-border: #d8ddd5;
+  --cf-ui-primary: #2f6f52;
+  --cf-ui-danger: #a33b32;
+}