@idleware/ringi 0.4.0 → 0.6.0

package/target/esm/adapters/transport-git/remote/signals.js

@@ -0,0 +1,63 @@
+// signals: a signal tag's name, object and target checked: its actor's own, on a message of the room's branch.
+import * as C from '../../../lib/index.js';
+import * as P from '../../../core/hub/protocol/index.js';
+import { branch } from './branch.js';
+import { git, isRemote, reason, rev } from './git.js';
+import { heartbeatName } from './heartbeat.js';
+import { checkSignature } from './signature.js';
+import { SHA, TAGS } from './types.js';
+export const SIGNAL_NAME = /^([a-z0-9]+(?:[_-][a-z0-9]+)*)\.([a-z][a-z0-9.-]*)\.([0-9a-f]{12})$/;
+export const signalName = (ref) => {
+    if (heartbeatName(ref))
+        C.fail('heartbeat is not an immutable signal');
+    const m = ref.startsWith(TAGS) && SIGNAL_NAME.exec(ref.slice(TAGS.length));
+    if (!m)
+        return C.fail('malformed signal tag namespace');
+    return { actor: m[1], id: m[3], signal: m[2] };
+};
+// The signed header carries the full target, tag name and actor; there is no message body.
+export const signalObject = (H, ref, sha) => {
+    const s = signalName(ref);
+    if (git(H, ['cat-file', '-t', sha]).trim() !== 'tag')
+        C.fail('signal must be an annotated tag');
+    const text = P.decodeText(git(H, ['cat-file', 'tag', sha], { raw: true }));
+    if (text.invalid)
+        C.fail(`signal tag is ${text.invalid}`);
+    const [header, ...rest] = text.text.split('\n\n');
+    const target = /^object ([0-9a-f]+)\ntype commit\ntag ([^\n]+)\ntagger ([^<\n]+) <[^\n]*> \d+ [+-]\d{4}\n?$/.exec(header) ?? C.fail('malformed signal tag headers');
+    if (!SHA.test(target[1]) || !target[1].startsWith(s.id) || target[2] !== ref.slice('refs/tags/'.length) || target[3].trim() !== s.actor)
+        C.fail('signal tag name, actor or target disagrees');
+    const body = rest.join('\n\n').split('-----BEGIN SSH SIGNATURE-----')[0];
+    if (body !== '')
+        C.fail('signal tag message must be empty');
+    return { ...s, message: target[1] };
+};
+// Derived signals belong to their message's author; read/taken marks may name another member's message.
+// The room is determined by the full target commit on its verified branch, never by a short name or a tag body.
+export const checkSignal = (H, R, ref, sha) => {
+    const s = signalObject(H, ref, sha);
+    const b = branch(H, R, rev(H, R.ref) ?? C.fail('signal room has no branch here'));
+    const signer = b.entries.find(e => e.principal === s.actor) ?? C.fail(`unadmitted signal principal ${s.actor}`);
+    checkSignature(H, sha, s.actor, signer.key, 'tag');
+    const mark = s.signal === 'read' || s.signal === 'taken';
+    if (s.message === R.genesis)
+        C.fail('signal points at no message of this room');
+    const author = b.authors.get(s.message);
+    if (!(mark ? author : author === s.actor))
+        C.fail(`signal points at no accepted message ${mark ? 'of this room' : 'of its actor'}`);
+};
+export const verifySignal = (H, R, ref, sha) => {
+    if (!isRemote(H))
+        return null;
+    const alarm = H.remoteAlarms?.[ref];
+    if (alarm)
+        return alarm;
+    try {
+        checkSignal(H, R, ref, sha);
+        return null;
+    }
+    catch (e) {
+        return reason(e);
+    }
+};
+//# sourceMappingURL=signals.js.map

package/target/esm/adapters/transport-git/remote/signature.js

