@phuetz/code-buddy 2.0.0 → 2.2.0

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

@@ -0,0 +1,138 @@
+/**
+ * Fleet rooms — membership and access policy.
+ *
+ * Buzz makes channel membership "the only gate", enforced by the relay before
+ * any read or write (`ARCHITECTURE.md` §7, `crates/buzz-relay/src/handlers/req.rs`).
+ * Here the hub operator declares members (public keys) and rooms in one file:
+ *
+ * ```json
+ * {
+ *   "version": 1,
+ *   "members": { "<pubkey hex>": { "name": "peer-alpha", "principals": ["key:abc"] } },
+ *   "rooms": { "general": { "members": ["<pubkey hex>"], "readers": ["<pubkey hex>"] } }
+ * }
+ * ```
+ *
+ * - `rooms.<id>.members` may read and write; `readers` may only read.
+ * - `principals` binds a key to WebSocket identities: when the field is ABSENT
+ *   the key is accepted on any authenticated connection; when it is a list the
+ *   connection principal must be in it; an EMPTY list refuses every connection.
+ *
+ * Fail-closed: a missing, unreadable or invalid file yields no member and no
+ * room. Refresh window: the file's `mtimeMs`/`ctimeMs`/size/inode are checked at
+ * most once per `reloadIntervalMs` (default 1000 ms), so a revocation applies
+ * to the first check after that window — including deliveries to subscriptions
+ * that are already open.
+ *
+ * @module fleet/rooms/room-access
+ */
+import { z } from 'zod';
+export declare const MAX_ROOM_ACCESS_MEMBERS = 1024;
+export declare const MAX_ROOM_ACCESS_ROOMS = 1024;
+declare const configSchema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    members: z.ZodRecord<z.ZodString, z.ZodObject<{
+        name: z.ZodString;
+        principals: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    }, "strict", z.ZodTypeAny, {
+        name: string;
+        principals?: string[] | undefined;
+    }, {
+        name: string;
+        principals?: string[] | undefined;
+    }>>;
+    rooms: z.ZodRecord<z.ZodString, z.ZodObject<{
+        description: z.ZodOptional<z.ZodString>;
+        members: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+        readers: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    }, "strict", z.ZodTypeAny, {
+        members: string[];
+        readers: string[];
+        description?: string | undefined;
+    }, {
+        description?: string | undefined;
+        members?: string[] | undefined;
+        readers?: string[] | undefined;
+    }>>;
+}, "strict", z.ZodTypeAny, {
+    version: 1;
+    members: Record<string, {
+        name: string;
+        principals?: string[] | undefined;
+    }>;
+    rooms: Record<string, {
+        members: string[];
+        readers: string[];
+        description?: string | undefined;
+    }>;
+}, {
+    version: 1;
+    members: Record<string, {
+        name: string;
+        principals?: string[] | undefined;
+    }>;
+    rooms: Record<string, {
+        description?: string | undefined;
+        members?: string[] | undefined;
+        readers?: string[] | undefined;
+    }>;
+}>;
+export type RoomAccessConfigInput = z.input<typeof configSchema>;
+export interface RoomMember {
+    readonly pubkey: string;
+    readonly name: string;
+    /** `undefined`: no binding. `[]`: refuse all connections. */
+    readonly principals?: readonly string[];
+}
+export type RoomAccessLevel = 'write' | 'read';
+interface CompiledRoom {
+    description?: string;
+    writers: ReadonlySet<string>;
+    readers: ReadonlySet<string>;
+}
+interface CompiledConfig {
+    members: ReadonlyMap<string, RoomMember>;
+    rooms: ReadonlyMap<string, CompiledRoom>;
+}
+export declare function defaultRoomAccessPath(): string;
+/** Validate and compile a configuration object; throws a readable error. */
+export declare function compileRoomAccessConfig(input: unknown): CompiledConfig;
+export interface RoomAccessPolicyOptions {
+    /** Read this JSON file (default `$CODEBUDDY_FLEET_ROOMS_CONFIG` or `<CODEBUDDY_HOME>/fleet/rooms.json`). */
+    path?: string;
+    /** Use an in-memory configuration instead of a file (tests, embedding). */
+    config?: RoomAccessConfigInput;
+    /** Minimum delay between two file checks, in ms (finite, >= 0). */
+    reloadIntervalMs?: number;
+}
+export declare class RoomAccessPolicy {
+    private readonly path?;
+    private readonly reloadIntervalMs;
+    private compiled;
+    private loadedStamp?;
+    private lastCheckMs;
+    private lastProblem?;
+    constructor(options?: RoomAccessPolicyOptions);
+    private report;
+    private deny;
+    private refresh;
+    /** Frozen member record, or undefined. */
+    member(pubkey: string): RoomMember | undefined;
+    /** May this key act on a connection authenticated as `principalId`? */
+    admit(pubkey: string, principalId: string): {
+        ok: true;
+        member: RoomMember;
+    } | {
+        ok: false;
+        reason: string;
+    };
+    access(pubkey: string, room: string): RoomAccessLevel | undefined;
+    canRead(pubkey: string, room: string): boolean;
+    canWrite(pubkey: string, room: string): boolean;
+    roomsFor(pubkey: string): Array<{
+        room: string;
+        access: RoomAccessLevel;
+        description?: string;
+    }>;
+}
+export {};

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

