@idleware/ringi 0.5.0 → 0.6.1

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

@@ -0,0 +1,128 @@
+// git-store: the Store port on git. The store directory holds one repository (`store/.git`):
+//   refs/heads/main                       the shared contract, one commit per amendment
+//   refs/heads/<room>                     the room: one linear branch, like a chat. Its first commit is the room's genesis
+//                                         (the root's, on top of main); then every message is a commit by its author, and
+//                                         every control record (Kind: room) a commit by the root
+//   refs/tags/<agent>.<signal>.<message12>   signals: annotated tags without text on the message's commit
+//   refs/archive/<room>@<genesis8>        an archived room, read-only
+//   refs/ringi/accepted/<genesis>/<reader>/<author>   readers' pins of each author's accepted last message
+// A member's log is its own commits in the room's branch, in branch order. The control files at the root of a room's
+// tree (members, profile, signers) change only in the root's control records.
+// A signed hub signs every commit and tag with its author's key and verifies what it fetches (remote.ts).
+// The class is layered by concern: repo.ts (repository, contract), branches.ts (rooms), marks.ts (signals, heartbeats)
+// and here the logs: messages, their files, staging and pins.
+import fs from 'node:fs';
+import path from 'node:path';
+import { fail } from '../../lib/index.js';
+import { mkdirIn } from '../fs/index.js';
+import * as Remote from './remote.js';
+import { runGitRaw, splitBuf } from './run.js';
+import { messageFiles } from './files.js';
+import { init } from './repo.js';
+import { CONTROL_FILES } from './branches.js';
+import { Marks } from './marks.js';
+export { runGit } from './run.js';
+import { TEXT_MAX, checkOutgoing } from '../../core/hub/protocol/index.js';
+export class GitStore extends Marks {
+    type = 'git';
+    static create(hubDir, d, connection, contract, text) {
+        const { home, signing } = typeof connection === 'string' ? { home: connection, signing: undefined } : connection;
+        const dir = path.join(hubDir, d.store.path, '.git');
+        // A signed hub's repository already exists: rootFor made it with the root key.
+        if (!fs.existsSync(dir)) {
+            mkdirIn(home, path.dirname(dir));
+            init(dir, home);
+        }
+        const s = new GitStore(hubDir, d, home, signing);
+        const sha = s.commit('operator', text, s.tree(null, Object.entries(contract).map(([p, c]) => ({ path: p, content: c, mode: '100644' }))), []);
+        if (d.trust === 'signed')
+            d.genesis = sha;
+        if (!s.advance('refs/heads/main', sha, null))
+            fail(`hub ${d.name}: main already exists`);
+        s.checkout();
+        return s;
+    }
+    // A new signed hub: the root key is generated on this machine and pinned in the descriptor.
+    static rootFor(hubDir, d, home, signing) {
+        const dir = path.join(hubDir, d.store.path, '.git');
+        mkdirIn(home, path.dirname(dir));
+        init(dir, home);
+        return Remote.setupSigned({ name: d.name, dir, d, signing }, home, d.store.remote).root;
+    }
+    logIds(room) { return [...new Set(this.live(room).map(e => e.author))]; }
+    logHead(room, id) { return this.live(room).filter(e => e.author === id).at(-1)?.sha ?? null; }
+    // One author's messages after the genesis up to `head`, oldest first, read as bytes: the text is the commit message,
+    // the files are the explicit Ringi-Files list, or the paths the commit adds or changes for records without it.
+    messages(room, id, head) {
+        const tip = this.trust === 'signed' ? this.tip(room.name) : null;
+        const skipped = new Set(tip ? this.entries(room, tip).filter(e => e.skipped).map(e => e.sha) : []);
+        const raw = runGitRaw(this.args(['log', '--topo-order', '--reverse', '--no-renames', '--raw', '--no-abbrev', '--format=%x1e%H%x1f%P%x1f%ct%x1f', head, `^${room.genesis}`]), this.home);
+        const records = splitBuf(raw, 0x1e).filter(b => b.length).map(rec => splitBuf(rec, 0x1f));
+        const commits = new Map(Remote.readCommits(this.h, records.map(([sha]) => sha.toString())).map(c => [c.sha, c]));
+        const lsTree = (sha) => runGitRaw(this.args(['ls-tree', '-r', '-z', sha]), this.home);
+        // The author's own messages: no control record, nothing a signed hub skips.
+        const own = (sha, author, body) => author === id && !skipped.has(sha) && !this.isControl(room, sha, id, body.toString('utf8'));
+        return records.flatMap(([sha, parent, ct, rest = Buffer.alloc(0)]) => {
+            const { author, body } = commits.get(sha.toString());
+            if (!own(sha.toString(), author, body))
+                return [];
+            return [{ id: sha.toString(), parent: parent.toString() || null, time: Number(ct.toString()), text: body,
+                    ...messageFiles(body, rest, sha.toString(), x => this.isRef(x), lsTree) }];
+        });
+    }
+    blob(file) {
+        const id = this.git(['hash-object', '-w', '--', file]).trim();
+        return { id, size: Number(this.git(['cat-file', '-s', id]).trim()) };
+    }
+    // A tree of the staged files under refs/ringi/staged/<genesis>/<who>: git keeps what a ref reaches.
+    retain(room, who, entries) {
+        const ref = `refs/ringi/staged/${room.genesis}/${who}`;
+        if (!entries.length) {
+            this.gitOk(['update-ref', '-d', ref]);
+            return;
+        }
+        this.git(['update-ref', ref, this.tree(null, entries)]);
+    }
+    // One message on top of the room's branch.
+    append(room, who, text, entries) {
+        if (room.archived)
+            fail(`room ${room.name} is archived: read-only`);
+        if (checkOutgoing(text, s => this.isRef(s)).trailers['ringi-files'])
+            fail('Ringi-Files is store metadata; supply attachments instead');
+        const own = entries.find(e => CONTROL_FILES.has(e.path));
+        if (own)
+            fail(`${own.path} is the room's own file; attach it under another path`);
+        if (entries.length)
+            text = `${text.trimEnd()}\nRingi-Files: ${JSON.stringify([...new Set(entries.map(e => e.path))])}\n`;
+        if (Buffer.byteLength(text) > TEXT_MAX)
+            fail('attachment list makes the message exceed 64 KiB; use fewer or shorter paths');
+        checkOutgoing(text, s => this.isRef(s));
+        return this.onTop(room, who, text, entries);
+    }
+    verifyLog(room, id, head) {
+        return this.trust === 'signed' ? Remote.verify(this.h, this.remote(room), id, head) : null;
+    }
+    pin(room, reader, id, rev) {
+        if (!room.archived)
+            this.git(['update-ref', `refs/ringi/accepted/${room.genesis}/${reader}/${id}`, rev]);
+    }
+    unpin(room, reader, id) {
+        this.gitOk(['update-ref', '-d', `refs/ringi/accepted/${room.genesis}/${reader}/${id}`]);
+    }
+    file(rev, p) { return runGitRaw(this.args(['show', `${rev}:${p}`]), this.home); }
+    sizes(rev, paths) {
+        if (!paths.length)
+            return new Map();
+        const wanted = new Set(paths);
+        return new Map(splitBuf(runGitRaw(this.args(['ls-tree', '-r', '-l', '-z', rev]), this.home), 0)
+            .map(b => /^\d+ blob [0-9a-f]+ +(\d+)\t(.*)$/s.exec(b.toString('utf8'))).filter((x) => !!x)
+            .filter(([, , p]) => wanted.has(p)).map(([, n, p]) => [p, Number(n)]));
+    }
+    admit(room, who, key) { return Remote.roomAdmit(this.h, this.remote(room), who, key, this.home); }
+    joinKey(room, who) { return Remote.join(this.h, this.remote(room), who, this.home); }
+    // A room's transport alarm is the room's, whichever author the operator forgets.
+    forgetLog(room, _id) { Remote.forget(this.h, this.remote(room)); }
+    rootKey() { return this.d.root ?? fail(`hub ${this.d.name} has no pinned root`); }
+    rootRoster() { return Remote.rootRoster(this.h); }
+}
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1,88 @@
+// marks: tags on a room's commits. Signals are immutable annotated tags `<agent>.<signal>.<message12>`; a heartbeat is
+// one mutable tag `<agent>.heartbeat.<genesis12>` per agent and room, replaced on every beat.
+import * as Remote from './remote.js';
+import { signedTag } from './signing.js';
+import { ZERO, frames, ident, runGitRaw } from './run.js';
+import { signalTags, tagObject } from './tags.js';
+import { Branches } from './branches.js';
+import { fail, note } from '../../lib/index.js';
+export class Marks extends Branches {
+    // The heartbeat of `who` in the room: a tag `<who>.heartbeat.<genesis12>` on the room's last commit here, its text the
+    // facts of the beat (core/agents/heartbeat). Each beat replaces the object under the same name, compare-and-swap on the one it
+    // read, so two writers do not overwrite each other blindly. No reader pins it; its replacement is no alarm.
+    // On a signed hub the object is signed by `who` and published with the OID it replaced; a newer beat there wins, and
+    // this one is taken back here (remote.ts).
+    heartbeat(room, who, target, text) {
+        const ref = Remote.heartbeatRef(who, room.genesis), name = ref.slice('refs/tags/'.length);
+        const old = this.rev(`${ref}^{tag}`) ? this.git(['rev-parse', ref]).trim() : null;
+        const obj = this.trust === 'signed' ? Remote.makeHeartbeat(this.h, this.remote(room), who, target, text, this.home)
+            : this.git(['mktag'], { input: `object ${target}\ntype commit\ntag ${name}\ntagger ${who} <${who}@ringi> ${Math.floor(Date.now() / 1000)} +0000\n\n${text}` }).trim();
+        if (this.gitOk(['update-ref', ref, obj, old ?? ZERO]).status !== 0)
+            fail(`${name} moved meanwhile; the next beat writes it`);
+        if (this.trust === 'signed' && !Remote.pushHeartbeat(this.h, this.remote(room), who, obj, old))
+            this.gitOk(['update-ref', ...(old ? [ref, old, obj] : ['-d', ref, obj])]);
+        return obj;
+    }
+    // The room's heartbeats as they stand: whose, on which commit, when, and what they say.
+    heartbeats(room) {
+        const g12 = room.genesis.slice(0, 12);
+        const tags = this.git(['for-each-ref', '--format=%(refname) %(objectname) %(objecttype)', 'refs/tags/']).split('\n')
+            .map(l => l.split(' ')).filter(([ref, , type]) => type === 'tag' && Remote.heartbeatName(ref ?? '')?.genesis12 === g12);
+        const objects = this.tagObjects(tags.map(([, object]) => object));
+        // On a signed hub only a verified beat shows.
+        const ok = (ref, object) => this.trust !== 'signed' || !Remote.verifyHeartbeat(this.h, this.remote(room), ref, object);
+        return tags.flatMap(([ref, object]) => {
+            const o = objects.get(object);
+            return o && ok(ref, object) ? [{ agent: Remote.heartbeatName(ref).actor, target: o.target, time: o.time, text: o.text }] : [];
+        });
+    }
+    // An annotated tag without text in its author's namespace, on the message's commit, signed on a signed hub. The
+    // message's id in the name keeps it unique, so writing the same signal twice is a no-op.
+    signal(room, who, target, name) {
+        const tag = `${who}.${name}`;
+        const ref = `refs/tags/${tag}`;
+        if (this.gitOk(['rev-parse', '-q', '--verify', ref]).status === 0) {
+            Remote.push(this.h, ref);
+            return;
+        }
+        if (this.h.signing)
+            this.git(['update-ref', ref, signedTag(this.h, who, tag, target, this.home), ZERO]);
+        else {
+            const sign = Remote.sign(this.h, who, this.home);
+            const key = sign[0]?.slice(2);
+            this.git([...(key ? ['-c', `user.signingkey=${key}`] : []), 'tag', key ? '-s' : '-a', '-F', '-', tag, target], { input: '', env: ident(who) });
+        }
+        Remote.push(this.h, ref);
+    }
+    // The tags named `<actor>.<signal>.<message12>`, with the objects they name; a heartbeat is no signal (heartbeats()).
+    tags() {
+        return signalTags(this.git(['for-each-ref', '--format=%(refname) %(objectname) %(objecttype)', 'refs/tags/']), ref => !!Remote.heartbeatName(ref));
+    }
+    // Annotated tag objects read whole (run.ts frames): their target, tagger and text are never split on bytes they hold.
+    tagObjects(shas) {
+        if (!shas.length)
+            return new Map();
+        const raw = runGitRaw(this.args(['cat-file', '--batch']), this.home, Buffer.from(shas.join('\n') + '\n'));
+        return new Map([...frames(raw, shas)].filter(([, f]) => f.type === 'tag').map(([sha, f]) => [sha, tagObject(f.body)]));
+    }
+    signals(room) {
+        const tags = this.tags(), objects = this.tagObjects(tags.filter(t => t.type === 'tag').map(t => t.object));
+        const mine = this.commitsOf(room);
+        const records = tags.flatMap(t => {
+            const o = objects.get(t.object);
+            // Only an annotated tag on a commit is a signal; anything else points nowhere.
+            if (!mine.has(o?.target || t.object))
+                return [];
+            return [{ ref: t.ref, object: t.object, name: t.name, actor: t.actor, target: o?.target ?? '', tagger: o?.tagger ?? '', text: o?.text ?? '' }];
+        });
+        if (this.trust !== 'signed' || room.archived)
+            return records;
+        return Remote.withVerification(this.h, () => records.filter(s => {
+            const why = Remote.verifySignal(this.h, this.remote(room), s.ref, s.object);
+            if (why)
+                note(`ALARM signal ${s.ref}: ${why}; quarantined and withheld`);
+            return !why;
+        }));
+    }
+}
+//# sourceMappingURL=marks.js.map

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