@@ -0,0 +1,56 @@
+// signature: commits and tags checked against the key of their principal; a branch checked to be linear.
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import * as C from '../../../lib/index.js';
+import * as P from '../../../core/hub/protocol/index.js';
+import { git, mkdir } from './git.js';
+import { signerLine } from './keys.js';
+export const verified = new Set();
+const signerFile = (H, text) => {
+    const dir = path.join(H.dir, 'ringi', 'verify');
+    mkdir(dir);
+    const file = path.join(dir, crypto.createHash('sha256').update(text).digest('hex') + '.allowed_signers');
+    if (!fs.existsSync(file))
+        fs.writeFileSync(file, text, { flag: 'wx', mode: 0o600 });
+    else if (fs.readFileSync(file, 'utf8') !== text)
+        C.fail('local signature verification cache was changed');
+    return file;
+};
+export const checkSignature = (H, sha, who, key, kind = 'commit') => {
+    const cache = `${kind}/${sha}/${who}/${key.fp}`;
+    if (verified.has(cache))
+        return;
+    const file = signerFile(H, signerLine(who, key));
+    const r = git(H, ['-c', `gpg.ssh.allowedSignersFile=${file}`, '-c', 'gpg.ssh.revocationFile=' + os.devNull, `verify-${kind}`, sha], { ok: true });
+    if (r.status !== 0)
+        C.fail(`bad or missing signature at ${sha.slice(0, 12)}: not signed by the admitted key of ${who}`);
+    const raw = git(H, ['cat-file', kind, sha], { raw: true });
+    const split = raw.indexOf(Buffer.from('\n\n'));
+    if (split < 0)
+        C.fail(`malformed ${kind}`);
+    const hdr = raw.subarray(0, split).toString('utf8');
+    if (/^encoding (?!UTF-8$|utf-8$)/m.test(hdr))
+        C.fail('commit declares a non-UTF-8 message');
+    const d = P.decodeText(raw.subarray(split + 2));
+    if (d.invalid)
+        C.fail(`${kind} message is ${d.invalid}`);
+    verified.add(cache);
+    if (verified.size > 4096)
+        verified.delete(verified.values().next().value);
+};
+export const chain = (H, head, base) => git(H, ['rev-list', '--parents', '--reverse', '--topo-order', head, ...(base ? [`^${base}`] : [])]).trim().split('\n').filter(Boolean).map(line => {
+    const [sha, ...parents] = line.split(' ');
+    return { sha, parents };
+});
+export const linear = (commits, initial, check) => {
+    let expect = initial;
+    for (const { sha, parents: ps } of commits) {
+        if (ps.length > 1 || (ps[0] || null) !== expect)
+            C.fail(`history is not linear at ${sha.slice(0, 12)}`);
+        check(sha);
+        expect = sha;
+    }
+};
+//# sourceMappingURL=signature.js.map

package/target/esm/adapters/transport-git/remote/sync-heartbeat.js

@@ -0,0 +1,26 @@
+// sync-heartbeat: a fetched heartbeat verified and installed as the remote's current object; its errors stay apart
+// from signal alarms.
+import * as C from '../../../lib/index.js';
+import { git, reason } from './git.js';
+import { checkHeartbeat, heartbeatObject } from './heartbeat.js';
+import { TAGS, TAG_ACCEPT, TAG_TRACK } from './types.js';
+export const syncHeartbeat = ({ H, tags, pinned, byGenesis }, name) => {
+    const beatRef = TAGS + name;
+    if (pinned.has(TAG_ACCEPT + name)) {
+        H.remoteAlarms[beatRef] = 'heartbeat namespace overlaps a previously accepted signal; operator review required';
+        return;
+    }
+    try {
+        const sha = tags.get(TAG_TRACK + name) ?? C.fail('heartbeat is absent from the remote');
+        const b = heartbeatObject(H, beatRef, sha);
+        const R = byGenesis.get(b.genesis) ?? C.fail('heartbeat room is missing or quarantined');
+        checkHeartbeat(H, R, beatRef, sha);
+        git(H, ['update-ref', beatRef, sha]);
+    }
+    catch (e) {
+        H.heartbeatErrors[beatRef] = reason(e);
+        git(H, ['update-ref', '-d', beatRef]);
+        C.note(`heartbeat ${name}: ${reason(e)}; withheld`);
+    }
+};
+//# sourceMappingURL=sync-heartbeat.js.map

package/target/esm/adapters/transport-git/remote/sync-rooms.js

