@volter/twin-upstash 0.1.0

package/api/src/manifest.ts

@@ -0,0 +1,103 @@
+// Upstash's Developer API manifest (the upstash pack's `api` lane; docs/contributing/architecture.md, "Other wires:
+// lanes"): the vendor facts its published OpenAPI document (../spec/openapi.yaml) does not carry, and the resource whose
+// state the lane moves. The surface is generated (./generated/surface.gen.json, by `bun scripts/derive-pack.ts
+// upstash/api`), at `https://api.upstash.com/v2`.
+//
+// The lane serves the slice the customers' lives reach: a Redis database's create, read and delete, its read regions and
+// password, its backups (semantics/backups.ts, with the daily backup on the World clock, semantics/time.ts), and teams
+// (semantics/teams.ts). Every other operation of the document (renaming, plans, stats, audit logs, listing teams and
+// members, Vector, Search, QStash) is the gap. The REST data plane (the pack
+// root) reads the tokens this lane issues, so both write the one kernel service `upstash`; a database is a
+// control-plane record, stored under the `_database` type, beside the root's `key` and `script` subjects.
+//
+// NO `auth`: the Developer API reads HTTP Basic with the account's email and an API key made in the console
+// (https://upstash.com/docs/devops/developer-api/authentication), and a key's owner and its permission (Read/Write or
+// Read Only) are the lane's records, which the kernel's gate cannot read. The lane's key gate (key-gate.ts) sits in front
+// of the dispatch instead.
+//
+// THE ERROR BODY is the twin's decision: the document declares no error response for any operation. The twin answers in
+// the document's own `Error` schema ({code, message}), which no operation references.
+import type { DerivedManifest, StateField } from '@volter/world-core';
+
+/** A backup's `state` (the Backup schema: pending, completed, failed). A backup is `pending` when it is made and
+ *  `completed` two minutes later, on the World clock (semantics/time.ts): the duration is the twin's decision; Upstash's
+ *  backup page says only that "Backup process will start and will appear in the backups table"
+ *  (https://upstash.com/docs/redis/features/backup). Not made by the twin: failed. */
+const backupState: StateField = {
+  initial: 'pending',
+  transitions: [
+    { actor: 'time', from: ['pending'], to: 'completed', source: 'spec:/components/schemas/Backup/properties/state "State of the backup"' },
+  ],
+};
+
+export const manifest: DerivedManifest = {
+  vendor: 'upstash',
+  service: 'upstash',
+  body: { json: 'always' },
+  // database ids are UUIDs (the Database schema's example, 96ad0856-03b1-4ee7-9666-e81abd0349e1); the handler mints one
+  // per database from the World's instant and name (semantics/index.ts), so a World mints the same ids every run
+  ids: { template: '{uuid}' },
+  // `creation_time`: "Creation time of the database as Unix time"
+  time: 'unix',
+  error: { code: '{code}', message: '{message}' },
+  readOnly: { status: 403, code: 'forbidden', message: 'The twin is read-only' },
+  malformedBody: { status: 400, code: 'bad_request', message: 'The request body is not valid JSON' },
+  notFound: { status: 404, code: 'not_found', message: 'database not found' },
+  // listDatabases answers a bare array, which the envelope cannot state; it is the gap. Required by the type.
+  list: { style: 'envelope', envelope: { data: '{data}' }, limit: { param: 'limit', default: 100, max: 100 } },
+  // deleteDatabase answers the string "OK" (its 200 schema: type string, example OK)
+  deleted: 'OK',
+  // the operations of a declared resource the lane does not serve: the gap
+  unmodeled: [
+    'listDatabases', 'renameDatabase', 'enableTls', 'enableEviction', 'disableEviction', 'enableAutoUpgrade',
+    'disableAutoUpgrade', 'changePlan', 'updateBudget', 'getDatabaseStats', 'listTeams', 'getTeamMembers',
+  ],
+  screens: [{
+    id: 'sign-in', kind: 'flow', host: 'console.upstash.com', path: '/login',
+    demand: 'every console page a person reaches: each asks who is signed in', status: 'done',
+    controls: ['Email', 'Password', 'Sign in'], source: 'https://upstash.com/docs/devops/developer-api/introduction',
+  }, {
+    id: 'developer-api', kind: 'flow', host: 'console.upstash.com', path: '/account/api',
+    demand: 'the Developer API needs an API key, and a key is made only here',
+    status: 'done', controls: ['Create API Key', 'Name', 'Permissions', 'Expiration', 'Submit', 'Delete'],
+    source: 'https://upstash.com/docs/devops/developer-api/introduction',
+  }, {
+    id: 'qstash', kind: 'flow', host: 'console.upstash.com', path: '/qstash',
+    demand: "QStash's token and signing keys are shown, and the token reset, only here (the qstash lane's life)",
+    status: 'done', controls: ['Select', 'Reset token', 'Roll keys'], source: 'https://upstash.com/docs/qstash/howto/reset-token',
+  }, {
+    id: 'teams', kind: 'workspace', host: 'console.upstash.com', path: '/account/teams',
+    demand: 'a pending member is shown, and a pending invitation revoked, only here', status: 'done',
+    controls: ['Pending', 'Revoke Invite'], source: 'https://upstash.com/docs/common/account/teams',
+  }, {
+    id: 'team-invite', kind: 'flow', host: 'console.upstash.com', path: '/invite/{token}',
+    demand: 'a person joins a team by the acceptance link in the invitation email; no API operation accepts one',
+    status: 'done', controls: ['Accept invitation'], source: 'https://upstash.com/docs/common/account/teams',
+  }],
+  resources: {
+    Database: {
+      storedAs: '_database',
+      idPrefix: '',
+      // Not state the twin moves. `state` (active, suspended, passive): a database is active from its create (the
+      // getDatabase example's "state": "active"); suspension is Upstash's act on an account, which the twin does not
+      // model. `type` is the plan and `primary_region`, `db_type`, `db_resource_size` are set when it is made;
+      // `db_acl_enabled`, `db_acl_default_user_status` and `prometheus_enabled` are settings no served operation changes.
+      // Fields no page states a value for, answered with the Database schema's example values as the reference page
+      // renders them (https://upstash.com/docs/devops/developer-api/redis/get_database), the twin's choice: `replicas`
+      // (5, whatever the regions; no page says how Upstash counts them), `securityAddons` (all false), and
+      // `db_conn_idle_timeout`, `db_lua_timeout`, `db_lua_credits_per_min`, `db_store_max_idle`, `db_max_loads_per_sec`.
+      // Also the twin's, no page stating them: `db_memory_threshold` (256 MB on every plan), `db_max_clients` (10000), and
+      // how "Unlimited" monthly commands are written, `db_request_limit` 8024278031528737000 on pay-as-you-go and fixed
+      // plans (the schema's example value, a paid database's). Only the data size and the limits the pricing table gives
+      // (monthly commands, commands per second, request and record size) follow https://upstash.com/pricing/redis, per
+      // plan (semantics/index.ts, PLAN_LIMITS).
+      notState: ['state', 'type', 'primary_region', 'db_type', 'db_resource_size', 'db_acl_enabled', 'db_acl_default_user_status', 'prometheus_enabled'],
+    },
+    // `daily_backup` is whether the daily schedule made it, and `hourly_backup` is never set: both fixed when it is made
+    Backup: { storedAs: '_backup', idPrefix: '', notState: ['daily_backup', 'hourly_backup'], state: { state: backupState } },
+    Team: { storedAs: '_team', idPrefix: '' },
+    // a member's role is fixed: "If you want to change a user's role, you will need to delete and re-add them"
+    // (https://upstash.com/docs/common/account/teams); whether they are pending is the lane's bookkeeping (`_pending`)
+    TeamMember: { storedAs: '_team_member', idPrefix: '', notState: ['member_role'] },
+  },
+};

