@ours.network/fleet 0.12.0 → 0.13.1

package/dist/owner-channel/attachments.js

@@ -0,0 +1,378 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { chmodSync, constants, existsSync, lstatSync, mkdirSync, readFileSync, } from 'node:fs';
+import { chmod, link, lstat, mkdir, open, readdir, rm } from 'node:fs/promises';
+import { basename, join } from 'node:path';
+import { replaceFileAtomically } from '../atomic-file.js';
+const WIRE = /^[A-Fa-f0-9]{64}$/;
+const CID = /^[A-Fa-f0-9]{64}$/;
+const MAX_PENDING_REQUESTS = 32;
+export function parseIncomingAttachments(raw) {
+    const values = raw?.files;
+    if (!Array.isArray(values))
+        return [];
+    const out = [];
+    for (const value of values) {
+        if (!value || typeof value !== 'object')
+            continue;
+        const file = value;
+        const from = file.from;
+        const reply = file.reply_to;
+        const wireId = String(file.wire_id ?? '');
+        const senderId = String(from?.id ?? '');
+        const size = Number(file.size);
+        const fileId = Number(file.file_id);
+        if (!WIRE.test(wireId) || !CID.test(senderId) || !Number.isSafeInteger(size) || size < 0
+            || !Number.isSafeInteger(fileId) || fileId < 1)
+            continue;
+        const replyWire = String(reply?.wire_id ?? '');
+        out.push({
+            fileId, wireId, senderId, senderName: safeField(from?.name, 160),
+            filename: safeField(file.filename, 255), mime: String(file.mime ?? '').toLowerCase(),
+            size, status: String(file.status ?? ''), date: safeField(file.date, 80),
+            kind: file.kind === 'voice_message' ? 'voice_message' : 'file',
+            replyTo: WIRE.test(replyWire) ? { wire_id: replyWire,
+                ...(Number.isSafeInteger(reply?.sentence) && Number(reply?.sentence) > 0
+                    ? { sentence: Number(reply?.sentence) } : {}) } : null,
+        });
+    }
+    return out;
+}
+export function parseRetrievedAttachments(raw, expected, recovered = false) {
+    const values = raw?.files;
+    if (!Array.isArray(values) || values.length !== expected.length)
+        throw new Error('ours-mcp returned an incomplete selected attachment set');
+    const byWire = new Map(expected.map(file => [file.wireId, file]));
+    const out = [];
+    for (const value of values) {
+        if (!value || typeof value !== 'object')
+            throw new Error('ours-mcp returned invalid attachment metadata');
+        const file = value;
+        const wireId = String(file.wire_id ?? '');
+        const listed = byWire.get(wireId);
+        const from = file.from;
+        const size = Number(file.size);
+        const sha256 = String(file.sha256 ?? '');
+        const mime = String(file.mime ?? '').toLowerCase();
+        const kind = file.kind === 'voice_message' ? 'voice_message' : 'file';
+        if (!listed || String(from?.id ?? '') !== listed.senderId
+            || !Number.isSafeInteger(size) || size !== listed.size || mime !== listed.mime
+            || kind !== listed.kind || !/^[a-f0-9]{64}$/.test(sha256)
+            || typeof file.path !== 'string' || !file.path)
+            throw new Error('ours-mcp selected attachment provenance or integrity metadata mismatched');
+        out.push({
+            ...listed, filename: safeField(file.filename, 255), mime, size, path: file.path, sha256, kind,
+            ...(recovered ? {} : parseTranscription(file.transcription, wireId)),
+        });
+        byWire.delete(wireId);
+    }
+    if (byWire.size)
+        throw new Error('ours-mcp omitted a selected attachment');
+    return out;
+}
+function parseTranscription(value, wireId) {
+    if (!value || typeof value !== 'object')
+        return {};
+    const item = value;
+    if (!['succeeded', 'failed', 'unavailable'].includes(String(item.status ?? ''))
+        || String(item.file_wire_id ?? '') !== wireId)
+        return {};
+    const status = item.status;
+    return { transcription: {
+            configured: item.configured === true, attempted: item.attempted === true, status,
+            provider: typeof item.provider === 'string' ? safeField(item.provider, 80) : null,
+            text: status === 'succeeded' && typeof item.text === 'string'
+                ? safeField(item.text, 16_000) : null,
+            errorCategory: typeof item.error_category === 'string'
+                ? safeField(item.error_category, 80) : null,
+            audioPath: typeof item.audio_path === 'string' ? item.audio_path : '',
+            fileWireId: wireId,
+        } };
+}
+export function validateAttachmentSelection(files, config) {
+    if (!config.enabled)
+        return 'attachments are disabled for this owner channel';
+    if (files.length > config.max_files_per_request)
+        return `the request exceeds the ${config.max_files_per_request}-file limit`;
+    let total = 0;
+    for (const file of files) {
+        if (!config.allowed_mime.includes(file.mime))
+            return `MIME type ${file.mime || '(missing)'} is not allowed`;
+        if (file.size > config.max_file_bytes)
+            return `a file exceeds the ${config.max_file_bytes}-byte limit`;
+        total += file.size;
+        if (!Number.isSafeInteger(total) || total > config.max_request_bytes)
+            return `the request exceeds the ${config.max_request_bytes}-byte total limit`;
+    }
+    return undefined;
+}
+export async function prepareAttachmentDirectory(root, requestId) {
+    mkdirSync(root, { recursive: true, mode: 0o700 });
+    const rootStat = lstatSync(root);
+    if (!rootStat.isDirectory() || rootStat.isSymbolicLink())
+        throw new Error('attachment root is not a safe directory');
+    chmodSync(root, 0o700);
+    const dir = join(root, requestId);
+    if (existsSync(dir))
+        await removeRequestDirectory(dir);
+    await mkdir(dir, { mode: 0o700 });
+    const stat = await lstat(dir);
+    if (!stat.isDirectory() || stat.isSymbolicLink())
+        throw new Error('attachment request path is not a safe directory');
+    await chmod(dir, 0o700);
+    return dir;
+}
+export async function admitAttachments(files, dir, config) {
+    const admitted = [];
+    let total = 0;
+    for (let index = 0; index < files.length; index++) {
+        const file = files[index];
+        const sourceStat = await lstat(file.path);
+        if (!sourceStat.isFile() || sourceStat.isSymbolicLink())
+            throw new Error('retrieved attachment path is not a regular file');
+        if (sourceStat.size > config.max_file_bytes)
+            throw new Error('retrieved attachment exceeds its size limit');
+        const handle = await open(file.path, constants.O_RDONLY | constants.O_NOFOLLOW);
+        let bytes;
+        try {
+            const opened = await handle.stat();
+            if (!opened.isFile() || opened.dev !== sourceStat.dev || opened.ino !== sourceStat.ino)
+                throw new Error('retrieved attachment changed during admission');
+            bytes = await handle.readFile();
+        }
+        finally {
+            await handle.close();
+        }
+        const digest = createHash('sha256').update(bytes).digest('hex');
+        if (bytes.length !== file.size || digest !== file.sha256)
+            throw new Error('retrieved attachment size or hash mismatched structured metadata');
+        total += bytes.length;
+        if (total > config.max_request_bytes)
+            throw new Error('retrieved attachments exceed the request size limit');
+        const detectedMime = detectMime(bytes, file.mime);
+        if (!mimeCompatible(file.mime, detectedMime))
+            throw new Error(`retrieved attachment content does not match declared MIME ${file.mime}`);
+        const filename = sanitizeFilename(file.filename);
+        const finalPath = join(dir, `${index + 1}-${file.wireId.slice(0, 12)}-${filename}`);
+        const tmp = join(dir, `.${basename(finalPath)}.${randomUUID()}.tmp`);
+        const output = await open(tmp, 'wx', 0o600);
+        try {
+            await output.writeFile(bytes);
+            await output.sync();
+        }
+        catch (error) {
+            await output.close().catch(() => { });
+            await rm(tmp, { force: true });
+            throw error;
+        }
+        await output.close();
+        try {
+            await link(tmp, finalPath);
+        }
+        catch (error) {
+            await rm(tmp, { force: true });
+            throw error;
+        }
+        await rm(tmp, { force: true });
+        await chmod(finalPath, 0o600);
+        admitted.push({
+            wireId: file.wireId, filename, path: finalPath, declaredMime: file.mime,
+            detectedMime, size: bytes.length, sha256: digest, kind: file.kind,
+            ...(file.transcription ? { transcription: {
+                    configured: file.transcription.configured, attempted: file.transcription.attempted,
+                    status: file.transcription.status, provider: file.transcription.provider,
+                    text: file.transcription.text, errorCategory: file.transcription.errorCategory,
+                    fileWireId: file.transcription.fileWireId,
+                } } : {}),
+        });
+    }
+    return admitted;
+}
+export async function recoveredAttachment(file, path) {
+    const stat = await lstat(path);
+    if (!stat.isFile() || stat.isSymbolicLink() || stat.size !== file.size)
+        throw new Error('recovered attachment is not the expected regular file');
+    await chmod(path, 0o600);
+    const handle = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW);
+    let bytes;
+    try {
+        bytes = await handle.readFile();
+    }
+    finally {
+        await handle.close();
+    }
+    return {
+        ...file, path, size: bytes.length,
+        sha256: createHash('sha256').update(bytes).digest('hex'),
+        ...(file.kind === 'voice_message' ? { transcription: {
+                configured: false, attempted: false, status: 'unavailable',
+                provider: null, text: null, errorCategory: 'restart_recovery',
+                audioPath: path, fileWireId: file.wireId,
+            } } : {}),
+    };
+}
+export async function removeRequestDirectory(path) {
+    let stat;
+    try {
+        stat = await lstat(path);
+    }
+    catch {
+        return;
+    }
+    if (stat.isSymbolicLink() || !stat.isDirectory()) {
+        await rm(path, { force: true });
+        return;
+    }
+    await rm(path, { recursive: true, force: true });
+}
+export async function cleanupAttachmentRoot(root, now, retentionMs, limit = 256) {
+    if (!existsSync(root))
+        return 0;
+    const rootStat = lstatSync(root);
+    if (!rootStat.isDirectory() || rootStat.isSymbolicLink())
+        throw new Error('attachment root is unsafe');
+    let removed = 0;
+    for (const name of (await readdir(root)).slice(0, limit)) {
+        const path = join(root, name);
+        const stat = await lstat(path).catch(() => undefined);
+        if (!stat || now - stat.mtimeMs < retentionMs)
+            continue;
+        await removeRequestDirectory(path);
+        removed++;
+    }
+    return removed;
+}
+export class AttachmentRecoveryState {
+    path;
+    pending = [];
+    corrupt = false;
+    constructor(path) {
+        this.path = path;
+        if (!existsSync(path))
+            return;
+        try {
+            const raw = JSON.parse(readFileSync(path, 'utf8'));
+            if (raw.version !== 1 || !Array.isArray(raw.pending) || raw.pending.length > MAX_PENDING_REQUESTS
+                || !raw.pending.every(item => validPending(item)))
+                throw new Error('invalid recovery state');
+            this.pending = raw.pending.map(item => ({ ...item, fileWireIds: [...item.fileWireIds] }));
+            chmodSync(path, 0o600);
+        }
+        catch {
+            this.corrupt = true;
+            this.pending = [];
+            try {
+                chmodSync(path, 0o600);
+            }
+            catch { }
+        }
+    }
+    integrity() { return !this.corrupt; }
+    list() {
+        this.assertHealthy();
+        return this.pending.map(item => ({ ...item, fileWireIds: [...item.fileWireIds] }));
+    }
+    add(item) {
+        this.assertHealthy();
+        if (!validPending(item))
+            throw new Error('invalid attachment recovery route');
+        if (this.pending.some(value => value.id === item.id))
+            return;
+        if (this.pending.length >= MAX_PENDING_REQUESTS)
+            throw new Error('too many pending attachment recoveries');
+        this.pending.push({ ...item, fileWireIds: [...item.fileWireIds] });
+        this.persist();
+    }
+    remove(id) {
+        this.assertHealthy();
+        const next = this.pending.filter(item => item.id !== id);
+        if (next.length === this.pending.length)
+            return;
+        this.pending = next;
+        this.persist();
+    }
+    cleanup(now, retentionMs) {
+        this.assertHealthy();
+        const old = this.pending.length;
+        this.pending = this.pending.filter(item => now - item.createdAt <= retentionMs);
+        if (this.pending.length !== old)
+            this.persist();
+        return old - this.pending.length;
+    }
+    assertHealthy() { if (this.corrupt)
+        throw new Error('attachment recovery state is corrupt'); }
+    persist() {
+        replaceFileAtomically(this.path, JSON.stringify({ version: 1, pending: this.pending }) + '\n', 0o600);
+        chmodSync(this.path, 0o600);
+    }
+}
+function validPending(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    const item = value;
+    return /^[a-f0-9]{64}$/.test(item.id) && CID.test(item.contact) && WIRE.test(item.originWireId)
+        && Array.isArray(item.fileWireIds) && item.fileWireIds.length >= 1 && item.fileWireIds.length <= 32
+        && item.fileWireIds.every(wire => WIRE.test(wire))
+        && new Set(item.fileWireIds).size === item.fileWireIds.length
+        && Number.isSafeInteger(item.createdAt) && item.createdAt >= 0;
+}
+export function safeField(value, max) {
+    return Array.from(String(value ?? '').normalize('NFC')
+        .replace(/[\u0000-\u001f\u007f-\u009f\u202a-\u202e\u2066-\u2069]/gu, ' '))
+        .slice(0, max).join('').trim();
+}
+export function sanitizeFilename(value) {
+    const clean = safeField(basename(value.replace(/\\/g, '/')), 180)
+        .replace(/[^\p{L}\p{N}._ -]+/gu, '_').replace(/^\.+/, '').trim();
+    return clean || 'attachment.bin';
+}
+function detectMime(bytes, declared) {
+    if (bytes.subarray(0, 5).toString() === '%PDF-')
+        return 'application/pdf';
+    if (bytes.subarray(0, 8).equals(Buffer.from([137, 80, 78, 71, 13, 10, 26, 10])))
+        return 'image/png';
+    if (bytes[0] === 0xff && bytes[1] === 0xd8 && bytes[2] === 0xff)
+        return 'image/jpeg';
+    if (/^GIF8[79]a/.test(bytes.subarray(0, 6).toString()))
+        return 'image/gif';
+    if (bytes.subarray(0, 4).toString() === 'RIFF' && bytes.subarray(8, 12).toString() === 'WEBP')
+        return 'image/webp';
+    if (bytes.subarray(0, 4).toString() === 'OggS')
+        return 'audio/ogg';
+    if (bytes.subarray(0, 4).toString() === 'RIFF' && bytes.subarray(8, 12).toString() === 'WAVE')
+        return 'audio/wav';
+    if (bytes.subarray(0, 3).toString() === 'ID3' || (bytes[0] === 0xff && (bytes[1] & 0xe0) === 0xe0))
+        return 'audio/mpeg';
+    if (bytes.subarray(4, 8).toString() === 'ftyp')
+        return declared === 'audio/mp4' ? 'audio/mp4' : 'application/mp4';
+    if (bytes.subarray(0, 4).equals(Buffer.from([0x1a, 0x45, 0xdf, 0xa3])))
+        return declared === 'audio/webm' ? 'audio/webm' : 'video/webm';
+    if (bytes.subarray(0, 4).equals(Buffer.from([0x50, 0x4b, 0x03, 0x04])))
+        return 'application/zip';
+    if (bytes.subarray(0, 8).equals(Buffer.from([0xd0, 0xcf, 0x11, 0xe0, 0xa1, 0xb1, 0x1a, 0xe1])))
+        return 'application/x-cfb';
+    const text = bytes.toString('utf8');
+    if (!text.includes('\ufffd') && !/[\u0000-\u0008\u000b\u000c\u000e-\u001f]/u.test(text)) {
+        if (declared === 'application/json') {
+            try {
+                JSON.parse(text);
+                return 'application/json';
+            }
+            catch { }
+        }
+        return 'text/plain';
+    }
+    return 'application/octet-stream';
+}
+function mimeCompatible(declared, detected) {
+    if (declared === detected)
+        return true;
+    if (['audio/wav', 'audio/x-wav'].includes(declared) && detected === 'audio/wav')
+        return true;
+    if (detected === 'application/zip' && declared.startsWith('application/vnd.openxmlformats-officedocument.'))
+        return true;
+    if (detected === 'application/x-cfb' && [
+        'application/msword', 'application/vnd.ms-excel', 'application/vnd.ms-powerpoint',
+    ].includes(declared))
+        return true;
+    return false;
+}