@@ -0,0 +1,38 @@
+// sync-rooms: the rooms' branches as fetched, verified, and indexed by genesis and by commit.
+import * as C from '../../../lib/index.js';
+import * as P from '../../../core/hub/protocol/index.js';
+import { branchData } from './branch.js';
+import { promote, reason, refs, rev } from './git.js';
+import { ACCEPT, TRACK } from './types.js';
+export const syncRooms = (H, fetched) => {
+    // Every other branch is a room.
+    const names = roomNames(H, fetched);
+    const byGenesis = new Map(), byTarget = new Map();
+    for (const name of names) {
+        const ref = 'refs/heads/' + name;
+        try {
+            if (!P.ID_RE.test(name))
+                C.fail('invalid room name');
+            const sha = fetched.get(TRACK + name) ?? C.fail(`${name} was deleted on the remote`);
+            const data = branchData(H, name, sha);
+            if (byGenesis.has(data.genesis))
+                C.fail('room genesis is already bound to another room');
+            promote(H, ref, sha);
+            // Local commits not yet published stay on top.
+            const local = branchData(H, name, rev(H, ref), data.genesis);
+            const R = { name, ref, head: local.control.at(-1), genesis: data.genesis };
+            byGenesis.set(data.genesis, R);
+            for (const target of [...local.control, ...local.authors.keys(), ...local.skipped.keys()])
+                byTarget.set(target, R);
+        }
+        catch (e) {
+            H.remoteAlarms[ref] = reason(e);
+        }
+    }
+    return { byGenesis, byTarget };
+};
+const roomNames = (H, fetched) => {
+    const names = new Set([...fetched.keys(), ...refs(H, ACCEPT).keys()].map(r => r.slice(r.startsWith(TRACK) ? TRACK.length : ACCEPT.length)).filter(r => r !== 'main' && !r.includes('/')));
+    return names;
+};
+//# sourceMappingURL=sync-rooms.js.map

package/target/esm/adapters/transport-git/remote/sync-tags.js

@@ -0,0 +1,48 @@
+// sync-tags: fetched tags sorted into signals (immutable, pinned) and heartbeats (replaced).
+import * as C from '../../../lib/index.js';
+import { git, object, reason, refs, zero } from './git.js';
+import { heartbeatName } from './heartbeat.js';
+import { SIGNAL_NAME, checkSignal, signalObject } from './signals.js';
+import { TAGS, TAG_ACCEPT, TAG_TRACK } from './types.js';
+import { syncHeartbeat } from './sync-heartbeat.js';
+const missingHeartbeats = (H, tags, pinned) => {
+    // Include local beats to remove disappeared remote telemetry; unlike signals, nothing is pinned.
+    for (const ref of refs(H, TAGS).keys())
+        if (heartbeatName(ref) && !tags.has(TAG_TRACK + ref.slice(TAGS.length))) {
+            if (pinned.has(TAG_ACCEPT + ref.slice(TAGS.length)))
+                continue; // never waive previously accepted history
+            git(H, ['update-ref', '-d', ref]);
+        }
+};
+const syncSignal = ({ H, tags, pinned, byTarget }, name) => {
+    const ref = TAGS + name;
+    try {
+        const sha = tags.get(TAG_TRACK + name) ?? C.fail('signal was deleted on the remote after acceptance');
+        const s = signalObject(H, ref, sha);
+        const R = byTarget.get(s.message) ?? C.fail('signal room is missing or quarantined');
+        checkSignal(H, R, ref, sha);
+        const acc = pinned.get(TAG_ACCEPT + name), cur = object(H, ref);
+        if (acc && acc !== sha)
+            C.fail('signal was replaced after transport acceptance');
+        if (cur && cur !== sha)
+            C.fail('signal diverges from the local tag object');
+        git(H, ['update-ref', ref, sha, cur ?? zero(H)]);
+        git(H, ['update-ref', TAG_ACCEPT + name, sha, acc ?? zero(H)]);
+    }
+    catch (e) {
+        H.remoteAlarms[ref] = reason(e);
+    }
+};
+export const syncTags = (H, rooms) => {
+    const tags = refs(H, TAG_TRACK), pinned = refs(H, TAG_ACCEPT);
+    missingHeartbeats(H, tags, pinned);
+    const state = { H, tags, pinned, ...rooms };
+    const names = new Set([...tags.keys()].map(r => r.slice(TAG_TRACK.length)).concat([...pinned.keys()].map(r => r.slice(TAG_ACCEPT.length))));
+    for (const name of names) {
+        if (heartbeatName(TAGS + name))
+            syncHeartbeat(state, name);
+        else if (SIGNAL_NAME.test(name))
+            syncSignal(state, name);
+    }
+};
+//# sourceMappingURL=sync-tags.js.map

package/target/esm/adapters/transport-git/remote/sync.js