@@ -0,0 +1,71 @@
+// admit: a member's key on a signed hub: made on its machine (join) and admitted by the root in a control record.
+import * as C from '../../../lib/index.js';
+import * as P from '../../../core/hub/protocol/index.js';
+import { branch, verifyRoom } from './branch.js';
+import { git, id, ident, isRemote, locked, rev } from './git.js';
+import { keyInput, identityKey, sign, signerLine } from './keys.js';
+import { signCommit } from '../signing.js';
+import { push } from './push.js';
+import { CONTROL_FILES, ROOT } from './types.js';
+export const join = (H, R, who, home) => {
+    const room = verifyRoom(H, R);
+    const key = locked(H, () => identityKey(H, who, home, true));
+    const admitted = !!room.entries.find(e => e.principal === who && e.key.line === key.line);
+    return { publicKey: key.line, fingerprint: key.fp, admitted };
+};
+// A tree from `base` with the control files as `control` has them, then `patches` on top.
+const treeWith = (H, base, control, patches) => {
+    const entries = (sha) => new Map(git(H, ['ls-tree', sha]).trim().split('\n').filter(Boolean).map(line => {
+        const m = /^(\d+) (\w+) ([0-9a-f]+)\t(.+)$/.exec(line) ?? C.fail('malformed room tree');
+        return [m[4], line];
+    }));
+    const files = entries(base), kept = entries(control);
+    for (const name of CONTROL_FILES) {
+        files.delete(name);
+        if (kept.has(name))
+            files.set(name, kept.get(name));
+    }
+    for (const [name, content] of Object.entries(patches))
+        files.set(name, `100644 blob ${git(H, ['hash-object', '-w', '--stdin'], { input: content }).trim()}\t${name}`);
+    return git(H, ['mktree'], { input: [...files].sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0).map(([, line]) => line).join('\n') + '\n' }).trim();
+};
+// The root's control record admitting a member, on top of the room's branch: the key and the member go in together.
+export const roomAdmit = (H, R, who, publicKey, home) => {
+    const key = admissionKey(H, R, who, publicKey);
+    for (let attempt = 0; attempt < 8; attempt++) {
+        const tip = rev(H, R.ref) ?? C.fail('room branch is missing');
+        const room = branch(H, R, tip), head = room.control.at(-1);
+        if (room.entries.some(e => e.principal === who || e.key.fp === key.fp))
+            C.fail('principal or key is already admitted; key rotation is not implemented');
+        const { sha, members } = admissionCommit({ H, R, who, home, tip, head, room, key });
+        if (git(H, ['update-ref', R.ref, sha, tip], { ok: true }).status !== 0)
+            continue;
+        if (!push(H, R.ref, { behind: true }))
+            continue;
+        R.head = sha;
+        R.members = members;
+        return sha;
+    }
+    return C.fail('room kept moving while admitting; retry');
+};
+const admissionCommit = ({ H, who, home, tip, head, room, key }) => {
+    const members = { ...room.members, [who]: { role: 'member', since: new Date().toISOString() } };
+    const roster = [...room.entries.map(e => signerLine(e.principal, e.key)), signerLine(who, key)].join('');
+    const tree = treeWith(H, tip, head, { 'members.json': JSON.stringify(members, null, 2) + '\n', allowed_signers: roster });
+    const sha = git(H, ['commit-tree', ...(H.signing ? [] : sign(H, ROOT, home)), tree, '-p', tip], {
+        input: P.compose(`admit ${who}`, [['To', '*'], ['Kind', 'room'], ['Key', key.fp]]), env: ident(ROOT),
+    }).trim();
+    return { sha: signCommit(H, ROOT, sha, home), members };
+};
+const admissionKey = (H, R, who, publicKey) => {
+    id(who);
+    if (!isRemote(H))
+        C.fail('room admit is for signed hubs; local membership is added by join');
+    if (who === ROOT)
+        C.fail('the root is already pinned; root replacement requires a separate trust transition');
+    if (R.archived)
+        C.fail('cannot admit into an archived room');
+    const key = keyInput(publicKey);
+    return key;
+};
+//# sourceMappingURL=admit.js.map

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

