@volter/twin-planetscale 0.1.0

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

@@ -0,0 +1 @@
+{"generatedBy":"scripts/derive-pack.ts","resources":{"Database":{"retrieve":"/v1/organizations/{organization}/databases/{database}","create":{"path":"/v1/organizations/{organization}/databases","encoding":"json","body":[{"name":"cluster_size","type":"string","required":true},{"name":"kind","type":"string","required":false},{"name":"major_version","type":"string","required":false},{"name":"name","type":"string","required":true},{"name":"region","type":"string","required":false},{"name":"replicas","type":"integer","required":false},{"name":"storage","type":"object","required":false}]},"actions":[],"states":{"state":["pending","ready"]},"embeds":{}},"Backup":{"retrieve":"/v1/organizations/{organization}/databases/{database}/branches/{branch}/backups/{id}","create":{"path":"/v1/organizations/{organization}/databases/{database}/branches/{branch}/backups","encoding":"json","body":[{"name":"emergency","type":"boolean","required":false},{"name":"name","type":"string","required":false},{"name":"retention_unit","type":"string","required":false},{"name":"retention_value","type":"integer","required":false}]},"actions":[],"states":{"state":["pending","running","success"]},"embeds":{}},"DatabaseBranchPassword":{"retrieve":"/v1/organizations/{organization}/databases/{database}/branches/{branch}/passwords/{id}","actions":[],"states":{},"embeds":{}},"ServiceToken":{"create":{"path":"/v1/organizations/{organization}/service-tokens","encoding":"json","body":[{"name":"name","type":"string","required":false},{"name":"ttl","type":"integer","required":false}]},"actions":[],"states":{},"embeds":{}}}}

package/api/src/index.ts

@@ -0,0 +1,19 @@
+// The management API lane of the planetscale pack (`api.planetscale.com/v1`), as a plain fetch: the whole pack's fetch
+// (the psdb data plane, the management API and app.planetscale.com's pages), whose owners are the operations this lane
+// serves. Its life walks through all of them: a customer of the management API makes its tokens on the settings page,
+// approves deploy requests on their page, and runs its migrations and queries through psdb on the branches the API makes
+// (journeys/customer-life.outline.md).
+import type { DerivedFetch } from '@volter/world-core';
+import { createPlanetscaleTwinFetch } from '../../src/planetscale-server.ts';
+import { createPlanetscaleApiLaneFetch } from './fetch.ts';
+
+export { manifest } from './manifest.ts';
+export { createPlanetscaleApiLaneFetch } from './fetch.ts';
+// how a journey reads a psdb answer: the pack's own view (../../src/index.ts)
+export { answerViews } from '../../src/index.ts';
+
+export function createPlanetscaleApiTwinFetch(options: { root?: string; readOnly?: boolean } = {}): DerivedFetch {
+  const lane = createPlanetscaleApiLaneFetch(options);
+  const pack = createPlanetscaleTwinFetch({ ...(options.root !== undefined ? { root: options.root } : {}), ...(options.readOnly !== undefined ? { readOnly: options.readOnly } : {}) });
+  return Object.assign((request: Request) => pack(request), { owners: () => lane.owners() });
+}

package/api/src/manifest.ts

