@volter/twin-planetscale 0.1.0

package/dist/api/src/semantics/shared.ts

@@ -0,0 +1,141 @@
+// What the management lane's handlers share: id minting, the paginated list answer, and the database a path names.
+import { createHash } from 'node:crypto';
+import type { SemanticsContext } from '@volter/world-core';
+
+type Row = Record<string, unknown>;
+
+/** An id from the instant, a seed and the count, stepped past any id already stored (two creates at one instant). */
+export function mintId(ctx: SemanticsContext, resource: string, prefix: string, seed: string): string {
+  const taken = new Set(ctx.rowsRaw(resource, { withDeleted: true }).map((r) => String(r.id)));
+  const n = taken.size + 1;
+  let id = '';
+  for (let k = 0; !id || taken.has(id); k++) id = `${prefix}${createHash('sha256').update(`${ctx.occurredAt}:${seed}:${n}:${k}`).digest('hex').slice(0, 12)}`;
+  return id;
+}
+
+/** A secret the vendor shows once, derived from what the World holds so a replay mints the same one. */
+export function mintSecret(prefix: string, seed: string, length: number): string {
+  return `${prefix}${createHash('sha256').update(seed).digest('base64url').slice(0, length)}`;
+}
+
+/** The spec's Paginated* answer over `rows`, paged by `page` and `per_page` (default 25). */
+export function page(ctx: SemanticsContext, rows: Row[]): Response {
+  const url = new URL(ctx.call.request.url);
+  const perPage = Math.max(1, Number(url.searchParams.get('per_page')) || 25);
+  const at = Math.max(1, Number(url.searchParams.get('page')) || 1);
+  const pages = Math.max(1, Math.ceil(rows.length / perPage));
+  const link = (p: number): string => { const u = new URL(url); u.searchParams.set('page', String(p)); return u.toString(); };
+  return ctx.reply({
+    type: 'list', current_page: at, per_page: perPage,
+    next_page: at < pages ? at + 1 : null, next_page_url: at < pages ? link(at + 1) : null,
+    prev_page: at > 1 ? at - 1 : null, prev_page_url: at > 1 ? link(at - 1) : null,
+    total_count: rows.length, total_pages: pages, data: rows.slice((at - 1) * perPage, at * perPage),
+  });
+}
+
+/** The database a path names. A database this lane created is found by its name (a deleted one answers 404); a name no
+ *  created database has is the World's own database, the one the psdb data plane serves: an application pointed at the
+ *  World (Dub's backup cron) addresses it by whatever names its own configuration holds. That second rule is the twin's
+ *  decision; the vendor answers 404 for a database the organization does not have. */
+export function databaseOf(ctx: SemanticsContext): { refused?: Response; record?: Row; branch?: Row } {
+  const name = String(ctx.call.params.database ?? '');
+  const record = ctx.rowsRaw('Database').find((d) => d.name === name);
+  if (record?._deleted_at) return { refused: ctx.notFound('Database', name, 'database') };
+  if (record === undefined) return {};
+  // a branch the path names must be one of the database's live branches (semantics/branches.ts)
+  const branch = ctx.call.params.branch;
+  if (branch === undefined) return { record };
+  const found = ctx.rowsRaw('DatabaseBranch').find((b) => b._database === name && b.name === branch && b.deleted_at === null);
+  if (!found) return { refused: ctx.notFound('DatabaseBranch', String(branch), 'branch') };
+  return { record, branch: found };
+}
+
+/** The branch a password or backup names, as the spec's `database_branch` reference carries it: the branch record, or
+ *  for the World's own database (no record) its production branch as the path names it. */
+export function branchRef(ctx: SemanticsContext, branch?: Row): Row {
+  return branch ? { id: String(branch.id), name: String(branch.name), production: branch.production === true, mysql_edge_address: 'aws.connect.psdb.cloud', private_edge_connectivity: false, created_at: String(branch.created_at), updated_at: String(branch.updated_at), deleted_at: null } : worldBranchRef(ctx);
+}
+
+/** The branch of the World's own database (one no lane record names), as the path names it. */
+function worldBranchRef(ctx: SemanticsContext): Row {
+  const name = String(ctx.call.params.branch ?? 'main');
+  return { id: `branch-${name}`, name, production: true, mysql_edge_address: 'aws.connect.psdb.cloud', private_edge_connectivity: false, created_at: ctx.occurredAt, updated_at: ctx.occurredAt, deleted_at: null };
+}
+
+/** The avatar an actor answers with: PlanetScale's fallback image, as its service-tokens page's example answer shows a
+ *  service token's actor with (https://planetscale.com/docs/api/reference/service-tokens: "avatar_url": a gravatar URL whose
+ *  default is https://app.planetscale.com/gravatar-fallback.png); the World holds no gravatar. */
+export const AVATAR = 'https://app.planetscale.com/gravatar-fallback.png';
+
+/** The one region a World's databases live in, as the service-tokens page's example answer gives AWS us-east-1
+ *  (https://planetscale.com/docs/api/reference/service-tokens, "Creating a PlanetScale branch with service tokens"): its
+ *  id, provider, public IP addresses, display name, location and slug. Where the page stops: which engines it supports
+ *  and whether it is the default for new branches, the twin's (MySQL and PostgreSQL, not Neki; the default). */
+export const REGION = (slug = 'us-east'): Row => ({
+  id: 'kc0e1ij8juzp', provider: 'AWS', enabled: true,
+  public_ip_addresses: ['23.23.187.137', '52.6.141.108', '52.70.2.89', '50.17.188.76', '52.2.251.189', '52.72.234.74', '35.174.68.24', '52.5.253.172', '54.156.81.4', '34.200.24.255', '35.174.79.154', '44.199.177.24'],
+  display_name: 'AWS us-east-1', location: 'Northern Virginia', slug, current_default: true, mysql_supported: true, postgresql_supported: true, neki_supported: false,
+});
+
+/** Each access's description, as the service tokens page's tables give it
+ *  (https://planetscale.com/docs/api/reference/service-tokens, "Organization access permissions" and "Database access
+ *  permissions"). */
+const ACCESS_DESCRIPTIONS: Record<string, string> = {
+  read_organization: "Get information about an organization",
+  read_invoices: "Get invoices for an organization",
+  read_audit_logs: "Get audit logs for an organization",
+  read_databases: "Get information about an organization's databases",
+  create_databases: "Create organization databases",
+  delete_databases: "Delete organization databases",
+  read_oauth_applications: "Get information about an organization's OAuth applications and their tokens",
+  read_oauth_tokens: "Get OAuth tokens for an OAuth application",
+  write_oauth_tokens: "Create and refresh OAuth grants and tokens for an OAuth application",
+  delete_oauth_tokens: "Delete OAuth tokens for an OAuth application",
+  read_service_tokens: "Get information about service tokens",
+  write_service_tokens: "Create and update service tokens",
+  delete_service_tokens: "Delete service tokens",
+  write_teams: "Create and update teams",
+  read_metrics_endpoints: "Get information about branch metrics endpoints",
+  read_database: "Get information about a database",
+  write_database: "Update information about a database",
+  delete_database: "Delete a database",
+  create_branch: "Create a database branch",
+  read_branch: "Read a database branch",
+  delete_branch: "Delete a database branch",
+  delete_production_branch: "Delete a production database branch",
+  connect_branch: "Connect to a database branch",
+  connect_production_branch: "Connect to a production database branch",
+  delete_branch_password: "Delete a password for a non-production branch",
+  delete_production_branch_password: "Delete a password for a production branch",
+  create_deploy_request: "Create a deploy request",
+  read_deploy_request: "Read a deploy request",
+  approve_deploy_request: "Approve a deploy request",
+  create_comment: "Create a deploy request comment",
+  read_comment: "Read a deploy request comment",
+  read_backups: "List backups",
+  write_backups: "Create and update backups",
+  delete_backups: "Delete development branch backups",
+  delete_production_branch_backups: "Delete production branch backups",
+  restore_backup: "Restore a development branch backup",
+  restore_production_branch_backup: "Restore a production branch backup",
+  write_branch_vschema: "Update the VSchema for a database branch",
+  write_production_branch_vschema: "Update the VSchema for a production database branch",
+};
+
+/** A service token access as the spec's ServiceToken answers it: the resource it gives access to, by name, id and the
+ *  resource itself. A database is its record; the organization, which the lane keeps no record of, is named by its
+ *  name, dated from the grant (the twin's decision). */
+export function accessOf(ctx: SemanticsContext, id: string, access: string, type: 'Database' | 'Organization', name: string): Row {
+  const db = type === 'Database' ? ctx.rowsRaw('Database').find((d) => d.name === name && !d._deleted_at) : undefined;
+  const resource = db
+    ? { id: String(db.id), name, created_at: String(db.created_at), updated_at: String(db.updated_at), deleted_at: null }
+    : { id: name, name, created_at: ctx.occurredAt, updated_at: ctx.occurredAt, deleted_at: null };
+  return { id, access, description: ACCESS_DESCRIPTIONS[access] ?? access, resource_name: name, resource_id: resource.id, resource_type: type, resource };
+}
+
+/** The actor the lane records on what it makes: the service token that asked, or the World's own. */
+export function actorOf(ctx: SemanticsContext): Row {
+  const id = /^([^:\s]+):/.exec(ctx.call.request.headers.get('authorization') ?? '')?.[1];
+  const token = id === undefined ? undefined : ctx.rowsRaw('ServiceToken').find((t) => t.id === id);
+  return token ? { id: String(token.id), display_name: String(token.display_name), avatar_url: AVATAR } : { id: 'service-token', display_name: 'Service token', avatar_url: AVATAR };
+}

