@pwfabric/cli 0.0.0-stage → 1.0.0-rc.1

package/dist/host/definitions.js

@@ -0,0 +1,136 @@
+/**
+ * What the local host reads from the pwpack folder.
+ *
+ *   app/definitions/auth.json      who may enter (definitions.md, `auth.json`)
+ *   app/definitions/entities.json  the collections the host keeps
+ *   app/surfaces/<key>.receipt.json  the pages it serves
+ *   app/data/<typeId>.jsonl | .json  seed rows (a convention of this host)
+ *
+ * Read on every call, never cached: `pwf dev` edits these files while the
+ * host runs, and a definition change must apply without a restart. An absent
+ * file is "not declared"; an unreadable one is reported as an error rather
+ * than guessed around.
+ */
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+function readJson(path) {
+    if (!existsSync(path))
+        return undefined;
+    const text = readFileSync(path, 'utf8');
+    try {
+        return JSON.parse(text);
+    }
+    catch (err) {
+        throw new Error(`${path} is not valid JSON: ${err.message}`);
+    }
+}
+const isObject = (v) => Boolean(v) && typeof v === 'object' && !Array.isArray(v);
+const strings = (v) => (Array.isArray(v) ? v.filter((x) => typeof x === 'string') : []);
+/** `undefined` when the app declares no `auth.json` (or an empty one). */
+export function readAuth(root) {
+    const raw = readJson(join(root, 'app', 'definitions', 'auth.json'));
+    if (!isObject(raw) || Object.keys(raw).length === 0)
+        return undefined;
+    const topology = raw.topology === 'external' ? 'external' : 'app';
+    const iss = isObject(raw.issuer) ? raw.issuer : undefined;
+    const access = isObject(raw.access) ? raw.access : {};
+    const rules = (Array.isArray(access.rules) ? access.rules : [])
+        .filter(isObject)
+        .map((r) => ({ subject: String(r.subject ?? ''), model: String(r.model ?? ''), rule: String(r.rule ?? '') }));
+    return {
+        required: raw.required === true,
+        topology,
+        methods: strings(raw.methods),
+        ...(iss && typeof iss.issuer === 'string' && typeof iss.clientId === 'string'
+            ? {
+                issuer: {
+                    issuer: iss.issuer,
+                    clientId: iss.clientId,
+                    scopes: Array.isArray(iss.scopes) ? strings(iss.scopes) : ['openid', 'profile', 'email'],
+                    ...(typeof iss.audience === 'string' && iss.audience ? { audience: iss.audience } : {}),
+                },
+            }
+            : {}),
+        access: { rules },
+    };
+}
+export function readEntities(root) {
+    const raw = readJson(join(root, 'app', 'definitions', 'entities.json'));
+    const list = isObject(raw) && Array.isArray(raw.entities) ? raw.entities : [];
+    return list.filter(isObject).flatMap((e) => {
+        if (typeof e.typeId !== 'string' || !e.typeId)
+            return [];
+        const fields = (Array.isArray(e.fields) ? e.fields : []).filter(isObject).flatMap((f) => typeof f.name === 'string' && f.name
+            ? [{ name: f.name, type: typeof f.type === 'string' ? f.type : 'text', required: f.required === true }]
+            : []);
+        return [
+            {
+                typeId: e.typeId,
+                ...(typeof e.displayName === 'string' ? { displayName: e.displayName } : {}),
+                fields,
+                ...(typeof e.scope === 'string' ? { scope: e.scope } : {}),
+            },
+        ];
+    });
+}
+/** A page key is a file name, never a path. */
+export const PAGE_KEY = /^[A-Za-z0-9][A-Za-z0-9_-]*$/;
+export function surfaceKeys(root) {
+    const dir = join(root, 'app', 'surfaces');
+    if (!existsSync(dir))
+        return [];
+    return readdirSync(dir)
+        .filter((f) => f.endsWith('.receipt.json'))
+        .map((f) => f.slice(0, -'.receipt.json'.length))
+        .filter((k) => PAGE_KEY.test(k))
+        .sort();
+}
+export function readReceipt(root, key) {
+    if (!PAGE_KEY.test(key))
+        return undefined;
+    const raw = readJson(join(root, 'app', 'surfaces', `${key}.receipt.json`));
+    return isObject(raw) ? raw : undefined;
+}
+/**
+ * Seed rows for one collection.
+ *
+ * THE CONVENTION (proposed for the spec): `app/data/<typeId>.json` holding
+ * `{ "data": [ …records ] }` — the same `data` envelope a record list answer
+ * uses. A record may carry its own `id`; `createdAt`/`updatedAt` are filled
+ * when absent. Also accepted, for hand-written seed files only:
+ * `app/data/<typeId>.jsonl`, one JSON object per line (blank lines skipped),
+ * read when no `.json` file exists.
+ */
+export function readSeed(root, typeId) {
+    if (!PAGE_KEY.test(typeId))
+        return [];
+    const dir = join(root, 'app', 'data');
+    const jsonPath = join(dir, `${typeId}.json`);
+    const json = readJson(jsonPath);
+    if (json !== undefined) {
+        if (!isObject(json) || !Array.isArray(json.data)) {
+            throw new Error(`${jsonPath} must be { "data": [ ...records ] }`);
+        }
+        return json.data.filter(isObject);
+    }
+    const jsonl = join(dir, `${typeId}.jsonl`);
+    if (!existsSync(jsonl))
+        return [];
+    return readFileSync(jsonl, 'utf8')
+        .split(/\r?\n/)
+        .map((line, i) => [line.trim(), i + 1])
+        .filter(([line]) => line !== '')
+        .map(([line, n]) => {
+        let row;
+        try {
+            row = JSON.parse(line);
+        }
+        catch {
+            throw new Error(`${jsonl}:${n} is not valid JSON`);
+        }
+        if (!isObject(row))
+            throw new Error(`${jsonl}:${n} is not a JSON object`);
+        return row;
+    });
+}
+//# sourceMappingURL=definitions.js.map

