@volter/twin-planetscale 0.1.0

package/api/src/token-gate.ts

@@ -0,0 +1,96 @@
+// The management lane's service-token gate, in front of its dispatch. PlanetScale reads a service token as
+// `Authorization: <SERVICE_TOKEN_ID>:<SERVICE_TOKEN>` (https://planetscale.com/docs/api/reference/service-tokens), and each
+// operation names, in its spec's "Authorization" section, the service token accesses any one of which lets a token call
+// it (`ACCESSES` below, copied from those sections for the operations this lane serves).
+//
+// Where the reference stops and the twin decides: a request without a well-formed token is 401 (the spec lists 401 for
+// every operation), a token this lane made answers 401 when its secret is wrong and 403 when it holds none of the
+// operation's accesses, and a token id no service token of this lane has is the World's own organization token, allowed
+// everything (as the World's own psdb credential is): an application pointed at the World (Dub's backup cron) carries
+// whatever token its own configuration holds.
+import { createHash } from 'node:crypto';
+import type { SemanticsContext } from '@volter/world-core';
+
+const ACCESSES: Record<string, string[]> = {
+  create_database: ['create_databases'],
+  get_database: ['read_database', 'delete_database', 'write_database', 'read_branch', 'delete_branch', 'create_branch', 'connect_branch', 'connect_production_branch', 'connect_production_read_only_branch', 'read_backups', 'write_backups', 'delete_backups'],
+  delete_database: ['delete_database'],
+  create_password: ['connect_production_branch', 'connect_production_read_only_branch', 'connect_branch'],
+  list_passwords: ['read_branch', 'delete_branch', 'create_branch', 'connect_production_branch', 'connect_production_read_only_branch', 'connect_branch'],
+  get_password: ['read_branch', 'delete_branch', 'create_branch', 'connect_production_branch', 'connect_production_read_only_branch', 'connect_branch'],
+  delete_password: ['delete_production_branch_password', 'delete_production_read_only_branch_password', 'delete_branch_password'],
+  create_backup: ['write_backups'],
+  list_backups: ['read_backups'],
+  get_backup: ['read_backups'],
+  delete_backup: ['delete_backups', 'delete_production_branch_backups'],
+  create_branch: ['create_branch', 'restore_production_branch_backup', 'restore_backup'],
+  get_branch: ['read_branch', 'delete_branch', 'create_branch', 'connect_production_branch', 'connect_branch'],
+  list_branches: ['read_branch', 'delete_branch', 'create_branch', 'connect_production_branch', 'connect_branch'],
+  delete_branch: ['delete_branch'],
+  // the spec's enable/disable_safe_migrations name no access; the twin asks what changing a database's setup asks
+  enable_safe_migrations: ['write_database'],
+  disable_safe_migrations: ['write_database'],
+  update_database_settings: ['write_database'],
+  create_deploy_request: ['create_deploy_request'],
+  get_deploy_request: ['read_deploy_request'],
+  list_deploy_requests: ['read_deploy_request'],
+  get_deployment: ['read_deploy_request'],
+  list_deploy_operations: ['read_deploy_request'],
+  list_deploy_request_reviews: ['read_deploy_request'],
+  review_deploy_request: ['approve_deploy_request', 'review_deploy_request'],
+  queue_deploy_request: ['create_deploy_request'],
+  close_deploy_request: ['create_deploy_request'],
+  complete_revert: ['create_deploy_request'],
+  list_audit_logs: ['read_audit_logs'],
+  create_backup_policy: ['write_backups'],
+  list_backup_policies: ['read_backups'],
+  get_backup_policy: ['read_backups'],
+  create_service_token: ['write_service_tokens'],
+  list_service_tokens: ['read_service_tokens'],
+  delete_service_token: ['delete_service_tokens'],
+};
+
+const refuse = (status: number, code: string, message: string): Response => Response.json({ code, message }, { status });
+
+/** The accesses the calling token holds on `database` (its organization accesses count everywhere), or undefined for a
+ *  token this lane did not make (the World's own, allowed everything). A handler asks it where one operation needs a
+ *  different access by what it acts on (a production branch's password, a restore from a production backup). */
+export function heldAccesses(ctx: SemanticsContext, database: string): Set<string> | undefined {
+  const id = /^([^:\s]+):/.exec(ctx.call.request.headers.get('authorization') ?? '')?.[1];
+  const token = id === undefined ? undefined : ctx.rowsRaw('ServiceToken').find((t) => t.id === id);
+  if (token === undefined) return undefined;
+  return new Set(((token.service_token_accesses ?? []) as Array<{ access: string; resource_type: string; resource_name: string }>)
+    .filter((a) => a.resource_type === 'Organization' || (a.resource_type === 'Database' && a.resource_name === database)).map((a) => a.access));
+}
+
+/** PlanetScale's 403 for a token that lacks every one of `needed`, or undefined when it holds one. */
+export function lacks(ctx: SemanticsContext, database: string, needed: string[]): Response | undefined {
+  const held = heldAccesses(ctx, database);
+  if (held === undefined || needed.some((a) => held.has(a))) return undefined;
+  return refuse(403, 'forbidden', `Forbidden: this service token needs one of these accesses: ${needed.join(', ')}`);
+}
+
+/** The gate's answer for a request, or undefined when it may pass. `operation` is the operation it matched, if any. */
+export function tokenGate(ctx: SemanticsContext, request: Request, operation: string | undefined): Response | undefined {
+  const header = request.headers.get('authorization') ?? '';
+  const m = /^([^:\s]+):(\S+)$/.exec(header);
+  if (!m) return refuse(401, 'unauthorized', 'Unauthorized: send a service token as Authorization: <SERVICE_TOKEN_ID>:<SERVICE_TOKEN>');
+  const token = ctx.rowsRaw('ServiceToken').find((t) => t.id === m[1]);
+  if (token === undefined) return undefined;
+  // a token deleted on the settings page or by delete_service_token is refused as any token PlanetScale does not hold
+  if (token._deleted_at) return refuse(401, 'unauthorized', 'Unauthorized: the service token is not valid');
+  // a token whose ttl has passed "will be invalid" (the spec's create_service_token)
+  if (typeof token.expires_at === 'string' && Date.parse(token.expires_at) <= Date.parse(ctx.occurredAt)) return refuse(401, 'unauthorized', 'Unauthorized: the service token is not valid');
+  if (token._secret_sha256 !== createHash('sha256').update(m[2]!).digest('hex')) return refuse(401, 'unauthorized', 'Unauthorized: the service token is not valid');
+  const needed = operation === undefined ? undefined : ACCESSES[operation];
+  if (needed === undefined) return undefined;
+  const database = ctx.call.params.database;
+  const held = ((token.service_token_accesses ?? []) as Array<{ access: string; resource_type: string; resource_name: string }>)
+    .filter((a) => a.resource_type === 'Organization' || (a.resource_type === 'Database' && a.resource_name === database));
+  return held.some((a) => needed.includes(a.access)) ? undefined : forbidden(needed);
+}
+
+/** PlanetScale's 403 for a token that holds none of an operation's accesses. */
+function forbidden(needed: string[]): Response {
+  return refuse(403, 'forbidden', `Forbidden: this service token needs one of these accesses: ${needed.join(', ')}`);
+}

