Autonomous development for real products. Governed agents build from specs you approve, follow the rules you set, and nothing merges until another agent proves it. Your decisions, judgement and taste are the bar that work must clear. Declare your vision and let agents build it.
JavaScript agentic-codingai-agentsai-governanceautonomous-agentsclaude-codeclicode-reviewcodexcoding-agentsdeveloper-toolsgit-hooksllmlocal-firstmulti-agentsoftware-factoryspec-driven-developmentverificationvibe-coding
feat(links): verify bilateral board consent through SSH [E32,H16]
Corey Olson79d2cca9eff5
diff --git a/src/board-link-format.js b/src/board-link-format.jsnew file mode 100644index 00000000..164c9c2e--- /dev/null+++ b/src/board-link-format.js@@ -0,0 +1,81 @@+/** Canonical bilateral consent and disclosure are independent of transport and key storage [E32,H17]. */+import { Refused } from './refused.js';+import { boardReference } from './board-reference.js';+import { boardReferenceId } from './board-reference.js';++const MODES = ['states', 'counts', 'nothing'];+const STATES = ['open', 'claimed', 'submitted', 'verified', 'withdrawn'];++/** Reject a malformed link rather than normalizing away signed fields. */+export function boardLinkFormat(message) { throw new Refused('BOARD_LINK_FORMAT', `${message}; use the exact version 1 board-link contract`); }++/** Require a bounded correlation or link identifier that cannot become a path. */+export function boardLinkName(value) {+ if (typeof value !== 'string' || !/^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/u.test(value)) boardLinkFormat('Use a bounded link or correlation ID');+ return value;+}++/** Validate the signed body and retain its fixed field order for the existing signature path. */+export function boardLinkBody(value) {+ if (!value || typeof value !== 'object' || Array.isArray(value)+ || Object.keys(value).some(key => !['version', 'linkId', 'parent', 'child', 'generation', 'disclosure', 'approvals', 'revocation'].includes(key))) boardLinkFormat('The link has unsupported fields');+ if (value.version !== 1 || !Number.isSafeInteger(value.generation) || value.generation < 1 || !MODES.includes(value.disclosure)) boardLinkFormat('Use a positive generation and a supported disclosure mode');+ const parent = boardReference(value.parent);+ const child = boardReference(value.child);+ if (parent.boardId === child.boardId) boardLinkFormat('A board cannot link to itself');+ return { version: 1, linkId: boardLinkName(value.linkId), parent, child, generation: value.generation, disclosure: value.disclosure };+}++/** Copy bounded public signature records before any asynchronous authority operation. */+function proof(value) {+ if (!value || typeof value !== 'object' || Array.isArray(value)) boardLinkFormat('Use a signed board approval');+ const allowed = ['version', 'type', 'firstCommit', 'initialHash', 'id', 'file', 'kind', 'source', 'replacement',+ 'text', 'decision', 'reason', 'commit', 'by', 'on', 'note', 'signature', 'boardId'];+ if (Object.keys(value).some(key => !allowed.includes(key))) boardLinkFormat('The approval has unsupported fields');+ let encoded;+ try { encoded = JSON.stringify(value); } catch { boardLinkFormat('Use a JSON signature record'); }+ if (typeof encoded !== 'string' || Buffer.byteLength(encoded) > 20000) boardLinkFormat('The approval exceeds its bound');+ const result = JSON.parse(encoded);+ boardReferenceId(result.boardId);+ return result;+}++/** Copy the complete document without accepting mutable caller-owned signature containers. */+export function boardLinkRecord(value) {+ const body = boardLinkBody(value);+ if (!Array.isArray(value.approvals) || value.approvals.length > 2 || value.revocation === undefined) boardLinkFormat('Include approvals and an explicit revocation field');+ const approvals = value.approvals.map(proof).sort((a, b) => a.boardId.localeCompare(b.boardId));+ if (new Set(approvals.map(row => row.boardId)).size !== approvals.length) boardLinkFormat('Each board approves at most once');+ const ends = [body.parent.boardId, body.child.boardId];+ if (approvals.some(row => !ends.includes(row.boardId))) boardLinkFormat('Only the two endpoint boards approve a link');+ return { ...body, approvals, revocation: value.revocation === null ? null : proof(value.revocation) };+}++/** Bind each side and each action as well as the exact document to the SSH signature. */+export function boardLinkSigningText(body, boardId, action) {+ if (!['approve', 'revoke'].includes(action)) boardLinkFormat('Use a link approval or revocation');+ const normalized = boardLinkBody(body);+ if (![normalized.parent.boardId, normalized.child.boardId].includes(boardReferenceId(boardId))) boardLinkFormat('The signer must be an endpoint board');+ return JSON.stringify(['pullboard-board-link', 1, normalized, boardId, action]);+}++/** Strip forbidden text before persistence or transmission; no caller field survives by default. */+export function discloseBoardState(mode, rows) {+ if (!MODES.includes(mode)) throw new Refused('BOARD_LINK_DISCLOSURE', 'use the link’s signed states, counts or nothing disclosure mode');+ if (!Array.isArray(rows) || rows.length > 10000) boardLinkFormat('Use a bounded item-state array');+ if (mode === 'nothing') return [];+ const selected = rows.map(row => {+ if (!row || !Number.isSafeInteger(row.id) || row.id < 1 || !STATES.includes(row.state)) boardLinkFormat('Use exact numeric item IDs and native item states');+ return { board: boardReferenceId(row.board), id: row.id, state: row.state };+ });+ const seen = new Set();+ for (const row of selected) {+ const key = `${row.board}:${row.id}`;+ if (seen.has(key)) boardLinkFormat('An item appears only once in a state announcement');+ seen.add(key);+ }+ if (mode === 'states') return selected;+ const counts = {};+ for (const row of selected) counts[row.state] = (counts[row.state] ?? 0) + 1;+ return counts;+}diff --git a/src/board-link-ssh.js b/src/board-link-ssh.jsnew file mode 100644index 00000000..381e2139--- /dev/null+++ b/src/board-link-ssh.js@@ -0,0 +1,58 @@+/** Board authority is the existing established SSH row-signature authority [E32,S17,H16]. */+import { Refused } from './refused.js';+import { boardId } from './board-query.js';+import { headCommit } from './git.js';+import { sha256 } from './signature.js';+import { hasSignerFile } from './signature.js';+import { isVerifiedSignoff } from './signature.js';+import { signRowDecision } from './signature.js';+import { verifyRowDecision } from './signature.js';++/** Refuse missing or unverifiable board authority without an unsigned compatibility fallback. */+function unauthorized() { throw new Refused('BOARD_LINK_AUTH', 'obtain this board’s established approver signature through its configured signer authority'); }++/** Keep signature-domain fields identical for signing and verification. */+function fields(text) {+ const id = 'board-link:' + sha256(text);+ return { id, file: '<board-link>', kind: 'board-link', source: text, replacement: '', text: id,+ decision: 'approve', reason: '', note: '' };+}++/**+ * Supply the signer port from trusted board handles and their roots, never message-provided paths.+ * A future verified person-signature adapter can implement the same sign/verify interface.+ */+export function createSshBoardLinkAuthority(boards) {+ if (!Array.isArray(boards)) unauthorized();+ const roots = new Map();+ for (const entry of boards) {+ if (!entry?.board || typeof entry.root !== 'string') unauthorized();+ const id = boardId(entry.board);+ if (roots.has(id)) unauthorized();+ roots.set(id, entry.root);+ }+ /** Resolve only a caller-pinned board and insist that SSH authority is actually enabled. */+ function rootFor(id) {+ const root = roots.get(id);+ if (!root || !hasSignerFile(root)) unauthorized();+ return root;+ }+ return Object.freeze({+ /** Sign without appending or materializing any spec row or decision. */+ sign(id, text, { by, key } = {}) {+ const root = rootFor(id);+ return { ...signRowDecision(root, { ...fields(text), commit: headCommit(root), by,+ on: new Date().toISOString() }, key), boardId: id };+ },+ /** Verify the exact link-domain record using the board's complete established signer history. */+ verify(id, text, receipt) {+ const root = rootFor(id);+ if (!receipt?.signature || receipt.boardId !== id || receipt.type !== 'row-decision') unauthorized();+ for (const [key, value] of Object.entries(fields(text))) if (receipt[key] !== value) unauthorized();+ try { verifyRowDecision(root, receipt); }+ catch (error) { if (error instanceof Refused) unauthorized(); throw error; }+ if (!isVerifiedSignoff(receipt)) unauthorized();+ return true;+ },+ });+}diff --git a/src/board-link.js b/src/board-link.jsnew file mode 100644index 00000000..9df6d80d--- /dev/null+++ b/src/board-link.js@@ -0,0 +1,158 @@+/** Shared board links retain bilateral consent, current generations and a multiple-parent DAG [E32,H16,H17]. */+import { Refused } from './refused.js';+import { atomic } from './board-event-log.js';+import { logEvent } from './board-event-log.js';+import { boardLinkBody } from './board-link-format.js';+import { boardLinkRecord } from './board-link-format.js';+import { boardLinkSigningText } from './board-link-format.js';+import { boardLinkFormat } from './board-link-format.js';+import { boardLinkName } from './board-link-format.js';+import { discloseBoardState } from './board-link-format.js';+export { discloseBoardState } from './board-link-format.js';+export { resolveBoardReference } from './board-reference.js';+export { boardItemReference } from './board-reference.js';++const PREFIX = 'board_link:';++/** Require a genuine authority operation instead of trusting document-supplied keys or flags. */+function authorityMethod(authority, method) {+ if (typeof authority?.[method] !== 'function') throw new Refused('BOARD_LINK_AUTH', 'configure the trusted signer authority for each endpoint board');+ return authority[method].bind(authority);+}++/** Add one real endpoint approval without mutating the caller's document or spec files. */+export async function approveBoardLink(value, boardId, authority, options) {+ const record = boardLinkRecord(value);+ if (record.revocation || record.approvals.some(row => row.boardId === boardId)) {+ throw new Refused('BOARD_LINK_CONFLICT', 'approve each side once; use a new generation after a revocation');+ }+ const text = boardLinkSigningText(record, boardId, 'approve');+ const approval = await authorityMethod(authority, 'sign')(boardId, text, options);+ if (approval?.boardId !== boardId) throw new Refused('BOARD_LINK_AUTH', 'the signer authority must return this exact board’s approval');+ return boardLinkRecord({ ...record, approvals: [...record.approvals, approval] });+}++/** Authenticate both sides over exactly the same body, and any later one-sided revocation. */+export async function verifyBoardLink(value, authority) {+ const record = boardLinkRecord(value);+ if (record.approvals.length !== 2) throw new Refused('BOARD_LINK_AUTH', 'obtain independent approvals from both endpoint boards');+ const verify = authorityMethod(authority, 'verify');+ for (const approval of record.approvals) {+ if (await verify(approval.boardId, boardLinkSigningText(record, approval.boardId, 'approve'), approval) !== true) {+ throw new Refused('BOARD_LINK_AUTH', 'obtain a verified approval from each endpoint board');+ }+ }+ if (record.revocation && await verify(record.revocation.boardId,+ boardLinkSigningText(record, record.revocation.boardId, 'revoke'), record.revocation) !== true) {+ throw new Refused('BOARD_LINK_AUTH', 'obtain the revoking endpoint’s verified signature');+ }+ return record;+}++/** Either board can revoke existing consent without obtaining another signature from its peer. */+export async function revokeBoardLink(value, boardId, authority, options) {+ const record = await verifyBoardLink(value, authority);+ if (record.revocation) return record;+ const text = boardLinkSigningText(record, boardId, 'revoke');+ const revocation = await authorityMethod(authority, 'sign')(boardId, text, options);+ if (revocation?.boardId !== boardId) throw new Refused('BOARD_LINK_AUTH', 'the revoking authority must name its exact board');+ return boardLinkRecord({ ...record, revocation });+}++/** Read a detached catalog of signed records; local paths and project registration add no authority. */+export function readBoardLinks(board) {+ return board.db.prepare('SELECT meta_value FROM board_meta WHERE meta_key>=? AND meta_key<? ORDER BY meta_key')+ .all(PREFIX, 'board_link;').map(row => {+ let document;+ try { document = JSON.parse(row.meta_value); } catch { boardLinkFormat('A stored link record is not JSON'); }+ return boardLinkRecord(document);+ });+}++/** Refuse a directed cycle while retaining multiple independent parents. */+function assertAcyclic(records) {+ const children = new Map();+ for (const record of records.filter(row => !row.revocation)) {+ const parent = record.parent.boardId;+ if (!children.has(parent)) children.set(parent, []);+ children.get(parent).push(record.child.boardId);+ }+ const active = new Set();+ const visited = new Set();+ /** Visit each reachable endpoint once, rejecting an edge into the current ancestry. */+ function visit(id) {+ if (active.has(id)) throw new Refused('BOARD_LINK_CYCLE', 'remove the cycle before approving this parent link');+ if (visited.has(id)) return;+ active.add(id);+ for (const child of children.get(id) ?? []) visit(child);+ active.delete(id); visited.add(id);+ }+ for (const id of children.keys()) visit(id);+}++/**+ * Persist a verified graph transition atomically. Signatures are checked before taking a board write+ * lock; generation, replay and cycle checks then use the catalog under that actual lock.+ */+export async function applyBoardLink(board, value, authority) {+ const record = await verifyBoardLink(value, authority);+ return atomic(board, () => {+ const records = readBoardLinks(board);+ const previous = records.find(row => row.linkId === record.linkId);+ if (previous) {+ if (previous.parent.boardId !== record.parent.boardId || previous.child.boardId !== record.child.boardId+ || record.generation < previous.generation+ || record.generation === previous.generation && JSON.stringify(boardLinkBody(previous)) !== JSON.stringify(boardLinkBody(record))) {+ throw new Refused('BOARD_LINK_CONFLICT', 'retain the link identity and use a newer generation with fresh bilateral consent');+ }+ if (record.generation === previous.generation) {+ if (previous.revocation && !record.revocation) throw new Refused('BOARD_LINK_CONFLICT', 'old consent cannot undo a signed revocation; approve a new generation');+ if (previous.revocation || !record.revocation) return previous;+ }+ }+ assertAcyclic([...records.filter(row => row.linkId !== record.linkId), record]);+ board.db.prepare('INSERT INTO board_meta(meta_key,meta_value) VALUES (?,?) ON CONFLICT(meta_key) DO UPDATE SET meta_value=excluded.meta_value')+ .run(PREFIX + record.linkId, JSON.stringify(record));+ const by = (record.revocation ?? record.approvals.at(-1)).by;+ logEvent(board, by, 'board_link', null, { record });+ return record;+ });+}++/** Resolve current structural identity; this lookup alone is never signer authorization. */+function currentBoardLink(board, { linkId, sourceBoardId, destinationBoardId, generation }) {+ const record = readBoardLinks(board).find(row => row.linkId === boardLinkName(linkId));+ if (!record || record.revocation || record.generation !== generation+ || ![record.parent.boardId, record.child.boardId].includes(sourceBoardId)+ || ![record.parent.boardId, record.child.boardId].includes(destinationBoardId) || sourceBoardId === destinationBoardId) {+ throw new Refused('BOARD_LINK_INACTIVE', 'use the current non-revoked bilateral link generation for these exact boards');+ }+ return record;+}++/** Authenticate current consent at an operation boundary, including records restored from storage. */+export async function authorizeBoardLink(board, context, authority) {+ const record = currentBoardLink(board, context);+ const verified = await verifyBoardLink(record, authority);+ // An asynchronous authority can outlive a concurrent revoke or generation transition.+ const current = currentBoardLink(board, context);+ if (JSON.stringify(current) !== JSON.stringify(record)) {+ throw new Refused('BOARD_LINK_CONFLICT', 'refresh the link after its consent changed during authorization');+ }+ return verified;+}++/** Serialize current upstream disclosure; callers still authorize before delivery or any side effect. */+export function boardStateAnnouncement(board, context) {+ if (!context || !Number.isSafeInteger(context.position) || context.position < 0) boardLinkFormat('Use a nonnegative source position');+ const record = currentBoardLink(board, context);+ if (context.sourceBoardId !== record.child.boardId || context.destinationBoardId !== record.parent.boardId) {+ throw new Refused('BOARD_LINK_DISCLOSURE', 'send the child’s disclosed state upstream to its consenting parent');+ }+ if (!Array.isArray(context.rows) || context.rows.some(row => row?.board !== context.sourceBoardId)) {+ throw new Refused('BOARD_LINK_DISCLOSURE', 'announce only items belonging to the authenticated source board');+ }+ return { version: 1, linkId: record.linkId, generation: record.generation,+ sourceBoardId: context.sourceBoardId, destinationBoardId: context.destinationBoardId,+ position: context.position, disclosure: record.disclosure, rows: discloseBoardState(record.disclosure, context.rows) };+}diff --git a/src/board-reference.js b/src/board-reference.jsnew file mode 100644index 00000000..54d73ed2--- /dev/null+++ b/src/board-reference.js@@ -0,0 +1,56 @@+/** One immutable identity resolver is shared by every cross-board interface [E32,H16]. */+import { Refused } from './refused.js';++/** Refuse an ambiguous or untrusted reference before choosing any board. */+function invalid() { throw new Refused('BOARD_REFERENCE', 'use an immutable board ID or one exact qualified name from the authorized project inventory'); }++/** Validate an immutable board ID without treating a display name or local path as authority. */+export function boardReferenceId(value) {+ if (typeof value !== 'string' || !/^[0-9a-f]{32}$/u.test(value)) invalid();+ return value;+}++/** Preserve exact qualified-name bytes rather than silently renaming a signed board. */+function name(value) {+ if (typeof value !== 'string' || !/^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/u.test(value)) invalid();+ return value;+}++/** Copy only the canonical public BoardRef fields. */+export function boardReference(value) {+ if (!value || typeof value !== 'object' || Array.isArray(value)+ || Object.keys(value).some(key => !['boardId', 'organization', 'handle'].includes(key))) invalid();+ return { boardId: boardReferenceId(value.boardId), organization: name(value.organization), handle: name(value.handle) };+}++/** Resolve only against the caller's authorized inventory, refusing duplicate IDs or names. */+export function resolveBoardReference(inventory, requested) {+ if (!Array.isArray(inventory) || inventory.length > 10000) invalid();+ const rows = inventory.map(boardReference);+ const ids = new Set();+ const names = new Set();+ for (const row of rows) {+ const qualified = `${row.organization}/${row.handle}`;+ if (ids.has(row.boardId) || names.has(qualified)) invalid();+ ids.add(row.boardId); names.add(qualified);+ }+ let found;+ if (typeof requested === 'string') {+ found = /^[0-9a-f]{32}$/u.test(requested)+ ? rows.find(row => row.boardId === requested)+ : rows.find(row => `${row.organization}/${row.handle}` === requested);+ } else if (requested && typeof requested === 'object' && !Array.isArray(requested)) {+ if (Object.keys(requested).some(key => !['boardId', 'organization', 'handle'].includes(key))) invalid();+ found = rows.find(row => row.boardId === boardReferenceId(requested.boardId));+ if (found && (requested.organization !== undefined && requested.organization !== found.organization+ || requested.handle !== undefined && requested.handle !== found.handle)) invalid();+ }+ if (!found) invalid();+ return { ...found };+}++/** Bind a numeric item ID to its immutable owning board at every composition boundary. */+export function boardItemReference(inventory, reference, itemId) {+ if (!Number.isSafeInteger(itemId) || itemId < 1) invalid();+ return { boardId: resolveBoardReference(inventory, reference).boardId, itemId };+}