@phuetz/code-buddy 1.6.1 → 2.1.0

package/dist/fleet/rooms/room-hub.d.ts

@@ -0,0 +1,154 @@
+/**
+ * Fleet rooms — transport-agnostic hub.
+ *
+ * Adapted from block/buzz @ 4cd82f51 (Apache-2.0):
+ * - publish pipeline order and machine-readable `OK` prefixes
+ *   (`auth-required:`, `invalid:`, `restricted:`, `rate-limited:`, `duplicate:`,
+ *   `error:`) from `crates/buzz-relay/src/handlers/event.rs` + `ARCHITECTURE.md` §4;
+ * - REQ handling (access checked before anything is read or registered, stored
+ *   events then `EOSE` then live fan-out, bounded subscriptions and history)
+ *   from `crates/buzz-relay/src/handlers/req.rs` + `ARCHITECTURE.md` §5;
+ * - NIP-42 challenge/response from `ARCHITECTURE.md` §3 and `crates/buzz-auth`.
+ *
+ * Messages are DATA. The hub stores and forwards signed events; nothing here
+ * turns a message into a prompt, a tool call or an agent turn, so a peer cannot
+ * start work on another member and no reply loop can form through the hub.
+ *
+ * @module fleet/rooms/room-hub
+ */
+import { type ReadonlyRoomEvent } from './room-event.js';
+import type { RoomAccessLevel, RoomAccessPolicy } from './room-access.js';
+import { type RoomRecord, type RoomStore } from './room-store.js';
+export interface RoomHubOptions {
+    store: RoomStore;
+    access: RoomAccessPolicy;
+    /** Canonical audiences accepted in auth proofs (see `canonicalRoomAudience`). */
+    audiences: readonly string[];
+    maxSubscriptionsPerSession?: number;
+    /** Accepted publications per member key per minute. */
+    publishPerMinute?: number;
+    maxFutureSkewSec?: number;
+    maxPastSkewSec?: number;
+    authSkewSec?: number;
+    challengeTtlMs?: number;
+    maxAuthAttempts?: number;
+    /** Clock in ms (tests). */
+    now?: () => number;
+}
+export interface RoomTransport {
+    readonly connectionId: string;
+    /** Server-derived WebSocket principal (`key:…`, `user:…`). */
+    readonly principalId: string;
+    send(frame: RoomStreamFrame): boolean;
+    isBackpressured(): boolean;
+}
+export type RoomStreamFrame = {
+    type: 'fleet.rooms.event';
+    payload: {
+        subId: string;
+        seq: number;
+        event: ReadonlyRoomEvent;
+    };
+} | {
+    type: 'fleet.rooms.eose';
+    payload: {
+        subId: string;
+        storeId: string;
+        throughSeq: number;
+        /** false: the replay was truncated; resubscribe after `throughSeq`. */
+        live: boolean;
+        truncated: boolean;
+        /** Records after the cursor were evicted; the replay is incomplete. */
+        gap: boolean;
+        /** The cursor named another ledger generation and was ignored. */
+        epochChanged: boolean;
+    };
+} | {
+    type: 'fleet.rooms.closed';
+    payload: {
+        subId: string;
+        message: string;
+        storeId: string;
+        throughSeq: number | null;
+    };
+};
+export type RoomAuthResult = {
+    ok: true;
+    pubkey: string;
+    name: string;
+    rooms: Array<{
+        room: string;
+        access: RoomAccessLevel;
+        description?: string;
+    }>;
+} | {
+    ok: false;
+    message: string;
+};
+export interface RoomPublishResult {
+    id: string;
+    accepted: boolean;
+    message: string;
+    seq?: number;
+    storeId: string;
+}
+export declare class RoomSession {
+    private readonly hub;
+    readonly transport: RoomTransport;
+    pubkey: string | undefined;
+    private challenge;
+    private authAttempts;
+    private readonly subscriptions;
+    private disposed;
+    constructor(hub: RoomHub, transport: RoomTransport);
+    get isDisposed(): boolean;
+    /** Issue a fresh single-use challenge (replaces any previous one). */
+    hello(): {
+        challenge: string;
+        expiresAt: string;
+    };
+    authenticate(input: unknown): RoomAuthResult;
+    publish(input: unknown): RoomPublishResult;
+    subscribe(request: unknown): {
+        ok: true;
+    } | {
+        ok: false;
+        message: string;
+    };
+    unsubscribe(subId: unknown): {
+        subId: string;
+        closed: boolean;
+    };
+    /** Hub fan-out for one stored record. */
+    deliver(record: RoomRecord): void;
+    private closeSubscription;
+    private closeAll;
+    get subscriptionCount(): number;
+    dispose(): void;
+}
+export declare class RoomHub {
+    readonly store: RoomStore;
+    readonly access: RoomAccessPolicy;
+    readonly audiences: readonly string[];
+    readonly maxSubscriptionsPerSession: number;
+    readonly publishPerMinute: number;
+    readonly maxFutureSkewSec: number;
+    readonly maxPastSkewSec: number;
+    readonly authSkewSec: number;
+    readonly challengeTtlMs: number;
+    readonly maxAuthAttempts: number;
+    readonly now: () => number;
+    private readonly sessions;
+    private readonly publishWindows;
+    constructor(options: RoomHubOptions);
+    open(transport: RoomTransport): RoomSession;
+    /** @internal */
+    forget(session: RoomSession): void;
+    /** @internal Fixed one-minute window per member key. */
+    takePublishToken(pubkey: string): boolean;
+    /** @internal */
+    deliver(record: RoomRecord): void;
+    get sessionCount(): number;
+    /** Dispose every session. The store stays owned by the caller. */
+    close(): void;
+}