package/dist/api/src/fetch.d.ts

@@ -0,0 +1,8 @@
+import { type DerivedFetch } from '@volter/world-core';
+export declare function createPlanetscaleApiLaneFetch(options?: {
+    root?: string;
+    readOnly?: boolean;
+    clock?: () => string;
+}): DerivedFetch & {
+    catchUp: (request: Request) => Promise<void>;
+};

package/dist/api/src/fetch.js

@@ -0,0 +1,51 @@
+// The management API lane of the planetscale pack (`api.planetscale.com/v1`), the lane's own dispatch: the pack's router
+// (../../src/planetscale-server.ts) sends every `/v1/organizations` request here, and the organization's service tokens
+// page (`app.planetscale.com/{organization}/settings/service-tokens`, screens/). The generated surface is PlanetScale's
+// own Swagger document; the service-token gate sits in front of the dispatch (token-gate.ts), then the kernel's
+// cross-cutting checks (read-only, a malformed body), then the handlers (semantics/). An operation this lane does not
+// serve answers PlanetScale's 404: the gap.
+import { bindSemantics, compileSurface, coreFor, createDerivedFetch, crossCutting, matchOperation, semanticsContext } from '@volter/world-core';
+import surface from './generated/surface.gen.json' with { type: 'json' };
+import { manifest } from "./manifest.js";
+import { apiSemantics } from "./semantics/index.js";
+import { catchUp } from "./semantics/time.js";
+import { tokenGate } from "./token-gate.js";
+import { serviceTokensPage } from "./screens/service-tokens.js";
+import { sessionFlow } from "./screens/session.js";
+import { deployRequestPage } from "./screens/deploy-request.js";
+const SCREEN = { id: 'ServiceTokensPage', method: 'POST', path: '/{organization}/settings/service-tokens', class: 'action' };
+const GATE = { id: 'TwinTokenGate', method: 'GET', path: '/v1/organizations', class: 'retrieve' };
+export function createPlanetscaleApiLaneFetch(options = {}) {
+    const scope = { ...(options.root !== undefined ? { root: options.root } : {}), ...(options.clock ? { clock: options.clock } : {}) };
+    const derived = createDerivedFetch({
+        surface: surface,
+        handlers: bindSemantics(manifest, apiSemantics, scope),
+        core: coreFor(manifest, scope),
+        around: crossCutting(manifest, { readOnly: options.readOnly ?? false, ...scope }),
+        gap: () => Response.json({ code: 'not_found', message: 'Not Found' }, { status: 404 }),
+    });
+    const routes = compileSurface(surface);
+    const contextFor = (request) => semanticsContext(manifest, request, SCREEN, scope);
+    return Object.assign(async (request) => {
+        // what the World clock has made due (a database turning ready, a backup running and completing) happens first, so
+        // every door reads the lane as it stands now (semantics/time.ts)
+        if (!options.readOnly)
+            await catchUp(await contextFor(new Request(request.url)));
+        // the organization's settings page, where a person makes a token and grants its accesses (screens/service-tokens.tsx)
+        const screen = (await sessionFlow(request.clone(), await contextFor(new Request(request.url))))
+            ?? (await serviceTokensPage(request.clone(), contextFor)) ?? (await deployRequestPage(request, contextFor));
+        if (screen)
+            return screen;
+        const url = new URL(request.url);
+        const matched = matchOperation(routes, request.method, url.pathname, url.searchParams, request.headers);
+        const ctx = await semanticsContext(manifest, new Request(request.url, { headers: request.headers }), matched?.operation ?? GATE, scope);
+        const call = { ...ctx.call, params: matched?.params ?? {} };
+        return tokenGate({ ...ctx, call }, request, matched?.operation.id) ?? derived(request);
+    }, {
+        owners: () => derived.owners(),
+        /** What the World clock has made due, caught up for a request another wire of the pack answers (psdb's Execute reads
+         *  the branch a deploy has just changed): a move time makes happens when any request next arrives. */
+        catchUp: async (request) => { if (!options.readOnly)
+            await catchUp(await contextFor(new Request(request.url))); },
+    });
+}

