@nicknisi/pi-relay 0.1.0 → 0.2.0

package/dist/registry.d.ts

@@ -34,6 +34,22 @@ export declare function ensureRoot(root: string): void;
 export declare function recordPath(root: string, addr: string): string;
 export declare function inboxDir(root: string, addr: string): string;
 export declare function asksDir(root: string, addr: string): string;
+export interface AliasRecord {
+    name: string;
+    addr: string;
+    sessionId: string;
+    claimedAt: number;
+}
+export declare function aliasesDir(root: string): string;
+export declare function aliasPath(root: string, name: string): string;
+export declare function writeAlias(root: string, alias: AliasRecord): void;
+/** Alias names: lowercase alnum start, then alnum/_/-, 1-32 chars. */
+export declare function isValidAliasName(name: string): boolean;
+export declare function readAlias(root: string, name: string): AliasRecord | null;
+export declare function listAliases(root: string): AliasRecord[];
+/** Last-claim-wins: overwrites any prior owner. */
+export declare function claimAlias(root: string, name: string, addr: string, sessionId: string): AliasRecord;
+export declare function clearAlias(root: string, name: string): void;
 export declare function writeRecord(root: string, record: SessionRecord): void;
 export declare function readRecord(root: string, addr: string): SessionRecord | null;
 /** Read-only listing, oldest first. Never mutates anything. */

package/dist/registry.js

