@elu-labs/elu 0.0.0-stage → 0.1.0

package/lib/peer/roster.mjs

@@ -0,0 +1,256 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { atomic, hash, isObject, mkdir, noSymlinks, refuse } from '../util.mjs';
+import { waitLock } from '../state.mjs';
+import { peerFile, peerRepo } from './paths.mjs';
+import { canonical, sign, verify } from './canonical.mjs';
+import { validName } from './identity.mjs';
+
+// A team roster is a grow-only set of signed ops (docs/peer-network.md, "Roster").
+//
+//   op  = {teamId, id, type, by, at, body, sig}
+//   id  = sha256 hex of canonical({teamId, type, by, at, body}); for create, teamId is
+//         the empty string inside this hashed object, and the team id is the resulting id
+//         (so the stored create op has teamId === id).
+//   sig = ed25519 by `by` over canonical({id, teamId, type, by, at, body}), i.e. the
+//         stored op without sig.
+//   at  = integer milliseconds since the epoch. makeOp never goes below the newest op in
+//         the local log, so an op always sorts after the ops its author had seen.
+//
+// Bodies: create {name, founderName} (the founder's display name, which the spec's {name}
+// lacks), admit {key, name, role, invite: sha256(secret)}, remove {key}, role {key, role},
+// relays {keys}, leave {}, channel {id, name, members}.
+//
+// A channel is a named group inside the team. Its op sets the whole channel: the name and
+// the member keys; no members deletes it. Any active member may create one they are in; a
+// channel's members and the team's admins may change it. Every team also has #general,
+// which is everyone and needs no op.
+//
+// fold() -> {id, name, founder, relays, members: [{key, name, role, removed, left, joinedAt}],
+// channels: [{id, name, members: [key], createdBy, createdAt}], rejected: [{id, reason}]}. State is the fold of all valid ops sorted by (at, id). Each
+// op applies only if its signer holds the needed role at that point: the founder for
+// create, an active admin for admit/remove/role/relays, and any active non-founder member
+// for their own leave. The founder's role is admin.
+// Removal wins: a removed or departed key's later ops are ignored and the key is never
+// admitted again. The founder cannot be removed, leave, or change role.
+// Ordering trusts `at`, so merge() refuses every new op from a key this machine already
+// saw removed or departed (a backdated op cannot bring it back), ops more than SKEW_MS in
+// the future, and ops the fold would not apply. Logs on two machines can then differ by
+// ops one of them refused; sync keeps offering them and the other keeps refusing.
+export const TYPES = Object.freeze(['create', 'admit', 'remove', 'role', 'relays', 'leave', 'channel']);
+export const CHANNEL_NAME = /^[a-z0-9][a-z0-9_-]{0,29}$/;
+// A member can fill the log only this far: CHANNEL_CHANGES channel ops each, CHANNELS live channels a team.
+const CHANNEL_ID = /^[0-9a-f]{16}$/, CHANNELS = 50, CHANNEL_CHANGES = 200, CHANNEL_MEMBERS = 20;
+const HEX64 = /^[0-9a-f]{64}$/;
+const MAX_OP = 4096, MAX_LINE = 8192, MAX_OPS = 10000, MAX_MERGE = 5000, MAX_LOG_BYTES = 16 * 1024 * 1024, SKEW_MS = 10 * 60000;
+// Signature checks dominate reading a log, and teams() reads every log several times a
+// tick. id binds every signed field but sig, so (id, sig) is checked once per process.
+const verified = new Map();
+function signed(op) {
+  const key = `${op.id}:${op.sig}`;
+  if (!verified.has(key)) { if (verified.size >= 50000) verified.clear(); verified.set(key, verify(op.by, unsigned(op), op.sig)); }
+  return verified.get(key);
+}
+const isKey = value => typeof value === 'string' && HEX64.test(value);
+export function teamPath(teamId, ...parts) {
+  if (!isKey(teamId)) refuse('A team id must be 64 hex characters.');
+  return peerFile('teams', teamId, ...parts);
+}
+const keysOf = (value, names) => isObject(value) && Object.keys(value).sort().join() === [...names].sort().join();
+const BODY = {
+  create: body => keysOf(body, ['name', 'founderName']) && validName(body.name, 60) && validName(body.founderName),
+  admit: body => keysOf(body, ['key', 'name', 'role', 'invite']) && isKey(body.key) && validName(body.name) && ['member', 'admin'].includes(body.role) && isKey(body.invite),
+  remove: body => keysOf(body, ['key']) && isKey(body.key),
+  role: body => keysOf(body, ['key', 'role']) && isKey(body.key) && ['member', 'admin'].includes(body.role),
+  relays: body => keysOf(body, ['keys']) && Array.isArray(body.keys) && body.keys.length <= 16 && body.keys.every(isKey) && new Set(body.keys).size === body.keys.length,
+  leave: body => keysOf(body, []),
+  channel: body => keysOf(body, ['id', 'name', 'members']) && typeof body.id === 'string' && CHANNEL_ID.test(body.id) && typeof body.name === 'string' && CHANNEL_NAME.test(body.name) && body.name !== 'general'
+    && Array.isArray(body.members) && body.members.length <= CHANNEL_MEMBERS && body.members.every(isKey) && new Set(body.members).size === body.members.length,
+};
+const unsigned = op => ({ id: op.id, teamId: op.teamId, type: op.type, by: op.by, at: op.at, body: op.body });
+const opId = ({ teamId, type, by, at, body }) => hash(canonical({ teamId: type === 'create' ? '' : teamId, type, by, at, body }));
+// Returns why an op is malformed, or null. Never throws, whatever it is given.
+export function opProblem(op) {
+  try {
+    if (!keysOf(op, ['teamId', 'id', 'type', 'by', 'at', 'body', 'sig'])) return 'The op has missing or unknown fields.';
+    if (!isKey(op.teamId) || !isKey(op.id) || !isKey(op.by) || typeof op.sig !== 'string') return 'The op has a malformed id or key.';
+    if (!TYPES.includes(op.type)) return 'The op type is unknown.';
+    if (!Number.isSafeInteger(op.at) || op.at <= 0) return 'The op time is invalid.';
+    if (!BODY[op.type](op.body)) return `The ${op.type} op body is invalid.`;
+    if (canonical(op).length > MAX_OP) return 'The op is too large.';
+    if (opId(op) !== op.id || (op.type === 'create' && op.teamId !== op.id)) return 'The op id does not match its contents.';
+    if (!signed(op)) return 'The op signature is invalid.';
+    return null;
+  } catch { return 'The op is not valid JSON data.'; }
+}
+export function validateOp(op) { const reason = opProblem(op); if (reason) refuse(reason); return op; }
+export function makeOp(identity, teamId, type, body) {
+  if (!TYPES.includes(type)) refuse('Unknown roster op.');
+  if (type !== 'create') teamPath(teamId);
+  // An op stamped far in the future (kept from before merge refused them) must not freeze the log.
+  const newest = type === 'create' ? 0 : readLog(teamId).ops.reduce((max, op) => op.at <= Date.now() + SKEW_MS ? Math.max(max, op.at) : max, 0);
+  const draft = { teamId: type === 'create' ? '' : teamId, type, by: identity.key, at: Math.max(Date.now(), newest + 1), body };
+  const id = opId(draft), op = { ...draft, id, teamId: type === 'create' ? id : teamId };
+  return validateOp({ ...op, sig: sign(identity.seed, unsigned(op)) });
+}
+
+const order = (a, b) => a.at - b.at || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0);
+// Folds any list of ops into team state. Bad and unauthorised ops land in `rejected`;
+// duplicates are ignored. With teamId, only that team's create op can start the fold.
+export function fold(ops, teamId = null) {
+  const rejected = [], seen = new Set(), valid = [];
+  for (const op of Array.isArray(ops) ? ops : []) {
+    const reason = opProblem(op);
+    if (reason) rejected.push({ id: isKey(op?.id) ? op.id : null, reason });
+    else if (!seen.has(op.id)) { seen.add(op.id); valid.push(op); }
+  }
+  const state = { id: null, name: null, founder: null, relays: [] }, members = new Map(), gone = new Set(), channels = new Map(), changes = new Map();
+  const active = key => members.has(key) && !members.get(key).removed;
+  const admin = key => active(key) && members.get(key).role === 'admin';
+  // Someone who leaves the team leaves its channels then; an emptied channel frees its name and its place among CHANNELS.
+  const quit = key => { for (const row of [...channels.values()]) { row.members = row.members.filter(k => k !== key); if (!row.members.length) channels.delete(row.id); } };
+  const apply = op => {
+    if (op.type === 'create') {
+      if (teamId && op.id !== teamId) return 'The op belongs to another team.';
+      if (state.id) return 'The team already exists.';
+      Object.assign(state, { id: op.id, name: op.body.name, founder: op.by });
+      members.set(op.by, { key: op.by, name: op.body.founderName, role: 'admin', removed: false, left: false, joinedAt: op.at }); return null;
+    }
+    if (!state.id) return 'The team does not exist yet.';
+    if (op.teamId !== state.id) return 'The op belongs to another team.';
+    if (gone.has(op.by)) return 'The signer was removed from the team.';
+    if (!active(op.by)) return 'The signer is not a member of the team.';
+    if (op.type === 'leave') {
+      if (op.by === state.founder) return 'The founder cannot leave the team.';
+      Object.assign(members.get(op.by), { removed: true, left: true }); gone.add(op.by); quit(op.by); return null;
+    }
+    if (op.type === 'channel') {
+      const { id, name, members: wanted } = op.body, current = channels.get(id), count = (changes.get(op.by) ?? 0) + 1;
+      if (count > CHANNEL_CHANGES) return 'The signer changed channels too many times.';
+      if (wanted.some(key => !active(key))) return 'A channel member is not on the team.';
+      if (!current) {
+        if (!wanted.includes(op.by)) return 'A new channel needs its creator as a member.';
+        if (channels.size >= CHANNELS) return 'The team has too many channels.';
+      } else if (!current.members.includes(op.by) && !admin(op.by)) return 'Only a channel member can change it.';
+      if (wanted.length && [...channels.values()].some(row => row.id !== id && row.name === name)) return 'A channel with that name exists.';
+      changes.set(op.by, count);
+      if (wanted.length) channels.set(id, { id, name, members: [...wanted], createdBy: current?.createdBy ?? op.by, createdAt: current?.createdAt ?? op.at });
+      else channels.delete(id);
+      return null;
+    }
+    if (!admin(op.by)) return 'The signer is not an admin.';
+    const { key } = op.body;
+    if (op.type === 'admit') {
+      if (gone.has(key)) return 'A removed key cannot be admitted again.';
+      if (active(key)) return 'The key is already a member.';
+      members.set(key, { key, name: op.body.name, role: op.body.role, removed: false, left: false, joinedAt: op.at }); return null;
+    }
+    if (op.type === 'relays') { state.relays = [...op.body.keys]; return null; }
+    if (key === state.founder) return `The founder cannot be ${op.type === 'remove' ? 'removed' : 'given another role'}.`;
+    if (!active(key)) return 'The key is not a member of the team.';
+    if (op.type === 'remove') { Object.assign(members.get(key), { removed: true }); gone.add(key); quit(key); return null; }
+    members.get(key).role = op.body.role; return null;
+  };
+  for (const op of valid.sort(order)) { const reason = apply(op); if (reason) rejected.push({ id: op.id, reason }); }
+  const list = [...members.values()].sort((a, b) => a.joinedAt - b.joinedAt || (a.key < b.key ? -1 : 1)).map(m => ({ ...m }));
+  // Someone removed from the team is out of its channels; a channel nobody is left in is gone.
+  const rooms = [...channels.values()].map(row => ({ ...row, members: row.members.filter(active) })).filter(row => row.members.length).sort((a, b) => a.createdAt - b.createdAt || (a.id < b.id ? -1 : 1));
+  return { ...state, members: list, channels: rooms, rejected };
+}
+
+const logFile = teamId => teamPath(teamId, 'log.jsonl');
+// Reads a log, skipping (and reporting) lines that are not valid ops for this team.
+export function readLog(teamId) {
+  const file = logFile(teamId); noSymlinks(file);
+  if (!fs.existsSync(file)) return { ops: [], bad: [] };
+  if (fs.statSync(file).size > MAX_LOG_BYTES) return { ops: [], bad: [{ line: 0, reason: 'The roster log is too large.' }] };
+  const ops = [], bad = [], seen = new Set();
+  fs.readFileSync(file, 'utf8').split('\n').forEach((text, index) => {
+    if (!text.trim()) return;
+    const line = index + 1;
+    if (text.length > MAX_LINE) return bad.push({ line, reason: 'The line is too long.' });
+    let op; try { op = JSON.parse(text); } catch { return bad.push({ line, reason: 'The line is not JSON.' }); }
+    const reason = opProblem(op) ?? (op.teamId !== teamId ? 'The op belongs to another team.' : null);
+    if (reason) return bad.push({ line, reason });
+    if (ops.length >= MAX_OPS) return bad.push({ line, reason: 'The roster log is full.' });
+    if (!seen.has(op.id)) { seen.add(op.id); ops.push(op); }
+  });
+  return { ops, bad };
+}
+export function team(teamId) {
+  const { ops, bad } = readLog(teamId);
+  if (!ops.length) return null;
+  const state = fold(ops, teamId); return state.id ? { ...state, bad } : null;
+}
+export function teams() {
+  const dir = peerFile('teams'); noSymlinks(dir);
+  if (!fs.existsSync(dir)) return [];
+  return fs.readdirSync(dir).filter(name => HEX64.test(name)).sort().flatMap(id => { try { const found = team(id); return found ? [found] : []; } catch { return []; } });
+}
+export function head(teamId) {
+  const ids = readLog(teamId).ops.map(op => op.id).sort();
+  return { seq: ids.length, head: hash(ids.join('\n')) };
+}
+function locked(teamId, fn) { teamPath(teamId); const release = waitLock(peerRepo(), `team-${teamId}`); try { return fn(); } finally { release(); } }
+function write(teamId, ops) {
+  if (ops.length > MAX_OPS) refuse('The roster log is full.');
+  mkdir(path.dirname(logFile(teamId)));
+  atomic(logFile(teamId), ops.map(op => `${JSON.stringify(op)}\n`).join(''));
+}
+// Adds one local op. It must apply on top of the current log, or nothing is written.
+export function appendOp(teamId, op) {
+  return locked(teamId, () => {
+    validateOp(op);
+    if (op.teamId !== teamId) refuse('The op belongs to another team.');
+    const { ops } = readLog(teamId);
+    if (ops.some(x => x.id === op.id)) return { added: false, op };
+    const problem = fold([...ops, op], teamId).rejected.find(x => x.id === op.id);
+    if (problem) refuse(problem.reason);
+    write(teamId, [...ops, op]); return { added: true, op };
+  });
+}
+// Merges ops from a teammate. Only ops the fold applies are written: malformed ops, other
+// teams' ops, ops by keys that were never members, ops their signer had no authority for,
+// ops stamped over SKEW_MS ahead, and any op by a key this log already shows removed or
+// departed are dropped. So a plain member can add nothing but their own leave and channel ops.
+export function merge(teamId, incoming, now = Date.now()) {
+  if (!Array.isArray(incoming)) refuse('Roster ops must be a list.');
+  return locked(teamId, () => {
+    const { ops } = readLog(teamId), have = new Set(ops.map(op => op.id)), rejected = [], fresh = [];
+    const gone = new Set(ops.length ? fold(ops, teamId).members.filter(m => m.removed).map(m => m.key) : []);
+    incoming.forEach((op, index) => {
+      const reason = index >= MAX_MERGE ? 'Too many ops in one push.' : opProblem(op) ?? (op.teamId !== teamId ? 'The op belongs to another team.' : op.at > now + SKEW_MS ? 'The op time is in the future.' : gone.has(op.by) ? 'The signer was removed from the team.' : null);
+      if (reason) rejected.push({ id: isKey(op?.id) ? op.id : null, reason });
+      else if (!have.has(op.id)) { have.add(op.id); fresh.push(op); }
+    });
+    const refused = new Map(fold([...ops, ...fresh], teamId).rejected.map(x => [x.id, x.reason])), added = [];
+    for (const op of fresh) {
+      if (refused.has(op.id)) rejected.push({ id: op.id, reason: refused.get(op.id) });
+      else added.push(op);
+    }
+    if (added.length) write(teamId, [...ops, ...added]);
+    return { added, rejected };
+  });
+}
+export function opsMissing(teamId, theirIds) {
+  if (!Array.isArray(theirIds) || theirIds.length > MAX_OPS * 2) refuse('Roster ids must be a list.');
+  const theirs = new Set(theirIds.filter(isKey));
+  return readLog(teamId).ops.filter(op => !theirs.has(op.id));
+}
+// Creates a channel (no id), or sets the name and members of one. No members deletes it.
+export function setChannel(identity, teamId, { id = null, name = null, members }) {
+  const state = team(teamId); if (!state) refuse('Unknown team.');
+  const current = id ? state.channels.find(row => row.id === id) : null;
+  if (id && !current) refuse('That channel no longer exists.');
+  const label = String(name ?? current?.name ?? '').replace(/^#/, '');
+  if (!CHANNEL_NAME.test(label) || label === 'general') refuse('Name a channel with 1 to 30 lowercase letters, digits, - or _. general is taken.');
+  if (!Array.isArray(members) || members.length > CHANNEL_MEMBERS || !members.every(isKey)) refuse(`A channel holds up to ${CHANNEL_MEMBERS} teammates.`);
+  const op = makeOp(identity, teamId, 'channel', { id: id ?? crypto.randomBytes(8).toString('hex'), name: label, members: [...new Set(members)] });
+  appendOp(teamId, op); return { op, id: op.body.id };
+}
+export function createTeam(identity, name) {
+  if (!validName(name, 60)) refuse('Choose a team name of 1 to 60 printable characters.');
+  const op = makeOp(identity, '', 'create', { name, founderName: identity.name });
+  appendOp(op.id, op); return team(op.id);
+}

package/lib/peer/rpc.mjs

@@ -0,0 +1,88 @@
+import { EventEmitter } from 'node:events';
+import { EluCodeError, isObject } from '../util.mjs';
+import { A2A_VERSION, BINDING, createRpcHandler, rpcError } from './a2a.mjs';
+import { frames, writeFrame } from './transport.mjs';
+
+// One JSON-RPC 2.0 session per connection, both directions (docs/peer-network.md,
+// "Binding"). The first frame each way is the elu.hello notification; without a valid
+// one within helloMs the connection closes. admit(hello, session) then returns
+// 'member', 'join' (only elu.join may follow) or a falsy value (closed).
+export const HELLO_MS = 5000;
+const HEX64 = /^[0-9a-f]{64}$/;
+// Any 1.x A2A version is accepted; minor versions only add fields, which are ignored.
+const validHello = value => isObject(value) && value.binding === BINDING && typeof value.a2aVersion === 'string' && /^1\.\d{1,4}$/.test(value.a2aVersion) && typeof value.name === 'string' && value.name.length <= 64
+  && Array.isArray(value.teams) && value.teams.length <= 32 && value.teams.every(team => isObject(team) && HEX64.test(team.id ?? '') && Number.isSafeInteger(team.seq) && HEX64.test(team.head ?? ''));
+
+export class Session extends EventEmitter {
+  constructor(socket, { key, hello, admit, methods = {}, onError, helloMs = HELLO_MS, limit = 20, windowMs = 10000, log = () => {} }) {
+    super();
+    Object.assign(this, { socket, key, admit, log, limit, windowMs, state: 'hello', pending: new Map(), nextId: 1, hits: [], remoteHello: null });
+    this.handle = createRpcHandler(methods, { onError });
+    this.timer = setTimeout(() => this.close('no hello'), helloMs);
+    frames(socket, frame => this.frame(frame), reason => this.close(reason));
+    socket.on('close', () => this.closed());
+    socket.on('error', () => {});
+    this.send({ jsonrpc: '2.0', method: 'elu.hello', params: { binding: BINDING, a2aVersion: A2A_VERSION, ...hello() } });
+  }
+  get admitted() { return this.state === 'member'; }
+  send(value) { try { writeFrame(this.socket, value); } catch (error) { this.log(`send failed: ${error.message}`); } }
+  close(reason) {
+    if (this.state === 'closed') return;
+    if (reason) this.log(`closed ${this.key.slice(0, 8)}: ${reason}`);
+    this.closed(); this.socket.destroy();
+  }
+  closed() {
+    if (this.state === 'closed') return;
+    this.state = 'closed'; clearTimeout(this.timer);
+    for (const { reject, timer } of this.pending.values()) { clearTimeout(timer); reject(new EluCodeError('The teammate disconnected.')); }
+    this.pending.clear(); this.emit('close');
+  }
+  request(method, params, { timeoutMs = 30000 } = {}) {
+    if (this.state === 'closed') return Promise.reject(new EluCodeError('The teammate is not connected.'));
+    const id = this.nextId++;
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => { this.pending.delete(id); reject(new EluCodeError('The teammate did not answer in time.', { timeout: true })); }, timeoutMs);
+      this.pending.set(id, { resolve, reject, timer });
+      this.send({ jsonrpc: '2.0', id, method, params });
+    });
+  }
+  notify(method, params) { if (this.state !== 'closed') this.send({ jsonrpc: '2.0', method, params }); }
+  // Marks a session admitted after a join or a roster change.
+  promote() { if (this.state !== 'closed' && this.state !== 'member') { clearTimeout(this.timer); this.state = 'member'; this.emit('admitted'); } }
+  frame(frame) {
+    if (this.state === 'closed') return;
+    if (!isObject(frame) || frame.jsonrpc !== '2.0') return this.close('not JSON-RPC 2.0');
+    if (this.state === 'hello') {
+      if (frame.method !== 'elu.hello' || Object.hasOwn(frame, 'id') || !validHello(frame.params)) return this.close(typeof frame.params?.a2aVersion === 'string' && !/^1\./.test(frame.params.a2aVersion) ? `unsupported A2A version ${JSON.stringify(frame.params.a2aVersion.slice(0, 16))}` : 'no valid hello');
+      clearTimeout(this.timer); this.remoteHello = frame.params;
+      let decision; try { decision = this.admit(frame.params, this); } catch (error) { this.log(`admission failed: ${error.message}`); }
+      this.log(`admission ${this.key.slice(0, 8)}: ${decision || 'refused'}`);
+      if (decision === 'member') { this.state = 'member'; this.emit('admitted'); return; }
+      if (decision === 'join') { this.state = 'join'; this.timer = setTimeout(() => this.close('no join'), 30000); return; }
+      return this.close('not a teammate');
+    }
+    if (Object.hasOwn(frame, 'method')) {
+      if (frame.method === 'elu.hello') return this.close('repeated hello');
+      // A machine that only came to join may send elu.join once, and nothing else.
+      if (this.state === 'join' && (frame.method !== 'elu.join' || this.joinTried)) return this.close('not a teammate');
+      if (this.state === 'join') this.joinTried = true;
+      const now = Date.now(); this.hits = this.hits.filter(at => now - at < this.windowMs); this.hits.push(now);
+      if (this.hits.length > this.limit * 2) return this.close('too many requests');
+      if (this.hits.length > this.limit) {
+        if (Object.hasOwn(frame, 'id')) this.send(rpcError(frame.id ?? null, -32000, 'Too many requests. Try again shortly.'));
+        return;
+      }
+      this.handle(frame, this).then(response => {
+        if (response) this.send(response);
+        // The join handler sets joinAccepted; the joiner is admitted once its reply is out.
+        if (this.state === 'join') { if (this.joinAccepted) this.promote(); else this.close('join finished without admission'); }
+      }, error => this.log(`handler failed: ${error.message}`));
+      return;
+    }
+    if (!Object.hasOwn(frame, 'id')) return this.close('frame without method or id');
+    const waiting = this.pending.get(frame.id); if (!waiting) return;
+    this.pending.delete(frame.id); clearTimeout(waiting.timer);
+    if (isObject(frame.error)) waiting.reject(new EluCodeError(typeof frame.error.message === 'string' ? frame.error.message.slice(0, 300) : 'The teammate refused.', { rpc: { code: frame.error.code, data: frame.error.data } }));
+    else waiting.resolve(frame.result);
+  }
+}

