@lapxo/head 0.0.0-stage → 0.1.0

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

@@ -0,0 +1,34 @@
+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 only through what the
+ * client can ask, else it is the person's 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) => ((how) => (how === undefined ? Promise.resolve('none')
+            : (how === 'form' ? form(message, { yes: { type: 'boolean', title: word } }) : paged(message, [{ name: 'yes', label: word, secret: false, options: [{ value: 'true', label: word }, { value: 'false', label: 'No' }] }], how))
+                .then((got) => (got?.['yes'] === 'true' ? 'yes' : 'no'))))(channel('ask/consent-channels')),
+        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,38 @@
+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 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 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,67 @@
+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') ?? '' };
+    }
+    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) && new URL(url).protocol === 'https:'
+    ? ((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 get = async (url, wait) => (URL.canParse(url) && new URL(url).protocol === 'https:' ? ((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,51 @@
+import type { Said } from '../core/lock.ts';
+import type { Outcome } from '../core/answer.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. */
+export declare const run: (name: string, cwd: string, args: readonly string[], env?: Readonly<Record<string, string>>, signal?: AbortSignal) => Promise<Printed | undefined>;
+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), 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 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. */
+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;
+};
+export declare const settledView: (name: string, place: string, view: string, signal?: AbortSignal) => Promise<Folded>;

package/dist/src/ports/bound.js

@@ -0,0 +1,68 @@
+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";
+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. */
+export const run = async (name, cwd, args, env = {}, signal) => ((bin) => (bin === undefined ? undefined
+    : spawned(process.execPath, [bin, ...args], { cwd, env: { ...process.env, ...env } }, { wait: limits.wait, most: limits.most || Number.MAX_SAFE_INTEGER, ...(signal ? { signal } : {}) })))(binOf(name));
+const facts = (out) => out.flatMap((line) => ((got) => (got.kind === 'fact' ? [got.value.fields] : []))(parse(line)));
+const readOf = (printed) => (printed === undefined || printed.code !== 0 ? { refused: printed?.err.at(-1) ?? '' } : { lines: facts(printed.out) });
+/**
+ * The lines a place stands on, from bound's public views alone: its folded normative standing (the lines view), 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 standingAt = async (name, place, devicesOf, isHistory, signal) => {
+    const folded = readOf(await run(name, place, [words.read, words.view, words.standing], {}, signal));
+    if ('refused' in folded)
+        return folded;
+    if (!folded.lines.some((line) => line.scope === words.profile))
+        return { 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` };
+    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: got?.err.at(-1) ?? '' }))(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. */
+export const landAct = async (name, place, lot, key, signer, env, signal) => ((got) => {
+    if (got === undefined || got.code !== 0)
+        return { refused: got?.err.at(-1) ?? '' };
+    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: got?.err.at(-1) ?? '' }))(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: got?.err.at(-1) ?? '' }))(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: '' };
+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/keychain.d.ts

@@ -0,0 +1,7 @@
+export interface KeyStore {
+    readonly read: (account: string) => string | undefined;
+    readonly write: (account: string, secret: string) => void;
+}
+export declare const plain: (word: string) => string;
+/** The secret store this host keeps head's keys in, by the name its lock gives the platform's: one adapter each, every secret crossing a command's stdin and stdout only. */
+export declare const keychain: (service: string, kind: string) => KeyStore;

package/dist/src/ports/keychain.js

@@ -0,0 +1,11 @@
+import { store as credentialManager } from "./stores/credential-manager.js";
+import { store as keychainOfMac } from "./stores/keychain.js";
+import { store as secretTool } from "./stores/secret-tool.js";
+export const plain = (word) => { if (!/^[\w.@/+=-]+$/.test(word))
+    throw Error('REFUSE·keychain a name holds more than word characters'); return word; };
+/** The secret store this host keeps head's keys in, by the name its lock gives the platform's: one adapter each, every secret crossing a command's stdin and stdout only. */
+export const keychain = (service, kind) => ((made) => {
+    if (made === undefined)
+        throw Error(`REFUSE·keychain ${kind} is no store head carries`);
+    return made(service);
+})({ keychain: keychainOfMac, 'secret-tool': secretTool, 'credential-manager': credentialManager }[kind]);

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