@@ -0,0 +1,30 @@
+// alarms: what a rejected push left to say, kept per hub until the next sync settles it.
+import fs from 'node:fs';
+import path from 'node:path';
+import * as C from '../../../lib/index.js';
+import * as FS from '../../fs/index.js';
+import { mkdir } from './git.js';
+const pushAlarmsFile = (H) => path.join(H.dir, 'ringi', 'push-alarms.json');
+const alarmState = (text, label) => {
+    const value = C.strictJson(text, label);
+    if (!value || typeof value !== 'object' || Array.isArray(value) || !Object.values(value).every(v => typeof v === 'string'))
+        C.fail(`${label}: expected an object of alarm strings`);
+    return value;
+};
+export const savePushAlarms = (H, alarms) => {
+    const file = pushAlarmsFile(H);
+    mkdir(path.dirname(file));
+    FS.writeJsonAtomic(file, alarms);
+};
+export const pushAlarms = (H) => {
+    const file = pushAlarmsFile(H);
+    try {
+        return alarmState(fs.readFileSync(file, 'utf8'), file);
+    }
+    catch (e) {
+        if (C.errno(e) !== 'ENOENT')
+            throw e;
+        return {};
+    }
+};
+//# sourceMappingURL=alarms.js.map

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

@@ -0,0 +1,47 @@
+// bootstrap: a replica of a published signed hub, verified against the root and genesis the operator gives out of
+// band before its descriptor is written.
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import * as C from '../../../lib/index.js';
+import { id, mkdir } from './git.js';
+import { checkUrl, keyInput } from './keys.js';
+import { command } from './process.js';
+import { sync } from './sync.js';
+import { SHA } from './types.js';
+export const hubAdd = ({ home, name, url, root, genesis }) => {
+    id(name);
+    checkUrl(url);
+    if (!root)
+        C.fail('hub add requires --root <public-key|file> from the operator; a key advertised by the hub is not a trust anchor');
+    const key = keyInput(root ?? C.fail('hub add requires --root <public-key|file>'));
+    if (genesis && !SHA.test(genesis))
+        C.fail('--genesis must be a full commit id');
+    // A hub is a descriptor (hub.json) beside its store; for a git store the repository is store/.git.
+    const hubDir = path.join(home, 'hub', name);
+    const dir = path.join(hubDir, 'store', '.git');
+    if (fs.existsSync(hubDir))
+        C.fail(`hub ${name} exists`);
+    mkdir(path.dirname(dir));
+    const stage = path.join(home, 'hub', `.${name}.${process.pid}.${crypto.randomBytes(4).toString('hex')}.git`);
+    try {
+        command('git', ['init', '--bare', '-q', '-b', 'main', stage]);
+        const descriptor = {
+            schema: 'ringi-hub/2', name, trust: 'signed', root: key.line, genesis,
+            store: { type: 'git', path: 'store', remote: url }
+        };
+        const H = { name, dir: stage, d: descriptor, bootstrap: !genesis };
+        sync(H);
+        fs.renameSync(stage, dir);
+        fs.writeFileSync(path.join(hubDir, 'hub.json'), JSON.stringify(descriptor, null, 2) + '\n', { mode: 0o600 });
+        return dir;
+    }
+    finally {
+        if (fs.existsSync(stage))
+            fs.rmSync(stage, { recursive: true, force: true });
+        // A failed add leaves no half-made hub behind (the directory did not exist before).
+        if (!fs.existsSync(dir))
+            fs.rmSync(hubDir, { recursive: true, force: true });
+    }
+};
+//# sourceMappingURL=bootstrap.js.map

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