@@ -0,0 +1,196 @@
+/**
+ * Fleet rooms — membership and access policy.
+ *
+ * Buzz makes channel membership "the only gate", enforced by the relay before
+ * any read or write (`ARCHITECTURE.md` §7, `crates/buzz-relay/src/handlers/req.rs`).
+ * Here the hub operator declares members (public keys) and rooms in one file:
+ *
+ * ```json
+ * {
+ *   "version": 1,
+ *   "members": { "<pubkey hex>": { "name": "peer-alpha", "principals": ["key:abc"] } },
+ *   "rooms": { "general": { "members": ["<pubkey hex>"], "readers": ["<pubkey hex>"] } }
+ * }
+ * ```
+ *
+ * - `rooms.<id>.members` may read and write; `readers` may only read.
+ * - `principals` binds a key to WebSocket identities: when the field is ABSENT
+ *   the key is accepted on any authenticated connection; when it is a list the
+ *   connection principal must be in it; an EMPTY list refuses every connection.
+ *
+ * Fail-closed: a missing, unreadable or invalid file yields no member and no
+ * room. Refresh window: the file's `mtimeMs`/`ctimeMs`/size/inode are checked at
+ * most once per `reloadIntervalMs` (default 1000 ms), so a revocation applies
+ * to the first check after that window — including deliveries to subscriptions
+ * that are already open.
+ *
+ * @module fleet/rooms/room-access
+ */
+import fs from 'fs';
+import { z } from 'zod';
+import { getCodeBuddyPath } from '../../utils/codebuddy-home.js';
+import { logger } from '../../utils/logger.js';
+import { ROOM_ID_PATTERN } from './room-event.js';
+export const MAX_ROOM_ACCESS_MEMBERS = 1_024;
+export const MAX_ROOM_ACCESS_ROOMS = 1_024;
+const MAX_CONFIG_BYTES = 1024 * 1024;
+const pubkeySchema = z.string().regex(/^[0-9a-f]{64}$/);
+const configSchema = z.object({
+    version: z.literal(1),
+    members: z.record(pubkeySchema, z.object({
+        name: z.string().min(1).max(64),
+        principals: z.array(z.string().min(1).max(256)).max(32).optional(),
+    }).strict()),
+    rooms: z.record(z.string().regex(ROOM_ID_PATTERN), z.object({
+        description: z.string().max(512).optional(),
+        members: z.array(pubkeySchema).max(MAX_ROOM_ACCESS_MEMBERS).default([]),
+        readers: z.array(pubkeySchema).max(MAX_ROOM_ACCESS_MEMBERS).default([]),
+    }).strict()),
+}).strict();
+const EMPTY_CONFIG = { members: new Map(), rooms: new Map() };
+export function defaultRoomAccessPath() {
+    return process.env.CODEBUDDY_FLEET_ROOMS_CONFIG || getCodeBuddyPath('fleet', 'rooms.json');
+}
+/** Validate and compile a configuration object; throws a readable error. */
+export function compileRoomAccessConfig(input) {
+    const parsed = configSchema.safeParse(input);
+    if (!parsed.success) {
+        const issue = parsed.error.issues[0];
+        throw new Error(`invalid rooms config at ${issue?.path.join('.') || '<root>'}: ${issue?.message ?? 'unknown'}`);
+    }
+    const memberEntries = Object.entries(parsed.data.members);
+    const roomEntries = Object.entries(parsed.data.rooms);
+    if (memberEntries.length > MAX_ROOM_ACCESS_MEMBERS) {
+        throw new Error(`invalid rooms config: more than ${MAX_ROOM_ACCESS_MEMBERS} members`);
+    }
+    if (roomEntries.length > MAX_ROOM_ACCESS_ROOMS) {
+        throw new Error(`invalid rooms config: more than ${MAX_ROOM_ACCESS_ROOMS} rooms`);
+    }
+    const members = new Map();
+    for (const [pubkey, member] of memberEntries) {
+        members.set(pubkey, Object.freeze({
+            pubkey,
+            name: member.name,
+            ...(member.principals ? { principals: Object.freeze([...member.principals]) } : {}),
+        }));
+    }
+    const rooms = new Map();
+    for (const [room, spec] of roomEntries) {
+        for (const pubkey of [...spec.members, ...spec.readers]) {
+            if (!members.has(pubkey)) {
+                throw new Error(`invalid rooms config: room ${room} lists an undeclared member ${pubkey.slice(0, 12)}…`);
+            }
+        }
+        rooms.set(room, {
+            ...(spec.description ? { description: spec.description } : {}),
+            writers: new Set(spec.members),
+            readers: new Set([...spec.members, ...spec.readers]),
+        });
+    }
+    return { members, rooms };
+}
+export class RoomAccessPolicy {
+    path;
+    reloadIntervalMs;
+    compiled = EMPTY_CONFIG;
+    loadedStamp;
+    lastCheckMs = -Infinity;
+    lastProblem;
+    constructor(options = {}) {
+        const interval = options.reloadIntervalMs ?? 1_000;
+        if (typeof interval !== 'number' || !Number.isFinite(interval) || interval < 0) {
+            throw new RangeError('reloadIntervalMs must be a finite number >= 0');
+        }
+        this.reloadIntervalMs = interval;
+        if (options.config) {
+            this.compiled = compileRoomAccessConfig(options.config);
+        }
+        else {
+            this.path = options.path ?? defaultRoomAccessPath();
+            this.refresh(true);
+        }
+    }
+    report(problem) {
+        if (problem && problem !== this.lastProblem) {
+            logger.warn(`[fleet-rooms] access policy denies everything: ${problem}`);
+        }
+        this.lastProblem = problem;
+    }
+    deny(problem) {
+        this.compiled = EMPTY_CONFIG;
+        this.report(problem);
+    }
+    refresh(force = false) {
+        if (!this.path)
+            return;
+        const now = Date.now();
+        if (!force && now - this.lastCheckMs < this.reloadIntervalMs)
+            return;
+        this.lastCheckMs = now;
+        let stat;
+        try {
+            stat = fs.statSync(this.path);
+        }
+        catch {
+            this.loadedStamp = undefined;
+            this.deny(`no rooms config at ${this.path}`);
+            return;
+        }
+        const stamp = `${stat.mtimeMs}:${stat.ctimeMs}:${stat.size}:${stat.ino}`;
+        if (stamp === this.loadedStamp)
+            return;
+        this.loadedStamp = stamp;
+        if (stat.size > MAX_CONFIG_BYTES) {
+            this.deny(`rooms config larger than ${MAX_CONFIG_BYTES} bytes`);
+            return;
+        }
+        try {
+            this.compiled = compileRoomAccessConfig(JSON.parse(fs.readFileSync(this.path, 'utf8')));
+            this.report(undefined);
+        }
+        catch (error) {
+            this.deny(error instanceof Error ? error.message : String(error));
+        }
+    }
+    /** Frozen member record, or undefined. */
+    member(pubkey) {
+        this.refresh();
+        return this.compiled.members.get(pubkey);
+    }
+    /** May this key act on a connection authenticated as `principalId`? */
+    admit(pubkey, principalId) {
+        const member = this.member(pubkey);
+        if (!member)
+            return { ok: false, reason: 'restricted: key is not a declared room member' };
+        if (member.principals !== undefined && !member.principals.includes(principalId)) {
+            return { ok: false, reason: 'restricted: key is not bound to this connection identity' };
+        }
+        return { ok: true, member };
+    }
+    access(pubkey, room) {
+        this.refresh();
+        const spec = this.compiled.rooms.get(room);
+        if (!spec || !this.compiled.members.has(pubkey))
+            return undefined;
+        if (spec.writers.has(pubkey))
+            return 'write';
+        return spec.readers.has(pubkey) ? 'read' : undefined;
+    }
+    canRead(pubkey, room) {
+        return this.access(pubkey, room) !== undefined;
+    }
+    canWrite(pubkey, room) {
+        return this.access(pubkey, room) === 'write';
+    }
+    roomsFor(pubkey) {
+        this.refresh();
+        const result = [];
+        for (const [room, spec] of this.compiled.rooms) {
+            const access = this.access(pubkey, room);
+            if (access)
+                result.push({ room, access, ...(spec.description ? { description: spec.description } : {}) });
+        }
+        return result.sort((a, b) => a.room.localeCompare(b.room));
+    }
+}
+//# sourceMappingURL=room-access.js.map

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