package/dist/owner-channel/channel.d.ts

@@ -1,7 +1,10 @@
 import { type ChildProcessWithoutNullStreams } from 'node:child_process';
-import type { OwnerChannelConfig } from '../config.js';
+import { type OwnerChannelConfig } from '../config.js';
 import type { SessionHandle } from '../session/types.js';
 import { type OursToolClient } from './mcp.js';
+import { type OwnerUpdatePhase } from './notices.js';
+import { type OwnerEntry } from './state.js';
+import { type OwnerTaskPhase } from './tasks.js';
 export interface OwnerChannelOptions {
     role: string;
     config: OwnerChannelConfig;
@@ -18,6 +21,84 @@ export interface OwnerChannelHandle {
     start(): Promise<void>;
     drain(): Promise<void>;
     close(): Promise<void>;
+    manage(request: OwnerChannelManagementRequest): Promise<OwnerChannelManagementResult>;
+}
+export type OwnerChannelManagementRequest = {
+    action: 'contact_list';
+} | {
+    action: 'contact_invite';
+    name?: string;
+} | {
+    action: 'contact_add';
+    invite: string;
+    name?: string;
+} | {
+    action: 'owner_list';
+} | {
+    action: 'owner_authorize';
+    cid: string;
+} | {
+    action: 'owner_revoke';
+    cid: string;
+} | {
+    action: 'request_update';
+    requestId: string;
+    phase: OwnerUpdatePhase;
+    message: string;
+} | {
+    action: 'task_open';
+    requestId: string;
+} | {
+    action: 'task_report';
+    taskId: string;
+    phase: OwnerTaskPhase;
+    message: string;
+};
+export type OwnerChannelManagementResult = {
+    action: 'contact_list';
+    contacts: OwnerContact[];
+} | {
+    action: 'contact_invite';
+    invite: string;
+} | {
+    action: 'contact_add';
+    status: 'pending';
+    contact?: OwnerContact;
+} | {
+    action: 'owner_list';
+    integrity: {
+        ok: boolean;
+        error?: string;
+    };
+    owners: OwnerEntry[];
+} | {
+    action: 'owner_authorize' | 'owner_revoke';
+    owner: OwnerEntry;
+} | {
+    action: 'request_update';
+    requestId: string;
+    sequence: number;
+} | {
+    action: 'task_open';
+    taskId: string;
+    expiresAt: string;
+} | {
+    action: 'task_report';
+    taskId: string;
+    phase: OwnerTaskPhase;
+    sequence: number;
+    state: 'open' | 'closed';
+};
+export type { OwnerUpdatePhase } from './notices.js';
+export interface OwnerContact {
+    cid: string;
+    name: string;
+    status: string;
+    kind?: string;
+    human?: {
+        cid?: string;
+        name?: string;
+    };
 }
 /**
  * Fleet-owned trusted ingress. The agent never binds this identity and never
@@ -27,28 +108,59 @@ export declare class OwnerChannel implements OwnerChannelHandle {
     private readonly options;
     private readonly client;
     private readonly state;
+    private readonly authorizations;
+    private readonly tasks;
+    private readonly attachmentRecovery;
+    private readonly attachmentConfig;
+    private readonly attachmentRoot;
+    /**
+     * Wire IDs whose turn is still running. They stay OUT of the durable state
+     * (a crash must replay them) but must not be queued twice while live.
+     */
+    private readonly inFlight;
     private stopping;
     private watchProcess?;
     private watchTask?;
     private drainTask?;
     private drainRequested;
-    private readonly inFlight;
     private readonly completionTasks;
+    private readonly activeRequests;
+    private managementTail;
+    private ready;
     constructor(options: OwnerChannelOptions);
     start(): Promise<void>;
     drain(): Promise<void>;
     close(): Promise<void>;
+    manage(request: OwnerChannelManagementRequest): Promise<OwnerChannelManagementResult>;
+    private manageNow;
+    private contacts;
+    private contact;
+    private assertCid;
+    private assertLabel;
+    private safeMetadata;
+    private sendOwnerUpdate;
+    private openOwnerTask;
+    private sendOwnerTaskReport;
+    private safeOwnerUpdate;
+    private safeTaskReport;
     private drainAll;
+    private attachmentGroups;
+    private handleAttachmentGroup;
     private handle;
     private complete;
+    private ownerAttachmentPrompt;
     private ownerPrompt;
     private outboxDir;
+    private requestId;
     private send;
     private sendAttachments;
     /** Bound message size without splitting Unicode code points. */
     private sendFinal;
     private wireId;
     private sender;
+    private latestEventSeq;
+    /** Map only event shape and allowlisted status to owner-safe phase text. */
+    private progressPhase;
     private watchLoop;
     private errorText;
     private logError;