@volter/twin-planetscale 0.1.0

package/dist/api/src/screens/service-tokens.js

@@ -0,0 +1,134 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+// 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 { makeServiceToken, removeServiceToken } from "../semantics/index.js";
+import { accessOf } from "../semantics/shared.js";
+import { audit, personActorOf } from "../semantics/audit.js";
+import { signedIn, toSignIn } from "./session.js";
+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',
+];
+function page(ctx, org, notice, status = 200) {
+    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: (_jsx(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 ?? []).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', method: 'post' }],
+                    })),
+                }], 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) {
+    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, contextFor) {
+    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 ?? []);
+    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, resource.resource_name);
+        await ctx.write('ServiceToken', String(token.id), { ...ctx.own(token), 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/dist/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/dist/api/src/screens/session.d.ts

@@ -0,0 +1,11 @@
+import type { SemanticsContext } from '@volter/world-core';
+/** The person the request's session cookie names, or undefined when nobody is signed in. */
+export declare function signedIn(ctx: SemanticsContext, request: Request): {
+    email: string;
+    organizations: string[];
+    role: string;
+} | undefined;
+/** Where a page asked for by nobody signed in sends its visitor: the sign-in, returning here after. */
+export declare function toSignIn(request: Request): Response;
+/** The sign-in's paths and the World's password door, or undefined for any other request. */
+export declare function sessionFlow(request: Request, ctx: SemanticsContext): Promise<Response | undefined>;

package/dist/api/src/screens/session.js

@@ -0,0 +1,108 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+// 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 { audit, createdById, personActorOf } from "../semantics/audit.js";
+const COOKIE = '_planetscale_session';
+const hex = (s) => createHash('sha256').update(s).digest('hex');
+const passwordHash = (email, password) => 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) => (raw && raw.startsWith('/') && !raw.startsWith('//') ? raw : '/');
+function page(back, email, error) {
+    return flowPage({
+        title: 'Sign in · PlanetScale',
+        css: [SIGN_IN_CSS, SKIN],
+        body: (_jsx(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() {
+    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, request) {
+    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 ?? []), 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) {
+    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) {
+    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, ctx) {
+    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 ?? []))
+            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 = {};
+        try {
+            body = JSON.parse(await request.text());
+        }
+        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/dist/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/dist/api/src/semantics/audit.d.ts

@@ -0,0 +1,31 @@
+import type { SemanticsContext } from '@volter/world-core';
+type Row = Record<string, unknown>;
+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 declare function callActor(ctx: SemanticsContext): AuditActor;
+export declare const SYSTEM: AuditActor;
+export declare const personOf: (email: string, id: string) => AuditActor;
+/** A person's id, as a page names them in an actor (the twin's: a hash of their email). */
+export declare const createdById: (email: string) => string;
+/** The actor for a person on a page. */
+export declare const personActorOf: (email: string) => AuditActor;
+/** Record one event of the organization `org`. */
+export declare function audit(ctx: SemanticsContext, org: string, event: string, action: string, target: AuditObject, o?: {
+    actor?: AuditActor;
+    auditable?: AuditObject;
+    metadata?: Row;
+}): Promise<void>;
+/** The organization a path names. */
+export declare const orgOf: (ctx: SemanticsContext) => string;
+/** list_audit_logs. */
+export declare function listAuditLogs(ctx: SemanticsContext): Promise<Response>;
+export {};

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

@@ -0,0 +1,80 @@
+// 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';
+const RETENTION_MS = 15 * 86_400_000;
+/** The actor a call acts as: the service token its Authorization names, or the World's own token. */
+export function callActor(ctx) {
+    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 = { type: 'PlanetScale', id: 'planetscale', name: 'PlanetScale' };
+export const personOf = (email, id) => ({ 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) => `u${createHash('sha256').update(email).digest('hex').slice(0, 12)}`;
+/** The actor for a person on a page. */
+export const personActorOf = (email) => personOf(email, createdById(email));
+/** Record one event of the organization `org`. */
+export async function audit(ctx, org, event, action, target, o = {}) {
+    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) => String(ctx.call.params.organization ?? '');
+/** list_audit_logs. */
+export async function listAuditLogs(ctx) {
+    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 = ctx.tree().filter((r) => r.type === '_audit_event').map((r) => ({ ...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) => (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,
+    });
+}