@lapxo/head 0.0.0-stage → 0.1.3

package/dist/src/ports/access/flow.js

@@ -0,0 +1,130 @@
+import { createHash, randomBytes } from 'node:crypto';
+import { jsonOf } from "../../access/contract.js";
+import { discovered } from "./authorizer.js";
+const one = (f, measure) => f?.[measure]?.[0];
+const pointed = (json, pointer) => pointer.split('/').slice(1).map((s) => s.replaceAll('~1', '/').replaceAll('~0', '~'))
+    .reduce((at, step) => at.flatMap((v) => (v === null || typeof v !== 'object' ? [] : step === '*' ? Object.values(v) : [v[step]])), [json])
+    .flatMap((v) => (typeof v === 'string' || typeof v === 'number' || typeof v === 'boolean' ? [String(v)] : []));
+const transforms = { s256: (s) => createHash('sha256').update(s).digest('base64url'), base64url: (s) => Buffer.from(s).toString('base64url'), base64: (s) => Buffer.from(s).toString('base64') };
+const empty = (v) => v === undefined || v === '' || (Array.isArray(v) && v.length === 0);
+const originOf = (url) => (URL.canParse(url) ? new URL(url).origin : '');
+/**
+ * Access as its document declares it, one way for every kind: the steps its flow names, in order — an operation of a
+ * source, an address its authorizer names, or a page the person is sent to and comes back from, opened first so every
+ * step before it knows where the person comes back — each sent what its payload says, with the token so far when it
+ * says so, keeping what its outputs point at — whatever its status, since an answer that calls for a next step may come
+ * as an error; a step whose when holds nothing is passed over, one whose answer holds nothing its outputs name stops the
+ * flow by its name, and so does one that answers an error and names nothing to keep. What the person is asked is asked the first time a step needs it, as the
+ * flow says: a form, a one-time code, a choice among what an answer listed, or a secret on head's own page as far as the
+ * place's root allows. What the person gives travels only to the source's origin or one its own document names. Only
+ * the token is kept, and it rides a request as the flow's template says.
+ */
+export const adapter = {
+    discover: discovered,
+    attach: (secret, params) => ((into, name, value) => (into === 'header' ? { headers: { [name]: value }, query: {} } : into === 'query' ? { headers: {}, query: { [name]: value } } : { headers: {}, query: {} }))(one(params, 'attach-in'), one(params, 'attach-name') ?? '', (one(params, 'attach-template') ?? '{token}').split('{token}').join(secret)),
+    obtain: async (want) => {
+        const [d, renewed] = [want.declared, ((r) => (r && typeof r === 'object' ? r : undefined))(jsonOf(want.renew ?? ''))];
+        if (renewed?.refresh && one(d[''], 'renew')) {
+            const got = await want.post(one(d[''], 'renew'), { grant_type: 'refresh_token', refresh_token: renewed.refresh, ...(renewed.client ? { client_id: renewed.client } : {}) }, 'form'), [secret, lasts, refresh] = ['/access_token', '/expires_in', '/refresh_token'].map((at) => pointed(got?.json, at)[0]);
+            if (got !== undefined && got.status < 300 && secret)
+                return { secret, ...(Number.isFinite(Number(lasts)) && lasts ? { expires: want.now + Number(lasts) * 1000 } : {}), renew: JSON.stringify({ ...renewed, refresh: refresh ?? renewed.refresh }) };
+        }
+        const [gen, inputs, outputs] = [{ state: randomBytes(24).toString('base64url'), verifier: randomBytes(32).toString('base64url') }, new Map(), new Map()];
+        let [callback, secrets, refused] = ['', 0, undefined];
+        const stop = (why) => { refused ??= why; return undefined; };
+        const ask = async (name) => {
+            const [f, label] = [d[`inputs/${name}`], one(d[`inputs/${name}`], 'label') ?? name];
+            const how = one(f, 'ask');
+            const got = how === 'secret' ? (++secrets > want.secrets ? stop({ refused: 'secret-unallowed', input: name }) : (await want.enter(`${want.source} in ${want.place} · ${label}`, [{ name, label, secret: true }]))?.[name])
+                : how === 'choice' ? await (async () => {
+                    const [values, labels] = [[(await resolve(one(f, 'from') ?? '')) ?? []].flat(), [(await resolve(one(f, 'label') ?? '')) ?? []].flat()];
+                    return (await want.choose(`Choose ${name} for ${want.source} in ${want.place}`, [{ name, options: values.map((value, i) => ({ value, label: labels[i] ?? value })) }]))?.[name];
+                })()
+                    : how === 'form' || how === 'one-time' ? (await want.choose(how === 'form' ? `${want.source} in ${want.place} asks for ${label}` : `${want.source} in ${want.place} sent you a one-time code: enter it within ${one(f, 'ttl') ?? '?'} seconds`, [{ name, label }]))?.[name]
+                        : stop({ refused: 'carry-unsettled', input: name });
+            if (got !== undefined)
+                inputs.set(name, got);
+            return got ?? stop({ refused: 'entry-unfinished', input: name });
+        };
+        const resolve = async (expr, response) => {
+            const [fn, head] = [/^(\w+)\((.*)\)$/.exec(expr), expr.split(/[.#(]/)[0]];
+            if (fn !== null)
+                return want.values.includes(fn[1]) && transforms[fn[1]] ? transforms[fn[1]](String(await resolve(fn[2], response) ?? '')) : stop({ refused: 'carry-unsettled', input: fn[1] });
+            if (/\{[^}]+\}/.test(expr)) {
+                let out = expr;
+                for (const [m, ref] of expr.matchAll(/\{([^}]+)\}/g))
+                    out = out.replace(m, String((await resolve(ref, response)) ?? ''));
+                return out;
+            }
+            if (/^'.*'$/.test(expr))
+                return expr.slice(1, -1);
+            if (!expr.startsWith('$'))
+                return expr;
+            if (!want.values.includes(head))
+                return stop({ refused: 'carry-unsettled', input: head });
+            const [, a = '', , b = ''] = expr.split('.');
+            return head === '$callback' ? callback : head === '$state' ? gen.state : head === '$verifier' ? gen.verifier : head === '$scopes' ? want.scopes.join(' ')
+                : head === '$client' ? one(d[''], 'client') ?? stop({ refused: 'no-client' }) : head === '$host' ? want.host[a] ?? stop({ refused: 'host-input', input: a }) : head === '$inputs' ? inputs.get(a) ?? (await ask(a)) : head === '$steps' ? outputs.get(a)?.get(b)
+                    : ((all) => (expr.includes('*') ? all : all[0]))(pointed(response, expr.slice(expr.indexOf('#') + 1)));
+        };
+        const gather = async (k, kind, response) => {
+            const held = {};
+            for (const key of Object.keys(d).filter((one_) => one_.startsWith(`${k}/${kind}/`)))
+                held[key.slice(k.length + kind.length + 2)] = d[key]['items'] ? (await Promise.all(d[key]['items'].map((e) => resolve(e, response)))).flatMap((v) => (v === undefined ? [] : [v].flat())) : await resolve(one(d[key], 'value') ?? '', response);
+            return held;
+        };
+        const kept = async (k, response, status = 200) => {
+            const held = await gather(k, 'outputs', response);
+            if (Object.values(held).every(empty) && (status >= 400 || Object.keys(held).length))
+                return Boolean(stop({ refused: 'step-unanswered', input: one(d[k], 'id') ?? k }));
+            outputs.set(one(d[k], 'id') ?? k, new Map(Object.entries(held)));
+            return true;
+        };
+        const guarded = (k) => ((at) => !(at !== undefined && d[k]['overlay'] && originOf(at) !== originOf(want.origin)
+            && Object.keys(d).some((key) => key.startsWith(`${k}/payload/`) && (d[key]['value'] ?? d[key]['items'] ?? []).some((e) => e.includes('$inputs.')))) || Boolean(stop({ refused: 'cross-origin' })))(one(d[k], 'url') ?? one(d[k], 'page'));
+        const run = async (k) => {
+            const f = d[k];
+            if (one(f, 'when') !== undefined && empty(await resolve(one(f, 'when'))))
+                return true;
+            if (!guarded(k))
+                return false;
+            const [sent, token] = [await gather(k, 'payload'), one(f, 'token') === undefined ? undefined : await resolve(one(f, 'token'))];
+            if (refused)
+                return false;
+            const answered = one(f, 'operation') !== undefined ? await want.call(one(f, 'source') ?? want.source, one(f, 'operation'), sent, typeof token === 'string' ? adapter.attach(token, d[''] ?? {}) : undefined)
+                : await want.post(one(f, 'url'), sent, one(f, 'encoding') === 'json' ? 'json' : 'form');
+            return refused ? false : answered === undefined ? Boolean(stop({ refused: 'login-refused' })) : kept(k, answered.json, answered.status);
+        };
+        const steps = Object.keys(d).filter((key) => /^steps\/\d+$/.test(key)).sort((a, b) => Number(a.slice(6)) - Number(b.slice(6)));
+        const page = steps.findIndex((k) => one(d[k], 'page') !== undefined);
+        if (page >= 0) {
+            const back = await want.visit(`Sign in to ${want.source} at its provider`, async (address) => {
+                callback = address;
+                for (const k of steps.slice(0, page))
+                    if (!(await run(k)))
+                        return undefined;
+                if (!guarded(steps[page]))
+                    return undefined;
+                const to = new URL(one(d[steps[page]], 'page'));
+                for (const [name, v] of Object.entries(await gather(steps[page], 'payload')))
+                    if (!empty(v))
+                        to.searchParams.set(name, String(v));
+                return refused ? undefined : to.href;
+            });
+            if (!refused && (back === undefined || (back['state'] !== undefined && back['state'] !== gen.state)))
+                stop({ refused: 'login-refused' });
+            if (!refused)
+                await kept(steps[page], back);
+        }
+        for (const k of page >= 0 ? steps.slice(page + 1) : steps)
+            if (refused || !(await run(k)))
+                break;
+        const [token, expires, refresh] = await Promise.all(['token', 'expires', 'refresh'].map(async (k) => (await Promise.all((d['']?.[k] ?? []).map((e) => resolve(e)))).find((v) => !empty(v))));
+        if (refused)
+            return refused;
+        if (typeof token !== 'string' || !token)
+            return { refused: 'login-refused' };
+        return { secret: token, ...(typeof expires === 'string' && Number.isFinite(Number(expires)) ? { expires: want.now + Number(expires) * 1000 } : {}), ...(steps.length ? {} : { manual: true }),
+            ...(typeof refresh === 'string' && refresh ? { renew: JSON.stringify({ refresh, client: outputs.get('register')?.get('client') ?? one(d[''], 'client') }) } : {}) };
+    },
+};

package/dist/src/ports/access/page.d.ts

@@ -0,0 +1,12 @@
+import type { Field, Held } from '../../access/contract.ts';
+/**
+ * One page on this device, for one person, once: served on a loopback port under a path no one can guess, it takes the
+ * fields it was opened with — a secret one as a password, never echoed, a choice among its options — or, as a return
+ * address, what a visit sends back.
+ * It answers the first submission and closes; a wait that runs out closes it with nothing.
+ */
+export declare const open: (title: string, fields: readonly Field[] | "return", wait: number) => Promise<{
+    readonly url: string;
+    readonly held: Promise<Held | undefined>;
+    readonly close: () => void;
+}>;

package/dist/src/ports/access/page.js

@@ -0,0 +1,50 @@
+import { randomBytes } from 'node:crypto';
+import { createServer } from 'node:http';
+const escape = (text) => text.replace(/[&<>"']/g, (c) => `&#${c.charCodeAt(0)};`);
+const box = 'style="width:100%;font:inherit;padding:.4rem"', press = 'style="font:inherit;padding:.4rem 1rem;margin-right:.5rem"';
+/** One field as the page asks it: a secret as a password, a choice as a list of its options — or, when it is the page's only question, as one button an option — anything else as text. */
+const asked = (f, alone) => (f.options && alone ? `<p>${escape(f.label)}</p>${f.options.map((o) => `<button name="${escape(f.name)}" value="${escape(o.value)}" ${press}>${escape(o.label)}</button>`).join('')}`
+    : `<label style="display:block;margin:1rem 0">${escape(f.label)}<br>${f.options ? `<select name="${escape(f.name)}" required ${box}>${f.options.map((o) => `<option value="${escape(o.value)}">${escape(o.label)}</option>`).join('')}</select>`
+        : `<input name="${escape(f.name)}" type="${f.secret ? 'password' : 'text'}" autocomplete="off" required ${box}>`}</label>`);
+const form = (title, fields) => `<!doctype html><meta charset="utf-8"><meta name="viewport" content="width=device-width"><title>${escape(title)}</title>
+<body style="font:16px system-ui;max-width:28rem;margin:3rem auto;padding:0 1rem"><h1 style="font-size:1.2rem">${escape(title)}</h1><form method="post">${fields.map((f) => asked(f, fields.length === 1)).join('')}
+${fields.length === 1 && fields[0].options ? '' : `<button ${press}>Send</button>`}</form></body>`;
+const done = `<!doctype html><meta charset="utf-8"><title>done</title><body style="font:16px system-ui;margin:3rem">Received. You can close this page.</body>`;
+/**
+ * One page on this device, for one person, once: served on a loopback port under a path no one can guess, it takes the
+ * fields it was opened with — a secret one as a password, never echoed, a choice among its options — or, as a return
+ * address, what a visit sends back.
+ * It answers the first submission and closes; a wait that runs out closes it with nothing.
+ */
+export const open = async (title, fields, wait) => {
+    const nonce = randomBytes(24).toString('base64url');
+    let settle = () => undefined;
+    const held = new Promise((resolve) => { settle = resolve; });
+    const server = createServer((request, response) => {
+        const url = new URL(request.url ?? '/', 'http://127.0.0.1');
+        if (url.pathname !== `/${nonce}`) {
+            response.writeHead(404).end();
+            return;
+        }
+        if (fields === 'return' && request.method === 'GET') {
+            response.writeHead(200, { 'content-type': 'text/html' }).end(done);
+            finish(Object.fromEntries(url.searchParams));
+            return;
+        }
+        if (fields !== 'return' && request.method === 'GET') {
+            response.writeHead(200, { 'content-type': 'text/html', 'cache-control': 'no-store' }).end(form(title, fields));
+            return;
+        }
+        let body = '';
+        request.on('data', (chunk) => { body += chunk.toString('utf8'); if (body.length > 65536)
+            request.destroy(); });
+        request.on('end', () => { response.writeHead(200, { 'content-type': 'text/html' }).end(done); finish(Object.fromEntries(new URLSearchParams(body))); });
+    });
+    let closed = false;
+    const finish = (got) => { if (closed)
+        return; closed = true; server.close(); settle(got); };
+    const signal = AbortSignal.timeout(wait);
+    signal.addEventListener('abort', () => finish(undefined), { once: true });
+    await new Promise((resolve) => server.listen(0, '127.0.0.1', resolve));
+    return { url: `http://127.0.0.1:${server.address().port}/${nonce}`, held, close: () => finish(undefined) };
+};

package/dist/src/ports/access/person.d.ts

@@ -0,0 +1,26 @@
+import type { Choice, Field, Held } from '../../access/contract.ts';
+import type { Said } from '../../core/lock.ts';
+/** What the client lets head ask of the person: whether it sends addresses and asks forms, and the asking itself. */
+export interface Client {
+    readonly can: () => {
+        readonly url: boolean;
+        readonly form: boolean;
+    };
+    readonly elicit: (params: Readonly<Record<string, unknown>>) => Promise<{
+        readonly action: string;
+        readonly content?: Readonly<Record<string, unknown>>;
+    }>;
+}
+/**
+ * The person at this device, asked through the richest channel the client declares, in the order head's lock lines name:
+ * the client's own form; head's one-time page, sent by the client as an address; the same page opened by this device's
+ * browser. A secret goes only through the page — never a form the model could see — and a yes is the person's answer on
+ * any of them, never the model's: where none reaches the person, nothing was asked and the lines are theirs to sign.
+ * A visit to a provider comes back to such a page.
+ */
+export declare const personOf: (lock: readonly Said[], client: Client) => {
+    consent: (message: string, word: string) => Promise<"yes" | "no" | "none">;
+    enter: (title: string, fields: readonly Field[]) => Promise<Held | undefined>;
+    choose: (message: string, choices: readonly Choice[]) => Promise<Held | undefined>;
+    visit: (message: string, to: (back: string) => string | undefined | Promise<string | undefined>) => Promise<Held | undefined>;
+};

package/dist/src/ports/access/person.js

@@ -0,0 +1,41 @@
+import { execFile } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
+import { aboutOf, members, valueOf } from "../../core/lock.js";
+import { fill } from "../../core/surface.js";
+import { open } from "./page.js";
+/**
+ * The person at this device, asked through the richest channel the client declares, in the order head's lock lines name:
+ * the client's own form; head's one-time page, sent by the client as an address; the same page opened by this device's
+ * browser. A secret goes only through the page — never a form the model could see — and a yes is the person's answer on
+ * any of them, never the model's: where none reaches the person, nothing was asked and the lines are theirs to sign.
+ * A visit to a provider comes back to such a page.
+ */
+export const personOf = (lock, client) => {
+    const wait = Number(valueOf(lock, 'access/wait').split('..')[1]);
+    const channel = (rule) => ((can) => members(valueOf(lock, rule)).find((c) => (c === 'device' ? true : can[c])))(client.can());
+    const offer = async (message, url, how) => (how === 'url' ? (await client.elicit({ mode: 'url', message, url, elicitationId: randomUUID() })).action === 'accept'
+        : how === 'device' ? new Promise((resolve) => ((opener) => execFile(opener[0] ?? '', [...opener.slice(1), url], (error) => resolve(error === null)))(members(valueOf(lock, `platform/${process.platform}/browser`)))) : false);
+    const offered = async (message, page, how, url = page.url) => ((await offer(message, url, how)) ? page.held : (page.close(), undefined));
+    const paged = async (title, fields, how) => offered(fill(aboutOf(lock, fields.some((f) => f.secret) ? 'said/enter' : 'said/answer'), { title }), await open(title, fields, wait), how);
+    const form = async (message, properties) => ((got) => (got.action === 'accept' ? Object.fromEntries(Object.entries(got.content ?? {}).map(([k, v]) => [k, String(v)])) : undefined))(await client.elicit({ message, requestedSchema: { type: 'object', properties, required: Object.keys(properties) } }));
+    return {
+        consent: async (message, word) => {
+            const how = channel('ask/consent-channels'), said = (got) => (got?.['yes'] === 'true' ? 'yes' : 'no');
+            if (how === undefined)
+                return 'none';
+            if (how === 'form')
+                return said(await form(message, { yes: { type: 'boolean', title: word } }));
+            const page = await open(message, [{ name: 'yes', label: word, secret: false, options: [{ value: 'true', label: word }, { value: 'false', label: 'No' }] }], wait);
+            return (await offer(fill(aboutOf(lock, 'said/answer'), { title: message }), page.url, how)) ? said(await page.held) : (page.close(), 'none');
+        },
+        enter: async (title, fields) => paged(title, fields, channel('ask/secret-channels')),
+        choose: async (message, choices) => ((how) => (how === 'form'
+            ? form(message, Object.fromEntries(choices.map((c) => [c.name, { type: 'string', title: c.label ?? c.name, ...(c.options ? { oneOf: c.options.map((o) => ({ const: o.value, title: o.label })) } : {}) }])))
+            : how === undefined ? Promise.resolve(undefined) : paged(message, choices.map((c) => ({ name: c.name, label: c.label ?? c.name, secret: false, ...(c.options ? { options: c.options } : {}) })), how)))(channel('ask/channels')),
+        visit: async (message, to) => {
+            const page = await open(message, 'return', wait);
+            const url = await to(page.url);
+            return url === undefined ? (page.close(), undefined) : offered(fill(aboutOf(lock, 'said/visit'), { message }), page, channel('ask/secret-channels'), url);
+        },
+    };
+};

package/dist/src/ports/adapters/request.d.ts

@@ -0,0 +1,41 @@
+import type { Said } from '../../core/lock.ts';
+import type { Call } from '../../core/read.ts';
+import type { Attachment } from '../../access/contract.ts';
+export type Fetched = {
+    readonly kind: 'got';
+    readonly status: number;
+    readonly bytes: Uint8Array;
+    readonly type: string;
+    readonly location?: string;
+    readonly authenticate?: string;
+} | {
+    readonly kind: 'over';
+} | {
+    readonly kind: 'failed';
+};
+export type Prepared = {
+    readonly key: string;
+    readonly describe: string;
+    readonly send: (attachment: Attachment | undefined, most: number) => Promise<Fetched>;
+} | {
+    readonly missing: string;
+} | {
+    readonly refused: string;
+};
+export declare const published: (url: string, digest: string, most: number, wait: number) => Promise<Uint8Array | undefined>;
+export declare const fetched: (url: string, attachment: Attachment | undefined, accept: string | undefined, most: number, wait: number) => Promise<Fetched>;
+export declare const get: (url: string, wait: number) => Promise<{
+    readonly bytes: Uint8Array;
+    readonly type: string;
+} | undefined>;
+/** A body posted to an address a declaration names — as a form, or as JSON where the declaration's protocol asks it — as one request under the same rules: encrypted unless it is this device, capped, never redirected. */
+export declare const post: (url: string, body: Readonly<Record<string, unknown>>, most: number, wait: number, as?: "form" | "json") => Promise<{
+    readonly status: number;
+    readonly json: unknown;
+} | undefined>;
+/**
+ * The request an offer's carry describes: its method and path, the path and query parameters its form names filled from
+ * what was asked, its body, and the headers and query members an access adapter attaches — only when it is sent, never
+ * in the request's key or its description. Plain transport reaches loopback only; anything else must be encrypted.
+ */
+export declare const prepare: (call: Call, args: Readonly<Record<string, unknown>>, lock: readonly Said[]) => Prepared;

package/dist/src/ports/adapters/request.js

@@ -0,0 +1,69 @@
+import { createHash } from 'node:crypto';
+import { valueOf } from "../../core/lock.js";
+import { jsonOf } from "../../access/contract.js";
+/**
+ * One request, stopped as soon as the body runs past the bytes it may hold or the wait runs out, its stream released
+ * either way; nothing is retried. No redirect is followed, but to bytes a digest pins: asked with no header and no body,
+ * so a secret stays with its origin, and answered only when they hash to the pin, their integrity and never the address.
+ */
+const requestCapped = async (method, url, headers, body, most, wait, redirect = 'manual') => {
+    try {
+        const response = await fetch(url, { method, headers, body, redirect: redirect === 'follow' && !Object.keys(headers).length && body === undefined ? 'follow' : 'manual', signal: AbortSignal.timeout(wait) });
+        const chunks = [];
+        let size = 0;
+        for await (const chunk of response.body ?? []) {
+            size += chunk.byteLength;
+            if (size > most)
+                break;
+            chunks.push(chunk);
+        }
+        return size > most ? { kind: 'over' } : { kind: 'got', status: response.status, bytes: Buffer.concat(chunks), type: response.headers.get('content-type') ?? '', ...((at) => (at ? { location: at } : {}))(response.headers.get('location')), ...((asks) => (asks ? { authenticate: asks } : {}))(response.headers.get('www-authenticate')) };
+    }
+    catch {
+        return { kind: 'failed' };
+    }
+};
+const loopback = new Set(['127.0.0.1', 'localhost', '[::1]']);
+export const published = async (url, digest, most, wait) => (URL.canParse(url) && ((at) => at.protocol === 'https:' || loopback.has(at.hostname))(new URL(url))
+    ? ((got) => (got.kind === 'got' && got.status < 300 && `sha256:${createHash('sha256').update(got.bytes).digest('hex')}` === digest ? got.bytes : undefined))(await requestCapped('GET', url, {}, undefined, most, wait, 'follow')) : undefined);
+export const fetched = async (url, attachment, accept, most, wait) => (!URL.canParse(url) || !((at) => at.protocol === 'https:' || loopback.has(at.hostname))(new URL(url)) ? { kind: 'failed' }
+    : requestCapped('GET', ((extra) => (extra.size ? `${url}${url.includes('?') ? '&' : '?'}${extra}` : url))(new URLSearchParams(Object.entries(attachment?.query ?? {}))), { ...(attachment?.headers ?? {}), ...(accept ? { accept } : {}) }, undefined, most, wait));
+export const get = async (url, wait) => (URL.canParse(url) && ((at) => at.protocol === 'https:' || loopback.has(at.hostname))(new URL(url)) ? ((got) => (got.kind === 'got' && got.status < 300 ? got : undefined))(await requestCapped('GET', url, {}, undefined, 16_777_216, wait)) : undefined);
+/** A body posted to an address a declaration names — as a form, or as JSON where the declaration's protocol asks it — as one request under the same rules: encrypted unless it is this device, capped, never redirected. */
+export const post = async (url, body, most, wait, as = 'form') => {
+    if (!URL.canParse(url) || !((at) => at.protocol === 'https:' || loopback.has(at.hostname))(new URL(url)))
+        return undefined;
+    const got = await requestCapped('POST', url, { 'content-type': as === 'json' ? 'application/json' : 'application/x-www-form-urlencoded', accept: 'application/json' }, as === 'json' ? JSON.stringify(body) : new URLSearchParams(Object.entries(body).map(([k, v]) => [k, String(v)])).toString(), most, wait);
+    return got.kind === 'got' ? { status: got.status, json: jsonOf(got.bytes) } : undefined;
+};
+/**
+ * The request an offer's carry describes: its method and path, the path and query parameters its form names filled from
+ * what was asked, its body, and the headers and query members an access adapter attaches — only when it is sent, never
+ * in the request's key or its description. Plain transport reaches loopback only; anything else must be encrypted.
+ */
+export const prepare = (call, args, lock) => {
+    const word = (key) => valueOf(lock, `adapter/request/${key}`);
+    const [method, ...more] = call.carry['method'] ?? [];
+    const [template, ...paths] = call.carry['path'] ?? [];
+    if (method === undefined || template === undefined || more.length || paths.length)
+        return { refused: 'carry-unsettled' };
+    const origin = ((at) => (at !== undefined && (at.protocol === 'https:' || loopback.has(at.hostname)) ? at : undefined))(URL.canParse(call.origin) ? new URL(call.origin) : undefined);
+    if (origin === undefined)
+        return { refused: 'insecure-origin' };
+    const named = (where) => (call.form['params'] ?? []).filter((p) => p.startsWith(`${where}:`)).map((p) => p.slice(where.length + 1));
+    const missing = named('path').find((p) => args[p] === undefined);
+    if (missing !== undefined)
+        return { missing };
+    const path = named('path').reduce((at, p) => at.split(`{${p}}`).join(encodeURIComponent(String(args[p]))), template);
+    const query = new URLSearchParams(named('query').flatMap((p) => (args[p] === undefined ? [] : [[p, String(args[p])]])));
+    const url = `${origin.href.replace(/\/$/, '')}${path}${query.size ? `?${query}` : ''}`;
+    const body = args['body'] === undefined ? undefined : JSON.stringify(args['body']);
+    const key = createHash('sha256').update(`${method.toUpperCase()} ${url} ${body ?? 'null'}`).digest('hex');
+    const idempotency = call.carry['idempotency']?.[0];
+    const send = (attachment, most) => {
+        const extra = new URLSearchParams(Object.entries(attachment?.query ?? {}));
+        const sent = extra.size ? `${url}${query.size ? '&' : '?'}${extra}` : url;
+        return requestCapped(method.toUpperCase(), sent, { ...(attachment?.headers ?? {}), ...(idempotency ? { [idempotency]: key } : {}), ...(body === undefined ? {} : { [word('content-type')]: word('json') }) }, body, most, Number(word('wait').split('..')[1]));
+    };
+    return { key, describe: `${method.toUpperCase()} ${url}`, send };
+};

package/dist/src/ports/bound.d.ts

@@ -0,0 +1,61 @@
+import type { Said } from '../core/lock.ts';
+import type { Outcome } from '../core/answer.ts';
+import { cooled } from './warm.ts';
+import type { Printed } from './process.ts';
+export type { Printed };
+export declare const limits: {
+    wait: number;
+    most: number;
+};
+/** bound run as a process in a folder, beside head and never blocking it, within the wait and the bytes head's lock gives it and stopped when the asker cancels: one started ahead when head holds one, else one started now. */
+export declare const run: (name: string, cwd: string, args: readonly string[], env?: Readonly<Record<string, string>>, signal?: AbortSignal) => Promise<Printed | undefined>;
+/** bound started ahead of the first ask of a call, as many times as head's lock keeps it started; resolved once each is ready. */
+export declare const warm: (name: string) => Promise<unknown>;
+export { cooled };
+export type Folded = {
+    readonly lines: readonly Said[];
+} | {
+    readonly refused: string;
+};
+/**
+ * The lines a place stands on, from bound's public views alone: its folded normative standing (the lines view) — its
+ * policy, all that a reader of its pins, keys and views needs, read alone where nothing else is — and from
+ * its authenticated evidence what this device's own keys signed. Receipts are history, each kept as it was made; any other
+ * line of a device key, the person's own attestation, stands only while it is the one line of its scope and measure,
+ * unwithdrawn and beside no line of the place's own: anything else needs a fold bound does not publish, and is refused by
+ * name. A place whose land prints no act result is refused before anything lands in it. Any refusal of bound is no standing.
+ */
+export declare const policyAt: (name: string, place: string, signal?: AbortSignal) => Promise<Folded>;
+export declare const standingAt: (name: string, place: string, devicesOf: (lines: readonly Said[]) => readonly string[], isHistory: (line: Said) => boolean, signal?: AbortSignal) => Promise<Folded>;
+export declare const sign: (name: string, place: string, lot: readonly string[], key: string, signer: string, env: Readonly<Record<string, string>>, signal?: AbortSignal) => Promise<Outcome>;
+/** A lot signed and landed in one process, its result read from what bound printed of the committed act: the records it admitted, never the receipt beside them; a place that declares no act result is refused by name. */
+/** A place's receipts rendered beside its lock, so bound alone checks the place: nothing when they closed, else why they did not. */
+export declare const closing: (name: string, place: string, signal?: AbortSignal) => Promise<string | undefined>;
+export declare const landAct: (name: string, place: string, lot: readonly string[], key: string, signer: string, env: Readonly<Record<string, string>>, signal?: AbortSignal) => Promise<Outcome>;
+export declare const land: (name: string, place: string, signed: readonly string[], signal?: AbortSignal) => Promise<Outcome>;
+export declare const told: (name: string, place: string, signed: readonly string[], view: string, signal?: AbortSignal) => Promise<readonly string[]>;
+export declare const pinnedAt: (name: string, place: string, file: string, signal?: AbortSignal) => Promise<{
+    readonly pin: string;
+    readonly bytes: string;
+    readonly lines: readonly Said[];
+} | {
+    readonly refused: string;
+} | undefined>;
+export declare const founded: (name: string, place: string, key: string, signer: string, env: Readonly<Record<string, string>>, signal?: AbortSignal) => Promise<Outcome>;
+export declare const words: {
+    read: string;
+    view: string;
+    sign: string;
+    land: string;
+    key: string;
+    signer: string;
+    pin: string;
+    topos: string;
+    standing: string;
+    evidence: string;
+    act: string;
+    profile: string;
+    receipts: string;
+    refusal: string;
+};
+export declare const settledView: (name: string, place: string, view: string, signal?: AbortSignal) => Promise<Folded>;

package/dist/src/ports/bound.js

@@ -0,0 +1,85 @@
+import { mkdtempSync, readFileSync, writeFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { parse } from '@lapxo/topos/wire';
+import { spawned } from "./process.js";
+import { cooled, kept, warmed } from "./warm.js";
+const binOf = (name) => {
+    try {
+        const manifest = createRequire(import.meta.url).resolve(join(name, 'package.json'));
+        const entry = Object.values(JSON.parse(readFileSync(manifest, 'utf8')).bin ?? {})[0];
+        return entry === undefined ? undefined : join(dirname(manifest), entry);
+    }
+    catch {
+        return undefined;
+    }
+};
+export const limits = { wait: 0, most: 0 };
+/** bound run as a process in a folder, beside head and never blocking it, within the wait and the bytes head's lock gives it and stopped when the asker cancels: one started ahead when head holds one, else one started now. */
+export const run = async (name, cwd, args, env = {}, signal) => ((bin, at, bounds) => (bin === undefined ? undefined
+    : (warmed(bin, args, at, bounds) ?? spawned(process.execPath, [bin, ...args], at, bounds)).then(apart)))(binOf(name), { cwd, env: { ...process.env, ...env } }, { wait: limits.wait, most: limits.most || Number.MAX_SAFE_INTEGER, ...(signal ? { signal } : {}) });
+/** The record bound prints after a refusal's diagnostic, read apart from it: what bound printed is kept whole, the record beside it, and why bound refused is the diagnostic's last line, never the record. */
+const recordOf = (line) => { try {
+    return ((got) => (got?.profile === words.refusal ? got : undefined))(JSON.parse(line));
+}
+catch {
+    return undefined;
+} };
+const isRecord = (line) => line.startsWith('{') && recordOf(line) !== undefined;
+const apart = (printed) => ((record) => (record === undefined ? printed : { ...printed, refusal: recordOf(record) }))([...printed.err].reverse().find(isRecord));
+const why = (printed) => printed?.err.filter((line) => !isRecord(line)).at(-1);
+/** bound started ahead of the first ask of a call, as many times as head's lock keeps it started; resolved once each is ready. */
+export const warm = (name) => ((bin) => (bin === undefined ? Promise.resolve() : kept(bin)))(binOf(name));
+export { cooled };
+const facts = (out) => out.flatMap((line) => ((got) => (got.kind === 'fact' ? [got.value.fields] : []))(parse(line)));
+const readOf = (printed) => (printed === undefined || printed.code !== 0 ? { refused: why(printed) ?? '' } : { lines: facts(printed.out) });
+/**
+ * The lines a place stands on, from bound's public views alone: its folded normative standing (the lines view) — its
+ * policy, all that a reader of its pins, keys and views needs, read alone where nothing else is — and from
+ * its authenticated evidence what this device's own keys signed. Receipts are history, each kept as it was made; any other
+ * line of a device key, the person's own attestation, stands only while it is the one line of its scope and measure,
+ * unwithdrawn and beside no line of the place's own: anything else needs a fold bound does not publish, and is refused by
+ * name. A place whose land prints no act result is refused before anything lands in it. Any refusal of bound is no standing.
+ */
+export const policyAt = async (name, place, signal) => ((folded) => ('refused' in folded || folded.lines.some((line) => line.scope === words.profile) ? folded
+    : { refused: `REFUSE·act the place declares no ${words.profile}: land would print nothing of what it admits, so head lands nothing there; its root can land the local-act@1 profile and view/act` }))(readOf(await run(name, place, [words.read, words.view, words.standing], {}, signal)));
+export const standingAt = async (name, place, devicesOf, isHistory, signal) => {
+    const folded = await policyAt(name, place, signal);
+    if ('refused' in folded)
+        return folded;
+    const evidence = readOf(await run(name, place, [words.read, words.view, words.evidence], {}, signal));
+    if ('refused' in evidence)
+        return evidence;
+    const ids = new Set(devicesOf(folded.lines)), own = evidence.lines.filter((line) => ids.has(line.by ?? ''));
+    const key = (line) => `${line.scope} ${line.measure}`, attested = own.filter((line) => !isHistory(line));
+    const unfolded = attested.find((line) => line.value === 'withdraw' || attested.filter((other) => key(other) === key(line)).length > 1 || folded.lines.some((other) => key(other) === key(line)));
+    return unfolded === undefined ? { lines: [...folded.lines, ...own] }
+        : { refused: `REFUSE·standing ${unfolded.by} attests ${key(unfolded)} more than once, withdrawn, or beside the place's own line: folding a device key's lines is bound's, and bound publishes no view of it` };
+};
+const lotFile = (lines) => ((at) => { writeFileSync(at, `${lines.join('\n')}\n`); return at; })(join(mkdtempSync(join(tmpdir(), 'head-lot-')), 'lot.bound'));
+export const sign = async (name, place, lot, key, signer, env, signal) => ((got) => (got !== undefined && got.code === 0 ? { lines: got.out.filter((line) => parse(line).kind === 'fact') } : { refused: why(got) ?? '' }))(await run(name, place, [words.sign, lotFile(lot), words.key, key, words.signer, signer], env, signal));
+/** A lot signed and landed in one process, its result read from what bound printed of the committed act: the records it admitted, never the receipt beside them; a place that declares no act result is refused by name. */
+/** A place's receipts rendered beside its lock, so bound alone checks the place: nothing when they closed, else why they did not. */
+export const closing = async (name, place, signal) => ((got) => (got !== undefined && got.code === 0 ? undefined : why(got) ?? 'nothing printed'))(await run(name, place, [words.read, words.view, words.receipts], {}, signal));
+export const landAct = async (name, place, lot, key, signer, env, signal) => ((got) => {
+    if (got === undefined || got.code !== 0)
+        return { refused: why(got) ?? '' };
+    const at = got.out.findIndex((line) => line.startsWith(words.act));
+    return at < 0 ? { refused: `REFUSE·act bound printed no act result, and the place declares ${words.profile}: what was admitted is bound's to say` }
+        : { lines: got.out.slice(at + 1).filter((line) => parse(line).kind === 'fact').slice(0, -1) };
+})(await run(name, place, [words.land, lotFile(lot), words.key, key, words.signer, signer], env, signal));
+export const land = async (name, place, signed, signal) => ((got) => (got !== undefined && got.code === 0 ? { lines: signed } : { refused: why(got) ?? '' }))(await run(name, place, [words.land, lotFile(signed)], {}, signal));
+export const told = async (name, place, signed, view, signal) => ((got) => [...(got?.out ?? []), ...(got?.err ?? [])])(await run(name, place, [words.read, words.view, view, lotFile(signed)], {}, signal));
+export const pinnedAt = async (name, place, file, signal) => {
+    const printed = await run(name, place, [words.read, file], {}, signal);
+    const read = readOf(printed);
+    if ('refused' in read)
+        return read;
+    const pin = printed.out.find((line) => line.startsWith(words.pin))?.slice(words.pin.length);
+    const bytes = printed.out.filter((line) => line.startsWith(words.topos)).map((line) => `${line.slice(words.topos.length)}\n`).join('');
+    return pin === undefined || !bytes ? undefined : { pin, bytes, lines: read.lines };
+};
+export const founded = async (name, place, key, signer, env, signal) => ((got) => (got !== undefined && got.code === 0 ? { lines: got.out } : { refused: why(got) ?? '' }))(await run(name, place, [words.land, words.key, key, words.signer, signer], env, signal));
+export const words = { read: '', view: '', sign: '', land: '', key: '', signer: '', pin: '', topos: '', standing: '', evidence: '', act: '', profile: '', receipts: '', refusal: '' };
+export const settledView = async (name, place, view, signal) => readOf(await run(name, place, [words.read, words.view, view], {}, signal));

package/dist/src/ports/cache.d.ts

@@ -0,0 +1,4 @@
+export declare const digestOf: (bytes: Uint8Array) => string;
+/** A read-s body kept by its digest, readable only by its owner; what is read back must hash to the name it is kept under. */
+export declare const keep: (bytes: Uint8Array) => string;
+export declare const held: (digest: string) => Uint8Array | undefined;

package/dist/src/ports/cache.js

@@ -0,0 +1,14 @@
+import { createHash } from 'node:crypto';
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+const folder = () => { const at = join(tmpdir(), 'head-reads'); mkdirSync(at, { recursive: true, mode: 0o700 }); return at; };
+export const digestOf = (bytes) => `sha256:${createHash('sha256').update(bytes).digest('hex')}`;
+/** A read-s body kept by its digest, readable only by its owner; what is read back must hash to the name it is kept under. */
+export const keep = (bytes) => ((digest) => { writeFileSync(join(folder(), digest.slice(7)), bytes, { mode: 0o600 }); return digest; })(digestOf(bytes));
+export const held = (digest) => { try {
+    return ((bytes) => (digestOf(bytes) === digest ? bytes : undefined))(readFileSync(join(folder(), digest.slice(7))));
+}
+catch {
+    return undefined;
+} };

package/dist/src/ports/documents.d.ts

@@ -0,0 +1,34 @@
+import type { Attachment } from '../access/contract.ts';
+import type { Context } from '../core/answer.ts';
+import type { Said } from '../core/lock.ts';
+import type { Call } from '../core/read.ts';
+export type Read = {
+    readonly bytes: Uint8Array;
+    readonly kind: string;
+};
+export declare const kindOf: (at: string, type?: string) => string;
+/**
+ * A document the person names: a file inside the place or a folder the client shares, or an encrypted address read with
+ * nothing attached — signed or expiring as it may be — and, when its digest is named, followed wherever it moves to the
+ * bytes that digest names, and only to them. Anything else is not read. Its kind is named, never read for: its file's
+ * extension, its address's, or the media type it was served as; bytes that say none are octet-stream.
+ */
+export declare const documentOf: (context: Context, place: string, at: string, named?: string) => Promise<Read | undefined>;
+/** A document read with the access a source the place connected holds: sent to that source's own origin alone, never redirected with it; a move is followed with nothing attached, only to the bytes its named digest names. */
+export declare const fetchedAs: (context: Context, at: string, via: string, got: {
+    readonly plan: Call;
+    readonly attachment: Attachment | undefined;
+}, named: string, accept: string | undefined) => Promise<Read | {
+    readonly said: readonly string[];
+}>;
+/**
+ * Every byte a package's lines name, by the path each names: read where a line of the same scope says — an encrypted
+ * address, signed or expiring, read with nothing attached and only to the bytes its digest names — or else beside the
+ * package's lock, in its folder or at its address. A path outside the package is never read. And what a place laid
+ * for a source it connected — its document and the overlay beside it — by the path the place keeps them at. And where
+ * an origin says its documents are: the catalog it publishes at its well-known address (RFC 9727), then the paths head's
+ * lock names, each once.
+ */
+export declare const besideOf: (context: Context, document: string, lines: readonly Said[]) => Promise<ReadonlyMap<string, Uint8Array | undefined>>;
+export declare const describedAt: (context: Context, origin: string) => Promise<readonly string[]>;
+export declare const laidOf: (context: Context, place: string, source: string) => readonly (readonly [string, Uint8Array])[];