@@ -0,0 +1,38 @@
+// sync: one fetch of a signed hub under its transport lock: contract, rooms, signals and heartbeats verified.
+import * as C from '../../../lib/index.js';
+import { pushAlarms } from './alarms.js';
+import { git, isRemote, locked, origin, promote, reason, refs, rev, suffix } from './git.js';
+import { checkUrl } from './keys.js';
+import { verifyHub, verifyMain } from './main.js';
+import { syncRooms } from './sync-rooms.js';
+import { syncTags } from './sync-tags.js';
+import { TAGS, TAG_TRACK, TRACK } from './types.js';
+const syncUnlocked = (H) => {
+    H.remoteAlarms = { ...pushAlarms(H) };
+    H.heartbeatErrors = {};
+    const url = origin(H);
+    if (!url) {
+        if (rev(H, 'refs/heads/main'))
+            verifyHub(H);
+        return H;
+    }
+    checkUrl(url);
+    git(H, ['-c', 'fetch.fsckObjects=true', 'fetch', '-q', '--no-tags', '--prune', url,
+        `+refs/heads/*:${TRACK}*`, `+${TAGS}*:${TAG_TRACK}*`]);
+    const fetched = refs(H, TRACK);
+    const main = fetched.get(TRACK + 'main') || C.fail('ALARM remote main was deleted or is missing; refusing authority from the hub');
+    try {
+        verifyMain(H, main);
+        promote(H, 'refs/heads/main', main);
+    }
+    catch (e) {
+        C.fail(`ALARM hub ${H.name}: ${reason(e)}; nothing is delivered`);
+    }
+    H.main = rev(H, 'refs/heads/main');
+    syncTags(H, syncRooms(H, fetched));
+    for (const [ref, why] of Object.entries(H.remoteAlarms))
+        C.note(`ALARM ${suffix(ref)}: ${why}; quarantined and withheld`);
+    return H;
+};
+export const sync = (H) => !isRemote(H) ? H : locked(H, () => syncUnlocked(H));
+//# sourceMappingURL=sync.js.map

package/target/esm/adapters/transport-git/remote/types.js

@@ -0,0 +1,10 @@
+// types: what the signed transport's modules share: the hub handle, a room, keys, signers, a verified branch.
+export const CONTROL_FILES = ['ROOM.md', 'members.json', 'profile.json', 'allowed_signers'];
+export const SHA = /^(?:[0-9a-f]{40}|[0-9a-f]{64})$/;
+export const ROOT = 'operator';
+export const TRACK = 'refs/remotes/origin/';
+export const ACCEPT = 'refs/ringi/remote-accepted/';
+export const TAGS = 'refs/tags/';
+export const TAG_TRACK = 'refs/ringi/remote-tags/';
+export const TAG_ACCEPT = 'refs/ringi/remote-accepted-tags/';
+//# sourceMappingURL=types.js.map

package/target/esm/adapters/transport-git/remote.js

@@ -0,0 +1,17 @@
+export { withVerification } from './remote/cache.js';
+export { gitEnv, gitTimeout, checkGitTimeout } from './remote/process.js';
+export { isRemote } from './remote/git.js';
+export { parseKey, setupSigned, sign, rootRoster } from './remote/keys.js';
+export { verifyHub } from './remote/main.js';
+export { readCommits } from './remote/commits.js';
+export { branch, verifyRoom, verify } from './remote/branch.js';
+export { heartbeatName, heartbeatRef, verifyHeartbeat, makeHeartbeat } from './remote/heartbeat.js';
+export { verifySignal } from './remote/signals.js';
+export { sync } from './remote/sync.js';
+export { hubAdd } from './remote/bootstrap.js';
+export { join, roomAdmit } from './remote/admit.js';
+export { push } from './remote/push.js';
+export { pushHeartbeat } from './remote/heartbeat-push.js';
+export { forget } from './remote/forget.js';
+export { strictJson } from '../../lib/index.js';
+//# sourceMappingURL=remote.js.map

package/target/esm/adapters/transport-git/repo.js