@@ -0,0 +1,136 @@
+// PlanetScale's management API manifest (the pack's `api` lane; docs/contributing/architecture.md, "Other wires: lanes"):
+// the vendor facts its published Swagger document (../spec/openapi.json.gz) does not carry, and the resources whose state
+// the lane moves. The surface is generated (./generated/surface.gen.json, by `bun scripts/derive-pack.ts planetscale/api`).
+//
+// The lane serves the slice an application and the pack's customer lives reach: databases (create, read, delete), their
+// branches (create from a parent or a backup, read, list, delete; semantics/branches.ts), a branch's passwords (create,
+// list, read, delete), a branch's backups (create, list, read, delete) and service tokens (create, list). Every other
+// operation of the spec is the gap. The psdb data plane (the pack root) reads the passwords
+// this lane issues, so both write the one kernel service `planetscale`; the lane's records are control-plane records the
+// pack never pushes to a real branch, so each is stored under a `_` type, beside psdb's `_session`.
+//
+// NO `auth`: PlanetScale reads a service token as `Authorization: <SERVICE_TOKEN_ID>:<SERVICE_TOKEN>`, with no scheme
+// (planetscale.com/docs/api/reference, "Service tokens"), which the kernel's scheme-prefixed gate cannot state. The lane's
+// token gate (token-gate.ts) sits in front of the dispatch instead, and checks each operation's service token
+// accesses as the spec's own "Authorization" section for it lists them.
+import type { DerivedManifest, StateField } from '@volter/world-core';
+
+/** A database's `state`. A new database is `pending` and not `ready`; PlanetScale provisions it, and a caller polls:
+ *  "After creation, poll `get_database` until `ready` is `true` before creating branches or backups"
+ *  (https://planetscale.com/docs/api/reference/create_database). The twin's database turns ready one minute after it was
+ *  created, on the World clock (semantics/time.ts): how long provisioning takes is the twin's decision, the reference
+ *  gives none. Not made by the twin: importing, import_ready, sleep_in_progress, sleeping, awakening. */
+const databaseState: StateField = {
+  initial: 'pending',
+  transitions: [
+    { actor: 'time', from: ['pending'], to: 'ready', source: 'spec:/definitions/Database/properties/ready "If the database is ready to be used"' },
+  ],
+};
+
+/** A backup's `state`. A new backup is `pending`; it starts `running` and ends `success`, and a caller polls: "Use
+ *  `get_backup` to poll the current state of a backup" (https://planetscale.com/docs/api/reference/create_backup). The
+ *  twin's backup starts 30 seconds after it was asked for and completes two minutes after (semantics/time.ts), its size
+ *  the branch's stored rows at completion: the timing is the twin's decision, the reference gives none. Not made by the
+ *  twin: failed, canceled, ignored. */
+const backupState: StateField = {
+  initial: 'pending',
+  transitions: [
+    { actor: 'time', from: ['pending'], to: 'running', source: 'spec:/definitions/Backup/properties/state "The current state of the backup"' },
+    { actor: 'time', from: ['running'], to: 'success', source: 'spec:/definitions/Backup/properties/state "The current state of the backup"' },
+  ],
+};
+
+/** A branch's `state`. A new branch is `pending` and not `ready`; PlanetScale's CI example waits for it before using it
+ *  (https://planetscale.com/docs/vitess/integrations/github-actions: "we create it and pass the `--wait` flag"). The twin's
+ *  branch turns ready one minute after it was made, on the World clock (semantics/time.ts): the delay is the twin's
+ *  decision. Not made by the twin: sleep_in_progress, sleeping, awakening. */
+const branchState: StateField = {
+  initial: 'pending',
+  transitions: [
+    { actor: 'time', from: ['pending'], to: 'ready', source: 'spec:/definitions/DatabaseBranch/properties/state "The current state of the branch"' },
+  ],
+};
+
+const DR_PAGE = 'https://planetscale.com/docs/vitess/schema-changes/deploy-requests';
+
+/** A deploy request's `state`: open until it is closed, by `close_deploy_request`, by a revert ("The deploy request will
+ *  be closed", the deploy-requests page), or when its deployment completes (the twin's reading: the request stays open
+ *  through its revert window). */
+const deployRequestState: StateField = {
+  initial: 'open',
+  transitions: [
+    { operation: 'close_deploy_request', from: ['open'], to: 'closed', source: 'spec:/paths/~1organizations~1{organization}~1databases~1{database}~1deploy-requests~1{number}/patch "The deploy request will be updated to this state"' },
+    { operation: 'complete_revert', from: ['open'], to: 'closed', source: `${DR_PAGE} "The deploy request will be closed, but the branch will remain"` },
+    { actor: 'time', from: ['open'], to: 'closed', source: `${DR_PAGE} "After the 30 minute period is up, the deployment becomes permanent"` },
+  ],
+};
+
+/** A deploy request's `deployment_state` (semantics/deploy-requests.ts): checked, queued, deployed into its revert window,
+ *  then permanent or reverted. The durations are the twin's. Not made by the twin: submitting, pending_cutover,
+ *  in_progress_vschema, in_progress_cancel, in_progress_cutover, complete_cancel, complete_error, in_progress_revert,
+ *  in_progress_revert_vschema, complete_revert_error, cancelled, error. */
+const deploymentState: StateField = {
+  initial: 'pending',
+  transitions: [
+    { actor: 'time', from: ['pending'], to: 'ready', source: `${DR_PAGE} "PlanetScale will check if the request is deployable"` },
+    { actor: 'time', from: ['pending'], to: 'no_changes', source: 'spec:/definitions/DatabaseDeployRequest/properties/deployment_state "The deployment state of the deploy request"' },
+    { operation: 'queue_deploy_request', from: ['ready'], to: 'queued', source: `${DR_PAGE} "The deployment will begin immediately, or join the serial deploy queue if other deployments are already pending"` },
+    { actor: 'time', from: ['queued'], to: 'in_progress', source: `${DR_PAGE} "only one deploy runs at a time, and later requests wait until earlier ones finish"` },
+    { actor: 'time', from: ['in_progress'], to: 'complete_pending_revert', source: `${DR_PAGE} "After you deploy, you have 30 minutes to \"undo\" it"` },
+    { actor: 'time', from: ['complete_pending_revert'], to: 'complete', source: `${DR_PAGE} "After the 30 minute period is up, the deployment becomes permanent"` },
+    { actor: 'time', from: ['in_progress'], to: 'complete', source: `${DR_PAGE} "these schema changes must be auto-applied and cannot be reverted"` },
+    { operation: 'complete_revert', from: ['complete_pending_revert'], to: 'complete_revert', source: `${DR_PAGE} "You can revert a deployment for up to 30 minutes after the deploying"` },
+  ],
+};
+
+export const manifest: DerivedManifest = {
+  vendor: 'planetscale',
+  service: 'planetscale',
+  body: { json: 'always' },
+  // PlanetScale's ids are opaque strings; the handlers mint each from the instant, the name and the count
+  // (semantics/shared.ts, `mintId`), prefixed per resource, so a World mints the same ids every run. The core mints none.
+  ids: { template: '{prefix}{n}' },
+  time: 'iso',
+  // the management API's error body (the pack's backups have answered it since they were served)
+  error: { code: '{code}', message: '{message}' },
+  readOnly: { status: 403, code: 'forbidden', message: 'The twin is read-only' },
+  malformedBody: { status: 422, code: 'unprocessable_entity', message: 'The request body is not valid JSON' },
+  notFound: { status: 404, code: 'not_found', message: 'Not Found' },
+  // the spec's Paginated* envelope; the lists are handlers (semantics/shared.ts, `page`)
+  list: {
+    style: 'envelope',
+    envelope: { type: 'list', data: '{data}' },
+    limit: { param: 'per_page', default: 25, max: 100 },
+    page: { param: 'page', link: false },
+  },
+  deleted: {},
+  // operations of the declared resources the lane does not serve: the gap
+  unmodeled: ['update_branch', 'update_backup_policy', 'delete_backup_policy', 'update_backup', 'update_password', 'get_service_token', 'get_oauth_token', 'delete_oauth_token'],
+  // the page where a service token is made and granted its accesses (no API operation grants an access)
+  screens: [{
+    id: 'sign-in', kind: 'flow', host: 'app.planetscale.com', path: '/sign-in',
+    demand: 'every app.planetscale.com page a person reaches: each asks who is signed in', status: 'done',
+    controls: ['Email', 'Password', 'Sign in'], source: 'https://planetscale.com/docs/api/reference/service-tokens',
+  }, {
+    id: 'service-tokens', kind: 'flow', host: 'app.planetscale.com', path: '/{organization}/settings/service-tokens',
+    demand: 'the first service token of an organization, and the accesses of every token, are made here',
+    status: 'done', controls: ['New service token', 'Name', 'Create service token', 'Service token', 'Database', 'Access', 'Save permissions', 'Delete service token'],
+    source: 'https://planetscale.com/docs/api/reference/service-tokens',
+  }, {
+    id: 'deploy-request', kind: 'flow', host: 'app.planetscale.com', path: '/{organization}/{database}/deploy-requests/{number}',
+    demand: 'a deploy request is approved by an administrator other than its creator here', status: 'done',
+    controls: ['Summary', 'Schema changes', 'Approve changes'],
+    source: 'https://planetscale.com/docs/vitess/schema-changes/deploy-requests',
+  }],
+  resources: {
+    Database: { storedAs: '_database', idPrefix: 'db', notFound: 'Not Found', notState: ['kind'], state: { state: databaseState } },
+    DatabaseBranch: { storedAs: '_branch', idPrefix: 'br', notFound: 'Not Found', notState: ['kind'], state: { state: branchState } },
+    DatabaseDeployRequest: { storedAs: '_deploy_request', idPrefix: 'dr', notFound: 'Not Found', state: { state: deployRequestState, deployment_state: deploymentState } },
+    BackupPolicy: { storedAs: '_backup_policy', idPrefix: 'bp', notFound: 'Not Found' },
+    Backup: { storedAs: '_backup', idPrefix: 'bk', notFound: 'Not Found', state: { state: backupState } },
+    // a password's role is set when it is made: "once a password is created, its role assignment cannot be changed"
+    // (planetscale.com/docs/vitess/connecting/password-roles)
+    DatabaseBranchPassword: { storedAs: '_password', idPrefix: 'pw', notFound: 'Not Found', notState: ['role'] },
+    ServiceToken: { storedAs: '_service_token', idPrefix: 'tk', notFound: 'Not Found' },
+  },
+};