@@ -0,0 +1,158 @@
+/**
+ * Fleet rooms — member client.
+ *
+ * Reconnection follows the Buzz ACP harness (`crates/buzz-acp/src/relay.rs`):
+ * resubscribe after reconnect from a per-subscription cursor and drop events
+ * already seen with a two-generation id set (`TwoGenDedup`, 12 000 ids). The
+ * cursor is the hub `seq` (plus its `storeId`) instead of `created_at`, so
+ * member clock drift cannot open a hole.
+ *
+ * Everything received is untrusted data: signatures and room tags are checked
+ * again locally (the hub could be compromised), and `text` is the content
+ * passed through the fleet peer-text sanitizer. This client never runs a tool,
+ * a prompt or a command because of a message.
+ *
+ * @module fleet/rooms/room-client
+ */
+import { EventEmitter } from 'events';
+import { type ReadonlyRoomEvent, type RoomEvent, type RoomMessageInput, type ThreadReference } from './room-event.js';
+import { type RoomFilter } from './room-filter.js';
+export interface FleetRoomClientOptions {
+    /** Hub WebSocket URL, e.g. `ws://127.0.0.1:3000/ws`. */
+    url: string;
+    apiKey?: string;
+    jwt?: string;
+    /** Member secret key (64 hex). Never logged or sent. */
+    secretKey: string;
+    /** Audience override for a hub reached through a proxy; defaults to `url`. */
+    audience?: string;
+    requestTimeoutMs?: number;
+    autoReconnect?: boolean;
+    reconnectInitialDelayMs?: number;
+    reconnectMaxDelayMs?: number;
+    /** Consecutive failed reconnection attempts before giving up. */
+    reconnectMaxAttempts?: number;
+}
+export interface RoomCursor {
+    storeId: string;
+    throughSeq: number;
+}
+export interface RoomFetchOptions {
+    /** Maximum messages retained by this one-shot read (default 500, maximum 1000). */
+    maxMessages?: number;
+    /** Maximum approximate encoded result size (default and maximum 4 MiB). */
+    maxBytes?: number;
+}
+export interface ReceivedRoomMessage {
+    seq: number;
+    room: string;
+    author: string;
+    event: ReadonlyRoomEvent;
+    mentions: string[];
+    thread?: ThreadReference;
+    /** Content after the peer-text sanitizer; display it, never execute it. */
+    text: string;
+}
+export interface RoomEoseInfo {
+    storeId: string;
+    throughSeq: number;
+    gap: boolean;
+    epochChanged: boolean;
+    /** More replay records exist after `throughSeq`. */
+    truncated: boolean;
+}
+export interface RoomSubscriptionHandlers {
+    onMessage(message: ReceivedRoomMessage): void;
+    /** Stored events delivered; later messages are live. */
+    onEose?(info: RoomEoseInfo): void;
+    /** Terminal close (`restricted:`, `invalid:` …); the subscription is gone. */
+    onClosed?(message: string): void;
+}
+export interface RoomSubscriptionHandle {
+    readonly subId: string;
+    cursor(): RoomCursor | undefined;
+    close(): Promise<void>;
+}
+export declare class RoomClientError extends Error {
+    readonly code: string;
+    constructor(message: string, code: string);
+}
+interface RoomConnectionInfo {
+    pubkey: string;
+    name: string;
+    rooms: unknown[];
+}
+export declare class FleetRoomClient extends EventEmitter {
+    readonly pubkey: string;
+    readonly audience: string;
+    private readonly options;
+    private readonly requestTimeoutMs;
+    private readonly reconnectInitialDelayMs;
+    private readonly reconnectMaxDelayMs;
+    private readonly reconnectMaxAttempts;
+    private ws;
+    private ready;
+    private closing;
+    private everConnected;
+    private requestCounter;
+    private readonly pending;
+    private readonly subscriptions;
+    private readonly seen;
+    private reconnectTimer;
+    private reconnectAttempts;
+    private readyWaiters;
+    private opening;
+    private connectionInfo;
+    constructor(options: FleetRoomClientOptions);
+    get isReady(): boolean;
+    /** Connect, authenticate the WebSocket, then prove the member key. */
+    connect(): Promise<RoomConnectionInfo>;
+    private startOpen;
+    private open;
+    private proveIdentity;
+    private sendRaw;
+    private request;
+    private handleMessage;
+    private onEvent;
+    private onEose;
+    private onClosed;
+    private closeSubscriptionLocally;
+    private callHandler;
+    private sendSubscribe;
+    private waitUntilReady;
+    /**
+     * Sign and publish. Resolves once the hub has durably stored the message
+     * (or already had it). A connection lost before the acknowledgement is
+     * retried once with the SAME signed event, which the hub deduplicates.
+     */
+    publish(input: RoomMessageInput): Promise<{
+        id: string;
+        seq: number;
+        duplicate: boolean;
+        storeId: string;
+    }>;
+    publishSigned(event: RoomEvent): Promise<{
+        id: string;
+        seq: number;
+        duplicate: boolean;
+        storeId: string;
+    }>;
+    /** Open a subscription; it survives reconnections until closed. */
+    subscribe(subId: string, filters: RoomFilter[], handlers: RoomSubscriptionHandlers, cursor?: RoomCursor): RoomSubscriptionHandle;
+    private openSubscription;
+    /**
+     * One-shot read: stored messages matching `filters` (or after `cursor`),
+     * returned with the cursor to resume from next time.
+     */
+    fetch(filters: RoomFilter[], cursor?: RoomCursor, options?: RoomFetchOptions): Promise<{
+        messages: ReceivedRoomMessage[];
+        cursor: RoomCursor;
+        gap: boolean;
+        epochChanged: boolean;
+        truncated: boolean;
+    }>;
+    private onSocketClosed;
+    private scheduleReconnect;
+    close(): Promise<void>;
+}
+export {};