@@ -0,0 +1,115 @@
+// repo: the store's repository and the contract on its main branch. Every commit is made here (signed on a signed hub),
+// every ref moves here compare-and-swap, and the work tree follows the contract so Git clients open the store cleanly.
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { fail } from '../../lib/index.js';
+import { mkdirIn } from '../fs/index.js';
+import * as Remote from './remote.js';
+import { ZERO, ident, runGit, runGitOk } from './run.js';
+import { signCommit } from './signing.js';
+// The store is a repository whose work tree holds the contract (`main`) as it is now, so Git clients (SourceTree, IDEs)
+// open `store/` without errors, on the contract, with every room's branch beside it; `git status` stays clean.
+export const init = (dir, home) => runGit(['init', '-q', '-b', 'main', path.dirname(dir)], { where: home });
+export class Repo {
+    trust;
+    dir;
+    d;
+    home;
+    // The handle remote.ts works on: the repository and what it learned on the last sync.
+    h;
+    constructor(hubDir, d, home, signing) {
+        this.d = d;
+        this.home = home;
+        this.trust = d.trust;
+        this.dir = path.join(hubDir, d.store.path, '.git');
+        this.h = { name: d.name, dir: this.dir, d, ...(d.trust === 'signed' && signing ? { signing } : {}) };
+        if (!fs.existsSync(this.dir))
+            fail(`hub ${d.name}: no git store at ${this.dir}`);
+        this.openable();
+    }
+    // A store made bare before, or a replica fetched bare, gets its work tree once (and loses the `_ringi` branch of an unreleased build).
+    openable() {
+        let changed = false;
+        if (/^\s*bare\s*=\s*true\s*$/m.test(fs.readFileSync(path.join(this.dir, 'config'), 'utf8'))) {
+            this.git(['config', 'core.bare', 'false']);
+            changed = true;
+        }
+        if (fs.readFileSync(path.join(this.dir, 'HEAD'), 'utf8') !== 'ref: refs/heads/main\n') {
+            this.git(['symbolic-ref', 'HEAD', 'refs/heads/main']);
+            changed = true;
+        }
+        if (fs.existsSync(path.join(this.dir, 'refs', 'heads', '_ringi'))) {
+            this.gitOk(['update-ref', '-d', 'refs/heads/_ringi']);
+            changed = true;
+        }
+        if (changed)
+            this.checkout();
+    }
+    // The work tree and the index follow the contract, so a Git client sees the store clean.
+    checkout() {
+        if (this.rev('refs/heads/main'))
+            this.git(['--work-tree', path.dirname(this.dir), 'read-tree', '-u', '--reset', 'refs/heads/main']);
+    }
+    args(a) { return ['--git-dir', this.dir, ...a]; }
+    git(a, o) { return runGit(this.args(a), { ...o, where: this.home }); }
+    gitOk(a, o) { return runGitOk(this.args(a), o); }
+    rev(ref) {
+        const r = this.gitOk(['rev-parse', '-q', '--verify', `${ref}^{commit}`]);
+        return r.status === 0 ? r.stdout.trim() : null;
+    }
+    isAncestor(a, b) { return this.gitOk(['merge-base', '--is-ancestor', a, b]).status === 0; }
+    isRef(s) { return /^[0-9a-f]{40}(?:[0-9a-f]{24})?$/.test(s ?? ''); }
+    extends(older, newer) { return older === newer || this.isAncestor(older, newer); }
+    // A tree from a base tree without the `drop` paths, with entries put on top; nested paths are fine.
+    tree(base, entries, drop = []) {
+        const idx = path.join(this.home, 'tmp', `index.${process.pid}.${crypto.randomBytes(4).toString('hex')}`);
+        mkdirIn(this.home, path.dirname(idx));
+        const env = { GIT_INDEX_FILE: idx };
+        try {
+            this.git(['read-tree', ...(base ? [base] : ['--empty'])], { env });
+            if (drop.length)
+                this.git(['update-index', '--index-info'], { env, input: drop.map(p => `0 ${ZERO}\t${p}\n`).join('') });
+            for (const e of entries) {
+                const sha = e.blob ?? this.git(['hash-object', '-w', ...(e.file ? ['--', e.file] : ['--stdin'])], { input: e.content }).trim();
+                this.git(['update-index', '--add', '--cacheinfo', `${e.mode},${sha},${e.path}`], { env });
+            }
+            return this.git(['write-tree'], { env }).trim();
+        }
+        finally {
+            fs.rmSync(idx, { force: true });
+        }
+    }
+    // Every commit is made here: on a signed hub, signed by its author's key on this machine.
+    commit(who, text, tree, parents) {
+        const sha = this.git(['commit-tree', ...(this.h.signing ? [] : Remote.sign(this.h, who, this.home)), tree, ...parents.flatMap(p => ['-p', p])], { input: text, env: ident(who) }).trim();
+        return signCommit(this.h, who, sha, this.home);
+    }
+    advance(ref, sha, old) {
+        if (this.gitOk(['update-ref', ref, sha, old ?? ZERO]).status !== 0)
+            return false;
+        // A signed hub publishes at once; a rejected push keeps the commit here and alarms (remote.ts).
+        return Remote.push(this.h, ref, { behind: !!old && ref !== 'refs/heads/main' });
+    }
+    sync() {
+        const main = this.rev('refs/heads/main');
+        Remote.sync(this.h);
+        if (this.rev('refs/heads/main') !== main)
+            this.checkout();
+    }
+    contractHead() { return this.rev('refs/heads/main') ?? fail(`hub ${this.d.name} has no contract (main)`); }
+    contractFile(rev, name) {
+        const r = this.gitOk(['show', `${rev}:${name}`]);
+        return r.status === 0 ? r.stdout : null;
+    }
+    contractFiles(rev) { return this.git(['ls-tree', '-r', '--name-only', rev]).split('\n').filter(Boolean); }
+    amendContract(who, text, files) {
+        const head = this.contractHead();
+        const sha = this.commit(who, text, this.tree(`${head}^{tree}`, Object.entries(files).map(([p, c]) => ({ path: p, content: c, mode: '100644' }))), [head]);
+        if (!this.advance('refs/heads/main', sha, head))
+            fail('the contract moved while amending; retry');
+        this.checkout();
+        return sha;
+    }
+}
+//# sourceMappingURL=repo.js.map

