vouchington-tooling 0.1.4 → 0.1.6

package/dist/session-friction/classify.mjs

@@ -0,0 +1,87 @@
+import { normalizeCommandPrefix } from './normalize.mjs';
+import { boundedText, isWellFormedUnicode, normalizeAuditText } from './text.mjs';
+const FAILURE_TOKENS = [
+    ['Operation not permitted', /Operation not permitted/i],
+    ['E2BIG', /\bE2BIG\b/i],
+    ['EPERM', /\bEPERM\b/i],
+];
+const CONNECTION_REFUSED = /\bECONNREFUSED\b/i;
+const URL_USERINFO = /([a-z][a-z0-9+.-]{0,31}:\/\/)[^\s/?#@]*@/gi;
+const STDERR_INSPECTION_MAX_LENGTH = 100_000;
+const COMMAND_INSPECTION_MAX_LENGTH = 10_000;
+const IPV4_OCTET = '(?:25[0-5]|2[0-4]\\d|1\\d{2}|[1-9]?\\d)';
+const LOOPBACK_ADDRESSES = [
+    new RegExp(String.raw `(?<![0-9a-z_.:-])(?:127\.${IPV4_OCTET}(?:\.${IPV4_OCTET}){2}|localhost)(?![0-9a-z_.-])`, 'i'),
+    /(?<![0-9a-z_.-])\[(?:::1|0:0:0:0:0:0:0:1)(?:%[a-z0-9_.-]+)?\](?![0-9a-z_.-])/i,
+    /(?<![0-9a-z_.:\x5b\x5d-])(?:::1|0:0:0:0:0:0:0:1)(?:%[a-z0-9_.-]+)?(?::\d{1,5})?(?![0-9a-z_.:\x5b\x5d-])/i,
+];
+const DETAIL_MAX_LENGTH = 1_000;
+function boundedTail(value, maximum) {
+    let start = Math.max(0, value.length - maximum);
+    const first = value.charCodeAt(start);
+    const previous = value.charCodeAt(start - 1);
+    if (first >= 0xdc00 && first <= 0xdfff && previous >= 0xd800 && previous <= 0xdbff)
+        start++;
+    return value.slice(start);
+}
+function boundedStderr(value) {
+    if (value.length <= STDERR_INSPECTION_MAX_LENGTH)
+        return value;
+    const headLength = Math.floor((STDERR_INSPECTION_MAX_LENGTH - 1) / 2);
+    const head = boundedText(value, headLength);
+    const tail = boundedTail(value, STDERR_INSPECTION_MAX_LENGTH - 1 - head.length);
+    return `${head}\n${tail}`;
+}
+function withoutUrlUserinfo(line) {
+    return line.includes('://') && line.includes('@') ? line.replace(URL_USERINFO, '$1') : line;
+}
+export function classifyFrictionObservation(observation) {
+    if (!observation || typeof observation !== 'object')
+        return null;
+    if (typeof observation.command !== 'string')
+        return null;
+    const command = boundedText(observation.command, COMMAND_INSPECTION_MAX_LENGTH);
+    if (!isWellFormedUnicode(command) || normalizeAuditText(command) === '')
+        return null;
+    const commandPrefix = normalizeCommandPrefix(command, observation.commandWrappers);
+    if (commandPrefix === '' || !isWellFormedUnicode(commandPrefix))
+        return null;
+    if (observation.type === 'permission-request') {
+        return { kind: 'sandbox-escalation', commandPrefix, detail: 'permission-request' };
+    }
+    if (observation.type !== 'tool-result')
+        return null;
+    if (observation.escalationDetail !== undefined &&
+        typeof observation.escalationDetail !== 'string')
+        return null;
+    const escalationDetail = normalizeAuditText(boundedText(observation.escalationDetail ?? '', DETAIL_MAX_LENGTH));
+    if (!isWellFormedUnicode(escalationDetail))
+        return null;
+    if (escalationDetail) {
+        return {
+            kind: 'sandbox-escalation',
+            commandPrefix,
+            detail: escalationDetail,
+        };
+    }
+    const rawStderr = observation.structuredStderr;
+    if (rawStderr !== undefined && (typeof rawStderr !== 'string' || !isWellFormedUnicode(rawStderr)))
+        return null;
+    const stderr = rawStderr ? boundedStderr(rawStderr) : rawStderr;
+    if (stderr === undefined)
+        return null;
+    const token = FAILURE_TOKENS.find(([, pattern]) => pattern.test(stderr))?.[0];
+    if (token)
+        return { kind: 'sandbox-failure', commandPrefix, detail: `stderr matched "${token}"` };
+    if (stderr.split(/\r\n|[\r\n]/).some((rawLine) => {
+        const line = withoutUrlUserinfo(rawLine);
+        return (CONNECTION_REFUSED.test(line) && LOOPBACK_ADDRESSES.some((pattern) => pattern.test(line)));
+    })) {
+        return {
+            kind: 'sandbox-failure',
+            commandPrefix,
+            detail: 'stderr matched localhost connection failure',
+        };
+    }
+    return null;
+}

package/dist/session-friction/directory.d.mts

@@ -0,0 +1 @@
+export declare function ensurePrivateDirectory(directory: string, create: boolean): boolean;

package/dist/session-friction/directory.mjs

@@ -0,0 +1,71 @@
+import { chmodSync, lstatSync, mkdirSync, statSync } from 'node:fs';
+import { dirname } from 'node:path';
+const PRIVATE_DIRECTORY_MODE = 0o700;
+function isCode(error, code) {
+    return Boolean(error && typeof error === 'object' && 'code' in error && error.code === code);
+}
+function directoryChain(directory) {
+    const chain = [directory];
+    let current = directory;
+    while (dirname(current) !== current) {
+        current = dirname(current);
+        chain.push(current);
+    }
+    return chain.reverse();
+}
+export function ensurePrivateDirectory(directory, create) {
+    const chain = directoryChain(directory);
+    const effectiveUserId = process.geteuid?.();
+    if (effectiveUserId === undefined)
+        throw new Error('session-friction requires POSIX directory permissions');
+    for (const [index, path] of chain.entries()) {
+        let created = false;
+        let status;
+        try {
+            status = lstatSync(path);
+        }
+        catch (error) {
+            /* v8 ignore next -- unexpected filesystem errors are propagated unchanged. */
+            if (!isCode(error, 'ENOENT'))
+                throw error;
+            if (!create)
+                return false;
+            try {
+                mkdirSync(path, { mode: PRIVATE_DIRECTORY_MODE });
+                created = true;
+            }
+            catch (mkdirError) {
+                /* v8 ignore next -- another process can create the directory after lstat. */
+                if (!isCode(mkdirError, 'EEXIST'))
+                    throw mkdirError;
+            }
+            status = lstatSync(path);
+        }
+        const leaf = index === chain.length - 1;
+        if (status.isSymbolicLink()) {
+            if (leaf || status.uid !== 0)
+                throw new Error('session-friction log directory must be a private directory');
+            try {
+                status = statSync(path);
+            }
+            catch {
+                throw new Error('session-friction log directory must be a private directory');
+            }
+        }
+        if (!status.isDirectory())
+            throw new Error('session-friction log directory must be a private directory');
+        if (created)
+            chmodSync(path, PRIVATE_DIRECTORY_MODE);
+        if (!created) {
+            const ownedByCaller = status.uid === effectiveUserId;
+            const ownedByRoot = status.uid === 0;
+            const writableByOthers = (status.mode & 0o022) !== 0;
+            const sticky = (status.mode & 0o1000) !== 0;
+            if ((leaf && ((status.mode & 0o777) !== PRIVATE_DIRECTORY_MODE || !ownedByCaller)) ||
+                (!leaf && !ownedByCaller && !ownedByRoot) ||
+                (!leaf && writableByOthers && !sticky))
+                throw new Error('session-friction log directory must be a private directory');
+        }
+    }
+    return true;
+}

package/dist/session-friction/index.d.mts

@@ -0,0 +1,6 @@
+export { classifyFrictionObservation } from './classify.mts';
+export { normalizeCommandPrefix } from './normalize.mts';
+export { FRICTION_LOG_MAX_EVENTS, readFrictionLog, recordFriction } from './log.mts';
+export { buildSessionFrictionReport } from './report.mts';
+export { isConformingCiFailureBlock } from './ci-failures.mts';
+export type { FrictionEvent, FrictionEventKind, FrictionLogOptions, FrictionLogReadResult, FrictionObservation, JournalEntry, JournalLoadResult, JournalLoader, PermissionRequestObservation, SessionFrictionReport, SessionFrictionReportOptions, ToolResultObservation, } from './types.mts';

package/dist/session-friction/index.mjs

@@ -0,0 +1,5 @@
+export { classifyFrictionObservation } from './classify.mjs';
+export { normalizeCommandPrefix } from './normalize.mjs';
+export { FRICTION_LOG_MAX_EVENTS, readFrictionLog, recordFriction } from './log.mjs';
+export { buildSessionFrictionReport } from './report.mjs';
+export { isConformingCiFailureBlock } from './ci-failures.mjs';

package/dist/session-friction/lock.d.mts

@@ -0,0 +1 @@
+export declare function withFileLock<Result>(path: string, action: () => Result): Result;

package/dist/session-friction/lock.mjs

@@ -0,0 +1,193 @@
+import { closeSync, constants, fstatSync, lstatSync, openSync, readSync, unlinkSync, writeFileSync, } from 'node:fs';
+import { basename } from 'node:path';
+const LOCK_ATTEMPTS = 200;
+const STALE_LOCK_AGE_MS = 30_000;
+const LOCK_OWNER_MAX_BYTES = 32;
+const MAX_PID = 2_147_483_647;
+const LOCK_CREATE_FLAGS = constants.O_CREAT | constants.O_EXCL | constants.O_WRONLY | constants.O_NOFOLLOW;
+const lockWait = new Int32Array(new SharedArrayBuffer(4));
+function waitForLock() {
+    // Intentional synchronous backoff for CLI and hook callers.
+    Atomics.wait(lockWait, 0, 0, 5);
+}
+function hasCode(error, code) {
+    return Boolean(error && typeof error === 'object' && 'code' in error && error.code === code);
+}
+function isFresh(mtimeMs) {
+    const age = Date.now() - Math.floor(mtimeMs);
+    return age > -STALE_LOCK_AGE_MS && age < STALE_LOCK_AGE_MS;
+}
+function inspectLock(lockPath) {
+    let descriptor;
+    try {
+        descriptor = openSync(lockPath, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+    }
+    catch {
+        /* v8 ignore next -- detects a lock that disappears or is replaced while being inspected. */
+        return null;
+    }
+    try {
+        const status = fstatSync(descriptor);
+        /* v8 ignore next -- opening a non-regular lock requires a platform-specific FIFO/device. */
+        if (!status.isFile())
+            return null;
+        if (status.size > LOCK_OWNER_MAX_BYTES)
+            return isFresh(status.mtimeMs)
+                ? null
+                : { dev: status.dev, ino: status.ino, mtimeMs: status.mtimeMs, owner: null };
+        const buffer = Buffer.alloc(LOCK_OWNER_MAX_BYTES + 1);
+        let length = 0;
+        while (length < buffer.length) {
+            const bytes = readSync(descriptor, buffer, length, buffer.length - length, length);
+            if (bytes === 0)
+                break;
+            length += bytes;
+        }
+        /* v8 ignore next -- detects external growth after the descriptor metadata check. */
+        if (length > LOCK_OWNER_MAX_BYTES)
+            return null;
+        const rawOwner = buffer.subarray(0, length).toString();
+        return {
+            dev: status.dev,
+            ino: status.ino,
+            mtimeMs: status.mtimeMs,
+            owner: /^[1-9][0-9]*$/.test(rawOwner) ? Number(rawOwner) : null,
+        };
+    }
+    finally {
+        closeSync(descriptor);
+    }
+}
+function withReaperLock(lockPath, action) {
+    const reaperPath = `${lockPath}.reap`;
+    let descriptor;
+    try {
+        descriptor = openSync(reaperPath, LOCK_CREATE_FLAGS, 0o600);
+    }
+    catch (error) {
+        /* v8 ignore next 2 -- requires a narrow filesystem race or platform open failure. */
+        if (hasCode(error, 'EEXIST') || hasCode(error, 'ENOENT'))
+            return false;
+        /* v8 ignore next -- unexpected platform errors must propagate. */
+        throw error;
+    }
+    try {
+        return action();
+    }
+    finally {
+        closeSync(descriptor);
+        try {
+            unlinkSync(reaperPath);
+        }
+        catch { }
+    }
+}
+function removeOrphanedReaper(reaperPath) {
+    try {
+        const inspected = lstatSync(reaperPath);
+        if (isFresh(inspected.mtimeMs))
+            return false;
+        const current = lstatSync(reaperPath);
+        /* v8 ignore next 5 -- requires external replacement during stale-reaper recovery. */
+        if (current.dev !== inspected.dev ||
+            current.ino !== inspected.ino ||
+            current.mtimeMs !== inspected.mtimeMs)
+            return false;
+        unlinkSync(reaperPath);
+        return true;
+    }
+    catch {
+        /* v8 ignore next -- requires external removal during stale-reaper recovery. */
+        return false;
+    }
+}
+function removeStaleLock(lockPath) {
+    return withReaperLock(lockPath, () => {
+        try {
+            const inspected = inspectLock(lockPath);
+            if (!inspected)
+                return false;
+            const fresh = isFresh(inspected.mtimeMs);
+            const { owner } = inspected;
+            if (typeof owner === 'number' && Number.isInteger(owner) && owner > 0 && owner <= MAX_PID) {
+                try {
+                    process.kill(owner, 0);
+                    return false;
+                }
+                catch (error) {
+                    if (!hasCode(error, 'ESRCH'))
+                        return false;
+                }
+            }
+            else if (fresh)
+                return false;
+            const current = lstatSync(lockPath);
+            /* v8 ignore next 5 -- requires external replacement despite the reaper protocol. */
+            if (current.dev !== inspected.dev ||
+                current.ino !== inspected.ino ||
+                current.mtimeMs !== inspected.mtimeMs)
+                return false;
+            unlinkSync(lockPath);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    });
+}
+export function withFileLock(path, action) {
+    const lockPath = `${path}.lock`;
+    const reaperPath = `${lockPath}.reap`;
+    for (let attempt = 0; attempt < LOCK_ATTEMPTS; attempt++) {
+        let reaperExists = false;
+        try {
+            lstatSync(reaperPath);
+            reaperExists = true;
+        }
+        catch (error) {
+            /* v8 ignore next -- unexpected reaper lstat failures must propagate. */
+            if (!hasCode(error, 'ENOENT'))
+                throw error;
+        }
+        if (reaperExists) {
+            if (removeOrphanedReaper(reaperPath))
+                continue;
+            waitForLock();
+            continue;
+        }
+        let descriptor;
+        try {
+            descriptor = openSync(lockPath, LOCK_CREATE_FLAGS, 0o600);
+        }
+        catch (error) {
+            if (!hasCode(error, 'EEXIST'))
+                throw error;
+            let lockStatus;
+            try {
+                lockStatus = lstatSync(lockPath);
+            }
+            catch (statusError) {
+                /* v8 ignore next -- requires the owner to release between EEXIST and lstat. */
+                if (hasCode(statusError, 'ENOENT'))
+                    continue;
+                /* v8 ignore next -- requires an unexpected lstat failure during the same race. */
+                throw statusError;
+            }
+            if (!lockStatus.isFile())
+                throw new Error('session-friction log lock must be a regular file');
+            if (removeStaleLock(lockPath))
+                continue;
+            waitForLock();
+            continue;
+        }
+        try {
+            writeFileSync(descriptor, String(process.pid));
+            return action();
+        }
+        finally {
+            closeSync(descriptor);
+            unlinkSync(lockPath);
+        }
+    }
+    throw new Error(`could not acquire session-friction log lock for ${basename(path)}`);
+}

package/dist/session-friction/log.d.mts

@@ -0,0 +1,8 @@
+import type { FrictionLogOptions, FrictionLogReadResult, FrictionObservation } from './types.mts';
+export declare const FRICTION_LOG_MAX_EVENTS = 500;
+export declare function requireDirectory(directory: string): string;
+export declare function eventLimit(maxEvents: number | undefined): number;
+export declare function recordFriction(sessionId: string, observation: FrictionObservation, options: FrictionLogOptions & {
+    timestamp?: string | (() => string);
+}): void;
+export declare function readFrictionLog(sessionId: string, options: FrictionLogOptions): FrictionLogReadResult;

package/dist/session-friction/log.mjs

@@ -0,0 +1,195 @@
+import { closeSync, constants, fchmodSync, fstatSync, openSync, readSync, writeSync } from 'node:fs';
+import { isAbsolute, join, resolve } from 'node:path';
+import { classifyFrictionObservation } from './classify.mjs';
+import { ensurePrivateDirectory } from './directory.mjs';
+import { withFileLock } from './lock.mjs';
+import { boundedText, isSafeAuditText, isWellFormedUnicode, normalizeAuditText } from './text.mjs';
+import { decodeUtf8 } from './utf8.mjs';
+import { sanitizeSessionId } from './session-id.mjs';
+export const FRICTION_LOG_MAX_EVENTS = 500;
+const LOG_MAX_BYTES = 2_000_000;
+const EVENT_FIELD_MAX_LENGTH = 1_000;
+export function requireDirectory(directory) {
+    if (typeof directory !== 'string')
+        throw new Error('log directory must be a string');
+    if (Buffer.byteLength(directory) > 4096)
+        throw new Error('session-friction log directory path is too long');
+    if (!isAbsolute(directory))
+        throw new Error('session-friction log directory must be absolute');
+    return resolve(directory);
+}
+export function eventLimit(maxEvents) {
+    const limit = maxEvents ?? FRICTION_LOG_MAX_EVENTS;
+    if (!Number.isInteger(limit) || limit < 1)
+        throw new Error('maxEvents must be a positive integer');
+    return Math.min(limit, FRICTION_LOG_MAX_EVENTS);
+}
+function logPath(sessionId, directory) {
+    return join(requireDirectory(directory), `${sanitizeSessionId(sessionId)}.jsonl`);
+}
+function validEvent(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    const record = value;
+    return ((record.kind === 'sandbox-escalation' || record.kind === 'sandbox-failure') &&
+        isSafeAuditText(record.timestamp) &&
+        isSafeAuditText(record.commandPrefix) &&
+        isSafeAuditText(record.detail));
+}
+function openLogFile(path, flags) {
+    let descriptor;
+    try {
+        descriptor = openSync(path, flags | constants.O_NOFOLLOW | constants.O_NONBLOCK, 0o600);
+    }
+    catch (error) {
+        if (error &&
+            typeof error === 'object' &&
+            'code' in error &&
+            (error.code === 'ELOOP' || error.code === 'EISDIR' || error.code === 'ENOTDIR'))
+            throw new Error('session-friction log must be a regular file');
+        throw error;
+    }
+    try {
+        const status = fstatSync(descriptor);
+        if (!status.isFile() || status.nlink !== 1)
+            throw new Error('session-friction log must be a regular file');
+        return descriptor;
+    }
+    catch (error) {
+        closeSync(descriptor);
+        throw error;
+    }
+}
+function readLogContent(descriptor) {
+    if (fstatSync(descriptor).size > LOG_MAX_BYTES)
+        throw new Error('session-friction log is too large');
+    const buffer = Buffer.alloc(LOG_MAX_BYTES + 1);
+    let length = 0;
+    while (length < buffer.length) {
+        const bytes = readSync(descriptor, buffer, length, buffer.length - length, length);
+        if (bytes === 0)
+            break;
+        length += bytes;
+    }
+    /* v8 ignore next -- detects external growth after the descriptor size check. */
+    if (length > LOG_MAX_BYTES)
+        throw new Error('session-friction log is too large');
+    return decodeUtf8(buffer.subarray(0, length));
+}
+function validEventCount(content, limit) {
+    let count = 0;
+    for (const line of content.split('\n')) {
+        if (!line.trim())
+            continue;
+        try {
+            if (validEvent(JSON.parse(line)))
+                count++;
+        }
+        catch { }
+        if (count >= limit)
+            break;
+    }
+    return count;
+}
+function atEventLimit(content, limit) {
+    return validEventCount(content, limit) >= limit;
+}
+function writeAll(descriptor, value) {
+    const buffer = Buffer.from(value);
+    let offset = 0;
+    while (offset < buffer.length) {
+        const written = writeSync(descriptor, buffer, offset, buffer.length - offset);
+        /* v8 ignore next -- a zero-byte synchronous file write is an external I/O failure. */
+        if (written === 0)
+            throw new Error('session-friction log write made no progress');
+        offset += written;
+    }
+}
+export function recordFriction(sessionId, observation, options) {
+    const maxEvents = eventLimit(options.maxEvents);
+    const timestamp = typeof options.timestamp === 'function' ? options.timestamp() : options.timestamp;
+    if (timestamp !== undefined && typeof timestamp !== 'string')
+        throw new Error('timestamp must be a string');
+    const rawTimestamp = timestamp ?? new Date().toISOString();
+    const normalizedTimestamp = normalizeAuditText(boundedText(rawTimestamp, EVENT_FIELD_MAX_LENGTH));
+    if (!normalizedTimestamp)
+        throw new Error('timestamp must be non-empty');
+    if (!isWellFormedUnicode(normalizedTimestamp))
+        throw new Error('timestamp must be well-formed Unicode');
+    const classified = classifyFrictionObservation(observation);
+    const path = logPath(sessionId, options.directory);
+    const directory = requireDirectory(options.directory);
+    ensurePrivateDirectory(directory, true);
+    withFileLock(path, () => {
+        /* v8 ignore next 2 -- requires the directory path to be replaced after its lock is acquired. */
+        if (!ensurePrivateDirectory(directory, false))
+            throw new Error('session-friction log directory disappeared while acquiring the lock');
+        const descriptor = openLogFile(path, constants.O_CREAT | constants.O_RDWR | constants.O_APPEND);
+        try {
+            fchmodSync(descriptor, 0o600);
+            if (fstatSync(descriptor).size > LOG_MAX_BYTES)
+                throw new Error('session-friction log is too large');
+            if (!classified)
+                return;
+            const content = readLogContent(descriptor);
+            if (atEventLimit(content, maxEvents))
+                return;
+            const event = {
+                ...classified,
+                commandPrefix: normalizeAuditText(classified.commandPrefix),
+                detail: normalizeAuditText(classified.detail),
+                timestamp: normalizedTimestamp,
+            };
+            /* v8 ignore next -- normalized classified fields satisfy validEvent defensively. */
+            if (!validEvent(event))
+                return;
+            const prefix = content && !content.endsWith('\n') ? '\n' : '';
+            const addition = `${prefix}${JSON.stringify(event)}\n`;
+            if (fstatSync(descriptor).size + Buffer.byteLength(addition) > LOG_MAX_BYTES)
+                throw new Error('session-friction log is too large');
+            writeAll(descriptor, addition);
+        }
+        finally {
+            closeSync(descriptor);
+        }
+    });
+}
+export function readFrictionLog(sessionId, options) {
+    const maxEvents = eventLimit(options.maxEvents);
+    const path = logPath(sessionId, options.directory);
+    const directory = requireDirectory(options.directory);
+    if (!ensurePrivateDirectory(directory, false))
+        return { status: 'absent' };
+    try {
+        return withFileLock(path, () => {
+            /* v8 ignore next -- detects directory removal after acquiring the file lock. */
+            if (!ensurePrivateDirectory(directory, false))
+                return { status: 'absent' };
+            const descriptor = openLogFile(path, constants.O_RDONLY);
+            try {
+                const events = [];
+                for (const line of readLogContent(descriptor).split('\n')) {
+                    if (!line.trim())
+                        continue;
+                    try {
+                        const value = JSON.parse(line);
+                        if (validEvent(value))
+                            events.push(value);
+                    }
+                    catch { }
+                    if (events.length >= maxEvents)
+                        break;
+                }
+                return events.length ? { status: 'events', events } : { status: 'empty' };
+            }
+            finally {
+                closeSync(descriptor);
+            }
+        });
+    }
+    catch (error) {
+        if (error && typeof error === 'object' && 'code' in error && error.code === 'ENOENT')
+            return { status: 'absent' };
+        throw error;
+    }
+}

package/dist/session-friction/normalize.d.mts

@@ -0,0 +1 @@
+export declare function normalizeCommandPrefix(command: string, wrappersToStrip?: string[]): string;