package/dist/host/definitions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"definitions.js","sourceRoot":"","sources":["../../src/host/definitions.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * What the local host reads from the pwpack folder.\n *\n *   app/definitions/auth.json      who may enter (definitions.md, `auth.json`)\n *   app/definitions/entities.json  the collections the host keeps\n *   app/surfaces/<key>.receipt.json  the pages it serves\n *   app/data/<typeId>.jsonl | .json  seed rows (a convention of this host)\n *\n * Read on every call, never cached: `pwf dev` edits these files while the\n * host runs, and a definition change must apply without a restart. An absent\n * file is \"not declared\"; an unreadable one is reported as an error rather\n * than guessed around.\n */\n\nimport { existsSync, readdirSync, readFileSync } from 'node:fs'\nimport { join } from 'node:path'\n\nexport interface AuthDeclaration {\n  readonly required: boolean\n  readonly topology: 'app' | 'external'\n  readonly methods: readonly string[]\n  readonly issuer?: {\n    readonly issuer: string\n    readonly clientId: string\n    readonly scopes: readonly string[]\n    readonly audience?: string\n  }\n  readonly access: {\n    readonly rules: readonly { readonly subject: string; readonly model: string; readonly rule: string }[]\n  }\n}\n\nexport interface EntityField {\n  readonly name: string\n  readonly type: string\n  readonly required: boolean\n}\n\nexport interface EntityDeclaration {\n  readonly typeId: string\n  readonly displayName?: string\n  readonly fields: readonly EntityField[]\n  /** Carried member (not in the spec yet): `\"owner\"` makes the collection per-visitor. */\n  readonly scope?: string\n}\n\nfunction readJson(path: string): unknown {\n  if (!existsSync(path)) return undefined\n  const text = readFileSync(path, 'utf8')\n  try {\n    return JSON.parse(text) as unknown\n  } catch (err) {\n    throw new Error(`${path} is not valid JSON: ${(err as Error).message}`)\n  }\n}\n\nconst isObject = (v: unknown): v is Record<string, unknown> => Boolean(v) && typeof v === 'object' && !Array.isArray(v)\nconst strings = (v: unknown): string[] => (Array.isArray(v) ? v.filter((x): x is string => typeof x === 'string') : [])\n\n/** `undefined` when the app declares no `auth.json` (or an empty one). */\nexport function readAuth(root: string): AuthDeclaration | undefined {\n  const raw = readJson(join(root, 'app', 'definitions', 'auth.json'))\n  if (!isObject(raw) || Object.keys(raw).length === 0) return undefined\n  const topology = raw.topology === 'external' ? 'external' : 'app'\n  const iss = isObject(raw.issuer) ? raw.issuer : undefined\n  const access = isObject(raw.access) ? raw.access : {}\n  const rules = (Array.isArray(access.rules) ? access.rules : [])\n    .filter(isObject)\n    .map((r) => ({ subject: String(r.subject ?? ''), model: String(r.model ?? ''), rule: String(r.rule ?? '') }))\n  return {\n    required: raw.required === true,\n    topology,\n    methods: strings(raw.methods),\n    ...(iss && typeof iss.issuer === 'string' && typeof iss.clientId === 'string'\n      ? {\n          issuer: {\n            issuer: iss.issuer,\n            clientId: iss.clientId,\n            scopes: Array.isArray(iss.scopes) ? strings(iss.scopes) : ['openid', 'profile', 'email'],\n            ...(typeof iss.audience === 'string' && iss.audience ? { audience: iss.audience } : {}),\n          },\n        }\n      : {}),\n    access: { rules },\n  }\n}\n\nexport function readEntities(root: string): EntityDeclaration[] {\n  const raw = readJson(join(root, 'app', 'definitions', 'entities.json'))\n  const list = isObject(raw) && Array.isArray(raw.entities) ? raw.entities : []\n  return list.filter(isObject).flatMap((e) => {\n    if (typeof e.typeId !== 'string' || !e.typeId) return []\n    const fields = (Array.isArray(e.fields) ? e.fields : []).filter(isObject).flatMap((f) =>\n      typeof f.name === 'string' && f.name\n        ? [{ name: f.name, type: typeof f.type === 'string' ? f.type : 'text', required: f.required === true }]\n        : []\n    )\n    return [\n      {\n        typeId: e.typeId,\n        ...(typeof e.displayName === 'string' ? { displayName: e.displayName } : {}),\n        fields,\n        ...(typeof e.scope === 'string' ? { scope: e.scope } : {}),\n      },\n    ]\n  })\n}\n\n/** A page key is a file name, never a path. */\nexport const PAGE_KEY = /^[A-Za-z0-9][A-Za-z0-9_-]*$/\n\nexport function surfaceKeys(root: string): string[] {\n  const dir = join(root, 'app', 'surfaces')\n  if (!existsSync(dir)) return []\n  return readdirSync(dir)\n    .filter((f) => f.endsWith('.receipt.json'))\n    .map((f) => f.slice(0, -'.receipt.json'.length))\n    .filter((k) => PAGE_KEY.test(k))\n    .sort()\n}\n\nexport function readReceipt(root: string, key: string): Record<string, unknown> | undefined {\n  if (!PAGE_KEY.test(key)) return undefined\n  const raw = readJson(join(root, 'app', 'surfaces', `${key}.receipt.json`))\n  return isObject(raw) ? raw : undefined\n}\n\n/**\n * Seed rows for one collection.\n *\n * THE CONVENTION (proposed for the spec): `app/data/<typeId>.json` holding\n * `{ \"data\": [ …records ] }` — the same `data` envelope a record list answer\n * uses. A record may carry its own `id`; `createdAt`/`updatedAt` are filled\n * when absent. Also accepted, for hand-written seed files only:\n * `app/data/<typeId>.jsonl`, one JSON object per line (blank lines skipped),\n * read when no `.json` file exists.\n */\nexport function readSeed(root: string, typeId: string): Record<string, unknown>[] {\n  if (!PAGE_KEY.test(typeId)) return []\n  const dir = join(root, 'app', 'data')\n  const jsonPath = join(dir, `${typeId}.json`)\n  const json = readJson(jsonPath)\n  if (json !== undefined) {\n    if (!isObject(json) || !Array.isArray(json.data)) {\n      throw new Error(`${jsonPath} must be { \"data\": [ ...records ] }`)\n    }\n    return json.data.filter(isObject)\n  }\n  const jsonl = join(dir, `${typeId}.jsonl`)\n  if (!existsSync(jsonl)) return []\n  return readFileSync(jsonl, 'utf8')\n    .split(/\\r?\\n/)\n    .map((line, i) => [line.trim(), i + 1] as const)\n    .filter(([line]) => line !== '')\n    .map(([line, n]) => {\n      let row: unknown\n      try {\n        row = JSON.parse(line)\n      } catch {\n        throw new Error(`${jsonl}:${n} is not valid JSON`)\n      }\n      if (!isObject(row)) throw new Error(`${jsonl}:${n} is not a JSON object`)\n      return row\n    })\n}\n"]}