package/api/src/screens/deploy-request.tsx

@@ -0,0 +1,111 @@
+// PLANETSCALE'S DEPLOY REQUEST PAGE — a flow (docs/contributing/architecture.md, "Screens"): the page at
+// app.planetscale.com/{organization}/{database}/deploy-requests/{number}, where a teammate reads a deploy request's schema
+// changes and approves it. https://planetscale.com/docs/vitess/schema-changes/deploy-requests, "Review a deploy request":
+// "Under "Summary", you'll see if the request is deployable. To review the schema changes, click the "Schema changes"
+// tab"; "If you have required deploy requests to be approved before deployment, other users in your Organization will
+// see the option to "Approve changes" or "Leave a comment" on the "Schema changes" tab." Built from @volter/world-ui's
+// settings layout (Portal) under PlanetScale's skin; nothing of PlanetScale's page is copied. Its controls are the ones
+// the lane's life needs: the Summary, the Schema changes, and "Approve changes".
+//
+// The person on the page is who signed in at /sign-in (screens/session.tsx); only a member of the organization reaches
+// it (another answers PlanetScale's 404). Where the documentation stops and the twin decides: approving takes an
+// administrator (the setting "Require administrator approval for deploy requests" names an administrator's approval),
+// the page posts the approval to `…/deploy-requests/{number}/review` and comes back to the page, and the approval is the
+// same review the API's review_deploy_request records (semantics/deploy-requests.ts), with the person as reviewer.
+import { flowPage, Portal, PORTAL_CSS } from '@volter/world-ui';
+import type { SemanticsContext } from '@volter/world-core';
+import { deploymentOf, recordReview, reviewsOf } from '../semantics/deploy-requests.ts';
+import { createdById, personActorOf } from '../semantics/audit.ts';
+import { signedIn, toSignIn } from './session.tsx';
+
+type Row = Record<string, unknown>;
+const PAGE = /^\/([^/]+)\/([^/]+)\/deploy-requests\/(\d+)(?:\/(review))?$/;
+const SKIN = `
+body { background: #ffffff; color: #111111; }
+.portal-side { background: #fafafa; border-right: 1px solid #e5e5e5; }
+.portal-section h2 { border-color: #e5e5e5; color: #525252; }
+.portal-notice { background: #f0f7ff; border: 1px solid #b6d4fe; }
+.portal-button { background: #ffffff; border: 1px solid #d4d4d4; border-radius: 6px; padding: 6px 12px; }
+.portal-primary { background: #1d4ed8; border-color: #1d4ed8; color: #ffffff; }
+`;
+
+/** The spec's actor object for a person on a page. */
+export const personActor = (email: string): Row => ({ id: createdById(email), display_name: email, avatar_url: 'https://app.planetscale.com/gravatar-fallback.png' });
+
+function page(ctx: SemanticsContext, org: string, database: string, dr: Row, canApprove: boolean, notice?: string, status = 200): Response {
+  const deployment = deploymentOf(dr);
+  const ops = deployment.deploy_operations as Row[];
+  const reviews = reviewsOf(ctx, dr);
+  const action = `/${org}/${database}/deploy-requests/${String(dr.number)}/review`;
+  const approvable = canApprove && dr.state === 'open' && dr.approved !== true;
+  return flowPage({
+    title: `Deploy request #${String(dr.number)} · ${database} · PlanetScale`,
+    css: [PORTAL_CSS, SKIN],
+    status,
+    body: (
+      <Portal
+        merchant={`${org} / ${database}`}
+        back={{ href: `/${org}/${database}`, label: 'Back to database' }}
+        {...(notice ? { notice } : {})}
+        sections={[
+          {
+            heading: 'Summary',
+            items: [{
+              title: `#${String(dr.number)}: ${String(dr.branch)} → ${String(dr.into_branch)}`,
+              detail: deployment.deployable === true ? 'Deployable' : 'Not deployable',
+              note: `${String(dr.state)} · ${String(dr.deployment_state)}${dr.approved === true ? ' · Approved' : ''}${dr.notes ? ` · ${String(dr.notes)}` : ''}`,
+              ...(approvable ? { actions: [{ label: 'Approve changes', action, fields: { state: 'approved' }, tone: 'primary' as const, method: 'post' as const }] } : {}),
+            }],
+          },
+          {
+            heading: 'Schema changes',
+            empty: 'No schema changes.',
+            items: ops.map((o) => ({ title: String(o.table_name), detail: String(o.ddl_statement), ...(o.can_drop_data === true ? { badge: 'Drops data' } : {}) })),
+          },
+          {
+            heading: 'Reviews',
+            empty: 'No reviews yet.',
+            items: reviews.map((r) => ({ title: String((r.actor as Row).display_name), detail: String(r.state), note: String(r.created_at) })),
+          },
+        ]}
+      />
+    ),
+  });
+}
+
+/** The page again with the refusal an approval drew (a creator approving their own request, or a token's maker its
+ *  request), in the page's notice. */
+async function approvalRefused(out: Response, again: (text: string, status: number) => Response): Promise<Response> {
+  return again(((await out.json()) as { message?: string }).message ?? 'The approval was refused.', out.status);
+}
+
+async function formOf(request: Request): Promise<Record<string, string>> {
+  return Object.fromEntries(new URLSearchParams(await request.text()));
+}
+
+/** The deploy request page, or undefined for any other request. `contextFor` gives the lane's semantics context. */
+export async function deployRequestPage(request: Request, contextFor: (request: Request) => Promise<SemanticsContext>): Promise<Response | undefined> {
+  const url = new URL(request.url);
+  const m = PAGE.exec(url.pathname.replace(/\/+$/, ''));
+  if (!m) return undefined;
+  const [, org, database, number, review] = m.map((x) => (x === undefined ? x : decodeURIComponent(x))) as [string, string, string, string, string | undefined];
+  const ctx = await contextFor(new Request(request.url));
+  const person = signedIn(ctx, request);
+  if (!person) return toSignIn(request);
+  const notFound = new Response('Not Found', { status: 404, headers: { 'content-type': 'text/plain' } });
+  if (!person.organizations.includes(org)) return notFound;
+  const db = ctx.rowsRaw('Database').find((d) => d.name === database && !d._deleted_at);
+  const find = (c: SemanticsContext): Row | undefined => c.rowsRaw('DatabaseDeployRequest').find((d) => d._database === database && String(d.number) === number);
+  const dr = db ? find(ctx) : undefined;
+  if (!db || !dr) return notFound;
+  const admin = person.role === 'admin';
+  if (!review && request.method === 'GET') return page(ctx, org, database, dr, admin);
+  if (!review || request.method !== 'POST') return undefined;
+  const form = await formOf(request);
+  if (form.state !== 'approved') return page(ctx, org, database, dr, admin, 'Choose Approve changes.', 422);
+  if (!admin) return page(ctx, org, database, dr, admin, 'Only an organization administrator can approve a deploy request.', 403);
+  const out = await recordReview(ctx, db, dr, `person:${person.email}`, personActor(person.email), 'approved', '', personActorOf(person.email));
+  const after = await contextFor(new Request(request.url));
+  if (out instanceof Response) return approvalRefused(out, (text, status) => page(after, org, database, find(after)!, admin, text, status));
+  return page(after, org, database, find(after)!, admin, `You approved deploy request #${number}.`);
+}

