@phuetz/code-buddy 2.0.0 → 2.1.0

package/dist/fleet/resource-catalog.js

@@ -0,0 +1,211 @@
+/** Explicit resources; health is not proof that a model/capability works. */
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { createHash } from 'node:crypto';
+import { z } from 'zod';
+import { writeJsonAtomic } from '../utils/atomic-write.js';
+const identifier = z.string().regex(/^[a-zA-Z0-9][a-zA-Z0-9._:-]{0,95}$/);
+export const resourceSchema = z.object({
+    id: identifier,
+    kind: z.enum(['inference', 'comfyui', 'storage', 'rag', 'database', 'docker', 'code-explorer', 'camera', 'microphone']),
+    hostId: identifier,
+    declaredCapabilities: z.array(identifier).min(1).max(32),
+    endpointRef: z.string().regex(/^[A-Z][A-Z0-9_]{0,95}$/),
+    healthPath: z.enum(['/health', '/healthz', '/api/health', '/v1/models', '/api/tags', '/system_stats', '/_ping']),
+    permissions: z.object({ probe: z.boolean(), use: z.boolean() }).strict(),
+    ttlMs: z.number().int().min(1000).max(3600000).default(60000),
+    timeoutMs: z.number().int().min(50).max(5000).default(1000),
+}).strict();
+const observationSchema = z.object({
+    state: z.enum(['online', 'offline', 'unknown']),
+    checkedAt: z.number().nonnegative(),
+    lastSeen: z.number().nonnegative().nullable(),
+    latencyMs: z.number().nonnegative().nullable(),
+    endpointFingerprint: z.string(),
+    reason: z.string(),
+}).strict();
+const entrySchema = z.object({ resource: resourceSchema, observation: observationSchema.nullable() }).strict();
+const storeSchema = z.object({ version: z.literal(1), entries: z.array(entrySchema).max(100) }).strict();
+/** Declarations and observations only: never the resolved endpoint value or the internal fingerprint. */
+export function publicResourceStatus(entry) {
+    return { resource: entry.resource, state: entry.state, reason: entry.reason,
+        checkedAt: entry.observation?.checkedAt ?? null, lastSeen: entry.observation?.lastSeen ?? null,
+        latencyMs: entry.observation?.latencyMs ?? null, load: entry.load, usageConfirmed: entry.usageConfirmed };
+}
+/** The RagChat connector reads this reference only; a selection never redirects it. */
+export const RAGCHAT_ENDPOINT_REF = 'RAGCHAT_BASE_URL';
+export function selectionWarning(selected) {
+    if (!selected || selected.resource.kind !== 'rag' || selected.resource.endpointRef === RAGCHAT_ENDPOINT_REF)
+        return undefined;
+    return `ragchat_search interroge toujours ${RAGCHAT_ENDPOINT_REF} ; cette ressource référence ${selected.resource.endpointRef} et la sélection ne redirige pas le connecteur.`;
+}
+const allowedPaths = {
+    inference: ['/health', '/healthz', '/v1/models', '/api/tags'],
+    comfyui: ['/system_stats'],
+    rag: ['/health', '/healthz', '/api/health'],
+    docker: ['/_ping'],
+    'code-explorer': ['/health', '/healthz', '/api/health'],
+};
+function endpoint(resource) {
+    const raw = process.env[resource.endpointRef];
+    if (!raw)
+        throw new Error('ENDPOINT_UNCONFIGURED');
+    let url;
+    try {
+        url = new URL(raw);
+    }
+    catch {
+        throw new Error('ENDPOINT_INVALID');
+    }
+    if (!['http:', 'https:'].includes(url.protocol) || url.username || url.password || url.search || url.hash || url.pathname !== '/') {
+        throw new Error('ENDPOINT_INVALID');
+    }
+    url.pathname = resource.healthPath;
+    return { url, fingerprint: createHash('sha256').update(url.href).digest('hex') };
+}
+export class ResourceCatalog {
+    filename;
+    now;
+    constructor(filename = path.join(os.homedir(), '.codebuddy', 'resources', 'catalog.json'), now = Date.now) {
+        this.filename = filename;
+        this.now = now;
+    }
+    async read() {
+        try {
+            const stat = await fs.lstat(this.filename);
+            if (!stat.isFile() || stat.isSymbolicLink() || stat.size > 1024 * 1024)
+                throw new Error('INVALID_CATALOG_FILE');
+            const parsed = storeSchema.safeParse(JSON.parse(await fs.readFile(this.filename, 'utf8')));
+            if (!parsed.success || new Set(parsed.data.entries.map(e => e.resource.id)).size !== parsed.data.entries.length) {
+                throw new Error('INVALID_CATALOG');
+            }
+            return parsed.data;
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                return { version: 1, entries: [] };
+            throw new Error('INVALID_CATALOG: existing data was not replaced');
+        }
+    }
+    async update(action) {
+        const directory = path.dirname(this.filename);
+        await fs.mkdir(directory, { recursive: true, mode: 0o700 });
+        const stat = await fs.lstat(directory);
+        if (!stat.isDirectory() || stat.isSymbolicLink())
+            throw new Error('INVALID_CATALOG_DIRECTORY');
+        await fs.chmod(directory, 0o700);
+        const lock = `${this.filename}.lock`;
+        try {
+            await fs.mkdir(lock, { mode: 0o700 });
+        }
+        catch {
+            throw new Error('CATALOG_BUSY: another writer or unrecovered lock');
+        }
+        try {
+            const store = await this.read();
+            const result = await action(store);
+            await writeJsonAtomic(this.filename, store, { mode: 0o600 });
+            return result;
+        }
+        finally {
+            await fs.rmdir(lock);
+        }
+    }
+    async add(input) {
+        const parsed = resourceSchema.safeParse(input);
+        if (!parsed.success)
+            throw new Error('INVALID_RESOURCE: check schema; inline endpoints and extra fields are forbidden');
+        return this.update(async (store) => {
+            if (store.entries.some(e => e.resource.id === parsed.data.id))
+                throw new Error('RESOURCE_EXISTS');
+            if (store.entries.length >= 100)
+                throw new Error('CATALOG_FULL');
+            store.entries.push({ resource: parsed.data, observation: null });
+            return parsed.data;
+        });
+    }
+    async remove(id) {
+        return this.update(async (store) => {
+            const index = store.entries.findIndex(e => e.resource.id === id);
+            if (index < 0)
+                throw new Error('RESOURCE_NOT_FOUND');
+            store.entries.splice(index, 1);
+            return { removed: id };
+        });
+    }
+    status(entry) {
+        const { resource, observation } = entry;
+        let state = observation?.state ?? 'unknown';
+        let reason = observation?.reason ?? 'NEVER_PROBED';
+        if (observation && (this.now() - observation.checkedAt >= resource.ttlMs || observation.checkedAt > this.now())) {
+            state = 'stale';
+            reason = 'OBSERVATION_EXPIRED';
+        }
+        try {
+            if (observation && observation.endpointFingerprint !== endpoint(resource).fingerprint) {
+                state = 'unknown';
+                reason = 'ENDPOINT_CHANGED';
+            }
+        }
+        catch {
+            state = 'unknown';
+            reason = 'ENDPOINT_UNCONFIGURED_OR_INVALID';
+        }
+        return { ...entry, state, reason, load: null, usageConfirmed: false };
+    }
+    async list() { return (await this.read()).entries.map(e => this.status(e)); }
+    async probe(id) {
+        // Lock covers the bounded probe so a later probe cannot be overwritten by an older completion.
+        return this.update(async (store) => {
+            const entry = store.entries.find(e => e.resource.id === id);
+            if (!entry)
+                throw new Error('RESOURCE_NOT_FOUND');
+            const r = entry.resource;
+            if (!r.permissions.probe)
+                throw new Error('PROBE_NOT_PERMITTED');
+            if (!allowedPaths[r.kind]?.includes(r.healthPath))
+                throw new Error('NO_READ_ONLY_PROBE_FOR_KIND_PATH');
+            const target = endpoint(r);
+            const start = this.now();
+            let state = 'offline';
+            let reason = 'PROBE_FAILED';
+            try {
+                const response = await fetch(target.url, { method: 'GET', redirect: 'manual', signal: AbortSignal.timeout(r.timeoutMs) });
+                state = response.ok ? 'online' : 'offline';
+                reason = response.ok ? 'HTTP_HEALTH_OK_NOT_USAGE_PROOF' : `HTTP_${response.status}`;
+                // Never parse service content, model lists, database contents or device frames.
+                await response.body?.cancel();
+            }
+            catch {
+                state = 'offline';
+                reason = 'UNREACHABLE_OR_TIMEOUT';
+            }
+            const checkedAt = this.now();
+            entry.observation = { state, reason, checkedAt, lastSeen: state === 'online' ? checkedAt
+                    : entry.observation?.endpointFingerprint === target.fingerprint ? entry.observation.lastSeen : null,
+                latencyMs: state === 'online' ? Math.max(0, checkedAt - start) : null, endpointFingerprint: target.fingerprint };
+            return this.status(entry);
+        });
+    }
+    async select(capability, kind) {
+        if (!identifier.safeParse(capability).success)
+            throw new Error('INVALID_CAPABILITY');
+        const excluded = [];
+        const candidates = (await this.list()).filter(e => {
+            const reason = kind && e.resource.kind !== kind ? 'KIND_MISMATCH'
+                : !e.resource.declaredCapabilities.includes(capability) ? 'CAPABILITY_NOT_DECLARED'
+                    : !e.resource.permissions.use ? 'USE_NOT_PERMITTED'
+                        : e.state !== 'online' ? e.reason : null;
+            if (reason)
+                excluded.push({ id: e.resource.id, reason });
+            return !reason;
+        });
+        // Load unknown: do not fabricate free capacity. Stable deterministic latency/id choice only.
+        candidates.sort((a, b) => (a.observation?.latencyMs ?? Infinity) - (b.observation?.latencyMs ?? Infinity)
+            || a.resource.id.localeCompare(b.resource.id));
+        return { selected: candidates[0] ?? null, excluded,
+            reason: candidates.length ? 'FRESH_HEALTH_DECLARED_CAPABILITY_LOAD_UNKNOWN' : 'NO_ELIGIBLE_RESOURCE' };
+    }
+}
+//# sourceMappingURL=resource-catalog.js.map

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