package/dist/host/http.d.ts

@@ -0,0 +1,39 @@
+/**
+ * The few HTTP chores the local host needs, on bare `node:http`.
+ *
+ * Every answer is JSON (or a redirect). Bodies are read up to 1 MiB and
+ * refused past it; JSON routes refuse any other content type. Nothing here
+ * logs — a request carries session tokens, and a development server's console
+ * is copied into bug reports.
+ */
+import type { IncomingMessage, ServerResponse } from 'node:http';
+/** Request bodies past this size are refused with 413. */
+export declare const MAX_BODY_BYTES: number;
+/** A failure that becomes `{ error: { code, message } }` with `status`. */
+export declare class HostError extends Error {
+    readonly status: number;
+    readonly code: string;
+    constructor(status: number, code: string, message: string);
+}
+export declare function sendJson(res: ServerResponse, status: number, body: unknown, headers?: Record<string, string>): void;
+export declare function sendError(res: ServerResponse, err: HostError): void;
+/** `302` to `location`, with any cookies to set on the way. */
+export declare function redirect(res: ServerResponse, location: string, cookies?: readonly string[]): void;
+/** The raw body, refused past `MAX_BODY_BYTES`. */
+export declare function readBody(req: IncomingMessage): Promise<string>;
+/** A JSON object body. An empty body is `{}`; anything else that is not an object is refused. */
+export declare function readJsonObject(req: IncomingMessage): Promise<Record<string, unknown>>;
+/** A form-encoded body (the OAuth token endpoint's only format). */
+export declare function readForm(req: IncomingMessage): Promise<URLSearchParams>;
+export declare function cookiesOf(req: IncomingMessage): Record<string, string>;
+/**
+ * The visitor's credential: `x-app-session`, else `Authorization: Bearer`.
+ * The session protocol accepts either on every session-server route.
+ */
+export declare function credentialOf(req: IncomingMessage): string | undefined;
+/**
+ * Only a path on the app's own origin may be the way back — the same rule the
+ * runner applies before it builds a start address (`//host` and `/\host` are
+ * other sites to a browser).
+ */
+export declare function safeReturnTo(value: string | null): string;