package/api/src/screens/developer-api.tsx

@@ -0,0 +1,106 @@
+// UPSTASH CONSOLE: ACCOUNT > DEVELOPER API — a flow (docs/contributing/architecture.md, "Screens"): the page where a person
+// makes the API key the Developer API reads. No API operation makes a key, so the first can only come from here.
+// https://upstash.com/docs/devops/developer-api/introduction: "Log in to the console, then open Account and click the
+// Developer API tab. Click the Create API Key button. Enter a name for your key (you can not use the same name for
+// multiple keys), choose the permissions (Read/Write or Read Only) and an expiration, then click Submit. You need to
+// download or copy/save your API key. Upstash does not remember or keep your API for security reasons." and "By default
+// one user can create up to 37 API keys." Built from @volter/world-ui's settings layout (Portal) under Upstash's skin;
+// nothing of Upstash's page is copied. Its controls are the ones the pack's lives need: Create API Key with its Name,
+// Permissions and Expiration, and Submit; and each key's Delete ("You can delete the API keys in the `Account > Developer
+// API` tab").
+//
+// The person on the page is who signed in at /login (screens/session.tsx): a visitor nobody signed in as is sent there
+// first. Where the documentation stops and the twin decides: the tab is at /account/api; the expirations offered are
+// 30 days, 90 days and 1 year (the page says a key has one, and names none); a name the person already used, and a 38th key, answer the page again with a
+// notice (422); the new key 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 { makeApiKey } from '../semantics/index.ts';
+import { signedIn, toSignIn } from './session.tsx';
+
+const PATH = '/account/api';
+const EXPIRATIONS: Record<string, number> = { '30d': 30, '90d': 90, '1y': 365 };
+const MAX_KEYS = 37;
+
+// Upstash's skin over the settings layout: its stone greys and green primary button
+const SKIN = `
+body { background: #ffffff; color: #1c1917; }
+.portal-side { background: #fafaf9; border-right: 1px solid #e7e5e4; }
+.portal-section h2 { border-color: #e7e5e4; color: #57534e; }
+.portal-notice { background: #ecfdf5; border: 1px solid #a7f3d0; font-family: ui-monospace, monospace; word-break: break-all; }
+.portal-button { background: #ffffff; border: 1px solid #d6d3d1; border-radius: 6px; padding: 6px 12px; }
+.portal-primary { background: #00c98d; border-color: #00c98d; color: #0c0a09; }
+`;
+
+function page(ctx: SemanticsContext, email: string, notice?: string, status = 200): Response {
+  const keys = ctx.rowsRaw('_api_key').filter((k) => k.email === email && k.deleted !== true);
+  return flowPage({
+    title: 'Developer API · Account · Upstash Console',
+    css: [PORTAL_CSS, SKIN],
+    status,
+    body: (
+      <Portal
+        merchant={`${email} · Account`}
+        back={{ href: '/', label: 'Back to console' }}
+        {...(notice ? { notice } : {})}
+        sections={[{
+          heading: 'Developer API',
+          empty: 'No API keys yet.',
+          items: keys.map((k) => ({
+            title: String(k.name),
+            detail: k.permission === 'read_only' ? 'Read Only' : 'Read/Write',
+            note: k.expires_at ? `Expires ${String(k.expires_at).slice(0, 10)}` : 'Never expires',
+            actions: [{ label: 'Delete', action: `${PATH}/delete`, tone: 'danger' as const, fields: { name: String(k.name) } }],
+          })),
+        }]}
+        forms={[{
+          heading: 'Create API Key',
+          action: PATH,
+          fields: [
+            { id: 'name', label: 'Name' },
+            { id: 'permission', label: 'Permissions', options: [{ value: 'read_write', label: 'Read/Write' }, { value: 'read_only', label: 'Read Only' }] },
+            { id: 'expiration', label: 'Expiration', options: [{ value: '30d', label: '30 days' }, { value: '90d', label: '90 days' }, { value: '1y', label: '1 year' }] },
+          ],
+          submit: { label: 'Submit' },
+        }]}
+      />
+    ),
+  });
+}
+
+/** Delete: the key stops working at once (key-gate.ts admits no deleted key); "When an API key is exposed ... or not
+ *  being used anymore; you should delete it. You can delete the API keys in the `Account > Developer API` tab." */
+async function deleteKey(ctx: SemanticsContext, email: string, name: string): Promise<Response> {
+  const key = ctx.rowsRaw('_api_key').find((k) => k.email === email && k.name === name && k.deleted !== true);
+  if (!key) return page(ctx, email, `You have no API key named ${name}.`, 422);
+  await ctx.record('_api_key', { deleted: true, deleted_at: ctx.occurredAt }, `apikey:${email}:${name}`);
+  return page(ctx, email, `API key ${name} deleted.`);
+}
+
+async function formOf(request: Request): Promise<Record<string, string>> {
+  return Object.fromEntries(new URLSearchParams(await request.text()));
+}
+
+/** The Developer API tab, or undefined for any other request. `contextFor` gives the lane's semantics context. */
+export async function developerApiPage(request: Request, contextFor: (request: Request) => Promise<SemanticsContext>): Promise<Response | undefined> {
+  const url = new URL(request.url);
+  const path = url.pathname.replace(/\/+$/, '');
+  if (path !== PATH && path !== `${PATH}/delete`) return undefined;
+  const person = signedIn(await contextFor(new Request(request.url)), request);
+  if (!person) return toSignIn(request);
+  if (request.method === 'GET' && path === PATH) return page(await contextFor(new Request(request.url)), person.email);
+  if (request.method !== 'POST') return undefined;
+  const form = await formOf(request);
+  const ctx = await contextFor(new Request(request.url));
+  if (path !== PATH) return deleteKey(ctx, person.email, (form.name ?? '').trim());
+  const name = (form.name ?? '').trim();
+  const held = ctx.rowsRaw('_api_key').filter((k) => k.email === person.email && k.deleted !== true);
+  if (!name) return page(ctx, person.email, 'An API key needs a name.', 422);
+  if (held.some((k) => k.name === name)) return page(ctx, person.email, `You already have an API key named ${name}.`, 422);
+  if (held.length >= MAX_KEYS) return page(ctx, person.email, `You can create up to ${MAX_KEYS} API keys.`, 422);
+  const permission = form.permission === 'read_only' ? 'read_only' : 'read_write';
+  const days = form.expiration !== undefined && form.expiration in EXPIRATIONS ? EXPIRATIONS[form.expiration]! : EXPIRATIONS['1y']!;
+  const expiresAt = new Date(Date.parse(ctx.occurredAt) + days * 86_400_000).toISOString();
+  const { key } = await makeApiKey(ctx, person.email, name, permission, expiresAt);
+  return page(await contextFor(new Request(request.url)), person.email, `API key ${name} created: ${key} — copy it now: Upstash does not keep it.`);
+}

