mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-10-28 20:21:50 +01:00
DottaandClaude Opus 4.8
ec7adcaf3d
Foundation for opt-in `tailscale_https` exposure of managed branch runtimes, implementing the PAP-17049 plan under the PAP-17050 threat-model verdict. Broker (packages/tailscale-https-broker): root/dedicated-account host broker exposing only idempotent list/expose/remove over a Unix socket. Implements the six required verdict controls: SO_PEERCRED + UID/GID allowlist + unguessable broker-issued lease handles (req #1); dedicated port allowlist + /proc listener ownership/loopback proof before mutation (req #2); per-mutation transaction (strict-parse serve JSON -> verify absence/exact-lease -> verify :443 -> one fixed per-port op -> reread -> require only-intended-changed + :443 identical -> atomic root-owned registry commit, quarantine-on-ambiguity) (req #3); execve/shell=false argv built only from canonical integers + fixed tokens, pinned CLI schema (req #4); versioned length-bounded strict-JSON protocol (req #5); bounded append-only audit events (req #6). Deny-by-default for Funnel/cert/Services/reset/set-config/path-handlers/:443/reserved ports. Shared contract (packages/shared): single source of truth for exposure config, lifecycle state (pending/ready/failed/cleanup_pending/removed), listener ownership, and status, with strict zod validators and deterministic app/HMR port-pair + URL derivation so DB/server/UI/runtime cannot drift. Tests: broker 57/57, shared runtime-exposure 13/13, both typecheck clean. Server/DB/UI lifecycle integration + docs land in follow-on commits. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
91 lines
2.9 KiB
TypeScript
91 lines
2.9 KiB
TypeScript
/**
|
|
* Append-only, bounded, redacted security audit (PAP-17050 verdict req #6).
|
|
*
|
|
* Every allow/deny and mutation outcome emits one event. Lease handles,
|
|
* bearer/session material, full environments, and raw unbounded CLI output are
|
|
* NEVER logged. All string fields are control-character-sanitized and length
|
|
* bounded to defeat log forging.
|
|
*/
|
|
import { appendFileSync } from "node:fs";
|
|
import type { BrokerErrorCode, PeerCredentials } from "./types.js";
|
|
|
|
const MAX_FIELD_LEN = 256;
|
|
|
|
export interface AuditEvent {
|
|
timestampIso: string;
|
|
peer: PeerCredentials | null;
|
|
op: string;
|
|
runtimeId: string | null;
|
|
ports: number[];
|
|
requestId: string | null;
|
|
decision: "allow" | "deny";
|
|
reasonCode: BrokerErrorCode | "ok";
|
|
reason: string;
|
|
beforeDigest?: string;
|
|
afterDigest?: string;
|
|
cliExitCategory?: "ok" | "error" | "timeout" | "none";
|
|
recovery?: "none" | "quarantine" | "cleanup";
|
|
}
|
|
|
|
/** Strip control chars (defeats newline/log-forging) and bound length. */
|
|
export function sanitizeField(value: string): string {
|
|
// eslint-disable-next-line no-control-regex
|
|
const stripped = value.replace(/[\x00-\x1f\x7f]/g, " ");
|
|
return stripped.length > MAX_FIELD_LEN ? `${stripped.slice(0, MAX_FIELD_LEN)}…` : stripped;
|
|
}
|
|
|
|
export function formatAuditLine(event: AuditEvent): string {
|
|
const safe = {
|
|
ts: event.timestampIso,
|
|
uid: event.peer?.uid ?? null,
|
|
gid: event.peer?.gid ?? null,
|
|
pid: event.peer?.pid ?? null,
|
|
op: sanitizeField(event.op),
|
|
runtimeId: event.runtimeId ? sanitizeField(event.runtimeId) : null,
|
|
ports: event.ports.filter((p) => Number.isInteger(p)).slice(0, 8),
|
|
requestId: event.requestId ? sanitizeField(event.requestId) : null,
|
|
decision: event.decision,
|
|
reasonCode: event.reasonCode,
|
|
reason: sanitizeField(event.reason),
|
|
beforeDigest: event.beforeDigest ? sanitizeField(event.beforeDigest) : undefined,
|
|
afterDigest: event.afterDigest ? sanitizeField(event.afterDigest) : undefined,
|
|
cliExitCategory: event.cliExitCategory,
|
|
recovery: event.recovery,
|
|
};
|
|
return JSON.stringify(safe);
|
|
}
|
|
|
|
export interface AuditSink {
|
|
write(event: AuditEvent): void;
|
|
}
|
|
|
|
/**
|
|
* Durable file audit sink. If the recommended `blockOnFailure` is set, a write
|
|
* failure throws so the caller can fail the mutation closed rather than mutate
|
|
* without a durable record.
|
|
*/
|
|
export class FileAuditSink implements AuditSink {
|
|
constructor(
|
|
private readonly path: string,
|
|
private readonly blockOnFailure = true,
|
|
) {}
|
|
|
|
write(event: AuditEvent): void {
|
|
try {
|
|
appendFileSync(this.path, `${formatAuditLine(event)}\n`, { mode: 0o600 });
|
|
} catch (error) {
|
|
if (this.blockOnFailure) {
|
|
throw new Error(`audit sink write failed: ${(error as Error).message}`);
|
|
}
|
|
}
|
|
}
|
|
}
|
|
|
|
/** In-memory sink for tests. */
|
|
export class MemoryAuditSink implements AuditSink {
|
|
readonly events: AuditEvent[] = [];
|
|
write(event: AuditEvent): void {
|
|
this.events.push(event);
|
|
}
|
|
}
|