package/target/esm/adapters/transport-git/run.js

@@ -0,0 +1,57 @@
+// run: git as a child process, with the hub's timeout, its isolated environment and the sandbox's one message; and
+// splitting what it prints.
+import { spawnSync } from 'node:child_process';
+import { fail } from '../../lib/index.js';
+import { cannotWrite, SANDBOX } from '../fs/index.js';
+import * as Remote from './remote.js';
+export const ZERO = '0'.repeat(40);
+export const ident = (id) => ({ GIT_AUTHOR_NAME: id, GIT_AUTHOR_EMAIL: `${id}@ringi`, GIT_COMMITTER_NAME: id, GIT_COMMITTER_EMAIL: `${id}@ringi` });
+export const runGit = (args, o = {}) => {
+    const r = spawnSync('git', args, { input: o.input, encoding: 'utf8', env: Remote.gitEnv(o.env), maxBuffer: 1 << 30, timeout: Remote.gitTimeout() });
+    return check(args, r, o.where).stdout;
+};
+export const runGitOk = (args, o = {}) => {
+    const r = spawnSync('git', args, { input: o.input, encoding: 'utf8', env: Remote.gitEnv(o.env), maxBuffer: 1 << 30, timeout: Remote.gitTimeout() });
+    Remote.checkGitTimeout(r.error);
+    return r;
+};
+export const runGitRaw = (args, where, input) => {
+    const r = spawnSync('git', args, { input, encoding: 'buffer', env: Remote.gitEnv(), maxBuffer: 1 << 30, timeout: Remote.gitTimeout() });
+    return check(args, r, where).stdout;
+};
+function check(args, r, where = 'the hub store') {
+    Remote.checkGitTimeout(r.error);
+    if (r.error)
+        throw r.error;
+    if (r.status !== 0) {
+        const err = String(r.stderr ?? '').trim();
+        if (SANDBOX.test(err))
+            cannotWrite(where, err.split('\n').at(-1));
+        fail(`git ${args.find(a => !a.startsWith('-') && !a.includes('/')) ?? ''}: ${err.split('\n').at(-1)}`);
+    }
+    return r;
+}
+export const splitBuf = (b, sep) => {
+    const parts = [];
+    let at = 0;
+    for (let i = b.indexOf(sep); i >= 0; i = b.indexOf(sep, at)) {
+        parts.push(b.subarray(at, i));
+        at = i + 1;
+    }
+    parts.push(b.subarray(at));
+    return parts;
+};
+// Objects of `git cat-file --batch`, read whole by their size, so no byte inside one can split it.
+export const frames = (raw, shas) => {
+    const out = new Map();
+    let at = 0;
+    for (const sha of shas) {
+        const nl = raw.indexOf(0x0a, at);
+        const [got, type, size] = raw.subarray(at, nl).toString('utf8').split(' ');
+        if (got === sha)
+            out.set(sha, { type, body: raw.subarray(nl + 1, nl + 1 + Number(size)) });
+        at = nl + 1 + Number(size) + 1;
+    }
+    return out;
+};
+//# sourceMappingURL=run.js.map

package/target/esm/adapters/transport-git/signing.js