package/dist/host/http.js

@@ -0,0 +1,156 @@
+/**
+ * The few HTTP chores the local host needs, on bare `node:http`.
+ *
+ * Every answer is JSON (or a redirect). Bodies are read up to 1 MiB and
+ * refused past it; JSON routes refuse any other content type. Nothing here
+ * logs — a request carries session tokens, and a development server's console
+ * is copied into bug reports.
+ */
+/** Request bodies past this size are refused with 413. */
+export const MAX_BODY_BYTES = 1024 * 1024;
+/** A failure that becomes `{ error: { code, message } }` with `status`. */
+export class HostError extends Error {
+    status;
+    code;
+    constructor(status, code, message) {
+        super(message);
+        this.status = status;
+        this.code = code;
+    }
+}
+export function sendJson(res, status, body, headers = {}) {
+    const text = JSON.stringify(body);
+    res.writeHead(status, {
+        'content-type': 'application/json; charset=utf-8',
+        'cache-control': 'no-store',
+        'content-length': String(Buffer.byteLength(text)),
+        ...headers,
+    });
+    res.end(text);
+}
+export function sendError(res, err) {
+    sendJson(res, err.status, { error: { code: err.code, message: err.message } });
+}
+/** `302` to `location`, with any cookies to set on the way. */
+export function redirect(res, location, cookies = []) {
+    res.writeHead(302, {
+        location,
+        'cache-control': 'no-store',
+        ...(cookies.length > 0 ? { 'set-cookie': [...cookies] } : {}),
+    });
+    res.end();
+}
+/** The raw body, refused past `MAX_BODY_BYTES`. */
+export function readBody(req) {
+    const tooLarge = () => new HostError(413, 'PAYLOAD_TOO_LARGE', 'The request body is larger than 1 MiB.');
+    const declared = Number(req.headers['content-length']);
+    if (Number.isFinite(declared) && declared > MAX_BODY_BYTES) {
+        req.resume();
+        return Promise.reject(tooLarge());
+    }
+    // Listeners, not an async iterator: leaving an iterator early destroys the
+    // socket, and the refusal would never reach the client. Past the limit the
+    // rest of the body is drained and dropped while the 413 goes out.
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        let size = 0;
+        let refused = false;
+        req.on('data', (chunk) => {
+            if (refused)
+                return;
+            const buf = typeof chunk === 'string' ? Buffer.from(chunk) : chunk;
+            size += buf.length;
+            if (size > MAX_BODY_BYTES) {
+                refused = true;
+                chunks.length = 0;
+                reject(tooLarge());
+                return;
+            }
+            chunks.push(buf);
+        });
+        req.on('end', () => {
+            if (!refused)
+                resolve(Buffer.concat(chunks).toString('utf8'));
+        });
+        req.on('error', reject);
+    });
+}
+function mediaTypeOf(req) {
+    return String(req.headers['content-type'] ?? '')
+        .split(';')[0]
+        .trim()
+        .toLowerCase();
+}
+/** A JSON object body. An empty body is `{}`; anything else that is not an object is refused. */
+export async function readJsonObject(req) {
+    const text = await readBody(req);
+    if (text.trim() === '')
+        return {};
+    if (mediaTypeOf(req) !== 'application/json') {
+        throw new HostError(415, 'UNSUPPORTED_MEDIA_TYPE', 'Send the body as application/json.');
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        throw new HostError(400, 'INVALID_JSON', 'The request body is not valid JSON.');
+    }
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        throw new HostError(400, 'INVALID_BODY', 'The request body must be a JSON object.');
+    }
+    return parsed;
+}
+/** A form-encoded body (the OAuth token endpoint's only format). */
+export async function readForm(req) {
+    const text = await readBody(req);
+    if (mediaTypeOf(req) !== 'application/x-www-form-urlencoded') {
+        throw new HostError(415, 'UNSUPPORTED_MEDIA_TYPE', 'Send the body as application/x-www-form-urlencoded.');
+    }
+    return new URLSearchParams(text);
+}
+export function cookiesOf(req) {
+    const out = {};
+    for (const part of String(req.headers.cookie ?? '').split(';')) {
+        const at = part.indexOf('=');
+        if (at <= 0)
+            continue;
+        const name = part.slice(0, at).trim();
+        const value = part.slice(at + 1).trim();
+        try {
+            out[name] = decodeURIComponent(value);
+        }
+        catch {
+            out[name] = value;
+        }
+    }
+    return out;
+}
+/**
+ * The visitor's credential: `x-app-session`, else `Authorization: Bearer`.
+ * The session protocol accepts either on every session-server route.
+ */
+export function credentialOf(req) {
+    const session = req.headers['x-app-session'];
+    if (typeof session === 'string' && session.trim())
+        return session.trim();
+    const auth = req.headers.authorization;
+    if (typeof auth === 'string') {
+        const m = /^Bearer\s+(\S+)\s*$/i.exec(auth);
+        if (m)
+            return m[1];
+    }
+    return undefined;
+}
+/**
+ * Only a path on the app's own origin may be the way back — the same rule the
+ * runner applies before it builds a start address (`//host` and `/\host` are
+ * other sites to a browser).
+ */
+export function safeReturnTo(value) {
+    if (!value || !value.startsWith('/'))
+        return '/';
+    const second = value.charAt(1);
+    return second === '/' || second === '\\' ? '/' : value;
+}
+//# sourceMappingURL=http.js.map