package/api/src/screens/qstash.tsx

@@ -0,0 +1,99 @@
+// UPSTASH CONSOLE: QSTASH — a flow (docs/contributing/architecture.md, "Screens"): the page where a person gets their QStash
+// token and signing keys, which no API call gives before the first token exists. "Go to the QStash tab in the Upstash
+// Console, pick the region you want to use (see Select a Region), and copy the QSTASH_TOKEN from the Quickstart section."
+// (https://upstash.com/docs/qstash/overall/getstarted); "To reset your token, simply click on the "Reset token" button at
+// the bottom in the QStash UI and confirm the dialog." (https://upstash.com/docs/qstash/howto/reset-token). The token and
+// keys are the account's (../../../qstash/src/semantics/account.ts). Built from @volter/world-ui's settings layout (Portal)
+// under Upstash's skin; nothing of Upstash's page is copied. Its controls are the ones the pack's lives need: a region's
+// Select, Reset token, and Roll keys ("Rolling your keys can be done by going to the QStash UI and clicking on the "Roll
+// keys" button", https://upstash.com/docs/qstash/howto/roll-signing-keys; the roll is the QStash lane's `rollKeys`).
+//
+// The person on the page is who signed in at /login (session.tsx). Where the documentation stops and the twin decides: the
+// page is at /qstash, a region is picked with `?region=` (us-east-1 or eu-central-1, both documents' `servers`;
+// eu-central-1 when none is picked, their default), the Quickstart lists `QSTASH_URL`, `QSTASH_TOKEN`,
+// `QSTASH_CURRENT_SIGNING_KEY` and `QSTASH_NEXT_SIGNING_KEY` as the getting-started page's screenshot does, and the reset's
+// confirmation is the button's form (`confirm=yes`), after which the page shows the new token with the reset page's words.
+import { flowPage, Portal, PORTAL_CSS } from '@volter/world-ui';
+import type { SemanticsContext } from '@volter/world-core';
+import { accountOf, resetToken, rollKeys } from '../../../qstash/src/semantics/account.ts';
+import { signedIn, toSignIn } from './session.tsx';
+
+const PATH = '/qstash';
+const REGIONS = ['us-east-1', 'eu-central-1'];
+
+const SKIN = `
+body { background: #ffffff; color: #1c1917; }
+.portal-side { background: #fafaf9; border-right: 1px solid #e7e5e4; }
+.portal-section h2 { border-color: #e7e5e4; color: #57534e; }
+.portal-detail { font-family: ui-monospace, monospace; word-break: break-all; }
+.portal-notice { background: #ecfdf5; border: 1px solid #a7f3d0; }
+.portal-button { background: #ffffff; border: 1px solid #d6d3d1; border-radius: 6px; padding: 6px 12px; }
+.portal-danger { border-color: #fecaca; color: #b91c1c; }
+`;
+
+function page(ctx: SemanticsContext, email: string, region: string, notice?: string): Response {
+  const a = accountOf(ctx, email);
+  return flowPage({
+    title: 'QStash · Upstash Console',
+    css: [PORTAL_CSS, SKIN],
+    body: (
+      <Portal
+        merchant={`${email} · QStash`}
+        back={{ href: '/', label: 'Back to console' }}
+        {...(notice ? { notice } : {})}
+        sections={[{
+          heading: 'Region',
+          items: REGIONS.map((r) => ({ title: r, ...(r === region ? { badge: 'Selected' } : {}), actions: r === region ? [] : [{ label: 'Select', action: PATH, method: 'get' as const, fields: { region: r } }] })),
+        }, {
+          heading: 'Quickstart',
+          items: [
+            { title: 'QSTASH_URL', detail: `QSTASH_URL="https://qstash-${region}.upstash.io"` },
+            { title: 'QSTASH_TOKEN', detail: `QSTASH_TOKEN="${a.token}"` },
+            { title: 'QSTASH_CURRENT_SIGNING_KEY', detail: `QSTASH_CURRENT_SIGNING_KEY="${a.current}"` },
+            { title: 'QSTASH_NEXT_SIGNING_KEY', detail: `QSTASH_NEXT_SIGNING_KEY="${a.next}"` },
+          ],
+        }, {
+          heading: 'Token',
+          items: [{
+            title: 'Reset token',
+            note: 'Resetting your token will invalidate your current token and all future requests with the old token will be rejected.',
+            actions: [{ label: 'Reset token', action: `${PATH}/reset-token`, tone: 'danger' as const, fields: { region, confirm: 'yes' } }],
+          }],
+        }, {
+          heading: 'Signing keys',
+          items: [{
+            title: 'Roll keys',
+            note: 'The current key is replaced with the next key and a new next key is generated. Rolling your keys twice without updating your applications will cause your apps to reject all requests.',
+            actions: [{ label: 'Roll keys', action: `${PATH}/roll-keys`, tone: 'danger' as const, fields: { region } }],
+          }],
+        }]}
+      />
+    ),
+  });
+}
+
+async function formOf(request: Request): Promise<Record<string, string>> {
+  return Object.fromEntries(new URLSearchParams(await request.text()));
+}
+
+/** The QStash page, or undefined for any other request. `contextFor` gives the lane's semantics context. */
+export async function qstashPage(request: Request, contextFor: (request: Request) => Promise<SemanticsContext>): Promise<Response | undefined> {
+  const url = new URL(request.url);
+  const path = url.pathname.replace(/\/+$/, '');
+  if (path !== PATH && path !== `${PATH}/reset-token` && path !== `${PATH}/roll-keys`) return undefined;
+  const ctx = await contextFor(new Request(request.url));
+  const person = signedIn(ctx, request);
+  if (!person) return toSignIn(request);
+  const pick = (r: string | null | undefined): string => (r && REGIONS.includes(r) ? r : 'eu-central-1');
+  if (path === PATH && request.method === 'GET') return page(ctx, person.email, pick(url.searchParams.get('region')));
+  if (request.method !== 'POST' || path === PATH) return undefined;
+  const form = await formOf(request);
+  const region = pick(form.region);
+  if (path === `${PATH}/roll-keys`) {
+    await rollKeys(ctx, person.email);
+    return page(await contextFor(new Request(request.url)), person.email, region, 'Your signing keys were rolled: update QSTASH_CURRENT_SIGNING_KEY and QSTASH_NEXT_SIGNING_KEY in your applications.');
+  }
+  if (form.confirm !== 'yes') return page(ctx, person.email, region, 'Confirm the dialog to reset your token.');
+  await resetToken(ctx, person.email);
+  return page(await contextFor(new Request(request.url)), person.email, region, 'Your token was reset. Afterwards you should immediately update your token in all your applications.');
+}