@@ -0,0 +1,44 @@
+// GitSigningBridge: Signer signs the exact unsigned Git object. Tags append its SSH armor; commits fold it into
+// gpgsig. Custody is injected; only legacy direct entrypoints retain their previous file-key signing default.
+import { fail } from '../../lib/index.js';
+import { git, id, ident, isRemote } from './remote/git.js';
+import { identityKey, parseKey, rootKey, sign } from './remote/keys.js';
+import { command } from './remote/process.js';
+import { checkSignature } from './remote/signature.js';
+export const signBytes = (H, who, payload, home) => {
+    if (!isRemote(H))
+        return '';
+    if (!H.signing) {
+        const file = sign(H, who, home)[0].slice(2);
+        return command('ssh-keygen', ['-Y', 'sign', '-n', 'git', '-f', file], { input: payload });
+    }
+    const context = H.signing, key = context.resolve(id(H.name), id(who));
+    const identity = context.signer.publicIdentity(key), publicKey = parseKey(identity.key);
+    if (who === 'operator' && publicKey.line !== rootKey(H).line)
+        fail('the local operator key does not match this hub\'s pinned root');
+    const signature = context.signer.sign({ key, payload: Buffer.isBuffer(payload) ? payload : Buffer.from(payload), namespace: 'git', interaction: 'forbidden', deadline: performance.now() + 30000 });
+    if (signature.format !== 'ssh' || signature.namespace !== 'git' || signature.fingerprint !== publicKey.fp)
+        fail('the signer returned an incompatible signature identity or format');
+    return Buffer.from(signature.bytes).toString('utf8');
+};
+// The legacy constructor path already asked Git to sign; only an injected provider uses the neutral byte bridge.
+export const signCommit = (H, who, sha, home) => {
+    if (!H.signing || !isRemote(H))
+        return sha;
+    const raw = git(H, ['cat-file', 'commit', sha], { raw: true }), end = raw.indexOf('\n\n');
+    if (end < 0)
+        fail('malformed unsigned commit');
+    const signature = signBytes(H, who, raw, home).trimEnd().replace(/\n/g, '\n ');
+    const body = Buffer.concat([raw.subarray(0, end), Buffer.from(`\ngpgsig ${signature}\n\n`), raw.subarray(end + 2)]);
+    const signed = git(H, ['hash-object', '-t', 'commit', '-w', '--stdin'], { input: body }).trim();
+    checkSignature(H, signed, who, identityKey(H, who, home));
+    return signed;
+};
+export const signedTag = (H, who, tag, target, home) => {
+    const tagger = git(H, ['var', 'GIT_COMMITTER_IDENT'], { env: ident(who) }).trim();
+    const raw = `object ${target}\ntype commit\ntag ${tag}\ntagger ${tagger}\n\n`;
+    const signed = git(H, ['mktag'], { input: raw + signBytes(H, who, raw, home) }).trim();
+    checkSignature(H, signed, who, identityKey(H, who, home), 'tag');
+    return signed;
+};
+//# sourceMappingURL=signing.js.map

package/target/esm/adapters/transport-git/tags.js

@@ -0,0 +1,21 @@
+// tags: signal tags as git lists them, and an annotated tag object read whole.
+const SIGNAL_REF = /^refs\/tags\/([a-z0-9]+(?:[_-][a-z0-9]+)*)\.([a-z][a-z0-9.-]*\.[0-9a-f]{12})$/;
+// `for-each-ref` lines `<ref> <object> <type>` of tags named `<actor>.<signal>.<message12>`, but for heartbeats.
+export const signalTags = (listing, heartbeat) => listing.split('\n').flatMap(line => {
+    const [ref, object, type] = line.split(' ');
+    const m = SIGNAL_REF.exec(ref ?? '');
+    return m && !heartbeat(ref) ? [{ ref, actor: m[1], name: m[2], object, type }] : [];
+});
+// A tag object's target commit, tagger and time, and its text without a signature.
+export const tagObject = (body) => {
+    const split = body.indexOf('\n\n');
+    const hdr = body.subarray(0, split < 0 ? body.length : split).toString('utf8');
+    const tagger = /^tagger (.*?) <[^>\n]*> (\d+) [+-]\d{4}$/m.exec(hdr);
+    return {
+        target: /^object ([0-9a-f]+)\ntype commit$/m.exec(hdr)?.[1] ?? '',
+        tagger: tagger?.[1] ?? '',
+        time: Number(tagger?.[2] ?? NaN),
+        text: split < 0 ? '' : body.subarray(split + 2).toString('utf8').split('-----BEGIN SSH SIGNATURE-----')[0],
+    };
+};
+//# sourceMappingURL=tags.js.map

package/target/esm/adapters/transport-git/transport.js