@@ -0,0 +1,10 @@
+import type { Said } from '../core/lock.ts';
+/** The lines head's own lock declares, decoded; a missing lock is an error, never an empty lock. */
+export declare const lockAt: (dir: string) => readonly Said[];
+/** A root the client shares, as the folder it names; a root that names no file folder is no place. */
+export declare const folderOf: (uri: string) => string | undefined;
+/** Bytes laid at a path inside a place, its folders made; a path outside the place is refused. */
+export declare const layAt: (place: string, rel: string, bytes: Uint8Array) => void;
+export declare const takeAt: (path: string) => Uint8Array | undefined;
+export declare const hasAt: (place: string, rel: string) => boolean;
+export declare const dropAt: (place: string, rel: string) => void;

package/dist/src/ports/place.js

@@ -0,0 +1,26 @@
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { LOCK } from '@lapxo/topos/wire';
+import { declaredOf } from "../core/lock.js";
+/** The lines head's own lock declares, decoded; a missing lock is an error, never an empty lock. */
+export const lockAt = (dir) => declaredOf(readFileSync(join(dir, LOCK), 'utf8'));
+/** A root the client shares, as the folder it names; a root that names no file folder is no place. */
+export const folderOf = (uri) => { try {
+    return fileURLToPath(uri);
+}
+catch {
+    return undefined;
+} };
+const inside = (place, rel) => ((at) => { if (!at.startsWith(`${resolve(place)}${sep}`))
+    throw Error('REFUSE·place a path outside its place'); return at; })(resolve(place, rel));
+/** Bytes laid at a path inside a place, its folders made; a path outside the place is refused. */
+export const layAt = (place, rel, bytes) => { const at = inside(place, rel); mkdirSync(dirname(at), { recursive: true }); writeFileSync(at, bytes); };
+export const takeAt = (path) => { try {
+    return readFileSync(path);
+}
+catch {
+    return undefined;
+} };
+export const hasAt = (place, rel) => existsSync(resolve(place, rel));
+export const dropAt = (place, rel) => rmSync(inside(place, rel), { force: true });

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

@@ -0,0 +1,20 @@
+export interface Printed {
+    readonly code: number;
+    readonly out: readonly string[];
+    readonly err: readonly string[];
+}
+export interface Bounds {
+    readonly wait: number;
+    readonly most: number;
+    readonly signal?: AbortSignal;
+}
+/**
+ * A process run beside head, never blocking it: what it printed, out and err, line by line, and its exit, which is
+ * transport and never the verdict. Its whole group is stopped when the wait runs out, when it prints more bytes than it
+ * may, when the asker cancels or when head exits; the exit is then -1 and the cause is err's last line.
+ */
+export declare const spawned: (command: string, args: readonly string[], at: {
+    readonly cwd?: string;
+    readonly env?: NodeJS.ProcessEnv;
+    readonly input?: string;
+}, bounds: Bounds) => Promise<Printed>;

package/dist/src/ports/process.js