package/dist/fleet/rooms/room-hub.js

@@ -0,0 +1,363 @@
+/**
+ * Fleet rooms — transport-agnostic hub.
+ *
+ * Adapted from block/buzz @ 4cd82f51 (Apache-2.0):
+ * - publish pipeline order and machine-readable `OK` prefixes
+ *   (`auth-required:`, `invalid:`, `restricted:`, `rate-limited:`, `duplicate:`,
+ *   `error:`) from `crates/buzz-relay/src/handlers/event.rs` + `ARCHITECTURE.md` §4;
+ * - REQ handling (access checked before anything is read or registered, stored
+ *   events then `EOSE` then live fan-out, bounded subscriptions and history)
+ *   from `crates/buzz-relay/src/handlers/req.rs` + `ARCHITECTURE.md` §5;
+ * - NIP-42 challenge/response from `ARCHITECTURE.md` §3 and `crates/buzz-auth`.
+ *
+ * Messages are DATA. The hub stores and forwards signed events; nothing here
+ * turns a message into a prompt, a tool call or an agent turn, so a peer cannot
+ * start work on another member and no reply loop can form through the hub.
+ *
+ * @module fleet/rooms/room-hub
+ */
+import { randomBytes } from 'crypto';
+import { logger } from '../../utils/logger.js';
+import { canonicalRoomAudience, checkRoomEventShape, MAX_ROOM_MENTIONS, ROOM_AUTH_KIND, ROOM_MESSAGE_KIND, roomOf, tagValues, verifyRoomEvent, } from './room-event.js';
+import { parseRoomFilters, roomFiltersMatch, roomsReferenced } from './room-filter.js';
+import { RoomStoreError } from './room-store.js';
+const SUB_ID_PATTERN = /^[A-Za-z0-9._:-]{1,64}$/;
+function finitePositive(name, value, fallback) {
+    if (value === undefined)
+        return fallback;
+    if (typeof value !== 'number' || !Number.isFinite(value) || value <= 0) {
+        throw new RangeError(`${name} must be a finite number > 0`);
+    }
+    return value;
+}
+export class RoomSession {
+    hub;
+    transport;
+    pubkey;
+    challenge;
+    authAttempts = 0;
+    subscriptions = new Map();
+    disposed = false;
+    constructor(hub, transport) {
+        this.hub = hub;
+        this.transport = transport;
+    }
+    get isDisposed() {
+        return this.disposed;
+    }
+    /** Issue a fresh single-use challenge (replaces any previous one). */
+    hello() {
+        const value = randomBytes(32).toString('hex');
+        const expiresAt = this.hub.now() + this.hub.challengeTtlMs;
+        this.challenge = { value, expiresAt };
+        return { challenge: value, expiresAt: new Date(expiresAt).toISOString() };
+    }
+    authenticate(input) {
+        if (this.disposed)
+            return { ok: false, message: 'error: session closed' };
+        this.authAttempts++;
+        const challenge = this.challenge;
+        this.challenge = undefined;
+        if (this.authAttempts > this.hub.maxAuthAttempts) {
+            return { ok: false, message: 'restricted: too many authentication attempts on this connection' };
+        }
+        if (!challenge || this.hub.now() > challenge.expiresAt) {
+            return { ok: false, message: 'auth-required: request a fresh challenge with fleet.rooms.hello' };
+        }
+        const shape = checkRoomEventShape(input);
+        if (!shape.ok)
+            return { ok: false, message: `invalid: ${shape.reason}` };
+        const event = shape.event;
+        if (event.kind !== ROOM_AUTH_KIND)
+            return { ok: false, message: 'invalid: auth proof must be kind 22242' };
+        const challengeTags = event.tags.filter((tag) => tag[0] === 'challenge');
+        if (challengeTags.length !== 1 || challengeTags[0]?.length !== 2 || challengeTags[0][1] !== challenge.value) {
+            return { ok: false, message: 'invalid: auth proof does not answer this challenge' };
+        }
+        const relayTags = event.tags.filter((tag) => tag[0] === 'relay');
+        let audience;
+        try {
+            audience = relayTags.length === 1 && relayTags[0]?.length === 2
+                ? canonicalRoomAudience(relayTags[0][1])
+                : undefined;
+        }
+        catch {
+            audience = undefined;
+        }
+        if (!audience || !this.hub.audiences.includes(audience)) {
+            return { ok: false, message: 'restricted: auth proof is addressed to another hub' };
+        }
+        const nowSec = Math.floor(this.hub.now() / 1000);
+        if (Math.abs(event.created_at - nowSec) > this.hub.authSkewSec) {
+            return { ok: false, message: 'invalid: auth proof timestamp outside the allowed window' };
+        }
+        const verified = verifyRoomEvent(event);
+        if (!verified.ok)
+            return { ok: false, message: `invalid: ${verified.reason}` };
+        const admission = this.hub.access.admit(event.pubkey, this.transport.principalId);
+        if (!admission.ok)
+            return { ok: false, message: admission.reason };
+        if (this.pubkey !== event.pubkey)
+            this.closeAll('restricted: room identity changed');
+        this.pubkey = event.pubkey;
+        this.authAttempts = 0;
+        return {
+            ok: true,
+            pubkey: event.pubkey,
+            name: admission.member.name,
+            rooms: this.hub.access.roomsFor(event.pubkey),
+        };
+    }
+    publish(input) {
+        const storeId = this.hub.store.storeId;
+        const claimedId = input && typeof input === 'object' && typeof input.id === 'string'
+            ? (input.id.match(/^[0-9a-f]{64}$/)?.[0] ?? '')
+            : '';
+        const reject = (message) => ({ id: claimedId, accepted: false, message, storeId });
+        if (this.disposed)
+            return reject('error: session closed');
+        if (!this.pubkey)
+            return reject('auth-required: authenticate with fleet.rooms.auth first');
+        const admission = this.hub.access.admit(this.pubkey, this.transport.principalId);
+        if (!admission.ok)
+            return reject(admission.reason);
+        const shape = checkRoomEventShape(input);
+        if (!shape.ok)
+            return reject(`invalid: ${shape.reason}`);
+        const event = shape.event;
+        if (event.pubkey !== this.pubkey)
+            return reject('invalid: event pubkey does not match authenticated identity');
+        if (event.kind === ROOM_AUTH_KIND)
+            return reject('invalid: AUTH events cannot be published');
+        if (event.kind !== ROOM_MESSAGE_KIND)
+            return reject('invalid: only kind 9 room messages are accepted');
+        const room = roomOf(event);
+        if (!room)
+            return reject('invalid: message must carry exactly one valid h tag');
+        if (tagValues(event, 'p').length > MAX_ROOM_MENTIONS) {
+            return reject(`invalid: at most ${MAX_ROOM_MENTIONS} mentions`);
+        }
+        const verified = verifyRoomEvent(event);
+        if (!verified.ok)
+            return reject(`invalid: ${verified.reason}`);
+        if (!this.hub.access.canWrite(this.pubkey, room)) {
+            return reject(`restricted: no write access to room ${room}`);
+        }
+        const existing = this.hub.store.get(event.id);
+        if (existing) {
+            return { id: event.id, accepted: true, message: 'duplicate: already stored', seq: existing.seq, storeId };
+        }
+        const nowSec = Math.floor(this.hub.now() / 1000);
+        if (event.created_at > nowSec + this.hub.maxFutureSkewSec) {
+            return reject('invalid: created_at is too far in the future');
+        }
+        if (event.created_at < nowSec - this.hub.maxPastSkewSec) {
+            return reject('invalid: created_at is too old');
+        }
+        if (!this.hub.takePublishToken(this.pubkey)) {
+            return reject('rate-limited: too many messages, slow down');
+        }
+        let stored;
+        try {
+            const result = this.hub.store.append(event, this.hub.now());
+            stored = result.record;
+            if (result.status === 'duplicate') {
+                return { id: event.id, accepted: true, message: 'duplicate: already stored', seq: stored.seq, storeId };
+            }
+        }
+        catch (error) {
+            if (error instanceof RoomStoreError && error.code === 'FULL')
+                return reject('error: room storage full');
+            logger.error('[fleet-rooms] append failed', {
+                error: error instanceof Error ? error.message : String(error),
+            });
+            return reject('error: room storage unavailable');
+        }
+        this.hub.deliver(stored);
+        return { id: event.id, accepted: true, message: '', seq: stored.seq, storeId };
+    }
+    subscribe(request) {
+        const storeId = this.hub.store.storeId;
+        const raw = request && typeof request === 'object' ? request : {};
+        const subId = raw.subId;
+        if (typeof subId !== 'string' || !SUB_ID_PATTERN.test(subId)) {
+            return { ok: false, message: 'invalid: subId must match ^[A-Za-z0-9._:-]{1,64}$' };
+        }
+        const closed = (message, throughSeq = null) => {
+            this.transport.send({ type: 'fleet.rooms.closed', payload: { subId, message, storeId, throughSeq } });
+            return { ok: true };
+        };
+        // NIP-01: a REQ reusing an id replaces the previous subscription.
+        this.subscriptions.delete(subId);
+        if (this.disposed)
+            return closed('error: session closed');
+        if (!this.pubkey)
+            return closed('auth-required: authenticate with fleet.rooms.auth first');
+        const admission = this.hub.access.admit(this.pubkey, this.transport.principalId);
+        if (!admission.ok)
+            return closed(admission.reason);
+        const parsed = parseRoomFilters(raw.filters);
+        if (!parsed.ok)
+            return closed(`invalid: ${parsed.reason}`);
+        const rooms = roomsReferenced(parsed.filters);
+        const denied = rooms.find((room) => !this.hub.access.canRead(this.pubkey, room));
+        if (denied)
+            return closed(`restricted: no read access to room ${denied}`);
+        if (this.subscriptions.size >= this.hub.maxSubscriptionsPerSession) {
+            return closed('error: too many subscriptions');
+        }
+        let afterSeq;
+        let epochChanged = false;
+        if (raw.afterSeq !== undefined) {
+            if (!Number.isSafeInteger(raw.afterSeq) || raw.afterSeq < 0 || typeof raw.storeId !== 'string') {
+                return closed('invalid: afterSeq must be a non-negative integer sent with its storeId');
+            }
+            if (raw.storeId === storeId)
+                afterSeq = raw.afterSeq;
+            else
+                epochChanged = true;
+        }
+        const latestSeq = this.hub.store.latestSeq;
+        const { records, truncated } = this.hub.store.query(parsed.filters, afterSeq === undefined ? {} : { afterSeq });
+        const gap = afterSeq !== undefined && this.hub.store.hasGapAfter(rooms, afterSeq);
+        let lastSent = afterSeq ?? null;
+        for (const record of records) {
+            if (this.transport.isBackpressured()) {
+                return closed('error: backpressure, resubscribe after throughSeq', lastSent);
+            }
+            if (!this.transport.send({ type: 'fleet.rooms.event', payload: { subId, seq: record.seq, event: record.event } })) {
+                this.dispose();
+                return { ok: true };
+            }
+            lastSent = record.seq;
+        }
+        const throughSeq = truncated ? (lastSent ?? 0) : latestSeq;
+        this.transport.send({
+            type: 'fleet.rooms.eose',
+            payload: { subId, storeId, throughSeq, live: !truncated, truncated, gap, epochChanged },
+        });
+        // Synchronous from the query to here: no append can interleave, so live
+        // delivery starts exactly after `throughSeq`.
+        if (!truncated)
+            this.subscriptions.set(subId, { subId, filters: parsed.filters, rooms, throughSeq });
+        return { ok: true };
+    }
+    unsubscribe(subId) {
+        const id = typeof subId === 'string' ? subId : '';
+        return { subId: id, closed: this.subscriptions.delete(id) };
+    }
+    /** Hub fan-out for one stored record. */
+    deliver(record) {
+        if (this.disposed || !this.pubkey)
+            return;
+        for (const sub of [...this.subscriptions.values()]) {
+            if (record.seq <= sub.throughSeq || !roomFiltersMatch(sub.filters, record.event))
+                continue;
+            const admission = this.hub.access.admit(this.pubkey, this.transport.principalId);
+            if (!admission.ok || sub.rooms.some((room) => !this.hub.access.canRead(this.pubkey, room))) {
+                this.closeSubscription(sub, 'restricted: membership revoked');
+                continue;
+            }
+            if (this.transport.isBackpressured()) {
+                this.closeSubscription(sub, 'error: backpressure, resubscribe after throughSeq');
+                continue;
+            }
+            if (!this.transport.send({ type: 'fleet.rooms.event', payload: { subId: sub.subId, seq: record.seq, event: record.event } })) {
+                this.dispose();
+                return;
+            }
+            sub.throughSeq = record.seq;
+        }
+    }
+    closeSubscription(sub, message) {
+        this.subscriptions.delete(sub.subId);
+        this.transport.send({
+            type: 'fleet.rooms.closed',
+            payload: { subId: sub.subId, message, storeId: this.hub.store.storeId, throughSeq: sub.throughSeq },
+        });
+    }
+    closeAll(message) {
+        for (const sub of [...this.subscriptions.values()])
+            this.closeSubscription(sub, message);
+    }
+    get subscriptionCount() {
+        return this.subscriptions.size;
+    }
+    dispose() {
+        if (this.disposed)
+            return;
+        this.disposed = true;
+        this.subscriptions.clear();
+        this.challenge = undefined;
+        this.pubkey = undefined;
+        this.hub.forget(this);
+    }
+}
+export class RoomHub {
+    store;
+    access;
+    audiences;
+    maxSubscriptionsPerSession;
+    publishPerMinute;
+    maxFutureSkewSec;
+    maxPastSkewSec;
+    authSkewSec;
+    challengeTtlMs;
+    maxAuthAttempts;
+    now;
+    sessions = new Set();
+    publishWindows = new Map();
+    constructor(options) {
+        this.store = options.store;
+        this.access = options.access;
+        const audiences = options.audiences.map((audience) => canonicalRoomAudience(audience));
+        if (audiences.length === 0)
+            throw new RangeError('at least one hub audience is required');
+        this.audiences = Object.freeze([...new Set(audiences)]);
+        this.maxSubscriptionsPerSession = Math.floor(finitePositive('maxSubscriptionsPerSession', options.maxSubscriptionsPerSession, 16));
+        this.publishPerMinute = Math.floor(finitePositive('publishPerMinute', options.publishPerMinute, 60));
+        this.maxFutureSkewSec = finitePositive('maxFutureSkewSec', options.maxFutureSkewSec, 300);
+        this.maxPastSkewSec = finitePositive('maxPastSkewSec', options.maxPastSkewSec, 86_400);
+        this.authSkewSec = finitePositive('authSkewSec', options.authSkewSec, 60);
+        this.challengeTtlMs = finitePositive('challengeTtlMs', options.challengeTtlMs, 120_000);
+        this.maxAuthAttempts = Math.floor(finitePositive('maxAuthAttempts', options.maxAuthAttempts, 5));
+        this.now = options.now ?? Date.now;
+    }
+    open(transport) {
+        const session = new RoomSession(this, transport);
+        this.sessions.add(session);
+        return session;
+    }
+    /** @internal */
+    forget(session) {
+        this.sessions.delete(session);
+    }
+    /** @internal Fixed one-minute window per member key. */
+    takePublishToken(pubkey) {
+        const now = this.now();
+        const window = this.publishWindows.get(pubkey);
+        if (!window || now - window.start >= 60_000) {
+            this.publishWindows.set(pubkey, { start: now, count: 1 });
+            return true;
+        }
+        if (window.count >= this.publishPerMinute)
+            return false;
+        window.count++;
+        return true;
+    }
+    /** @internal */
+    deliver(record) {
+        for (const session of [...this.sessions])
+            session.deliver(record);
+    }
+    get sessionCount() {
+        return this.sessions.size;
+    }
+    /** Dispose every session. The store stays owned by the caller. */
+    close() {
+        for (const session of [...this.sessions])
+            session.dispose();
+        this.publishWindows.clear();
+    }
+}
+//# sourceMappingURL=room-hub.js.map