@@ -0,0 +1,36 @@
+// branch-commit: one commit of a room's branch, judged: a control record, a valid message of an admitted author, or
+// skipped with the reason.
+import * as C from '../../../lib/index.js';
+import { acceptControl, broken, isControl } from './branch-control.js';
+import { reason } from './git.js';
+import { checkSignature } from './signature.js';
+const acceptMessage = (s, c) => {
+    const signer = s.roster.entries.find(e => e.principal === c.author) ?? C.fail(`${c.author || 'its author'} is unadmitted in this room`);
+    if (s.touching.has(c.sha))
+        C.fail('it changes the room\'s control files, which only the root changes');
+    checkSignature(s.H, c.sha, c.author, signer.key);
+    s.authors.set(c.sha, c.author);
+};
+const fatal = (s, c, e) => {
+    if (!(e instanceof C.Fail))
+        return true;
+    const brokenRoom = c === s.genesis || e.broken;
+    return !!brokenRoom || C.errno(e) === 'ETIMEDOUT';
+};
+export const visitCommit = (s, c) => {
+    if (c.parents.length !== 1 || c.parents[0] !== s.parent)
+        throw broken('a merge or non-linear history; a room is one linear branch');
+    s.parent = c.sha;
+    try {
+        if (isControl(s, c))
+            acceptControl(s, c);
+        else
+            acceptMessage(s, c);
+    }
+    catch (e) {
+        if (fatal(s, c, e))
+            throw e;
+        s.skipped.set(c.sha, reason(e));
+    }
+};
+//# sourceMappingURL=branch-commit.js.map

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