@@ -0,0 +1,49 @@
+import { spawn } from 'node:child_process';
+const running = new Set();
+process.once('exit', () => { for (const stop of running)
+    stop(); });
+/**
+ * A process run beside head, never blocking it: what it printed, out and err, line by line, and its exit, which is
+ * transport and never the verdict. Its whole group is stopped when the wait runs out, when it prints more bytes than it
+ * may, when the asker cancels or when head exits; the exit is then -1 and the cause is err's last line.
+ */
+export const spawned = (command, args, at, bounds) => new Promise((resolve) => {
+    const child = spawn(command, [...args], { cwd: at.cwd, env: at.env, stdio: ['pipe', 'pipe', 'pipe'], detached: process.platform !== 'win32', windowsHide: true });
+    const [out, err] = [[], []];
+    let [printed, cause, done] = [0, undefined, false];
+    const kill = () => { try {
+        if (child.pid !== undefined && process.platform !== 'win32')
+            process.kill(-child.pid, 'SIGKILL');
+        else
+            child.kill('SIGKILL');
+    }
+    catch {
+        child.kill('SIGKILL');
+    } };
+    const stop = (why) => { cause ??= why; kill(); };
+    const signal = AbortSignal.any([...(bounds.wait > 0 ? [AbortSignal.timeout(bounds.wait)] : []), ...(bounds.signal ? [bounds.signal] : [])]);
+    const cancel = () => stop(bounds.signal?.aborted ? 'cancelled' : `waited ${bounds.wait} ms`);
+    const finish = (code) => {
+        if (done)
+            return;
+        done = true;
+        signal.removeEventListener('abort', cancel);
+        running.delete(kill);
+        const lines = (chunks) => Buffer.concat(chunks).toString('utf8').split('\n').filter(Boolean);
+        resolve({ code: cause === undefined ? code : -1, out: lines(out), err: [...lines(err), ...(cause === undefined ? [] : [cause])] });
+    };
+    const take = (into) => (chunk) => { printed += chunk.length; if (printed > bounds.most)
+        stop(`printed more than ${bounds.most} bytes`);
+    else
+        into.push(chunk); };
+    running.add(kill);
+    child.stdout.on('data', take(out));
+    child.stderr.on('data', take(err));
+    child.on('error', (error) => { cause ??= error.message; finish(-1); });
+    child.on('close', (code) => finish(code ?? -1));
+    child.stdin.on('error', () => undefined).end(at.input ?? '');
+    if (signal.aborted)
+        cancel();
+    else
+        signal.addEventListener('abort', cancel, { once: true });
+});

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

@@ -0,0 +1,6 @@
+/**
+ * The host's registry bound reads to bind a declared signer name to a program: head's own signer, started by this node,
+ * told the keychain service, the account its secret is kept under, the key it signs as, the algorithm and the store this
+ * host keeps secrets in. It holds no secret; it lives beside nothing a repository ships.
+ */
+export declare const registryFor: (name: string, service: string, account: string, key: string, algorithm: string, store?: string) => string;

package/dist/src/ports/signers.js