package/api/src/screens/service-tokens.tsx

@@ -0,0 +1,141 @@
+// PLANETSCALE'S SERVICE TOKENS PAGE — a flow (docs/contributing/architecture.md, "Screens"): the organization's settings
+// page at app.planetscale.com/{organization}/settings/service-tokens, where a token is made and granted its accesses. No
+// operation of the management API grants an access, and the first token of an organization can only come from here.
+// https://planetscale.com/docs/api/reference/service-tokens: "Navigate to Settings > Service tokens > New service token.
+// Provide a descriptive name and click Create service token", after which the Service Token ID and the Service Token are
+// shown to be stored; organization and database accesses are checked on the token's settings and saved with "Save
+// permissions". Built from @volter/world-ui's settings layout (Portal) under PlanetScale's skin; nothing of PlanetScale's
+// page is copied. Its controls are the ones the pack's lives need: "New service token" with its Name and "Create service
+// token"; the permissions form with its Service token, Database and Access, and "Save permissions"; and each token's
+// "Delete service token" ("You can delete a service token at any time from the service token detail page. Simply click
+// the "Delete service token" button", https://planetscale.com/docs/cli/service-tokens).
+//
+// The person on the page is who signed in at /sign-in (screens/session.tsx): a visitor nobody signed in as is sent there
+// first, and only a person of the organization reaches its settings (another answers PlanetScale's 404).
+//
+// Where the documentation stops and the twin decides: a database access names a database this
+// lane created, and "Organization" grants the access across the organization; one access is saved per submission; the
+// accesses offered are the ones the spec's operations this lane serves name. Each form posts and comes back to the page,
+// and the new token is shown once in the page's notice.
+import { flowPage, Portal, PORTAL_CSS } from '@volter/world-ui';
+import type { SemanticsContext } from '@volter/world-core';
+import { makeServiceToken, removeServiceToken } from '../semantics/index.ts';
+import { accessOf } from '../semantics/shared.ts';
+import { audit, personActorOf } from '../semantics/audit.ts';
+import { signedIn, toSignIn } from './session.tsx';
+
+type Row = Record<string, unknown>;
+const PAGE = /^\/([^/]+)\/settings\/service-tokens(?:\/(accesses|delete))?$/;
+
+// PlanetScale's skin over the settings layout: its near-black ink, grey rules and its blue primary button
+const SKIN = `
+body { background: #ffffff; color: #111111; }
+.portal-side { background: #fafafa; border-right: 1px solid #e5e5e5; }
+.portal-section h2 { border-color: #e5e5e5; color: #525252; }
+.portal-notice { background: #f0f7ff; border: 1px solid #b6d4fe; font-family: ui-monospace, monospace; word-break: break-all; }
+.portal-button { background: #ffffff; border: 1px solid #d4d4d4; border-radius: 6px; padding: 6px 12px; }
+.portal-primary { background: #1d4ed8; border-color: #1d4ed8; color: #ffffff; }
+`;
+
+/** The accesses the page offers: those the operations of this lane name (token-gate.ts). */
+const ACCESS_OPTIONS = [
+  // organization accesses
+  'create_databases', 'read_audit_logs', 'read_service_tokens', 'write_service_tokens', 'delete_service_tokens',
+  // database accesses
+  'read_database', 'write_database', 'delete_database', 'create_branch', 'read_branch', 'delete_branch', 'delete_production_branch',
+  'connect_branch', 'connect_production_branch', 'delete_branch_password', 'delete_production_branch_password',
+  'create_deploy_request', 'read_deploy_request', 'approve_deploy_request',
+  'read_backups', 'write_backups', 'delete_backups', 'restore_backup', 'restore_production_branch_backup',
+];
+
+type Access = { id: string; access: string; description: string; resource_name: string; resource_type: string };
+
+function page(ctx: SemanticsContext, org: string, notice?: string, status = 200): Response {
+  const tokens = ctx.rowsRaw('ServiceToken').filter((t) => !t._deleted_at);
+  const databases = ctx.rowsRaw('Database').filter((d) => !d._deleted_at).map((d) => String(d.name));
+  const action = `/${org}/settings/service-tokens`;
+  return flowPage({
+    title: `Service tokens · ${org} · PlanetScale`,
+    css: [PORTAL_CSS, SKIN],
+    status,
+    body: (
+      <Portal
+        merchant={`${org} · Settings`}
+        back={{ href: `/${org}`, label: 'Back to organization' }}
+        {...(notice ? { notice } : {})}
+        sections={[{
+          heading: 'Service tokens',
+          empty: 'No service tokens yet.',
+          items: tokens.map((t) => ({
+            title: String(t.display_name),
+            detail: `ID ${String(t.id)}`,
+            note: ((t.service_token_accesses ?? []) as Access[]).map((a) => `${a.access} (${a.resource_type === 'Organization' ? 'organization' : a.resource_name})`).join(', ') || 'No accesses',
+            actions: [{ label: 'Delete service token', action: `${action}/delete`, fields: { token: String(t.id) }, tone: 'danger' as const, method: 'post' as const }],
+          })),
+        }]}
+        forms={[
+          { heading: 'New service token', action, fields: [{ id: 'name', label: 'Name' }], submit: { label: 'Create service token' } },
+          ...(tokens.length ? [{
+            heading: 'Permissions',
+            action: `${action}/accesses`,
+            fields: [
+              { id: 'token', label: 'Service token', options: tokens.map((t) => ({ value: String(t.id), label: String(t.display_name) })) },
+              { id: 'database', label: 'Database', options: [{ value: '', label: 'Organization' }, ...databases.map((d) => ({ value: d, label: d }))] },
+              { id: 'access', label: 'Access', options: ACCESS_OPTIONS.map((a) => ({ value: a, label: a })) },
+            ],
+            submit: { label: 'Save permissions' },
+          }] : []),
+        ]}
+      />
+    ),
+  });
+}
+
+async function formOf(request: Request): Promise<Record<string, string>> {
+  return Object.fromEntries(new URLSearchParams(await request.text()));
+}
+
+/** The service tokens page, or undefined for any other request. `contextFor` gives the lane's semantics context. */
+export async function serviceTokensPage(request: Request, contextFor: (request: Request) => Promise<SemanticsContext>): Promise<Response | undefined> {
+  const url = new URL(request.url);
+  const m = PAGE.exec(url.pathname.replace(/\/+$/, ''));
+  if (!m) return undefined;
+  const org = decodeURIComponent(m[1]!);
+  const accesses = m[2] === 'accesses';
+  const deleting = m[2] === 'delete';
+  const person = signedIn(await contextFor(new Request(request.url)), request);
+  if (!person) return toSignIn(request);
+  if (!person.organizations.includes(org)) return new Response('Not Found', { status: 404, headers: { 'content-type': 'text/plain' } });
+  if (request.method === 'GET' && !accesses && !deleting) return page(await contextFor(new Request(request.url)), org);
+  if (request.method !== 'POST') return undefined;
+  const form = await formOf(request);
+  const ctx = await contextFor(new Request(request.url));
+  if (deleting) {
+    const doomed = ctx.rowsRaw('ServiceToken').find((t) => t.id === form.token && !t._deleted_at);
+    if (!doomed) return page(ctx, org, 'Choose a service token.', 422);
+    await removeServiceToken(ctx, doomed, org, personActorOf(person.email));
+    return page(await contextFor(new Request(request.url)), org, `Service token ${String(doomed.display_name)} deleted.`);
+  }
+  if (!accesses) {
+    const name = (form.name ?? '').trim();
+    if (!name) return page(ctx, org, 'A service token needs a name.', 422);
+    const { record, token } = await makeServiceToken(ctx, name, [], person.email, org);
+    // PlanetScale shows the new token's ID and value once; the notice is where a person copies them from
+    return page(await contextFor(new Request(request.url)), org, `Service token ${name} created. ID: ${String(record.id)} Token: ${token} — copy the token now: it will not be shown again.`);
+  }
+  const token = ctx.rowsRaw('ServiceToken').find((t) => t.id === form.token && !t._deleted_at);
+  if (!token) return page(ctx, org, 'Choose a service token.', 422);
+  if (!ACCESS_OPTIONS.includes(form.access ?? '')) return page(ctx, org, 'Choose an access.', 422);
+  const database = form.database ?? '';
+  const held = (token.service_token_accesses ?? []) as Access[];
+  const resource = database ? { resource_type: 'Database', resource_name: database } : { resource_type: 'Organization', resource_name: org };
+  if (!held.some((a) => a.access === form.access && a.resource_type === resource.resource_type && a.resource_name === resource.resource_name)) {
+    const granted = accessOf(ctx, `${String(token.id)}-${held.length + 1}`, form.access!, resource.resource_type as 'Database' | 'Organization', resource.resource_name) as Access;
+    await ctx.write('ServiceToken', String(token.id), { ...ctx.own(token as Row), service_token_accesses: [...held, granted], updated_at: ctx.occurredAt }, 'service_token.grant');
+    // saving a token's database accesses is audited as "service_token … updated_bulk_database_access"
+    // (https://planetscale.com/docs/security/audit-log, "Audited organization events"); the table names no event for an
+    // organization access
+    if (database) await audit(ctx, org, 'service_token', 'updated_bulk_database_access', { type: 'ServiceToken', id: String(token.id), name: String(token.display_name) }, { actor: personActorOf(person.email), metadata: { database, access: form.access } });
+  }
+  return page(await contextFor(new Request(request.url)), org, `${form.access} added to ${String(token.display_name)} on ${database || 'the organization'}.`);
+}