@@ -0,0 +1,37 @@
+// branch-control: root-signed control records and the room's roster, as a branch scan meets them.
+import * as C from '../../../lib/index.js';
+import * as P from '../../../core/hub/protocol/index.js';
+import { reason } from './git.js';
+import { rootKey } from './keys.js';
+import { rosterAt } from './roster.js';
+import { checkSignature } from './signature.js';
+import { ROOT, SHA } from './types.js';
+export const broken = (why) => Object.assign(new C.Fail(why), { broken: true });
+export const isControl = (s, c) => c === s.genesis || (c.author === ROOT && P.parse(c.text, x => SHA.test(x)).kind === 'room');
+const rootSignature = (s, c) => {
+    try {
+        checkSignature(s.H, c.sha, ROOT, rootKey(s.H));
+    }
+    catch (e) {
+        if (c === s.genesis || C.errno(e) === 'ETIMEDOUT')
+            throw e;
+        C.fail(`${reason(e)}; only the root writes control records`);
+    }
+};
+export const acceptControl = (s, c) => {
+    rootSignature(s, c);
+    let next;
+    try {
+        next = rosterAt(s.H, c.sha);
+    }
+    catch (e) {
+        throw broken(reason(e));
+    }
+    for (const e of s.roster.entries) {
+        if (!next.entries.some(n => n.principal === e.principal && n.key.line === e.key.line))
+            throw broken('room roster drops or changes an admitted key; revocation/freeze is not implemented');
+    }
+    s.roster = next;
+    s.control.push(c.sha);
+};
+//# sourceMappingURL=branch-control.js.map

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