package/api/src/screens/session.tsx

@@ -0,0 +1,125 @@
+// UPSTASH CONSOLE SIGN-IN — the door before every console.upstash.com page (docs/contributing/architecture.md, "Who is on a
+// screen"), following planetscale's (packages/twin/planetscale/api/src/screens/session.tsx): console.upstash.com/login shows
+// the form, which posts back to /login; 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 Upstash's skin; nothing of
+// Upstash's page is copied. "Log in to the console" (https://upstash.com/docs/devops/developer-api/introduction).
+//
+// Where Upstash's documentation stops and the twin decides: a person's account is their email, and their password is what
+// the World gave them (`POST /_twin/users/:email/password` {password}, standing in for Upstash's sign-up, as planetscale's
+// door of the same path does); the sign-in is at /login and its cookie is named `upstash_console_session` (Upstash
+// documents neither); a refused sign-in shows the form again with "Incorrect email or password." (answered 200); 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 { makeApiKey } from '../semantics/index.ts';
+
+const COOKIE = 'upstash_console_session';
+const hex = (s: string): string => createHash('sha256').update(s).digest('hex');
+const passwordHash = (email: string, password: string): string => hex(`password:${email.toLowerCase()}:${password}`);
+
+// Upstash's skin over the sign-in: its dark ink and green primary button
+const SKIN = `
+body { background: #f5f5f4; color: #1c1917; }
+.sign-in-mark { background: #00c98d; }
+.sign-in-error { background: #fef2f2; border-color: #fecaca; color: #1c1917; }
+.sign-in-box { background: #ffffff; border-color: #e7e5e4; }
+.sign-in-hint { color: #57534e; }
+.sign-in-submit { background: #00c98d; border-color: #00c98d; color: #0c0a09; }
+`;
+
+/** A return_to the console follows: a path on console.upstash.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: 'Log in · Upstash Console',
+    css: [SIGN_IN_CSS, SKIN],
+    body: (
+      <SignIn
+        heading="Log in to Upstash"
+        action="/login"
+        fields={{ return_to: back }}
+        account={{ name: 'email', label: 'Email', ...(email ? { value: email } : {}) }}
+        password={{ name: 'password', label: 'Password' }}
+        submit="Sign in"
+        {...(error ? { error } : {})}
+      />
+    ),
+  });
+}
+
+/** The person the request's session cookie names, or undefined when nobody is signed in. */
+export function signedIn(ctx: SemanticsContext, request: Request): { email: 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) } : 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: `/login?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 === '/login' && request.method === 'GET') return page(returnTo(url.searchParams.get('return_to')));
+  if (path === '/login' && 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}`);
+    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, plan?}: the password the World gives a person, with which they sign in at
+  // /login. Upstash's sign-up is not modelled; 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 : '';
+    if (!/^[^@\s]+@[^@\s]+$/.test(email) || password.length < 8) return badPassword();
+    // `plan: "payg"` makes the account pay-as-you-go (a card on file), so a database made without a plan is on it
+    await ctx.record('_person', { email, hash: passwordHash(email, password), set_at: ctx.occurredAt, plan: body.plan === 'payg' ? 'payg' : 'free' }, `person:${email}`);
+    return new Response(null, { status: 204 });
+  }
+  // POST /_twin/users/:email/api-key {name, permission?}: an API key the World issues for an account of its own (a World
+  // whose application calls the Developer API), made as the console's Developer API tab makes one, Read/Write unless
+  // `read_only` is asked, never expiring; answered 201 {email, key}. The account needs no console password.
+  const keyDoor = /^\/_twin\/users\/([^/]+)\/api-key$/.exec(path);
+  return keyDoor && request.method === 'POST' ? apiKeyDoor(ctx, decodeURIComponent(keyDoor[1]!).toLowerCase(), request) : undefined;
+}
+
+/** The password door's refusal: no email, or a password shorter than 8 characters. */
+function badPassword(): Response {
+  return Response.json({ code: 'bad_request', message: 'an email and a password of at least 8 characters are required' }, { status: 400 });
+}
+
+/** POST /_twin/users/:email/api-key's key, made for the World's own account. */
+async function apiKeyDoor(ctx: SemanticsContext, email: string, request: Request): Promise<Response> {
+  let body: Record<string, unknown> = {};
+  try { body = JSON.parse(await request.text()) as Record<string, unknown>; } catch { /* refused below */ }
+  const name = typeof body.name === 'string' ? body.name.trim() : '';
+  if (!/^[^@\s]+@[^@\s]+$/.test(email) || !name) return Response.json({ code: 'bad_request', message: 'an email and a key name are required' }, { status: 400 });
+  if (ctx.rowsRaw('_api_key').some((k) => k.email === email && k.name === name && k.deleted !== true)) return Response.json({ code: 'bad_request', message: `${email} already has an API key named ${name}` }, { status: 400 });
+  const { key } = await makeApiKey(ctx, email, name, body.permission === 'read_only' ? 'read_only' : 'read_write', null);
+  return Response.json({ email, key }, { status: 201 });
+}