@@ -41,6 +41,71 @@ export function inboxDir(root, addr) {
 export function asksDir(root, addr) {
     return path.join(root, `${addr}.asks`);
 }
+export function aliasesDir(root) {
+    return path.join(root, 'aliases');
+}
+export function aliasPath(root, name) {
+    return path.join(aliasesDir(root), `${name}.json`);
+}
+export function writeAlias(root, alias) {
+    const file = aliasPath(root, alias.name);
+    fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+    const tmp = `${file}.${process.pid}.tmp`;
+    fs.writeFileSync(tmp, JSON.stringify(alias, null, 2), { mode: 0o600 });
+    fs.renameSync(tmp, file);
+}
+/** Alias names: lowercase alnum start, then alnum/_/-, 1-32 chars. */
+export function isValidAliasName(name) {
+    return /^[a-z0-9][a-z0-9_-]{0,31}$/.test(name);
+}
+export function readAlias(root, name) {
+    // The name can come from LLM-controlled tool input — never let it reach
+    // the filesystem unvalidated (e.g. '@../../../../tmp/x').
+    if (!isValidAliasName(name))
+        return null;
+    try {
+        const parsed = JSON.parse(fs.readFileSync(aliasPath(root, name), 'utf8'));
+        if (parsed && typeof parsed.name === 'string' && typeof parsed.addr === 'string') {
+            return parsed;
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+export function listAliases(root) {
+    let entries;
+    try {
+        entries = fs.readdirSync(aliasesDir(root), { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const entry of entries) {
+        if (!entry.isFile() || !entry.name.endsWith('.json'))
+            continue;
+        const alias = readAlias(root, entry.name.slice(0, -'.json'.length));
+        if (alias)
+            out.push(alias);
+    }
+    return out.sort((a, b) => a.claimedAt - b.claimedAt);
+}
+/** Last-claim-wins: overwrites any prior owner. */
+export function claimAlias(root, name, addr, sessionId) {
+    const alias = { name, addr, sessionId, claimedAt: Date.now() };
+    writeAlias(root, alias);
+    return alias;
+}
+export function clearAlias(root, name) {
+    try {
+        fs.unlinkSync(aliasPath(root, name));
+    }
+    catch {
+        // already gone
+    }
+}
 export function writeRecord(root, record) {
     ensureRoot(root);
     const file = recordPath(root, record.addr);
@@ -146,4 +211,11 @@ export function sweep(root, now = Date.now(), sessionExists) {
             // already gone
         }
     }
+    // Aliases are swept when the owning session dies: an alias whose record
+    // was just reaped (or never existed) is reclaimed. A resumable-but-offline
+    // session keeps its record, so it keeps its alias too.
+    for (const alias of listAliases(root)) {
+        if (readRecord(root, alias.addr) === null)
+            clearAlias(root, alias.name);
+    }
 }

package/dist/relay.test.js

@@ -6,10 +6,10 @@ import * as fs from 'node:fs';
 import * as os from 'node:os';
 import * as path from 'node:path';
 import { afterEach, describe, expect, it } from 'vitest';
-import { BOUNDARY_PREAMBLE, formatDelivery, formatListing, refusalAmbiguous, refusalUnknown } from './format.js';
-import { awaitReceipt, clearAsk, deposit, drain, pendingAsks, readOutgoingAsk, trackIncomingAsk, trackOutgoingAsk, unreadCount, watchInbox, } from './mailbox.js';
+import { BOUNDARY_PREAMBLE, formatAudit, formatDelivery, formatListing, refusalAmbiguous, refusalUnknown, } from './format.js';
+import { appendAudit, auditLogPath, awaitReceipt, clearAsk, deposit, drain, pendingAsks, previewBody, readAudit, readOutgoingAsk, resolveAskByRef, trackIncomingAsk, trackOutgoingAsk, unreadCount, watchInbox, } from './mailbox.js';
 import { BACKLOG_CAP, OutboundPolicy, inboundAccepts } from './policy.js';
-import { deriveAddr, listRecords, presenceOf, sweep, writeRecord } from './registry.js';
+import { claimAlias, clearAlias, deriveAddr, isValidAliasName, listAliases, listRecords, presenceOf, readAlias, readRecord, sweep, writeAlias, writeRecord, } from './registry.js';
 const dirs = [];
 function tmpRoot() {
     const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'pi-relay-test-'));
@@ -179,6 +179,167 @@ describe('mailbox', () => {
         expect(drain(root, addr).map((l) => l.body)).toEqual(['while you were out']);
     });
 });
+describe('aliases', () => {
+    function alias(over = {}) {
+        return { name: 'ci', addr: 'aaaa1111bbbb', sessionId: 'sid-1', claimedAt: Date.now(), ...over };
+    }
+    it('claim is last-claim-wins and persists on disk across restart', () => {
+        const root = tmpRoot();
+        writeAlias(root, alias({ addr: 'old00000000', sessionId: 'old-sid' }));
+        expect(readAlias(root, 'ci')?.addr).toBe('old00000000');
+        // a new session claims the same name — overwrites
+        claimAlias(root, 'ci', 'new00000001', 'new-sid');
+        expect(readAlias(root, 'ci')?.addr).toBe('new00000001');
+        expect(listAliases(root).map((a) => a.name)).toEqual(['ci']);
+    });
+    it('sweep reaps an alias whose owning session record is gone', () => {
+        const root = tmpRoot();
+        // live owner keeps its alias
+        const live = record({ addr: 'live00000001', pid: process.pid });
+        writeRecord(root, live);
+        claimAlias(root, 'ci', live.addr, live.sessionId);
+        sweep(root);
+        expect(readAlias(root, 'ci')?.addr).toBe(live.addr);
+        // owner record reaped (offline, empty, not resumable) → alias reaped too
+        const dead = record({ addr: 'dead00000002', offline: true, pid: 2_000_000_010, sessionId: 'gone' });
+        writeRecord(root, dead);
+        claimAlias(root, 'dotfiles', dead.addr, dead.sessionId);
+        sweep(root, Date.now(), () => false); // nothing resumable
+        expect(readAlias(root, 'ci')?.addr).toBe(live.addr); // untouched
+        expect(readAlias(root, 'dotfiles')).toBeNull();
+    });
+    it('a resumable-but-offline owner keeps its alias (deliverable while down)', () => {
+        const root = tmpRoot();
+        const down = record({ addr: 'down00000003', offline: true, pid: 2_000_000_011, sessionId: 'can-resume' });
+        writeRecord(root, down);
+        claimAlias(root, 'ci', down.addr, down.sessionId);
+        sweep(root, Date.now(), (id) => id === 'can-resume');
+        expect(readAlias(root, 'ci')?.addr).toBe(down.addr);
+    });
+    it('clearAlias is idempotent', () => {
+        const root = tmpRoot();
+        writeAlias(root, alias());
+        clearAlias(root, 'ci');
+        clearAlias(root, 'ci'); // no throw
+        expect(readAlias(root, 'ci')).toBeNull();
+        expect(readRecord(root, 'aaaa1111bbbb')).toBeNull(); // sanity: readRecord on missing → null
+    });
+    it('alias names are validated — traversal never reaches the filesystem', () => {
+        const root = tmpRoot();
+        expect(isValidAliasName('ci')).toBe(true);
+        expect(isValidAliasName('dotfiles-2')).toBe(true);
+        expect(isValidAliasName('../../tmp/x')).toBe(false);
+        expect(isValidAliasName('..')).toBe(false);
+        expect(isValidAliasName('a/b')).toBe(false);
+        expect(isValidAliasName('UPPER')).toBe(false); // case-sensitive storage, lowercase-only names
+        expect(isValidAliasName('')).toBe(false);
+        // readAlias refuses invalid names outright (defense in depth behind resolveTarget)
+        expect(readAlias(root, '../../../../etc/passwd')).toBeNull();
+        expect(readAlias(root, 'UPPER')).toBeNull();
+    });
+});
+describe('audit log', () => {
+    it('append-only: deposit writes one line, never the full body', () => {
+        const root = tmpRoot();
+        const addr = 'aud00000001';
+        const long = 'x'.repeat(500);
+        deposit(root, addr, letter({ id: 'a-1', body: long, ts: 1000 }));
+        const entries = readAudit(root, 100);
+        expect(entries).toHaveLength(1);
+        const e = entries[0];
+        expect(e.event).toBe('deposit');
+        expect(e.kind).toBe('message');
+        expect(e.from).toBe(letter().from.addr);
+        expect(e.to).toBe(addr);
+        expect(e.messageId).toBe('a-1');
+        // preview is bounded — the full 500-char body never lands in the log
+        expect(e.preview).toBe(previewBody(long));
+        expect(e.preview.length).toBeLessThan(long.length);
+    });
+    it('append-only survives corruption and returns a bounded tail', () => {
+        const root = tmpRoot();
+        for (let i = 0; i < 3; i++)
+            deposit(root, 'aud00000002', letter({ id: `a-${i}`, ts: 1000 + i }));
+        // a corrupt line must not poison reads (append-only, skip-on-parse-fail)
+        fs.appendFileSync(path.join(root, 'audit.log'), '{not json}\n');
+        const entries = readAudit(root, 2);
+        expect(entries).toHaveLength(2);
+        expect(entries.map((e) => e.messageId)).toEqual(['a-1', 'a-2']);
+    });
+    it('deliver and deposit both record (evidence survives drain-as-receipt)', () => {
+        const root = tmpRoot();
+        const addr = 'aud00000003';
+        deposit(root, addr, letter({ id: 'd-1', kind: 'ask', body: 'can I push?' }));
+        // drain consumes (unlinks) the letter, but the audit line stays
+        drain(root, addr);
+        const entries = readAudit(root);
+        expect(entries.filter((e) => e.event === 'deposit' && e.messageId === 'd-1')).toHaveLength(1);
+        // a deliver record is appended by index.ts deliver(); simulate it here:
+        appendAudit(root, {
+            ts: Date.now(),
+            event: 'deliver',
+            kind: 'ask',
+            from: letter().from.addr,
+            to: addr,
+            messageId: 'd-1',
+            preview: previewBody('can I push?'),
+        });
+        const after = readAudit(root).filter((e) => e.messageId === 'd-1');
+        expect(after.map((e) => e.event)).toEqual(['deposit', 'deliver']);
+    });
+    it('audit log rotates at the 1 MB cap, keeping one previous generation', () => {
+        const root = tmpRoot();
+        const big = 'y'.repeat(1024);
+        // ~1.1 MB of audit records
+        for (let i = 0; i < 1100; i++) {
+            appendAudit(root, {
+                ts: 1000 + i,
+                event: 'deposit',
+                kind: 'message',
+                from: 'from-addr',
+                to: 'to-addr',
+                messageId: `m-${i}`,
+                preview: big,
+            });
+        }
+        const file = auditLogPath(root);
+        expect(fs.existsSync(`${file}.1`)).toBe(true); // rotated generation exists
+        expect(fs.statSync(file).size).toBeLessThan(1024 * 1024); // fresh log is small
+        expect(readAudit(root, 10).length).toBeGreaterThan(0); // still readable after rotation
+    });
+    it('previewBody strips ANSI/CSI escapes (peer-controlled text reaches raw terminals)', () => {
+        expect(previewBody('hello \x1b[31mred\x1b[0m world')).toBe('hello red world');
+        expect(previewBody('\x1b[2J\x1b[Hbye')).toBe('bye');
+    });
+    it('resolveAskByRef matches by id or unique prefix, never by inference', () => {
+        const root = tmpRoot();
+        const addr = 'ask00000001';
+        const a1 = letter({ id: 'aaaa1111-0000-0000-0000-000000000001', kind: 'ask' });
+        const a2 = letter({ id: 'bbbb2222-0000-0000-0000-000000000002', kind: 'ask' });
+        trackIncomingAsk(root, addr, a1);
+        trackIncomingAsk(root, addr, a2);
+        expect(resolveAskByRef(root, addr, a1.id)?.id).toBe(a1.id); // exact id
+        expect(resolveAskByRef(root, addr, 'bbbb2222')?.id).toBe(a2.id); // prefix
+        expect(resolveAskByRef(root, addr, 'nope')).toBeNull(); // no match
+        // one pending ask alone is NOT implicitly the reply target — caller must pass its ref
+        expect(resolveAskByRef(root, addr, '')).toBeNull();
+    });
+    it('formatAudit renders entries and handles the empty case', () => {
+        expect(formatAudit([])).toContain('No audit entries');
+        const root = tmpRoot();
+        deposit(root, 'aud00000004', letter({ id: 'f-1', kind: 'message', body: 'hello world' }));
+        const text = formatAudit(readAudit(root));
+        expect(text).toContain('deposit');
+        expect(text).toContain('f-1'.slice(0, 8));
+        expect(text).toContain('hello world'); // preview present
+        // a long body is only present as its bounded preview
+        const root2 = tmpRoot();
+        const long = 'A'.repeat(500);
+        deposit(root2, 'aud00000005', letter({ id: 'f-2', body: long }));
+        const text2 = formatAudit(readAudit(root2));
+        expect(text2).not.toContain(long);
+    });
+});
 describe('inbound refuse', () => {
     it('refused mail is never consumed, so receipts honestly read queued', async () => {
         expect(inboundAccepts('refuse')).toBe(false);
@@ -209,6 +370,16 @@ describe('policy', () => {
         now += 11_000;
         expect(p.check('same', 0).ok).toBe(true);
     });
+    it('dedupe is per-target: a broadcast of one body reaches distinct peers', () => {
+        const p = new OutboundPolicy();
+        expect(p.check('main moved', 0, 'peerA').ok).toBe(true);
+        p.recordSend('main moved', 'peerA');
+        // same body, different peer → not deduped (loop-breaking is per-peer)
+        expect(p.check('main moved', 0, 'peerB').ok).toBe(true);
+        p.recordSend('main moved', 'peerB');
+        // same body, same peer again → still deduped inside the window
+        expect(p.check('main moved', 0, 'peerA').ok).toBe(false);
+    });
     it('rate limits at 8 per 30s', () => {
         const p = new OutboundPolicy();
         for (let i = 0; i < 8; i++) {

package/format.ts

@@ -3,7 +3,7 @@
  * pinned by tests; change them deliberately.
  */
 
-import type { Letter } from './mailbox.js';
+import type { AuditRecord, Letter } from './mailbox.js';
 import type { Presence, SessionRecord } from './registry.js';
 
 export const BOUNDARY_PREAMBLE =
@@ -58,3 +58,16 @@ export function refusalUnknown(to: string, reachable: string[]): string {
 export function refusalAmbiguous(to: string, candidates: string[]): string {
   return `'${to}' is ambiguous; matches: ${candidates.join(', ')}. Use a full name or address prefix.`;
 }
+
+/** Render recent audit entries for `/relay log`. */
+export function formatAudit(records: AuditRecord[], now: number = Date.now()): string {
+  if (records.length === 0) return 'No audit entries yet.';
+  const head = `relay audit · ${records.length} entr${records.length === 1 ? 'y' : 'ies'}`;
+  const lines = [head];
+  for (const r of records) {
+    const when = age(r.ts, now);
+    const dir = `${shortAddr(r.from)} → ${shortAddr(r.to)}`;
+    lines.push(`• ${r.event} ${r.kind}  ${dir}  id ${r.messageId.slice(0, 8)}  ${when}  ${r.preview}`);
+  }
+  return lines.join('\n');
+}