@@ -0,0 +1,28 @@
+// branch-scan: a room's branch scanned from its genesis to a tip.
+import * as C from '../../../lib/index.js';
+import { visitCommit } from './branch-commit.js';
+import { readCommits } from './commits.js';
+import { git } from './git.js';
+import { verifyHub } from './main.js';
+import { CONTROL_FILES } from './types.js';
+export const scanBranch = (H, name, tip) => {
+    const main = verifyHub(H) ?? C.fail('room verification requires a signed hub');
+    const shas = git(H, ['rev-list', '--first-parent', '--reverse', tip, `^${main.head}`]).trim().split('\n').filter(Boolean);
+    if (!shas.length)
+        C.fail(`room ${name} has no genesis`);
+    const list = readCommits(H, shas), genesis = list[0];
+    if (genesis.parents.length !== 1 || !main.commits.includes(genesis.parents[0]))
+        C.fail('room does not descend from the verified hub contract');
+    const touching = new Set(git(H, ['log', '--first-parent', '--format=%H', tip, `^${main.head}`, '--', ...CONTROL_FILES]).trim().split('\n').filter(Boolean));
+    const scan = {
+        H, genesis, touching, parent: genesis.parents[0], roster: { entries: [], members: {} },
+        control: [], authors: new Map(), skipped: new Map()
+    };
+    for (const c of list)
+        visitCommit(scan, c);
+    return {
+        genesis: genesis.sha, subject: genesis.text.split('\n')[0], ...scan.roster,
+        control: scan.control, authors: scan.authors, skipped: scan.skipped
+    };
+};
+//# sourceMappingURL=branch-scan.js.map

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

