@volter/twin-upstash 0.1.0

package/dist/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/dist/api/src/screens/qstash.d.ts

@@ -0,0 +1,3 @@
+import type { SemanticsContext } from '@volter/world-core';
+/** The QStash page, or undefined for any other request. `contextFor` gives the lane's semantics context. */
+export declare function qstashPage(request: Request, contextFor: (request: Request) => Promise<SemanticsContext>): Promise<Response | undefined>;

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

@@ -0,0 +1,92 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+// 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 { accountOf, resetToken, rollKeys } from "../../../qstash/src/semantics/account.js";
+import { signedIn, toSignIn } from "./session.js";
+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, email, region, notice) {
+    const a = accountOf(ctx, email);
+    return flowPage({
+        title: 'QStash · Upstash Console',
+        css: [PORTAL_CSS, SKIN],
+        body: (_jsx(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', 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', 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', fields: { region } }],
+                        }],
+                }] })),
+    });
+}
+async function formOf(request) {
+    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, contextFor) {
+    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) => (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/dist/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/dist/api/src/screens/session.d.ts

@@ -0,0 +1,9 @@
+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;
+} | 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,118 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+// 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 { makeApiKey } from "../semantics/index.js";
+const COOKIE = 'upstash_console_session';
+const hex = (s) => createHash('sha256').update(s).digest('hex');
+const passwordHash = (email, password) => 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) => (raw && raw.startsWith('/') && !raw.startsWith('//') ? raw : '/');
+function page(back, email, error) {
+    return flowPage({
+        title: 'Log in · Upstash Console',
+        css: [SIGN_IN_CSS, SKIN],
+        body: (_jsx(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, 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) } : 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: `/login?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 === '/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 = {};
+        try {
+            body = JSON.parse(await request.text());
+        }
+        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() {
+    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, email, request) {
+    let body = {};
+    try {
+        body = JSON.parse(await request.text());
+    }
+    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/dist/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/dist/api/src/screens/teams.d.ts

@@ -0,0 +1,3 @@
+import type { SemanticsContext } from '@volter/world-core';
+/** The Teams page, the invitation's link and the World's mail door, or undefined for any other request. */
+export declare function teamsPages(request: Request, contextFor: (request: Request) => Promise<SemanticsContext>): Promise<Response | undefined>;