package/api/src/screens/teams.tsx

@@ -0,0 +1,114 @@
+// UPSTASH CONSOLE: ACCOUNT > TEAMS, and the invitation's acceptance link (docs/contributing/architecture.md, "Screens").
+// https://upstash.com/docs/common/account/teams: "we will send an invitation email to that address. The user joins the team
+// by clicking the acceptance link in the email ... Until the invitation is accepted, the user appears as a **pending
+// member** and does not have access to the team yet. You can revoke a pending invitation (**Revoke Invite**) or remove an
+// existing member from the same page." No API operation accepts an invitation, and none says a member is pending: both
+// are here. Built from @volter/world-ui's settings layout (Portal) under Upstash's skin; nothing of Upstash's page is
+// copied. Its controls are the ones a life needs: a member's Pending mark, Revoke Invite, and the invitation's Accept.
+//
+// The person on a page is who signed in at /login (session.tsx). Where the documentation stops and the twin decides: the
+// page is at /account/teams and lists every team the person has joined, each with its members; the acceptance link is
+// /invite/<token> and asks the invited person to accept (a person signed in as anyone else is told the invitation is not
+// theirs, 403); a revoked or accepted invitation's link answers 404. The invitation email itself is the World's record,
+// read at GET /_twin/mail?to=<email> → {to, mails: [{at, subject, text}]} (standing in for the person's inbox).
+import { flowPage, Portal, PORTAL_CSS } from '@volter/world-ui';
+import type { SemanticsContext } from '@volter/world-core';
+import { MAIL, membersOf, removeMember, roleOf, teamOf } from '../semantics/teams.ts';
+import { signedIn, toSignIn } from './session.tsx';
+
+const PATH = '/account/teams';
+
+const SKIN = `
+body { background: #ffffff; color: #1c1917; }
+.portal-side { background: #fafaf9; border-right: 1px solid #e7e5e4; }
+.portal-section h2 { border-color: #e7e5e4; color: #57534e; }
+.portal-notice { background: #ecfdf5; border: 1px solid #a7f3d0; }
+.portal-button { background: #ffffff; border: 1px solid #d6d3d1; border-radius: 6px; padding: 6px 12px; }
+.portal-primary { background: #00c98d; border-color: #00c98d; color: #0c0a09; }
+.portal-danger { border-color: #fecaca; color: #b91c1c; }
+`;
+
+const ROLE_LABEL: Record<string, string> = { owner: 'Owner', admin: 'Admin', dev: 'Dev', finance: 'Finance' };
+
+function teamsPage(ctx: SemanticsContext, email: string, notice?: string): Response {
+  const joined = ctx.rowsRaw('TeamMember').filter((m) => m.member_email === email && !m._removed_at && m._pending !== true && teamOf(ctx, String(m.team_id)));
+  return flowPage({
+    title: 'Teams · Account · Upstash Console',
+    css: [PORTAL_CSS, SKIN],
+    body: (
+      <Portal
+        merchant={`${email} · Account`}
+        back={{ href: '/', label: 'Back to console' }}
+        {...(notice ? { notice } : {})}
+        sections={joined.length === 0 ? [{ heading: 'Teams', items: [], empty: 'You are not a member of any team.' }] : joined.map((j) => {
+          const team = String(j.team_id);
+          const manager = ['owner', 'admin'].includes(String(j.member_role));
+          return {
+            heading: String(j.team_name),
+            items: membersOf(ctx, team).map((m) => ({
+              title: String(m.member_email),
+              detail: ROLE_LABEL[String(m.member_role)] ?? String(m.member_role),
+              ...(m._pending === true ? { badge: 'Pending', note: 'Invitation sent, not yet accepted' } : typeof m._joined_at === 'string' ? { note: `Joined ${m._joined_at.slice(0, 10)}` } : {}),
+              actions: m._pending === true && manager ? [{ label: 'Revoke Invite', action: `${PATH}/revoke`, tone: 'danger' as const, fields: { team_id: team, member_email: String(m.member_email) } }] : [],
+            })),
+          };
+        })}
+      />
+    ),
+  });
+}
+
+function invitePage(team: string, role: string, token: string, notice?: string, status = 200): Response {
+  return flowPage({
+    title: 'Team invitation · Upstash Console',
+    css: [PORTAL_CSS, SKIN],
+    status,
+    body: (
+      <Portal
+        merchant="Team invitation"
+        {...(notice ? { notice } : {})}
+        sections={[{ heading: `Join ${team}`, items: [{ title: team, detail: `as ${ROLE_LABEL[role] ?? role}`, actions: notice ? [] : [{ label: 'Accept invitation', action: `/invite/${token}`, tone: 'primary' as const }] }] }]}
+      />
+    ),
+  });
+}
+
+async function formOf(request: Request): Promise<Record<string, string>> {
+  return Object.fromEntries(new URLSearchParams(await request.text()));
+}
+
+/** The Teams page, the invitation's link and the World's mail door, or undefined for any other request. */
+export async function teamsPages(request: Request, contextFor: (request: Request) => Promise<SemanticsContext>): Promise<Response | undefined> {
+  const url = new URL(request.url);
+  const path = url.pathname.replace(/\/+$/, '');
+  if (path === '/_twin/mail' && request.method === 'GET') {
+    const to = (url.searchParams.get('to') ?? '').toLowerCase();
+    const mails = (await contextFor(new Request(request.url))).rowsRaw(MAIL).filter((m) => m.to === to).map((m) => ({ at: m.at, subject: m.subject, text: m.text }));
+    return Response.json({ to, mails });
+  }
+  const invite = /^\/invite\/([0-9a-f]+)$/.exec(path);
+  if (path !== PATH && path !== `${PATH}/revoke` && !invite) return undefined;
+  const ctx = await contextFor(new Request(request.url));
+  const person = signedIn(ctx, request);
+  if (!person) return toSignIn(request);
+  if (invite) {
+    const member = ctx.rowsRaw('TeamMember').find((m) => m._invite === invite[1] && m._pending === true && !m._removed_at);
+    if (!member) return new Response('Not Found', { status: 404, headers: { 'content-type': 'text/plain' } });
+    const [team, role] = [String(member.team_name), String(member.member_role)];
+    if (member.member_email !== person.email) return invitePage(team, role, invite[1]!, `This invitation is for ${String(member.member_email)}. Log in as that user to accept it.`, 403);
+    if (request.method !== 'POST') return invitePage(team, role, invite[1]!);
+    await ctx.write('TeamMember', `${String(member.team_id)}:${person.email}`, { ...ctx.own(member), _pending: false, _joined_at: ctx.occurredAt }, 'team.accept-invite');
+    return teamsPage(await contextFor(new Request(request.url)), person.email, `You joined ${team}.`);
+  }
+  return path === PATH ? teamsPage(ctx, person.email) : revokeInvite(ctx, person.email, request, contextFor);
+}
+
+/** Revoke Invite: a pending member goes, by the team's Owner or an Admin. */
+async function revokeInvite(ctx: SemanticsContext, email: string, request: Request, contextFor: (request: Request) => Promise<SemanticsContext>): Promise<Response> {
+  const form = await formOf(request);
+  const team = String(form.team_id ?? '');
+  const pending = membersOf(ctx, team).find((m) => m.member_email === form.member_email && m._pending === true);
+  if (!pending || !['owner', 'admin'].includes(roleOf(ctx, team, email) ?? '')) return teamsPage(ctx, email, 'There is no pending invitation you can revoke.');
+  await removeMember(ctx, team, String(pending.member_email), 'team.revoke-invite');
+  return teamsPage(await contextFor(new Request(request.url)), email, `The invitation to ${String(pending.member_email)} was revoked.`);
+}