package/dist/api/src/semantics/time.d.ts

@@ -0,0 +1,2 @@
+import type { SemanticsContext } from '@volter/world-core';
+export declare function catchUp(ctx: SemanticsContext): Promise<void>;

package/dist/api/src/semantics/time.js

@@ -0,0 +1,81 @@
+import { branchBytes } from "./index.js";
+import { catchUpDeployRequests } from "./deploy-requests.js";
+import { catchUpPolicies, COMPLETE_AFTER, snapshotBranch, START_AFTER } from "./backups.js";
+const READY_AFTER = 60_000;
+const later = (iso, ms) => new Date(Date.parse(iso) + ms).toISOString();
+export async function catchUp(ctx) {
+    const now = Date.parse(ctx.occurredAt);
+    for (const d of ctx.rowsRaw('Database')) {
+        if (d.state !== 'pending' || d._deleted_at)
+            continue;
+        const due = later(String(d.created_at), READY_AFTER);
+        if (Date.parse(due) > now)
+            continue;
+        const at = await ctx.at(due);
+        const refused = at.legal('Database', 'state', 'provision', 'pending', 'ready', String(d.id), 'time');
+        if (refused)
+            continue;
+        await at.write('Database', String(d.id), { ...at.own(d), state: 'ready', ready: true, updated_at: due }, 'database.ready');
+    }
+    // a branch turns ready as its database does, one minute after it was made (the twin's delay; PlanetScale's CI example
+    // waits for it: "pass the `--wait` flag", https://planetscale.com/docs/vitess/integrations/github-actions)
+    for (const br of ctx.rowsRaw('DatabaseBranch')) {
+        if (br.state !== 'pending' || br.deleted_at !== null)
+            continue;
+        const due = later(String(br.created_at), READY_AFTER);
+        if (Date.parse(due) > now)
+            continue;
+        const at = await ctx.at(due);
+        if (at.legal('DatabaseBranch', 'state', 'provision', 'pending', 'ready', String(br.id), 'time'))
+            continue;
+        await at.write('DatabaseBranch', String(br.id), { ...at.own(br), state: 'ready', ready: true, schema_ready: true, updated_at: due }, 'branch.ready');
+    }
+    // a password with a ttl expires when it has passed ("The password will be invalid when TTL has passed", the spec)
+    for (const p of ctx.rowsRaw('DatabaseBranchPassword')) {
+        if (p.expired === true || p.deleted_at !== null || typeof p.expires_at !== 'string' || Date.parse(p.expires_at) > now)
+            continue;
+        const at = await ctx.at(p.expires_at);
+        await at.write('DatabaseBranchPassword', String(p.id), { ...at.own(p), expired: true }, 'password.expire');
+    }
+    await catchUpDeployRequests(ctx);
+    await catchUpPolicies(ctx);
+    for (const k of ctx.rowsRaw('Backup')) {
+        if (k.deleted_at !== null && k.deleted_at !== undefined)
+            continue;
+        let row = k;
+        if (row.state === 'pending') {
+            const due = later(String(row.created_at), START_AFTER);
+            if (Date.parse(due) > now)
+                continue;
+            const at = await ctx.at(due);
+            if (at.legal('Backup', 'state', 'start', 'pending', 'running', String(row.id), 'time'))
+                continue;
+            await at.write('Backup', String(row.id), { ...at.own(row), state: 'running', started_at: due, updated_at: due }, 'backup.start');
+            row = at.rowsRaw('Backup').find((x) => x.id === row.id) ?? row;
+        }
+        if (row.state === 'running') {
+            const due = later(String(row.created_at), COMPLETE_AFTER);
+            if (Date.parse(due) > now)
+                continue;
+            const at = await ctx.at(due);
+            if (at.legal('Backup', 'state', 'complete', 'running', 'success', String(row.id), 'time'))
+                continue;
+            // what it holds: its branch's schema and rows (a restore copies them into a new branch); a backup of `main` is
+            // sized by the World's stored rows, as it always has been
+            const snapshot = await snapshotBranch(at, row);
+            const onMain = String(row.database_branch?.name ?? 'main') === 'main';
+            const size = onMain ? branchBytes(at) : snapshot.size;
+            const own = at.own(row);
+            await at.write('Backup', String(row.id), {
+                ...own, state: 'success', size, pvc_size: size, uncompressed_size: size, completed_at: due, updated_at: due,
+                expires_at: later(due, Number(own._retention_ms ?? 7 * 86_400_000)), _snapshot: snapshot.id,
+            }, 'backup.complete');
+            row = at.rowsRaw('Backup').find((x) => x.id === row.id) ?? row;
+        }
+        // a backup is deleted when its retention has passed (the twin's reading of a retention period)
+        if (row.state === 'success' && typeof row.expires_at === 'string' && Date.parse(row.expires_at) <= now && (row.deleted_at === null || row.deleted_at === undefined)) {
+            const at = await ctx.at(row.expires_at);
+            await at.write('Backup', String(row.id), { ...at.own(row), deleted_at: row.expires_at, updated_at: row.expires_at }, 'backup.expire');
+        }
+    }
+}