package/dist/api/src/fetch.ts

@@ -0,0 +1,50 @@
+// The management API lane of the planetscale pack (`api.planetscale.com/v1`), the lane's own dispatch: the pack's router
+// (../../src/planetscale-server.ts) sends every `/v1/organizations` request here, and the organization's service tokens
+// page (`app.planetscale.com/{organization}/settings/service-tokens`, screens/). The generated surface is PlanetScale's
+// own Swagger document; the service-token gate sits in front of the dispatch (token-gate.ts), then the kernel's
+// cross-cutting checks (read-only, a malformed body), then the handlers (semantics/). An operation this lane does not
+// serve answers PlanetScale's 404: the gap.
+import { bindSemantics, compileSurface, coreFor, createDerivedFetch, crossCutting, matchOperation, semanticsContext, type DerivedFetch, type DerivedOperation, type DerivedSurface } from '@volter/world-core';
+import surface from './generated/surface.gen.json' with { type: 'json' };
+import { manifest } from './manifest.ts';
+import { apiSemantics } from './semantics/index.ts';
+import { catchUp } from './semantics/time.ts';
+import { tokenGate } from './token-gate.ts';
+import { serviceTokensPage } from './screens/service-tokens.tsx';
+import { sessionFlow } from './screens/session.tsx';
+import { deployRequestPage } from './screens/deploy-request.tsx';
+
+const SCREEN: DerivedOperation = { id: 'ServiceTokensPage', method: 'POST', path: '/{organization}/settings/service-tokens', class: 'action' };
+const GATE: DerivedOperation = { id: 'TwinTokenGate', method: 'GET', path: '/v1/organizations', class: 'retrieve' };
+
+export function createPlanetscaleApiLaneFetch(options: { root?: string; readOnly?: boolean; clock?: () => string } = {}): DerivedFetch & { catchUp: (request: Request) => Promise<void> } {
+  const scope = { ...(options.root !== undefined ? { root: options.root } : {}), ...(options.clock ? { clock: options.clock } : {}) };
+  const derived = createDerivedFetch({
+    surface: surface as DerivedSurface,
+    handlers: bindSemantics(manifest, apiSemantics, scope),
+    core: coreFor(manifest, scope),
+    around: crossCutting(manifest, { readOnly: options.readOnly ?? false, ...scope }),
+    gap: () => Response.json({ code: 'not_found', message: 'Not Found' }, { status: 404 }),
+  });
+  const routes = compileSurface(surface as DerivedSurface);
+  const contextFor = (request: Request) => semanticsContext(manifest, request, SCREEN, scope);
+  return Object.assign(async (request: Request): Promise<Response> => {
+    // what the World clock has made due (a database turning ready, a backup running and completing) happens first, so
+    // every door reads the lane as it stands now (semantics/time.ts)
+    if (!options.readOnly) await catchUp(await contextFor(new Request(request.url)));
+    // the organization's settings page, where a person makes a token and grants its accesses (screens/service-tokens.tsx)
+    const screen = (await sessionFlow(request.clone(), await contextFor(new Request(request.url))))
+      ?? (await serviceTokensPage(request.clone(), contextFor)) ?? (await deployRequestPage(request, contextFor));
+    if (screen) return screen;
+    const url = new URL(request.url);
+    const matched = matchOperation(routes, request.method, url.pathname, url.searchParams, request.headers);
+    const ctx = await semanticsContext(manifest, new Request(request.url, { headers: request.headers }), matched?.operation ?? GATE, scope);
+    const call = { ...ctx.call, params: matched?.params ?? {} };
+    return tokenGate({ ...ctx, call }, request, matched?.operation.id) ?? derived(request);
+  }, {
+    owners: () => derived.owners(),
+    /** What the World clock has made due, caught up for a request another wire of the pack answers (psdb's Execute reads
+     *  the branch a deploy has just changed): a move time makes happens when any request next arrives. */
+    catchUp: async (request: Request): Promise<void> => { if (!options.readOnly) await catchUp(await contextFor(new Request(request.url))); },
+  });
+}