mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-10-29 12:59:13 +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>
62 lines
2.2 KiB
TypeScript
62 lines
2.2 KiB
TypeScript
/**
|
|
* Tailscale CLI argv construction. Every command is a fixed token vector with a
|
|
* single validated integer interpolated; there is never a shell, an arbitrary
|
|
* target URL, a path handler, Funnel, cert, Service, reset, or set-config
|
|
* operation (PAP-17049 plan; PAP-17050 verdict requirement #4 + invariants).
|
|
*
|
|
* The caller must pass an absolute, root-owned tailscale binary path. Callers
|
|
* spawn with shell:false and a minimal environment.
|
|
*/
|
|
import { assertCanonicalPort } from "./integers.js";
|
|
import { PROTECTED_PRIMARY_PORT } from "./types.js";
|
|
|
|
/** The loopback target is always same-number and always plain-http loopback. */
|
|
export function loopbackTarget(port: number): string {
|
|
assertCanonicalPort(port);
|
|
return `http://127.0.0.1:${port}`;
|
|
}
|
|
|
|
function assertMutablePort(port: number): number {
|
|
const p = assertCanonicalPort(port);
|
|
if (p === PROTECTED_PRIMARY_PORT) {
|
|
throw new Error("refusing to operate on the protected primary port 443");
|
|
}
|
|
if (p < 1024) {
|
|
throw new Error("refusing to operate on a privileged/reserved port (<1024)");
|
|
}
|
|
return p;
|
|
}
|
|
|
|
/** `tailscale serve status --json` — read-only. */
|
|
export function buildStatusArgv(binPath: string): string[] {
|
|
assertAbsolute(binPath);
|
|
return [binPath, "serve", "status", "--json"];
|
|
}
|
|
|
|
/**
|
|
* Add one same-number HTTPS-to-loopback listener in the background without
|
|
* disturbing other Serve entries.
|
|
*/
|
|
export function buildExposeArgv(binPath: string, port: number): string[] {
|
|
assertAbsolute(binPath);
|
|
const p = assertMutablePort(port);
|
|
return [binPath, "serve", "--bg", `--https=${p}`, loopbackTarget(p)];
|
|
}
|
|
|
|
/** Remove exactly one HTTPS listener by port. Never `reset`, never `off` all. */
|
|
export function buildRemoveArgv(binPath: string, port: number): string[] {
|
|
assertAbsolute(binPath);
|
|
const p = assertMutablePort(port);
|
|
return [binPath, "serve", `--https=${p}`, "off"];
|
|
}
|
|
|
|
function assertAbsolute(binPath: string): void {
|
|
if (typeof binPath !== "string" || !binPath.startsWith("/")) {
|
|
throw new Error("tailscale binary path must be absolute");
|
|
}
|
|
// No shell metacharacters, whitespace, or NUL in the pinned binary path.
|
|
if (/[\s;&|`$<>(){}\\"'*?\0]/.test(binPath)) {
|
|
throw new Error("tailscale binary path contains disallowed characters");
|
|
}
|
|
}
|