package/dist/api/src/semantics/time.ts

@@ -0,0 +1,77 @@
+// What the World clock does to the management lane's records (manifest.ts's `time` moves), caught up before any request
+// is answered, each written at the instant it fell due: a database turns ready one minute after it was created; a backup
+// starts running 30 seconds after it was asked for and completes two minutes after, with its size, and expires its
+// retention after it completes. The delays are the twin's decisions; PlanetScale documents polling, not durations.
+import type { SemanticsContext } from '@volter/world-core';
+import { branchBytes } from './index.ts';
+import { catchUpDeployRequests } from './deploy-requests.ts';
+import { catchUpPolicies, COMPLETE_AFTER, snapshotBranch, START_AFTER } from './backups.ts';
+
+const READY_AFTER = 60_000;
+
+const later = (iso: string, ms: number): string => new Date(Date.parse(iso) + ms).toISOString();
+
+export async function catchUp(ctx: SemanticsContext): Promise<void> {
+  const now = Date.parse(ctx.occurredAt);
+  for (const d of ctx.rowsRaw('Database')) {
+    if (d.state !== 'pending' || d._deleted_at) continue;
+    const due = later(String(d.created_at), READY_AFTER);
+    if (Date.parse(due) > now) continue;
+    const at = await ctx.at(due);
+    const refused = at.legal('Database', 'state', 'provision', 'pending', 'ready', String(d.id), 'time');
+    if (refused) continue;
+    await at.write('Database', String(d.id), { ...at.own(d), state: 'ready', ready: true, updated_at: due }, 'database.ready');
+  }
+  // a branch turns ready as its database does, one minute after it was made (the twin's delay; PlanetScale's CI example
+  // waits for it: "pass the `--wait` flag", https://planetscale.com/docs/vitess/integrations/github-actions)
+  for (const br of ctx.rowsRaw('DatabaseBranch')) {
+    if (br.state !== 'pending' || br.deleted_at !== null) continue;
+    const due = later(String(br.created_at), READY_AFTER);
+    if (Date.parse(due) > now) continue;
+    const at = await ctx.at(due);
+    if (at.legal('DatabaseBranch', 'state', 'provision', 'pending', 'ready', String(br.id), 'time')) continue;
+    await at.write('DatabaseBranch', String(br.id), { ...at.own(br), state: 'ready', ready: true, schema_ready: true, updated_at: due }, 'branch.ready');
+  }
+  // a password with a ttl expires when it has passed ("The password will be invalid when TTL has passed", the spec)
+  for (const p of ctx.rowsRaw('DatabaseBranchPassword')) {
+    if (p.expired === true || p.deleted_at !== null || typeof p.expires_at !== 'string' || Date.parse(p.expires_at) > now) continue;
+    const at = await ctx.at(p.expires_at);
+    await at.write('DatabaseBranchPassword', String(p.id), { ...at.own(p), expired: true }, 'password.expire');
+  }
+  await catchUpDeployRequests(ctx);
+  await catchUpPolicies(ctx);
+  for (const k of ctx.rowsRaw('Backup')) {
+    if (k.deleted_at !== null && k.deleted_at !== undefined) continue;
+    let row = k;
+    if (row.state === 'pending') {
+      const due = later(String(row.created_at), START_AFTER);
+      if (Date.parse(due) > now) continue;
+      const at = await ctx.at(due);
+      if (at.legal('Backup', 'state', 'start', 'pending', 'running', String(row.id), 'time')) continue;
+      await at.write('Backup', String(row.id), { ...at.own(row), state: 'running', started_at: due, updated_at: due }, 'backup.start');
+      row = at.rowsRaw('Backup').find((x) => x.id === row.id) ?? row;
+    }
+    if (row.state === 'running') {
+      const due = later(String(row.created_at), COMPLETE_AFTER);
+      if (Date.parse(due) > now) continue;
+      const at = await ctx.at(due);
+      if (at.legal('Backup', 'state', 'complete', 'running', 'success', String(row.id), 'time')) continue;
+      // what it holds: its branch's schema and rows (a restore copies them into a new branch); a backup of `main` is
+      // sized by the World's stored rows, as it always has been
+      const snapshot = await snapshotBranch(at, row);
+      const onMain = String((row.database_branch as Record<string, unknown> | undefined)?.name ?? 'main') === 'main';
+      const size = onMain ? branchBytes(at) : snapshot.size;
+      const own = at.own(row);
+      await at.write('Backup', String(row.id), {
+        ...own, state: 'success', size, pvc_size: size, uncompressed_size: size, completed_at: due, updated_at: due,
+        expires_at: later(due, Number(own._retention_ms ?? 7 * 86_400_000)), _snapshot: snapshot.id,
+      }, 'backup.complete');
+      row = at.rowsRaw('Backup').find((x) => x.id === row.id) ?? row;
+    }
+    // a backup is deleted when its retention has passed (the twin's reading of a retention period)
+    if (row.state === 'success' && typeof row.expires_at === 'string' && Date.parse(row.expires_at) <= now && (row.deleted_at === null || row.deleted_at === undefined)) {
+      const at = await ctx.at(row.expires_at);
+      await at.write('Backup', String(row.id), { ...at.own(row), deleted_at: row.expires_at, updated_at: row.expires_at }, 'backup.expire');
+    }
+  }
+}