package/dist/host/http.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"http.js","sourceRoot":"","sources":["../../src/host/http.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The few HTTP chores the local host needs, on bare `node:http`.\n *\n * Every answer is JSON (or a redirect). Bodies are read up to 1 MiB and\n * refused past it; JSON routes refuse any other content type. Nothing here\n * logs — a request carries session tokens, and a development server's console\n * is copied into bug reports.\n */\n\nimport type { IncomingMessage, ServerResponse } from 'node:http'\n\n/** Request bodies past this size are refused with 413. */\nexport const MAX_BODY_BYTES = 1024 * 1024\n\n/** A failure that becomes `{ error: { code, message } }` with `status`. */\nexport class HostError extends Error {\n  constructor(\n    readonly status: number,\n    readonly code: string,\n    message: string\n  ) {\n    super(message)\n  }\n}\n\nexport function sendJson(res: ServerResponse, status: number, body: unknown, headers: Record<string, string> = {}): void {\n  const text = JSON.stringify(body)\n  res.writeHead(status, {\n    'content-type': 'application/json; charset=utf-8',\n    'cache-control': 'no-store',\n    'content-length': String(Buffer.byteLength(text)),\n    ...headers,\n  })\n  res.end(text)\n}\n\nexport function sendError(res: ServerResponse, err: HostError): void {\n  sendJson(res, err.status, { error: { code: err.code, message: err.message } })\n}\n\n/** `302` to `location`, with any cookies to set on the way. */\nexport function redirect(res: ServerResponse, location: string, cookies: readonly string[] = []): void {\n  res.writeHead(302, {\n    location,\n    'cache-control': 'no-store',\n    ...(cookies.length > 0 ? { 'set-cookie': [...cookies] } : {}),\n  })\n  res.end()\n}\n\n/** The raw body, refused past `MAX_BODY_BYTES`. */\nexport function readBody(req: IncomingMessage): Promise<string> {\n  const tooLarge = (): HostError => new HostError(413, 'PAYLOAD_TOO_LARGE', 'The request body is larger than 1 MiB.')\n  const declared = Number(req.headers['content-length'])\n  if (Number.isFinite(declared) && declared > MAX_BODY_BYTES) {\n    req.resume()\n    return Promise.reject(tooLarge())\n  }\n  // Listeners, not an async iterator: leaving an iterator early destroys the\n  // socket, and the refusal would never reach the client. Past the limit the\n  // rest of the body is drained and dropped while the 413 goes out.\n  return new Promise((resolve, reject) => {\n    const chunks: Buffer[] = []\n    let size = 0\n    let refused = false\n    req.on('data', (chunk: Buffer | string) => {\n      if (refused) return\n      const buf = typeof chunk === 'string' ? Buffer.from(chunk) : chunk\n      size += buf.length\n      if (size > MAX_BODY_BYTES) {\n        refused = true\n        chunks.length = 0\n        reject(tooLarge())\n        return\n      }\n      chunks.push(buf)\n    })\n    req.on('end', () => {\n      if (!refused) resolve(Buffer.concat(chunks).toString('utf8'))\n    })\n    req.on('error', reject)\n  })\n}\n\nfunction mediaTypeOf(req: IncomingMessage): string {\n  return String(req.headers['content-type'] ?? '')\n    .split(';')[0]!\n    .trim()\n    .toLowerCase()\n}\n\n/** A JSON object body. An empty body is `{}`; anything else that is not an object is refused. */\nexport async function readJsonObject(req: IncomingMessage): Promise<Record<string, unknown>> {\n  const text = await readBody(req)\n  if (text.trim() === '') return {}\n  if (mediaTypeOf(req) !== 'application/json') {\n    throw new HostError(415, 'UNSUPPORTED_MEDIA_TYPE', 'Send the body as application/json.')\n  }\n  let parsed: unknown\n  try {\n    parsed = JSON.parse(text)\n  } catch {\n    throw new HostError(400, 'INVALID_JSON', 'The request body is not valid JSON.')\n  }\n  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {\n    throw new HostError(400, 'INVALID_BODY', 'The request body must be a JSON object.')\n  }\n  return parsed as Record<string, unknown>\n}\n\n/** A form-encoded body (the OAuth token endpoint's only format). */\nexport async function readForm(req: IncomingMessage): Promise<URLSearchParams> {\n  const text = await readBody(req)\n  if (mediaTypeOf(req) !== 'application/x-www-form-urlencoded') {\n    throw new HostError(415, 'UNSUPPORTED_MEDIA_TYPE', 'Send the body as application/x-www-form-urlencoded.')\n  }\n  return new URLSearchParams(text)\n}\n\nexport function cookiesOf(req: IncomingMessage): Record<string, string> {\n  const out: Record<string, string> = {}\n  for (const part of String(req.headers.cookie ?? '').split(';')) {\n    const at = part.indexOf('=')\n    if (at <= 0) continue\n    const name = part.slice(0, at).trim()\n    const value = part.slice(at + 1).trim()\n    try {\n      out[name] = decodeURIComponent(value)\n    } catch {\n      out[name] = value\n    }\n  }\n  return out\n}\n\n/**\n * The visitor's credential: `x-app-session`, else `Authorization: Bearer`.\n * The session protocol accepts either on every session-server route.\n */\nexport function credentialOf(req: IncomingMessage): string | undefined {\n  const session = req.headers['x-app-session']\n  if (typeof session === 'string' && session.trim()) return session.trim()\n  const auth = req.headers.authorization\n  if (typeof auth === 'string') {\n    const m = /^Bearer\\s+(\\S+)\\s*$/i.exec(auth)\n    if (m) return m[1]\n  }\n  return undefined\n}\n\n/**\n * Only a path on the app's own origin may be the way back — the same rule the\n * runner applies before it builds a start address (`//host` and `/\\host` are\n * other sites to a browser).\n */\nexport function safeReturnTo(value: string | null): string {\n  if (!value || !value.startsWith('/')) return '/'\n  const second = value.charAt(1)\n  return second === '/' || second === '\\\\' ? '/' : value\n}\n"]}