package/api/src/screens/session.tsx

@@ -0,0 +1,117 @@
+// PLANETSCALE'S SIGN-IN — the door before every app.planetscale.com page (docs/contributing/architecture.md, "Who is on a
+// screen"), following github's (packages/twin/github/src/screens/session.tsx): app.planetscale.com/sign-in shows the form,
+// which posts back to /sign-in; the right password for the account signs its person in, and a session cookie names them
+// to every page after. A page asked for by nobody signed in sends its visitor to the sign-in with `return_to`, and the
+// sign-in returns them there. Built from @volter/world-ui's sign-in piece under PlanetScale's skin; nothing of
+// PlanetScale's page is copied.
+//
+// Where PlanetScale's documentation stops and the twin decides: a person's account is their email; their password and the
+// organization they own are what the World gave them (`POST /_twin/users/:email/password` {password, organization},
+// standing in for PlanetScale's sign-up, as github's door of the same path does); the session cookie is named
+// `_planetscale_session` (PlanetScale does not document its cookie); a refused sign-in shows the form again with the
+// message "Incorrect email or password." (answered 200), naming neither half; a session does not end, since no life signs
+// out yet.
+import { createHash } from 'node:crypto';
+import { cookieOf, flowPage, SignIn, SIGN_IN_CSS } from '@volter/world-ui';
+import type { SemanticsContext } from '@volter/world-core';
+import { audit, createdById, personActorOf } from '../semantics/audit.ts';
+
+const COOKIE = '_planetscale_session';
+const hex = (s: string): string => createHash('sha256').update(s).digest('hex');
+const passwordHash = (email: string, password: string): string => hex(`password:${email.toLowerCase()}:${password}`);
+
+// PlanetScale's skin over the sign-in: its near-black ink and dark primary button
+const SKIN = `
+body { background: #fafafa; color: #111111; }
+.sign-in-mark { background: #111111; }
+.sign-in-error { background: #fef2f2; border-color: #fecaca; color: #111111; }
+.sign-in-box { background: #ffffff; border-color: #e5e5e5; }
+.sign-in-hint { color: #525252; }
+.sign-in-submit { background: #111111; border-color: #111111; color: #ffffff; }
+`;
+
+/** A return_to PlanetScale follows: a path on app.planetscale.com, never another site. */
+const returnTo = (raw: string | null | undefined): string => (raw && raw.startsWith('/') && !raw.startsWith('//') ? raw : '/');
+
+function page(back: string, email?: string, error?: string): Response {
+  return flowPage({
+    title: 'Sign in · PlanetScale',
+    css: [SIGN_IN_CSS, SKIN],
+    body: (
+      <SignIn
+        heading="Sign in to PlanetScale"
+        action="/sign-in"
+        fields={{ return_to: back }}
+        account={{ name: 'email', label: 'Email', ...(email ? { value: email } : {}) }}
+        password={{ name: 'password', label: 'Password' }}
+        submit="Sign in"
+        {...(error ? { error } : {})}
+      />
+    ),
+  });
+}
+
+/** The World's door refusing an account it cannot make. */
+function malformedAccount(): Response {
+  return Response.json({ code: 'unprocessable_entity', message: 'an email, a password of at least 8 characters and an organization are required' }, { status: 422 });
+}
+
+/** The person the request's session cookie names, or undefined when nobody is signed in. */
+export function signedIn(ctx: SemanticsContext, request: Request): { email: string; organizations: string[]; role: string } | undefined {
+  const token = cookieOf(request, COOKIE);
+  if (!token) return undefined;
+  const session = ctx.rowsRaw('_web_session').find((s) => s.token === token);
+  if (!session) return undefined;
+  const person = ctx.rowsRaw('_person').find((p) => p.email === session.email);
+  return person ? { email: String(person.email), organizations: (person.organizations ?? []) as string[], role: typeof person.role === 'string' ? person.role : 'admin' } : undefined;
+}
+
+/** Where a page asked for by nobody signed in sends its visitor: the sign-in, returning here after. */
+export function toSignIn(request: Request): Response {
+  const url = new URL(request.url);
+  return new Response(null, { status: 302, headers: { location: `/sign-in?return_to=${encodeURIComponent(url.pathname + url.search)}` } });
+}
+
+async function formOf(request: Request): Promise<Record<string, string>> {
+  return Object.fromEntries(new URLSearchParams(await request.text()));
+}
+
+/** The sign-in's paths and the World's password door, or undefined for any other request. */
+export async function sessionFlow(request: Request, ctx: SemanticsContext): Promise<Response | undefined> {
+  const url = new URL(request.url);
+  const path = url.pathname.replace(/\/+$/, '');
+  if (path === '/sign-in' && request.method === 'GET') return page(returnTo(url.searchParams.get('return_to')));
+  if (path === '/sign-in' && request.method === 'POST') {
+    const f = await formOf(request);
+    const email = (f.email ?? '').trim().toLowerCase();
+    const back = returnTo(f.return_to);
+    const person = ctx.rowsRaw('_person').find((p) => p.email === email);
+    if (!email || !person || person.hash !== passwordHash(email, f.password ?? '')) return page(back, email, 'Incorrect email or password.');
+    const n = ctx.rowsRaw('_web_session').length + 1;
+    const token = hex(`session:${email}:${ctx.occurredAt}:${n}`).slice(0, 48);
+    await ctx.record('_web_session', { token, email, created_at: ctx.occurredAt }, `websession:${token}`);
+    // "user … signed_in" (https://planetscale.com/docs/security/audit-log, "Audited organization events")
+    for (const org of (person.organizations ?? []) as string[]) await audit(ctx, org, 'user', 'signed_in', { type: 'User', id: createdById(email), name: email }, { actor: personActorOf(email) });
+    const headers = new Headers({ location: back });
+    headers.append('set-cookie', `${COOKIE}=${token}; path=/; HttpOnly; Secure; SameSite=Lax`);
+    return new Response(null, { status: 302, headers });
+  }
+  // POST /_twin/users/:email/password {password, organization, role?}: the password the World gives a person, the
+  // organization they belong to, and their role in it (`admin`, the default, as the person who made it is; or `member`),
+  // with which they sign in at /sign-in. PlanetScale's sign-up and its invitations are not modelled (the management API's
+  // spec has no invitation operation); the World keeps the password's hash, never the password.
+  const door = /^\/_twin\/users\/([^/]+)\/password$/.exec(path);
+  if (door && request.method === 'POST') {
+    const email = decodeURIComponent(door[1]!).toLowerCase();
+    let body: Record<string, unknown> = {};
+    try { body = JSON.parse(await request.text()) as Record<string, unknown>; } catch { /* refused below */ }
+    const password = typeof body.password === 'string' ? body.password : '';
+    const organization = typeof body.organization === 'string' ? body.organization : '';
+    const role = body.role === undefined ? 'admin' : String(body.role);
+    if (role !== 'admin' && role !== 'member') return Response.json({ code: 'unprocessable_entity', message: 'role must be admin or member' }, { status: 422 });
+    if (!/^[^@\s]+@[^@\s]+$/.test(email) || password.length < 8 || !organization) return malformedAccount();
+    await ctx.record('_person', { email, hash: passwordHash(email, password), organizations: [organization], ...(body.role === undefined ? {} : { role }), set_at: ctx.occurredAt }, `person:${email}`);
+    return new Response(null, { status: 204 });
+  }
+  return undefined;
+}