package/lib/peer/secrets.mjs

@@ -0,0 +1,88 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { within } from '../util.mjs';
+
+// Patterns for credentials that must never leave this machine in a reply. Order matters:
+// when two matches overlap, the earlier, more specific kind is reported.
+const VALUE = `(?!(?:process\\.env|os\\.environ|ENV\\b|getenv|null|undefined|true|false|none|changeme|example|your[-_]|xxx|\\*{3}|<|\\$|\\{))[^\\s"'\`;,)]{6,}`;
+const PATTERNS = [
+  ['private-key', /-----BEGIN (?:[A-Z0-9]+ )*PRIVATE KEY(?: BLOCK)?-----/g],
+  ['aws-access-key', /\b(?:AKIA|ASIA)[0-9A-Z]{16}\b/g],
+  ['github-token', /\b(?:gh[pousr]_[A-Za-z0-9]{36,255}|github_pat_[A-Za-z0-9_]{22,255})\b/g],
+  ['anthropic-key', /\bsk-ant-[A-Za-z0-9_-]{20,}/g],
+  ['openai-key', /\bsk-(?:proj-)?(?=[A-Za-z0-9_-]*[0-9])[A-Za-z0-9_-]{20,}/g],
+  ['slack-token', /\bxox[abpr]-[A-Za-z0-9-]{10,}/g],
+  ['google-api-key', /\bAIza[0-9A-Za-z_-]{35}(?![0-9A-Za-z_-])/g],
+  ['stripe-key', /\b(?:sk|rk)_live_[0-9A-Za-z]{16,}/g],
+  ['jwt', /\beyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}/g],
+  ['npm-token', /\bnpm_[A-Za-z0-9]{36}(?![A-Za-z0-9])/g],
+  ['url-credentials', /\b[a-z][a-z0-9+.-]*:\/\/[^\s:/@'"`]+:[^\s/@'"`]+@/gi],
+  // KEY=value: an upper-case variable name may take a bare value; any other name needs a quoted one.
+  ['assignment', new RegExp(`\\b[A-Z0-9_]*(?:PASSWORD|PASSWD|SECRET|TOKEN|API_?KEY|PRIVATE_?KEY|ACCESS_?KEY)\\s*[:=]\\s*["']?${VALUE}`, 'g')],
+  ['assignment', new RegExp(`\\b[A-Za-z0-9_]*(?:password|passwd|secret|token|api_?key|private_?key|access_?key)\\s*[:=]\\s*["']${VALUE}`, 'gi')],
+];
+// "=" only as base64 padding, so in KEY=value the value is judged on its own.
+const TOKEN = /[A-Za-z0-9+/_-]{32,}={0,2}/g;
+const HARMLESS = [/^[0-9a-f]{40}$/i, /^[0-9a-f]{64}$/i, /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i];
+export function entropy(text) {
+  const counts = new Map(); for (const char of text) counts.set(char, (counts.get(char) ?? 0) + 1);
+  let bits = 0; for (const count of counts.values()) { const p = count / text.length; bits -= p * Math.log2(p); }
+  return bits;
+}
+// A generic token must look random: over 4 bits per character (which hex can never reach)
+// and switching between lowercase, uppercase, digits and symbols on at least 40% of
+// adjacent characters, with lowercase runs under 3.5 characters on average. Random base64
+// switches on about 64% with runs near 1.7; camelCase names, words and paths have long
+// lowercase runs and switch far less, so they are not flagged.
+const charClass = char => /[a-z]/.test(char) ? 0 : /[A-Z]/.test(char) ? 1 : /[0-9]/.test(char) ? 2 : 3;
+function switches(token) {
+  let count = 0; for (let i = 1; i < token.length; i++) if (charClass(token[i]) !== charClass(token[i - 1])) count++;
+  return count / (token.length - 1);
+}
+function lowerRun(token) { const runs = token.match(/[a-z]+/g) ?? []; return runs.length ? runs.join('').length / runs.length : 0; }
+const randomLooking = token => !HARMLESS.some(re => re.test(token)) && entropy(token) > 4 && switches(token) >= 0.4 && lowerRun(token) < 3.5;
+export function scanSecrets(text) {
+  const value = String(text ?? ''), found = [];
+  const overlaps = (start, end) => found.some(x => start < x.end && end > x.index);
+  for (const [kind, re] of PATTERNS) {
+    for (const m of value.matchAll(re)) if (!overlaps(m.index, m.index + m[0].length)) found.push({ kind, index: m.index, end: m.index + m[0].length });
+  }
+  for (const m of value.matchAll(TOKEN)) {
+    if (!overlaps(m.index, m.index + m[0].length) && randomLooking(m[0])) found.push({ kind: 'high-entropy', index: m.index, end: m.index + m[0].length });
+  }
+  return found.sort((a, b) => a.index - b.index).map(({ kind, index }) => ({ kind, index }));
+}
+// Absolute paths of two or more segments that are not part of a URL or a relative path.
+const ABSOLUTE = /(?<![\w:/.~\u0000-])\/[\w.@+-]+(?:\/[\w.@+-]+)+\/?/g;
+const HOME_PATH = /(?<![\w:/.~\u0000-])~\/[\w.@+-]+(?:\/[\w.@+-]+)*\/?/g;
+function spellings(root) {
+  if (!root) return [];
+  const resolved = path.resolve(root); let real = resolved;
+  try { real = fs.realpathSync(resolved); } catch { /* A missing root is matched as given. */ }
+  return [...new Set([resolved, real])].filter(x => x !== path.parse(x).root).sort((a, b) => b.length - a.length);
+}
+export function redactPaths(text, { root } = {}) {
+  const home = os.homedir(), roots = spellings(root), mark = `\u0000${crypto.randomBytes(6).toString('hex')}\u0000`;
+  let value = String(text ?? '').replaceAll('\u0000', '');
+  // The root may contain spaces, which the path pattern stops at, so it is masked first.
+  for (const r of roots) value = value.replace(new RegExp(`${r.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}(?![\\w.@+-])`, 'g'), mark);
+  value = value.replace(ABSOLUTE, match => {
+    const found = match.replace(/\.+$/, ''), tail = match.slice(found.length);
+    return (roots.some(r => within(r, found.replace(/\/$/, ''))) ? found : '[path]') + tail;
+  });
+  // A ~/ path in the text names a place in the owner's home, never the masked repository.
+  value = value.replace(HOME_PATH, match => `[path]${match.slice(match.replace(/\.+$/, '').length)}`);
+  if (roots.length) value = value.replaceAll(mark, path.resolve(root));
+  return home && home !== '/' ? value.replaceAll(home, '~') : value;
+}
+// trusted: the text goes as written, paths and all; the secret scan still
+// decides ok. pathsCut says a path became [path], so the owner can learn why a teammate
+// could not find a file.
+export function prepareOutgoing(text, { root, trusted = false } = {}) {
+  const problems = scanSecrets(text), value = String(text ?? '');
+  if (trusted) return { ok: problems.length === 0, text: value, problems, pathsCut: false };
+  const redacted = redactPaths(value, { root });
+  return { ok: problems.length === 0, text: redacted, problems, pathsCut: redacted.split('[path]').length > value.split('[path]').length };
+}

package/lib/peer/settings.mjs

@@ -0,0 +1,45 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import { atomic, readJson, isObject, refuse } from '../util.mjs';
+import { peerFile } from './paths.mjs';
+
+export const DEFAULT_PEER_SETTINGS = Object.freeze({
+  enabled: false, bootstrap: null, relays: [], peerSlots: 1, localA2A: false, box: null,
+  caps: Object.freeze({ threadMessages: 8, hops: 2, threadUsd: 1, peerRunsPerDay: 20, peerUsdPerDay: 5, teamUsdPerDay: 10, runUsd: 0.5 }),
+});
+// holdReplies: I read each reply to this teammate before it goes. Off, a reply goes back into
+// the thread when the run ends, unless the secret scan holds it. trusted: my
+// text to them keeps its paths and their text shows as sent; the secret scan still applies.
+// Trust is mine about them, never sent over the wire and never implied by a team role.
+export const DEFAULT_PEER_POLICY = Object.freeze({ autoAccept: false, holdReplies: false, autoAsk: false, autoContinue: false, muted: false, trusted: false });
+// autoSend (replies held unless it was on) became holdReplies; saved copies are dropped.
+const policyOf = value => { const { autoSend, ...rest } = isObject(value) ? value : {}; return rest; };
+const read = (name, fallback) => { const file = peerFile(name); try { return fs.existsSync(file) ? readJson(file) : fallback; } catch { return fallback; } };
+export function peerSettings() {
+  const saved = read('settings.json', {});
+  return { ...DEFAULT_PEER_SETTINGS, ...saved, caps: { ...DEFAULT_PEER_SETTINGS.caps, ...saved.caps } };
+}
+export function savePeerSettings(update) {
+  if (!isObject(update)) refuse('Peer settings must be an object.');
+  const current = peerSettings(), next = { ...current, ...update, caps: { ...current.caps, ...update.caps } };
+  if (!Number.isInteger(next.peerSlots) || next.peerSlots < 0 || next.peerSlots > 16) refuse('Peer slots must be 0 to 16.');
+  if (update.box != null && !validBox(update.box)) refuse('Name this machine with 1 to 32 letters, digits, dots, - or _.');
+  next.box ??= null;
+  atomic(peerFile('settings.json'), next); return next;
+}
+// box: what this machine is called, told to teammates beside its owner's name. null is the
+// default: the first label of the host name, without any character a box name cannot have.
+export const BOX = /^[A-Za-z0-9._-]{1,32}$/;
+const validBox = value => typeof value === 'string' && BOX.test(value);
+const hostName = () => { try { return os.hostname(); } catch { return ''; } };
+export const defaultBox = (host = hostName()) => String(host ?? '').split('.')[0].replace(/[^A-Za-z0-9_-]/g, '').slice(0, 32) || 'box';
+// The box name in use. A saved name that is no longer valid counts as none.
+export function peerBox() { const { box } = peerSettings(); return validBox(box) ? box : defaultBox(); }
+export function peerPolicy(key) { return { ...DEFAULT_PEER_POLICY, ...policyOf(read('peers.json', {})[key]) }; }
+export function savePeerPolicy(key, update) {
+  if (!/^[0-9a-f]{64}$/.test(key)) refuse('Choose a peer by its key.');
+  const all = read('peers.json', {}), next = { ...DEFAULT_PEER_POLICY, ...policyOf(all[key]), ...update };
+  for (const name of Object.keys(next)) if (!(name in DEFAULT_PEER_POLICY)) refuse(`Unknown teammate setting: ${name}.`);
+  for (const name of Object.keys(DEFAULT_PEER_POLICY)) if (typeof next[name] !== 'boolean') refuse(`${name} must be true or false.`);
+  atomic(peerFile('peers.json'), { ...all, [key]: next }); return next;
+}

package/lib/peer/shares.mjs

@@ -0,0 +1,120 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { atomic, hash, isObject, noSymlinks, readJson, refuse, within } from '../util.mjs';
+import { waitLock } from '../state.mjs';
+import { git } from '../git.mjs';
+import { registeredProjects } from '../projects.mjs';
+import { peerFile, peerRepo } from './paths.mjs';
+
+// A share lets teammates ask about one registered project by its handle. repoId lets two
+// machines recognise the same repository without sending paths.
+const HANDLE = /^[a-z0-9][a-z0-9-]{0,39}$/;
+const HEX64 = /^[0-9a-f]{64}$/;
+const file = () => peerFile('shares.json');
+const validRow = row => isObject(row) && HANDLE.test(row.handle ?? '') && typeof row.root === 'string' && path.isAbsolute(row.root)
+  && (row.repoId === null || HEX64.test(row.repoId ?? '')) && typeof row.status === 'boolean' && typeof row.createdAt === 'string'
+  && (row.teams === undefined || Array.isArray(row.teams) && row.teams.every(id => typeof id === 'string' && HEX64.test(id)));
+export function shares() {
+  noSymlinks(file());
+  if (!fs.existsSync(file())) return [];
+  let rows; try { rows = readJson(file()); } catch { return []; }
+  return Array.isArray(rows) ? rows.filter(validRow) : [];
+}
+// git@host:owner/repo, ssh://user@host:22/owner/repo.git and https://user:token@Host/owner/repo
+// all become host/owner/repo: no credentials, scheme, port or trailing .git, host lowercased.
+export function normalizeRemote(url) {
+  const text = typeof url === 'string' ? url.trim() : '';
+  if (!text || text.length > 2048 || /[\x00-\x20\x7f]/.test(text)) return null;
+  let host, rest;
+  const scp = !text.includes('://') && /^(?:[^@/:]+@)?([^/:]+):(.*)$/.exec(text);
+  if (scp) [host, rest] = [scp[1], scp[2]];
+  else if (text.startsWith('/')) [host, rest] = ['file', text];
+  else {
+    let parsed; try { parsed = new URL(text); } catch { return null; }
+    host = parsed.protocol === 'file:' ? 'file' : parsed.hostname;
+    try { rest = decodeURIComponent(parsed.pathname); } catch { return null; }
+  }
+  rest = rest.replace(/^\/+/, '').replace(/\/+$/, '').replace(/\.git$/i, '').replace(/\/+$/, '');
+  return host && rest ? `${host.toLowerCase()}/${rest}` : null;
+}
+export function repoId(root) {
+  const result = git(root, ['config', '--get', 'remote.origin.url'], { allowFailure: true });
+  const remote = result.status === 0 ? normalizeRemote(result.stdout) : null;
+  return remote ? hash(remote) : null;
+}
+const defaultHandle = root => path.basename(root).toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+/, '').slice(0, 40).replace(/-+$/, '');
+// A share is for the teams it was shared with (teams), and a question from any other team
+// cannot reach it, by name or otherwise. A share saved before teams were kept with it stays
+// open to every team of the owner's, as it was, until it is shared again.
+const projectTeams = handle => Object.entries(teamProjects()).filter(([, value]) => value === handle).map(([id]) => id);
+export function sharedWith(row, teamIds) {
+  return Array.isArray(row?.teams) ? row.teams.some(id => teamIds.includes(id)) : teamIds.length > 0;
+}
+// A project shared again keeps its handle, status and teams; teams named now are added. One
+// saved before teams were kept is tied then to every team of the owner's (mine) as well, so
+// no team loses it, and a team joined after that is not included.
+export function share(root, { handle, status, teams, mine } = {}) {
+  for (const list of [teams, mine]) if (list !== undefined && (!Array.isArray(list) || list.some(id => typeof id !== 'string' || !HEX64.test(id)))) refuse('Choose the teams to share with.');
+  if (status !== undefined && typeof status !== 'boolean') refuse('Share status must be true or false.');
+  if (handle !== undefined && (typeof handle !== 'string' || !HANDLE.test(handle))) refuse('A share handle is 1 to 40 lowercase letters, digits or dashes.');
+  let resolved; try { resolved = fs.realpathSync(path.resolve(String(root ?? ''))); } catch { refuse('That folder does not exist.'); }
+  // The home folder holds every other project and the owner's own files. It is never shared
+  // from here on; a share of it made before this still answers until it is unshared.
+  let home = os.homedir(); try { home = fs.realpathSync(home); } catch { /* Compared as given. */ }
+  if (within(resolved, home)) refuse('Your home folder cannot be shared. Open the project\'s own folder and share that.');
+  // Only the folder that was named is shared: a folder inside a project never stands for the
+  // whole project, so a share cannot reach further than what was asked.
+  const projects = registeredProjects(), project = projects.find(p => p.root === resolved);
+  if (!project) refuse(projects.some(p => within(p.root, resolved)) ? 'This folder is inside a project but is not one. Share the project from its own folder, or open this folder as a project first.' : 'Open this project in ELU Code before sharing it.');
+  const id = repoId(project.root);
+  const release = waitLock(peerRepo(), 'shares');
+  try {
+    const rows = shares(), existing = rows.find(row => row.root === project.root);
+    const name = handle ?? existing?.handle ?? defaultHandle(project.root);
+    if (!HANDLE.test(name)) refuse('A share handle is 1 to 40 lowercase letters, digits or dashes.');
+    if (rows.some(row => row.handle === name && row.root !== project.root)) refuse(`The handle ${name} is already shared.`);
+    const known = teams ? [...new Set([...(existing ? existing.teams ?? mine ?? projectTeams(existing.handle) : []), ...teams])] : existing?.teams;
+    const row = { handle: name, root: project.root, repoId: id, status: status ?? existing?.status ?? true, createdAt: existing?.createdAt ?? new Date().toISOString(), ...(known ? { teams: known } : {}) };
+    atomic(file(), [...rows.filter(x => x.root !== project.root), row]);
+    // A renamed share stays the project of the teams that had it.
+    if (existing && existing.handle !== name && fs.existsSync(teamFile())) atomic(teamFile(), Object.fromEntries(Object.entries(teamProjects()).map(([id, value]) => [id, value === existing.handle ? name : value])));
+    return row;
+  } finally { release(); }
+}
+export function unshare(handle) {
+  const release = waitLock(peerRepo(), 'shares');
+  try {
+    const rows = shares(), row = rows.find(x => x.handle === handle);
+    if (!row) refuse(`No share is named ${String(handle).slice(0, 40)}.`);
+    atomic(file(), rows.filter(x => x !== row));
+    const projects = teamProjects(); atomic(teamFile(), Object.fromEntries(Object.entries(projects).filter(([, value]) => value !== row.handle)));
+    return row;
+  } finally { release(); }
+}
+// Each team's project on this machine: the share a teammate's question goes to when it names
+// none. It is chosen when the teammate is added (/invite and /join in a project), and /share
+// in another project moves it there. team-projects.json = {teamId: handle}.
+const teamFile = () => peerFile('team-projects.json');
+export function teamProjects() {
+  noSymlinks(teamFile());
+  let value; try { value = fs.existsSync(teamFile()) ? readJson(teamFile()) : {}; } catch { return {}; }
+  return isObject(value) ? Object.fromEntries(Object.entries(value).filter(([id, handle]) => HEX64.test(id) && typeof handle === 'string' && HANDLE.test(handle))) : {};
+}
+export function setTeamProject(teamId, handle) {
+  if (typeof teamId !== 'string' || !HEX64.test(teamId)) refuse('Choose a team.');
+  const release = waitLock(peerRepo(), 'shares');
+  try {
+    if (!shares().some(row => row.handle === handle)) refuse(`No share is named ${String(handle).slice(0, 40)}.`);
+    atomic(teamFile(), { ...teamProjects(), [teamId]: handle });
+  } finally { release(); }
+}
+export function teamShare(teamIds) {
+  const projects = teamProjects();
+  for (const id of teamIds) { const row = projects[id] ? shareFor(projects[id]) : null; if (row) return row; }
+  return null;
+}
+export function shareFor(handleOrRepoId) {
+  if (typeof handleOrRepoId !== 'string') return null;
+  return shares().find(row => row.handle === handleOrRepoId || (HEX64.test(handleOrRepoId) && row.repoId === handleOrRepoId)) ?? null;
+}