@@ -0,0 +1,14 @@
+import { writeFileSync, mkdtempSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+/**
+ * The host's registry bound reads to bind a declared signer name to a program: head's own signer, started by this node,
+ * told the keychain service, the account its secret is kept under, the key it signs as, the algorithm and the store this
+ * host keeps secrets in. It holds no secret; it lives beside nothing a repository ships.
+ */
+export const registryFor = (name, service, account, key, algorithm, store = 'keychain') => {
+    const at = join(mkdtempSync(join(tmpdir(), 'head-signers-')), 'signers.json');
+    writeFileSync(at, JSON.stringify({ [name]: { kind: 'command', executable: process.execPath, args: [fileURLToPath(new URL(`../signer${import.meta.url.slice(import.meta.url.lastIndexOf('.'))}`, import.meta.url)), service, account, key, algorithm, store] } }));
+    return at;
+};

package/dist/src/ports/stores/credential-manager.d.ts

@@ -0,0 +1,3 @@
+import type { KeyStore } from '../keychain.ts';
+/** The Windows Credential Manager: the secret travels inside the program head writes to PowerShell's stdin, base64, and comes back on its stdout; never an argument a process list shows. */
+export declare const store: (service: string) => KeyStore;

package/dist/src/ports/stores/credential-manager.js

@@ -0,0 +1,22 @@
+import { execFileSync } from 'node:child_process';
+import { plain } from "../keychain.js";
+/** Windows PowerShell, reading its whole program from stdin: the password vault of the Credential Manager, an entry by its resource and user. */
+const vault = (program) => execFileSync('powershell.exe', ['-NoProfile', '-NonInteractive', '-Command', '-'], {
+    input: ['$ErrorActionPreference = \'Stop\'', '[void][Windows.Security.Credentials.PasswordVault, Windows.Security.Credentials, ContentType = WindowsRuntime]', '$v = New-Object Windows.Security.Credentials.PasswordVault', ...program, ''].join('\n'),
+    encoding: 'utf8', stdio: ['pipe', 'pipe', 'ignore'],
+});
+/** The Windows Credential Manager: the secret travels inside the program head writes to PowerShell's stdin, base64, and comes back on its stdout; never an argument a process list shows. */
+export const store = (service) => ({
+    read: (account) => {
+        try {
+            return vault([`$r = '${plain(service)}'; $u = '${plain(account)}'`, 'try { $c = $v.Retrieve($r, $u); $c.RetrievePassword(); [Console]::Out.Write($c.Password) } catch { exit 1 }']).trim() || undefined;
+        }
+        catch {
+            return undefined;
+        }
+    },
+    write: (account, secret) => {
+        vault([`$r = '${plain(service)}'; $u = '${plain(account)}'; $b = '${Buffer.from(plain(secret)).toString('base64')}'`, 'try { $v.Remove($v.Retrieve($r, $u)) } catch { }',
+            '$v.Add((New-Object Windows.Security.Credentials.PasswordCredential($r, $u, [Text.Encoding]::UTF8.GetString([Convert]::FromBase64String($b)))))']);
+    },
+});

package/dist/src/ports/stores/keychain.d.ts

@@ -0,0 +1,3 @@
+import type { KeyStore } from '../keychain.ts';
+/** The macOS keychain through the system's own command: a secret crosses its stdin and stdout only, never an argument a process list shows. */
+export declare const store: (service: string) => KeyStore;

package/dist/src/ports/stores/keychain.js

@@ -0,0 +1,16 @@
+import { execFileSync } from 'node:child_process';
+import { plain } from "../keychain.js";
+/** The macOS keychain through the system's own command: a secret crosses its stdin and stdout only, never an argument a process list shows. */
+export const store = (service) => ({
+    read: (account) => {
+        try {
+            return execFileSync('security', ['find-generic-password', '-a', plain(account), '-s', plain(service), '-w'], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim() || undefined;
+        }
+        catch {
+            return undefined;
+        }
+    },
+    write: (account, secret) => {
+        execFileSync('security', ['-i'], { input: `add-generic-password -U -a ${plain(account)} -s ${plain(service)} -w ${plain(secret)}\n`, stdio: ['pipe', 'ignore', 'ignore'] });
+    },
+});

package/dist/src/ports/stores/secret-tool.d.ts

@@ -0,0 +1,3 @@
+import type { KeyStore } from '../keychain.ts';
+/** The Secret Service of a Linux session through libsecret's own command: an entry found by its service and account attributes, the secret crossing stdin and stdout only. */
+export declare const store: (service: string) => KeyStore;

package/dist/src/ports/stores/secret-tool.js

@@ -0,0 +1,16 @@
+import { execFileSync } from 'node:child_process';
+import { plain } from "../keychain.js";
+/** The Secret Service of a Linux session through libsecret's own command: an entry found by its service and account attributes, the secret crossing stdin and stdout only. */
+export const store = (service) => ({
+    read: (account) => {
+        try {
+            return execFileSync('secret-tool', ['lookup', 'service', plain(service), 'account', plain(account)], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim() || undefined;
+        }
+        catch {
+            return undefined;
+        }
+    },
+    write: (account, secret) => {
+        execFileSync('secret-tool', ['store', `--label=${plain(service)} ${plain(account)}`, 'service', plain(service), 'account', plain(account)], { input: plain(secret), stdio: ['pipe', 'ignore', 'ignore'] });
+    },
+});

package/dist/src/resources/view.d.ts

@@ -0,0 +1 @@
+export { answer } from '../tools/look.ts';

package/dist/src/resources/view.js

@@ -0,0 +1 @@
+export { answer } from "../tools/look.js";

package/dist/src/signer.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/src/signer.js

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+import { readFileSync } from 'node:fs';
+import { signLot } from "./core/keys.js";
+import { keychain } from "./ports/keychain.js";
+const [service = '', account = '', key = '', algorithm = '', store = 'keychain'] = process.argv.slice(2);
+const secret = keychain(service, store).read(account);
+if (secret === undefined)
+    process.exit(1);
+try {
+    process.stdout.write(signLot(readFileSync(0, 'utf8'), secret, key, algorithm));
+}
+catch {
+    process.exit(1);
+}

package/dist/src/sources/access.d.ts

@@ -0,0 +1,8 @@
+import type { Asked, Context } from '../core/answer.ts';
+/**
+ * Access to a source obtained ahead of any call, at the origin the person picked once where several are declared: the
+ * way its document says access is proven, run by the adapter of
+ * that kind — the person's own page, or the provider they are sent to with a client registered for the visit — its
+ * secret kept in this keychain and its obtaining landed as a receipt the device key signs. Nothing is called.
+ */
+export declare const accessed: (asked: Asked, context: Context) => Promise<readonly string[]>;

package/dist/src/sources/access.js

@@ -0,0 +1,34 @@
+import { inPlace, placeNameOf } from "../core/answer.js";
+import { uncoveredIn } from "../core/device.js";
+import { valueOf } from "../core/lock.js";
+import { planRead, vocabOf } from "../core/read.js";
+import { sayIn } from "../core/surface.js";
+import { attachmentFor } from "../access/obtain.js";
+import { pickedOrigin } from "../flows/call.js";
+import { standingFor } from "../flows/world.js";
+/**
+ * Access to a source obtained ahead of any call, at the origin the person picked once where several are declared: the
+ * way its document says access is proven, run by the adapter of
+ * that kind — the person's own page, or the provider they are sent to with a client registered for the visit — its
+ * secret kept in this keychain and its obtaining landed as a receipt the device key signs. Nothing is called.
+ */
+export const accessed = (asked, context) => inPlace(asked, context, async (place) => {
+    const [say, v, source] = [sayIn(context.lock), vocabOf(context.lock), asked['source'] ?? ''];
+    const held = await standingFor(context, place);
+    if ('unsettled' in held)
+        return [say('unsettled', { source, why: held.unsettled })];
+    const operation = asked['operation'] || held.lines.filter((l) => l.measure === v.class && l.value === v.callable && l.scope?.startsWith(`${v.offers}/${source}/`)).map((l) => l.scope.split('/').slice(2).join('/')).sort()[0];
+    if (operation === undefined)
+        return [say('unread', { source })];
+    const picked = await pickedOrigin(context, place, held.lines, source, planRead(held.lines, context.lock, source, operation, placeNameOf(place)));
+    if ('said' in picked)
+        return picked.said;
+    const plan = planRead(picked.lines, context.lock, source, operation, placeNameOf(place));
+    if (plan.kind === 'said')
+        return [say(plan.key, plan.fields)];
+    const stopped = uncoveredIn(context.lock, held.lines, context.device('head'), place, [], [`${valueOf(context.lock, 'access/family')}/${source}/${plan.access.scheme || v.anonymous}/obtained`]);
+    if (stopped)
+        return stopped;
+    const got = await attachmentFor(context, place, picked.lines, plan);
+    return 'said' in got ? [say(got.said, { source, operation, kinds: plan.access.kind, input: got.input })] : [say(plan.access.account === undefined ? 'access-anonymous' : 'access-kept', { source })];
+});

package/dist/src/sources/connect.d.ts

@@ -0,0 +1,10 @@
+import type { Asked, Context } from '../core/answer.ts';
+/**
+ * A source connected to a place, once the person said yes; a lock is no source, and adopting one as a parent is refused
+ * by name, since composing two places' policies is bound's. A document — and an overlay beside it — is laid whatever its
+ * kind, with every world head carries adopted, and the fold decides which reads it: what no world compiles is open, the
+ * bytes taken back and the line that pays it handed on. What one does is compiled once per digest of what it read — the
+ * same bytes again find their compiled standing by name — and pinned from the place's store: a new pin lands with the
+ * old one's withdraw, said at its own time, since a withdrawn saying stays withdrawn.
+ */
+export declare const connected: (asked: Asked, context: Context) => Promise<readonly string[]>;