@@ -0,0 +1,37 @@
+// branch: a room's branch as verified up to a tip, kept per tip; its roster, and why a log's head is not valid.
+import * as C from '../../../lib/index.js';
+import { scanBranch } from './branch-scan.js';
+import { memo } from './cache.js';
+import { isRemote, reason } from './git.js';
+// Memoize by immutable tip; ref names and expected genesis are checked outside the cache.
+export const branchData = (H, name, tip, expectedGenesis) => {
+    const data = memo(H, `branch/${tip}`, () => scanBranch(H, name, tip));
+    if (data.subject !== `room ${name}`)
+        C.fail(`room genesis subject must be "room ${name}"`);
+    if (expectedGenesis && data.genesis !== expectedGenesis)
+        C.fail('room changed its genesis');
+    return data;
+};
+// The room's branch verified up to `tip`; a quarantined room is not read.
+export const branch = (H, R, tip) => {
+    if (!isRemote(H))
+        C.fail('room verification requires a signed hub');
+    if (H.remoteAlarms?.[R.ref])
+        C.fail(`ALARM ${H.remoteAlarms[R.ref]}; room is quarantined`);
+    return branchData(H, R.name, tip, R.genesis);
+};
+// The roster in effect at the room's latest control record.
+export const verifyRoom = (H, R) => branch(H, R, R.head);
+// Why `head` is not a valid message of `who`, or null.
+export const verify = (H, R, who, head) => {
+    if (!isRemote(H))
+        return null;
+    try {
+        const b = branch(H, R, head);
+        return b.authors.get(head) === who ? null : b.skipped.get(head) ?? `${head.slice(0, 12)} is not a message of ${who}`;
+    }
+    catch (e) {
+        return reason(e);
+    }
+};
+//# sourceMappingURL=branch.js.map

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