package/api/src/semantics/audit.ts

@@ -0,0 +1,82 @@
+// The organization's audit log. "The organization audit log grants Organization Administrators access to review actions
+// performed by individual members of the organization. In addition, each audit log includes events detailing who
+// performed the action and when it happened"; its table "Audited organization events" names each event and its actions
+// (https://planetscale.com/docs/security/audit-log). The lane records one event for each act of its operations and pages
+// that the table names: database created/deleted; database_branch created/deleted/enabled_safe_migrations/
+// disabled_safe_migrations; database_branch_password created/deleted; database_deploy_request created/closed;
+// deploy_request_review approved; backup_policy created; service_token created/deleted; user signed_in.
+//
+// Where the pages stop and the twin decides: an event's `audit_action` is `<event>.<action>` and its `action` the action;
+// the auditable is the organization (the database, for what happens inside one); the actor is the service token that
+// asked, the person on the page, or PlanetScale for what the World clock does; `location` and `remote_ip` are null (a
+// World has no network). The log keeps events for 15 days, the audit-log page's retention for the Base plan (the plans
+// page's table says 6 months; the twin follows the more specific page). list_audit_logs answers newest first, `limit`
+// events (at most 100, 25 by default): `starting_after` an event's id gives the events older than it, and `ending_before`
+// an event's id the `limit` events just newer than it (the next page toward the present); an id orders events even once
+// its own event has aged out of the log.
+import { createHash } from 'node:crypto';
+import type { SemanticsContext } from '@volter/world-core';
+
+type Row = Record<string, unknown>;
+const RETENTION_MS = 15 * 86_400_000;
+
+export type AuditActor = { type: 'ServiceToken' | 'User' | 'PlanetScale'; id: string; name: string };
+export type AuditObject = { type: string; id: string; name: string };
+
+/** The actor a call acts as: the service token its Authorization names, or the World's own token. */
+export function callActor(ctx: SemanticsContext): AuditActor {
+  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 ? { type: 'ServiceToken', id: String(token.id), name: String(token.display_name) } : { type: 'ServiceToken', id: id ?? 'service-token', name: 'Service token' };
+}
+export const SYSTEM: AuditActor = { type: 'PlanetScale', id: 'planetscale', name: 'PlanetScale' };
+export const personOf = (email: string, id: string): AuditActor => ({ type: 'User', id, name: email });
+/** A person's id, as a page names them in an actor (the twin's: a hash of their email). */
+export const createdById = (email: string): string => `u${createHash('sha256').update(email).digest('hex').slice(0, 12)}`;
+/** The actor for a person on a page. */
+export const personActorOf = (email: string): AuditActor => personOf(email, createdById(email));
+
+/** Record one event of the organization `org`. */
+export async function audit(ctx: SemanticsContext, org: string, event: string, action: string, target: AuditObject, o: { actor?: AuditActor; auditable?: AuditObject; metadata?: Row } = {}): Promise<void> {
+  const n = ctx.tree().filter((r) => r.type === '_audit_event').length + 1;
+  const id = `ale${String(n).padStart(8, '0')}`;
+  const actor = o.actor ?? callActor(ctx);
+  const auditable = o.auditable ?? { type: 'Organization', id: org, name: org };
+  await ctx.record('_audit_event', {
+    id, actor_id: actor.id, actor_type: actor.type, auditable_id: auditable.id, auditable_type: auditable.type,
+    target_id: target.id, target_type: target.type, location: null, target_display_name: target.name,
+    audit_action: `${event}.${action}`, action, actor_display_name: actor.name, auditable_display_name: auditable.name,
+    remote_ip: null, created_at: ctx.occurredAt, updated_at: ctx.occurredAt, metadata: o.metadata ?? null, _organization: org, _n: n,
+  }, id);
+}
+
+/** The organization a path names. */
+export const orgOf = (ctx: SemanticsContext): string => String(ctx.call.params.organization ?? '');
+
+/** list_audit_logs. */
+export async function listAuditLogs(ctx: SemanticsContext): Promise<Response> {
+  const org = orgOf(ctx);
+  const q = new URL(ctx.call.request.url).searchParams;
+  const limitRaw = q.get('limit');
+  const limit = limitRaw === null ? 25 : Number(limitRaw);
+  if (!Number.isInteger(limit) || limit < 1 || limit > 100) return ctx.refuse({ status: 422, code: 'unprocessable_entity', message: 'limit must be between 1 and 100' });
+  const since = Date.parse(ctx.occurredAt) - RETENTION_MS;
+  const events: Row[] = ctx.tree().filter((r) => r.type === '_audit_event').map((r): Row => ({ ...ctx.own(r), id: String(r.id) }))
+    .filter((e) => e._organization === org && Date.parse(String(e.created_at)) >= since)
+    .sort((a, b) => Number(b._n) - Number(a._n));
+  // a cursor is an event's id, which counts up, so it orders every event, kept or aged out of the log
+  const nOf = (id: string | null): number | undefined => (id && /^ale\d+$/.test(id) ? Number(id.slice(3)) : undefined);
+  const after = nOf(q.get('starting_after'));
+  const before = nOf(q.get('ending_before'));
+  if ((q.get('starting_after') && after === undefined) || (q.get('ending_before') && before === undefined)) return ctx.refuse({ status: 422, code: 'unprocessable_entity', message: 'starting_after and ending_before take an audit log id' });
+  let from = after === undefined ? 0 : events.findIndex((e) => Number(e._n) < after);
+  if (from < 0) from = events.length;
+  let to = events.length;
+  if (before !== undefined) { to = events.findIndex((e) => Number(e._n) <= before); if (to < 0) to = events.length; from = Math.max(from, to - limit); }
+  const slice = events.slice(from, Math.min(to, from + limit));
+  const data = slice.map(({ _organization: _o, _n: _k, ...e }) => e);
+  return ctx.reply({
+    type: 'list', has_next: from + slice.length < events.length, has_prev: from > 0,
+    cursor_start: data[0]?.id ?? null, cursor_end: data.at(-1)?.id ?? null, data,
+  });
+}