package/dist/api/src/token-gate.d.ts

@@ -0,0 +1,9 @@
+import type { SemanticsContext } from '@volter/world-core';
+/** 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 declare function heldAccesses(ctx: SemanticsContext, database: string): Set<string> | undefined;
+/** PlanetScale's 403 for a token that lacks every one of `needed`, or undefined when it holds one. */
+export declare function lacks(ctx: SemanticsContext, database: string, needed: string[]): Response | undefined;
+/** The gate's answer for a request, or undefined when it may pass. `operation` is the operation it matched, if any. */
+export declare function tokenGate(ctx: SemanticsContext, request: Request, operation: string | undefined): Response | undefined;

package/dist/api/src/token-gate.js

@@ -0,0 +1,97 @@
+// 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';
+const ACCESSES = {
+    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, code, message) => 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, database) {
+    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 ?? [])
+        .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, database, needed) {
+    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, request, operation) {
+    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 ?? [])
+        .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) {
+    return refuse(403, 'forbidden', `Forbidden: this service token needs one of these accesses: ${needed.join(', ')}`);
+}

package/dist/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/src/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/src/cli.js

@@ -0,0 +1,61 @@
+#!/usr/bin/env node
+import { keepProcessAlive } from '@volter/world-core/lifecycle';
+// world-planetscale CLI: serve the KERNEL-BACKED PlanetScale psdb twin, or run conformance.
+// State lives in the @volter/world-core action log (no in-memory side-store). Conformance is dev-only +
+// lazy-imported so the bin runs without @volter/world-tooling (E2).
+import { hasFlag, optionValue } from '@volter/world-core/args';
+import { createPlanetscaleTwinServer } from "./planetscale-server.js";
+import { pack } from "./index.js";
+const [cmd, ...rest] = process.argv.slice(2);
+const port = Number(optionValue(rest, '--port', String(process.env.PORT ?? '0'))) || undefined;
+const root = optionValue(rest, '--root') || undefined;
+// The credentials this twin will DEMAND. Omit them and any non-empty user:password pair is
+// accepted (a missing or malformed Authorization header is still a vendor-shaped 401) — the right
+// default for a local twin that holds no real secret.
+const username = optionValue(rest, '--username') || undefined;
+const password = optionValue(rest, '--password') || undefined;
+const database = optionValue(rest, '--database') || undefined;
+const branch = optionValue(rest, '--branch') || undefined;
+const readOnly = hasFlag(rest, '--read-only'); // a twin accepts writes unless started read-only
+if ((cmd === 'serve' || cmd === undefined) && hasFlag(rest, '--mysql')) {
+    if (readOnly)
+        throw new Error('Set read-only on the upstream HTTP twin; native connections share its policy');
+    const { startPlanetscaleMysql } = await import("./planetscale-mysql.js");
+    const upstreamEnv = pack.nativeTransport.upstreamEnv;
+    const upstream = optionValue(rest, '--upstream') || process.env[upstreamEnv];
+    if (!upstream)
+        throw new Error(`--mysql requires ${upstreamEnv} or --upstream pointing at the World HTTP twin (declare the HTTP twin service first)`);
+    const server = await startPlanetscaleMysql({ upstream, port, username, password, database, ...(hasFlag(rest, '--trace-sql') ? { onQuery: (query) => process.stderr.write(`mysql: ${query}\n`) } : {}) });
+    process.stdout.write(`planetscale MySQL frontend at mysql://127.0.0.1:${server.port} (shared HTTP state)\n`);
+    let closing = false;
+    const close = async () => { if (closing)
+        return; closing = true; await server.stop(); process.exit(0); };
+    process.once('SIGTERM', () => { void close(); });
+    process.once('SIGINT', () => { void close(); });
+    await keepProcessAlive();
+}
+else if (cmd === 'serve' || cmd === undefined) {
+    const s = await createPlanetscaleTwinServer({
+        readOnly,
+        ...(root ? { root } : {}),
+        ...(port ? { port } : {}),
+        ...(username ? { username } : {}),
+        ...(password ? { password } : {}),
+        ...(database ? { database } : {}),
+        ...(branch ? { branch } : {}),
+    });
+    process.stdout.write(`planetscale twin (psdb.v1alpha1.Database over Connect-JSON: CreateSession, Execute, CloseSession)${readOnly ? ' [read-only]' : ''} at http://127.0.0.1:${s.port}\n`
+        + `  point a client at it with PLANETSCALE_DATABASE_URL=http://user:pass@127.0.0.1:${s.port}\n`
+        + '  (the http: scheme is honoured by @planetscale/database itself — every other scheme is forced to https)\n');
+    await keepProcessAlive();
+}
+else if (cmd === 'conformance') {
+    const { checkPlanetscaleConformance } = await import("./planetscale-conformance.js");
+    const report = await checkPlanetscaleConformance();
+    process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+    if (!report.ok)
+        process.exitCode = 1;
+}
+else {
+    process.stdout.write('Usage: world-planetscale serve|conformance [--port N] [--root DIR] [--username U] [--password P] [--database D] [--branch B] [--read-only] [--mysql --upstream URL]\n');
+}