@@ -0,0 +1,23 @@
+// cache: checks of immutable heads reused within one operation; nothing survives into the next one.
+// Reuse immutable-head checks within one operation; no ref or alarm survives into the next one.
+const checking = new WeakMap();
+export const withVerification = (H, fn) => {
+    if (checking.has(H))
+        return fn();
+    checking.set(H, new Map());
+    try {
+        return fn();
+    }
+    finally {
+        checking.delete(H);
+    }
+};
+export const memo = (H, key, fn) => {
+    const cache = checking.get(H);
+    if (cache?.has(key))
+        return cache.get(key);
+    const value = fn();
+    cache?.set(key, value);
+    return value;
+};
+//# sourceMappingURL=cache.js.map

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

@@ -0,0 +1,25 @@
+// commits: commit objects read whole: author, parents and message as bytes.
+import * as C from '../../../lib/index.js';
+import * as P from '../../../core/hub/protocol/index.js';
+import { git } from './git.js';
+export const readCommits = (H, shas) => {
+    if (!shas.length)
+        return [];
+    const out = git(H, ['cat-file', '--batch'], { input: Buffer.from(shas.join('\n') + '\n'), raw: true });
+    let at = 0;
+    return shas.map(sha => {
+        const nl = out.indexOf(0x0a, at);
+        const [got, type, size] = out.subarray(at, nl).toString('utf8').split(' ');
+        if (got !== sha || type !== 'commit')
+            C.fail(`malformed commit ${sha.slice(0, 12)}`);
+        const body = out.subarray(nl + 1, nl + 1 + Number(size));
+        at = nl + 1 + Number(size) + 1;
+        const split = body.indexOf(Buffer.from('\n\n'));
+        const hdr = body.subarray(0, split < 0 ? body.length : split).toString('utf8');
+        const parents = [...hdr.matchAll(/^parent ([0-9a-f]+)$/gm)].map(m => m[1]);
+        const author = /^author (.*?) <[^>\n]*> \d+ [+-]\d{4}$/m.exec(hdr)?.[1] ?? '';
+        const message = split < 0 ? Buffer.alloc(0) : body.subarray(split + 2);
+        return { sha, parents, author, body: message, text: P.decodeText(message).text ?? '' };
+    });
+};
+//# sourceMappingURL=commits.js.map

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

@@ -0,0 +1,35 @@
+// forget: after the operator reviews a room's transport alarm, the remote branch becomes the accepted baseline.
+import { pushAlarms, savePushAlarms } from './alarms.js';
+import { branchData } from './branch.js';
+import { accepted, git, isRemote, locked, rev, tracking, zero } from './git.js';
+// Only the operator command calls this after reviewing a room's transport alarm: the room's branch as the remote has
+// it becomes the accepted baseline, and the displaced local branch is kept as evidence. Nothing is waived: the branch
+// must verify, and its invalid commits stay skipped.
+export const forget = (H, R) => {
+    if (!isRemote(H))
+        return;
+    return locked(H, () => {
+        const alarms = pushAlarms(H);
+        if (!alarms[R.ref] && !H.remoteAlarms?.[R.ref])
+            return;
+        replaceBaseline(H, R);
+        delete alarms[R.ref];
+        savePushAlarms(H, alarms);
+        if (H.remoteAlarms)
+            delete H.remoteAlarms[R.ref];
+    });
+};
+const replaceBaseline = (H, R) => {
+    const sha = rev(H, tracking(R.ref));
+    if (sha)
+        branchData(H, R.name, sha, R.genesis);
+    const old = rev(H, R.ref);
+    if (old)
+        git(H, ['update-ref', `refs/ringi/quarantine/${R.genesis}/${old}`, old]);
+    git(H, ['update-ref', '-d', accepted(R.ref)]);
+    if (sha)
+        git(H, ['update-ref', R.ref, sha, old || zero(H)]);
+    else if (old)
+        git(H, ['update-ref', '-d', R.ref, old]);
+};
+//# sourceMappingURL=forget.js.map