@@ -0,0 +1,29 @@
+// transport: the git store as a store type: a hub's repository is `store/.git` in the hub's directory; a signed hub's
+// root key is made here (remote/keys.ts) and a published hub is replicated by bootstrap (remote/bootstrap.ts).
+import path from 'node:path';
+import { GitStore } from './index.js';
+import * as Remote from './remote.js';
+const context = (d, opt) => d.trust === 'signed'
+    ? typeof opt.signer === 'function' ? opt.signer() : opt.signer
+    : undefined;
+// `home`: where this machine keeps its state; the git store keeps its keys and scratch indexes there.
+export const gitTransport = (home, opt = {}) => ({
+    // One branch per room with its messages and control records, signals as tags on them (hub-1, Layout).
+    layout: 'git/2',
+    // Before contracts named it: ringi 0.1 kept a room as branches under `<room>/` (git/1).
+    layoutOf: store => store.roomBranches().some(b => b.includes('/')) ? 'git/1' : 'git/2',
+    open: (at, d) => new GitStore(at, d, home, context(d, opt)),
+    create: (at, d, genesis) => {
+        const signing = context(d, opt);
+        if (d.trust === 'signed')
+            d.root = GitStore.rootFor(at, d, home, signing);
+        const g = genesis(d);
+        const store = GitStore.create(at, d, { home, signing }, g.files, g.text);
+        if (d.trust === 'signed')
+            d.genesis = store.contractHead();
+        const custody = d.trust !== 'signed' ? null : signing ? signing.custody?.(d.name, 'operator') ?? null : path.join(home, 'keys', d.name, 'operator');
+        return { store, custody };
+    },
+    attach: (name, url, pins) => { Remote.hubAdd({ home, name, url, ...pins }); },
+});
+//# sourceMappingURL=transport.js.map

package/target/esm/adapters/transport-kafka/index.js

@@ -0,0 +1,4 @@
+import { fail } from '../../lib/index.js';
+const planned = (d) => fail(`hub ${d.name}: the kafka store is planned and not implemented in this ringi`);
+export const kafka = { layout: 'kafka/1', open: (_at, d) => planned(d), create: (_at, d) => planned(d) };
+//# sourceMappingURL=index.js.map

package/target/esm/adapters/transport-temporal/index.js

@@ -0,0 +1,4 @@
+import { fail } from '../../lib/index.js';
+const planned = (d) => fail(`hub ${d.name}: the temporal store is planned and not implemented in this ringi`);
+export const temporal = { layout: 'temporal/1', open: (_at, d) => planned(d), create: (_at, d) => planned(d) };
+//# sourceMappingURL=index.js.map

package/target/esm/cli.js

@@ -1,13 +1,14 @@
 #!/usr/bin/env node
-// The `ringi` executable. The interface itself is cli/; this file only runs it when started as a program.
+// The `ringi` executable. The interface itself is clients/cli/, put together by composition/; this file only runs it
+// when started as a program.
 import fs from 'node:fs';
 import { fileURLToPath } from 'node:url';
-import { main } from './cli/index.js';
-import { Fail } from './lib/index.js';
+import './composition/index.js';
+import { failure, main } from './clients/cli/index.js';
 export { main };
 if (process.argv[1] && fs.realpathSync(process.argv[1]) === fileURLToPath(import.meta.url)) {
     main().catch(e => {
-        process.stderr.write(`ringi: ${e instanceof Fail ? e.message : e.stack}\n`);
+        process.stderr.write(`ringi: ${failure(e)}\n`);
         process.exitCode = 1;
     });
 }

package/target/esm/{cli/agent.js → clients/cli/agent/index.js}

@@ -1,9 +1,10 @@
-// Agent interface: parse options, call the app, render its result.
-import * as Agent from '../app/agent.js';
-import { asJson, render } from '../app/view.js';
-import { fail, short, when } from '../lib/index.js';
-import { dump, flag, list, opt, out, textOf } from './args.js';
-import { scopeLine, waiting } from './shared.js';
+// agent: the commands only an agent runs, as the agent its session is bound to (`ringi agent inbox`, whoami, card,
+// ping, wait, take); joining and leaving a room are session.ts.
+import * as Agent from '../../../core/agents/sessions/agent.js';
+import { asJson, render } from '../../../core/hub/usecases/view.js';
+import { fail, short, when } from '../../../lib/index.js';
+import { dump, flag, list, opt, out, textOf } from '../args.js';
+import { scopeLine, waiting } from '../shared/index.js';
 const options = (o) => ({ peek: flag(o, 'peek'), limit: opt(o, 'limit') ? Number(opt(o, 'limit')) : undefined });
 export const showInbox = ({ R, me, s }, res, o) => {
     if (flag(o, 'json'))
@@ -43,4 +44,4 @@ export const wait = async (a, o) => {
     out(`wait: nothing for ${a.me} in ${Math.round(r.seconds)}s`);
     process.exitCode = 3;
 };
-//# sourceMappingURL=agent.js.map
+//# sourceMappingURL=index.js.map