package/dist/src/generated/surface.gen.json

@@ -0,0 +1 @@
+{"generatedBy":"scripts/derive-pack.ts","spec":"proto","format":"proto","version":"psdb.v1alpha1.Database","resources":[{"name":"CloseSessionResponse","schema":"CloseSessionResponse","fields":[{"name":"session","type":"Session","nullable":true},{"name":"error","type":"RPCError","nullable":true}],"stateCandidates":[],"expandable":[]},{"name":"CreateSessionResponse","schema":"CreateSessionResponse","fields":[{"name":"branch","type":"string","nullable":false},{"name":"user","type":"User","nullable":true},{"name":"session","type":"Session","nullable":true}],"stateCandidates":[],"expandable":[]},{"name":"ExecuteResponse","schema":"ExecuteResponse","fields":[{"name":"session","type":"Session","nullable":true},{"name":"result","type":"QueryResult","nullable":true},{"name":"error","type":"RPCError","nullable":true},{"name":"timing","type":"number","nullable":false}],"stateCandidates":[],"expandable":[]},{"name":"PrepareResponse","schema":"PrepareResponse","fields":[{"name":"session","type":"Session","nullable":true},{"name":"fields","type":"array","nullable":false},{"name":"error","type":"RPCError","nullable":true},{"name":"paramsCount","type":"integer","nullable":false}],"stateCandidates":[],"expandable":[]}],"operations":[{"id":"CreateSession","method":"post","path":"/psdb.v1alpha1.Database/CreateSession","pathParams":[],"query":[],"body":[],"bodyEncoding":"json","successStatus":200,"answers":{"resource":"CreateSessionResponse","list":false},"class":"action"},{"id":"Execute","method":"post","path":"/psdb.v1alpha1.Database/Execute","pathParams":[],"query":[],"body":[{"name":"bindVariables","type":"object","required":false},{"name":"prepared","type":"boolean","required":false},{"name":"query","type":"string","required":false},{"name":"session","type":"Session","required":false}],"bodyEncoding":"json","successStatus":200,"answers":{"resource":"ExecuteResponse","list":false},"class":"action"},{"id":"StreamExecute","method":"post","path":"/psdb.v1alpha1.Database/StreamExecute","pathParams":[],"query":[],"body":[{"name":"bindVariables","type":"object","required":false},{"name":"prepared","type":"boolean","required":false},{"name":"query","type":"string","required":false},{"name":"session","type":"Session","required":false}],"bodyEncoding":"json","successStatus":200,"streams":true,"answers":{"resource":"ExecuteResponse","list":false},"class":"action"},{"id":"Prepare","method":"post","path":"/psdb.v1alpha1.Database/Prepare","pathParams":[],"query":[],"body":[{"name":"bindVariables","type":"object","required":false},{"name":"query","type":"string","required":false},{"name":"session","type":"Session","required":false}],"bodyEncoding":"json","successStatus":200,"answers":{"resource":"PrepareResponse","list":false},"class":"action"},{"id":"CloseSession","method":"post","path":"/psdb.v1alpha1.Database/CloseSession","pathParams":[],"query":[],"body":[{"name":"session","type":"Session","required":false}],"bodyEncoding":"json","successStatus":200,"answers":{"resource":"CloseSessionResponse","list":false},"class":"action"}]}

package/dist/src/generated/ui.gen.json

@@ -0,0 +1 @@
+{"generatedBy":"scripts/derive-pack.ts","resources":{"Session":{"actions":[],"states":{"closed":["false","true"]},"embeds":{}}}}