package/dist/host/local-host.d.ts

@@ -0,0 +1,59 @@
+/**
+ * The local host — the session protocol and the data protocol, in process,
+ * for development.
+ *
+ * NOT A PRODUCTION SERVER. Records live in memory and vanish on restart; the
+ * one development user signs in without a password; the issuer stand-in mints
+ * unsigned ID tokens; there is no rate limit, no CORS, no TLS. It exists so an
+ * app that declares data and sign-in runs on a laptop with no hosted service,
+ * and so the runner's sign-in wall, account control, gate and data paths are
+ * exercised against the same addresses and answers a session server gives.
+ *
+ * Everything is mounted under `prefix` (e.g. `/_host`); `<base>` below is
+ * `<origin><prefix>`, which is also the app's own API base the runner derives
+ * from `loginUrl` (session-protocol §2).
+ *
+ *   App door (session-protocol §4, §8)
+ *     POST <base>/login, <base>/register   any credentials → the development user
+ *     POST <base>/logout                   revokes the presented token
+ *     GET  <base>/session                  the principal behind the token
+ *     GET  <base>/_auth/start/<method>     provider sign-in, through the same redirects
+ *     GET  <base>/_auth/callback/<method>  …ends here: HttpOnly cookie, back to returnTo
+ *     GET  <base>/_auth/session            the cookie's session (needs x-pwapp-request: 1)
+ *     POST <base>/_auth/logout             deletes the cookie (needs x-pwapp-request: 1)
+ *   External issuer stand-in (session-protocol §3) — see ./oidc.ts
+ *     GET  <base>/oidc/.well-known/openid-configuration, GET <base>/oidc/authorize,
+ *     POST <base>/oidc/token
+ *   Records (data-protocol §5) — see ./records.ts
+ *     GET|POST <base>/records/<T>, GET <base>/records/<T>/count, GET <base>/records/<T>/aggregate,
+ *     GET|PATCH|DELETE <base>/records/<T>/<id>
+ *   Pages
+ *     GET  <base>/surfaces/<key>.receipt.json   the receipt, entity sources rewritten to <base>,
+ *                                               refused without a session when sign-in is required
+ *
+ * Every credential is accepted on `x-app-session` or `Authorization: Bearer`.
+ * Tokens are opaque and random, kept only as hashes, and never logged.
+ */
+import { type AuthDeclaration } from './definitions.js';
+import type { CreateLocalHost } from './types.js';
+export declare const DEFAULT_DEV_USER: {
+    readonly id: "dev-user";
+    readonly name: "Developer";
+    readonly email: "dev@localhost";
+};
+/** The cookie the provider round trip leaves on the app's origin. */
+export declare const SESSION_COOKIE = "pwf_dev_session";
+/**
+ * The envelope `auth.json` for this declaration, pointed at `base` — the
+ * same shape a publisher writes (session-protocol §2), or `undefined` when the
+ * app has no way in.
+ *
+ *  - `external`: `oauth2-pkce` against the local issuer stand-in, keeping the
+ *    declared client id, scopes (plus `offline_access`, which is what makes a
+ *    refresh token exist) and audience.
+ *  - `app`: the password door when `password` is declared; the provider
+ *    buttons and the start address for every declared provider method; the
+ *    gateway's session and logout addresses for either; `methods` as declared.
+ */
+export declare function authAddresses(auth: AuthDeclaration | undefined, base: string): Record<string, unknown> | undefined;
+export declare const createLocalHost: CreateLocalHost;