package/dist/fleet/rooms/room-identity.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Fleet rooms — member key file.
+ *
+ * A Buzz agent is identified by its own keypair (`BUZZ_PRIVATE_KEY`); a fleet
+ * room member likewise owns a secp256k1 key stored in a 0600 JSON file,
+ * `$CODEBUDDY_FLEET_ROOMS_IDENTITY` or `<CODEBUDDY_HOME>/fleet/rooms-identity.json`.
+ * The file is only created on explicit request and never overwritten silently;
+ * on POSIX a file readable by group or others is refused, like an SSH key.
+ * The secret never leaves this module except as the signing input.
+ *
+ * @module fleet/rooms/room-identity
+ */
+export interface RoomIdentity {
+    readonly publicKey: string;
+    readonly secretKey: string;
+    readonly path: string;
+}
+export declare class RoomIdentityError extends Error {
+    constructor(message: string);
+}
+export declare function defaultRoomIdentityPath(): string;
+/** Create a new identity file. Refuses to replace an existing one unless `force`. */
+export declare function createRoomIdentity(filePath?: string, options?: {
+    force?: boolean;
+}): RoomIdentity;
+export declare function loadRoomIdentity(filePath?: string): RoomIdentity;

package/dist/fleet/rooms/room-identity.js

@@ -0,0 +1,82 @@
+/**
+ * Fleet rooms — member key file.
+ *
+ * A Buzz agent is identified by its own keypair (`BUZZ_PRIVATE_KEY`); a fleet
+ * room member likewise owns a secp256k1 key stored in a 0600 JSON file,
+ * `$CODEBUDDY_FLEET_ROOMS_IDENTITY` or `<CODEBUDDY_HOME>/fleet/rooms-identity.json`.
+ * The file is only created on explicit request and never overwritten silently;
+ * on POSIX a file readable by group or others is refused, like an SSH key.
+ * The secret never leaves this module except as the signing input.
+ *
+ * @module fleet/rooms/room-identity
+ */
+import fs from 'fs';
+import path from 'path';
+import { getCodeBuddyPath } from '../../utils/codebuddy-home.js';
+import { deriveRoomPublicKey, generateRoomSecretKey, isHex64 } from './room-event.js';
+export class RoomIdentityError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'RoomIdentityError';
+    }
+}
+export function defaultRoomIdentityPath() {
+    return process.env.CODEBUDDY_FLEET_ROOMS_IDENTITY || getCodeBuddyPath('fleet', 'rooms-identity.json');
+}
+/** Create a new identity file. Refuses to replace an existing one unless `force`. */
+export function createRoomIdentity(filePath = defaultRoomIdentityPath(), options = {}) {
+    fs.mkdirSync(path.dirname(filePath), { recursive: true, mode: 0o700 });
+    const secretKey = generateRoomSecretKey();
+    const publicKey = deriveRoomPublicKey(secretKey);
+    const body = `${JSON.stringify({ version: 1, publicKey, secretKey, createdAt: new Date().toISOString() }, null, 2)}\n`;
+    if (options.force && fs.existsSync(filePath)) {
+        fs.renameSync(filePath, `${filePath}.replaced-${Date.now()}`);
+    }
+    let fd;
+    try {
+        fd = fs.openSync(filePath, 'wx', 0o600);
+    }
+    catch (error) {
+        if (error.code === 'EEXIST') {
+            throw new RoomIdentityError(`identity file already exists: ${filePath} (use --force to rotate it)`);
+        }
+        throw error;
+    }
+    try {
+        fs.writeSync(fd, body);
+        fs.fsyncSync(fd);
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+    return Object.freeze({ publicKey, secretKey, path: filePath });
+}
+export function loadRoomIdentity(filePath = defaultRoomIdentityPath()) {
+    let stat;
+    try {
+        stat = fs.statSync(filePath);
+    }
+    catch {
+        throw new RoomIdentityError(`no fleet room identity at ${filePath}; run \`buddy fleet rooms identity init\``);
+    }
+    if (process.platform !== 'win32' && (stat.mode & 0o077) !== 0) {
+        throw new RoomIdentityError(`identity file ${filePath} is readable by other users; chmod 600 it`);
+    }
+    if (stat.size > 4_096)
+        throw new RoomIdentityError(`identity file ${filePath} is not a room identity`);
+    let parsed;
+    try {
+        parsed = JSON.parse(fs.readFileSync(filePath, 'utf8'));
+    }
+    catch {
+        throw new RoomIdentityError(`identity file ${filePath} is not valid JSON`);
+    }
+    if (parsed.version !== 1 || !isHex64(parsed.secretKey) || !isHex64(parsed.publicKey)) {
+        throw new RoomIdentityError(`identity file ${filePath} is not a room identity`);
+    }
+    if (deriveRoomPublicKey(parsed.secretKey) !== parsed.publicKey) {
+        throw new RoomIdentityError(`identity file ${filePath} is inconsistent (public key mismatch)`);
+    }
+    return Object.freeze({ publicKey: parsed.publicKey, secretKey: parsed.secretKey, path: filePath });
+}
+//# sourceMappingURL=room-identity.js.map

package/dist/fleet/rooms/room-lock.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Fleet rooms — exclusive single-writer lock for one ledger directory.
+ *
+ * Two `buddy server` processes commonly share one HOME. Without a lock both
+ * would hand out the same `seq` and one compaction would erase the other's
+ * appends. The lock is a `writer.lock` file created with `O_CREAT|O_EXCL`
+ * holding `{ pid, hostname, token }`.
+ *
+ * Recovery is deliberately narrow: a lock is reclaimed only when it names THIS
+ * host and a pid that no longer exists (`ESRCH`). A live pid (even a reused
+ * one), another host, `EPERM` or an unreadable/corrupt lock file all fail
+ * closed with {@link RoomLockError}; the operator removes the file by hand.
+ *
+ * @module fleet/rooms/room-lock
+ */
+export declare class RoomLockError extends Error {
+    constructor(message: string);
+}
+export declare class RoomDirectoryLock {
+    readonly lockPath: string;
+    private readonly recoveryLockPath;
+    private readonly token;
+    private released;
+    private constructor();
+    /** Acquire the lock or throw {@link RoomLockError}. */
+    static acquire(directory: string): RoomDirectoryLock;
+    private tryCreateRecoveryMutex;
+    private releaseRecoveryMutex;
+    private tryCreate;
+    /** True while the lock file on disk still carries this holder's token. */
+    isHeld(): boolean;
+    /** Release once; never removes a lock that another holder now owns. */
+    release(): void;
+}