@catalyst-cloud/cli 0.14.10 → 0.15.0

package/dist/onboard-runner-cloud.js

@@ -0,0 +1,213 @@
+import { randomUUID } from "node:crypto";
+import { closeSync, constants, fsyncSync, lstatSync, mkdirSync, openSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { loadConfig, normalizeBaseUrl, readManifest } from "./config.js";
+import { contractVersionInRange } from "./contract.js";
+const ADMISSION = "/api/v1/agent/runner-admission";
+const KEYS = "/api/v1/agent/runner-keys";
+const KEY_RESOURCE = `${KEYS}/:requestId`;
+const SCOPES = ["mirror:read", "mirror:write", "mirror:feed"];
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
+const object = (v) => v !== null && typeof v === "object" && !Array.isArray(v) ? v : null;
+function identity(ctx, binding) {
+    const cfg = loadConfig(ctx.home);
+    if (!cfg?.user || !["owner", "admin"].includes(cfg.user.role) || cfg.account !== (binding.account ?? binding.tenant) || cfg.user.id !== binding.membershipId || !binding.baseUrl || normalizeBaseUrl(cfg.baseUrl) !== normalizeBaseUrl(binding.baseUrl))
+        return null;
+    const expiry = cfg.auth ? Date.parse(cfg.auth.expiresAt) - ctx.now().getTime() : 0;
+    const bearer = cfg.key || (cfg.auth && Number.isFinite(expiry) && expiry > 30_000 ? cfg.auth.accessToken : undefined);
+    try {
+        const url = new URL(cfg.baseUrl);
+        if (url.protocol !== "https:" || url.username || url.password || url.search || url.hash || url.pathname !== "/")
+            return null;
+        return bearer ? { account: cfg.account, origin: url.origin, bearer } : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Mutation failures and provider bodies never become terminal/receipt text. */
+async function request(ctx, binding, path, method, body, signal) {
+    const who = identity(ctx, binding);
+    if (!who)
+        return { reason: "runner_identity_unverified" };
+    if (signal?.aborted)
+        return { reason: "interrupted" };
+    try {
+        const response = await ctx.fetch(`${who.origin}${path}`, { method, redirect: "error", signal: signal ? AbortSignal.any([signal, AbortSignal.timeout(30_000)]) : AbortSignal.timeout(30_000), headers: { authorization: `Bearer ${who.bearer}`, accept: "application/json", "cache-control": "no-cache", ...(body ? { "content-type": "application/json" } : {}) }, ...(body ? { body: JSON.stringify(body) } : {}) });
+        const value = object(await response.json().catch(() => null));
+        if (signal?.aborted)
+            return { reason: "interrupted" };
+        const current = identity(ctx, binding);
+        if (!current || current.account !== who.account || current.origin !== who.origin || current.bearer !== who.bearer)
+            return { reason: "runner_identity_unverified" };
+        return { status: response.status, body: value };
+    }
+    catch {
+        return { reason: signal?.aborted ? "interrupted" : "runner_cloud_unavailable" };
+    }
+}
+const RUNNER_ROUTES = new Map([
+    ["GET", ADMISSION], ["PUT", ADMISSION], ["POST", KEYS], ["GET", KEY_RESOURCE], ["DELETE", KEY_RESOURCE],
+].map(([method, path]) => [`${method} ${path}`, method === "POST" ? "requestId" : null]));
+/** Optional runner discovery never widens either legacy route parser. A fresh same-account
+ * personal response advertises exact deployed operations, not authorization or consent. */
+export async function verifyRunnerRoutes(ctx, binding, requirements, signal) {
+    const who = identity(ctx, binding);
+    if (!who)
+        return { reason: "runner_identity_unverified" };
+    const read = await request(ctx, binding, "/api/v1/agent/contract", "GET", undefined, signal);
+    if ("reason" in read)
+        return read;
+    const body = read.body;
+    if (read.status !== 200)
+        return { reason: "runner_capability_unavailable" };
+    if (object(body?.account)?.id !== who.account)
+        return { reason: "runner_identity_unverified" };
+    if (!body || typeof body.contractVersion !== "string" || contractVersionInRange(body.contractVersion, readManifest().tenantContractRange) !== true)
+        return { reason: "runner_capability_unverified" };
+    if (body.runnerOnboarding === undefined)
+        return { reason: "cloud_capability_unavailable" };
+    const section = object(body.runnerOnboarding);
+    if (!section || section.schema !== 1 || !Array.isArray(section.routes) || section.routes.length > RUNNER_ROUTES.size)
+        return { reason: "runner_capability_unverified" };
+    const routes = new Set();
+    for (const value of section.routes) {
+        const row = object(value);
+        if (!row || typeof row.method !== "string" || typeof row.path !== "string")
+            return { reason: "runner_capability_unverified" };
+        const key = `${row.method} ${row.path}`;
+        if (!RUNNER_ROUTES.has(key) || routes.has(key) || row.personalBearer !== true || row.takesWriteBudgetUnit !== false || row.idempotencyKeyField !== RUNNER_ROUTES.get(key))
+            return { reason: "runner_capability_unverified" };
+        routes.add(key);
+    }
+    if (requirements.some(row => !routes.has(`${row.method} ${row.path}`)))
+        return { reason: "cloud_capability_unavailable" };
+    return { origin: who.origin };
+}
+/** Read mode never changes admission. Act sends only the approved field; safe defaults and policy
+ * refusal belong to the server. A successful PUT still requires a fresh same-team readback. */
+export async function runnerAdmission(ctx, journal, teamId, allowAct, signal) {
+    if (!identity(ctx, journal))
+        return { reason: "runner_identity_unverified" };
+    const support = await verifyRunnerRoutes(ctx, journal, [{ method: "GET", path: ADMISSION }, ...(allowAct ? [{ method: "PUT", path: ADMISSION }] : [])], signal);
+    if ("reason" in support)
+        return { reason: support.reason };
+    const path = `${ADMISSION}?account=${encodeURIComponent((journal.account ?? journal.tenant))}&team=${encodeURIComponent(teamId)}`;
+    if (allowAct) {
+        const write = await request(ctx, journal, path, "PUT", { admissionEnabled: true }, signal);
+        if ("reason" in write)
+            return write;
+        if (write.status === 409)
+            return { reason: "runner_admission_operator" };
+        if (write.status === 403)
+            return { reason: "runner_identity_unverified" };
+        if (write.status !== 200)
+            return { reason: "runner_admission_unverified" };
+        if (write.body?.account !== (journal.account ?? journal.tenant) || write.body?.team !== teamId || write.body?.admissionEnabled !== true)
+            return { reason: "runner_admission_unverified" };
+    }
+    const read = await request(ctx, journal, path, "GET", undefined, signal);
+    if ("reason" in read)
+        return read;
+    if (read.status === 409)
+        return { reason: "runner_admission_operator" };
+    if (read.status !== 200 || read.body?.account !== (journal.account ?? journal.tenant) || read.body?.team !== teamId || typeof read.body?.admissionEnabled !== "boolean")
+        return { reason: "runner_admission_unverified" };
+    return { ready: read.body.admissionEnabled };
+}
+/** Exclusive private marker, fsynced before POST. Malformed/foreign markers fail closed; they are
+ * never deleted or replaced to obtain a fresh provider key after an uncertain outcome. */
+function keyRequest(ctx, journal, setup) {
+    const who = identity(ctx, journal);
+    if (!who || !journal.membershipId)
+        return { reason: "runner_identity_unverified" };
+    const path = join(setup.dir, "key-request.json");
+    try {
+        mkdirSync(setup.dir, { recursive: true, mode: 0o700 });
+        if (lstatSync(setup.dir).isSymbolicLink())
+            return { reason: "runner_org_key_journal_unavailable" };
+        const marker = { version: 1, requestId: randomUUID(), account: who.account, origin: who.origin, membershipId: journal.membershipId, teamId: setup.teamId, hostName: setup.hostName };
+        let fd;
+        try {
+            fd = openSync(path, constants.O_CREAT | constants.O_EXCL | constants.O_WRONLY, 0o600);
+        }
+        catch (error) {
+            if (!(error instanceof Error) || !("code" in error) || error.code !== "EEXIST")
+                return { reason: "runner_org_key_journal_unavailable" };
+            const info = lstatSync(path);
+            if (!info.isFile() || (info.mode & 0o077) !== 0 || info.size > 4096)
+                return { reason: "runner_org_key_journal_unavailable" };
+            const old = object(JSON.parse(readFileSync(path, "utf8")));
+            if (!old || old.version !== 1 || typeof old.requestId !== "string" || !UUID.test(old.requestId) || Object.entries(marker).some(([key, value]) => key !== "requestId" && old[key] !== value))
+                return { reason: "runner_org_key_journal_unavailable" };
+            return { marker: { ...marker, requestId: old.requestId }, existing: true };
+        }
+        try {
+            writeFileSync(fd, JSON.stringify(marker) + "\n");
+            fsyncSync(fd);
+        }
+        finally {
+            closeSync(fd);
+        }
+        const directory = openSync(setup.dir, constants.O_RDONLY);
+        try {
+            fsyncSync(directory);
+        }
+        finally {
+            closeSync(directory);
+        }
+        return { marker, existing: false };
+    }
+    catch {
+        return { reason: "runner_org_key_journal_unavailable" };
+    }
+}
+/** Called only for an explicitly selected runner that needs a key. One response may carry its
+ * value; it goes directly to the private volume. Recovered issuance never silently rotates,
+ * revokes or mints a second key. The caller revalidates the stored key before reporting ready. */
+export async function issueRunnerOrgKey(ctx, journal, setup, store, signal) {
+    if (!identity(ctx, journal))
+        return { reason: "runner_identity_unverified" };
+    const support = await verifyRunnerRoutes(ctx, journal, [{ method: "POST", path: KEYS }, { method: "GET", path: KEY_RESOURCE }], signal);
+    if ("reason" in support)
+        return { reason: support.reason };
+    if (signal?.aborted)
+        return { reason: "interrupted" };
+    const saved = keyRequest(ctx, journal, setup);
+    if ("reason" in saved)
+        return saved;
+    const { marker } = saved;
+    const suffix = `?account=${encodeURIComponent(marker.account)}`;
+    if (saved.existing) {
+        const read = await request(ctx, journal, `${KEYS}/${marker.requestId}${suffix}`, "GET", undefined, signal);
+        if ("reason" in read)
+            return read;
+        // Only the exact deployed no-record response can retry this same UUID. The server's atomic
+        // claim prevents a delayed/concurrent POST from minting twice. Pending claims, missing orgs,
+        // malformed responses and lost issued values never authorize a new UUID or rotation.
+        const absent = read.status === 404 && read.body?.error === "not_found" && Object.keys(read.body).length === 1;
+        if (!absent) {
+            if (read.status !== 200 || read.body?.account !== marker.account || read.body?.requestId !== marker.requestId)
+                return { reason: "runner_org_key_reconciliation_pending" };
+            return { reason: "runner_org_key_recovery_required" };
+        }
+    }
+    const issued = await request(ctx, journal, `${KEYS}${suffix}`, "POST", { requestId: marker.requestId, name: setup.hostName }, signal);
+    if ("reason" in issued)
+        return issued;
+    if (issued.status === 403)
+        return { reason: "runner_identity_unverified" };
+    if (issued.status === 409)
+        return { reason: "runner_org_key_recovery_required" };
+    const key = object(issued.body?.key);
+    if (issued.status !== 201 || issued.body?.account !== marker.account || issued.body?.requestId !== marker.requestId || issued.body?.status !== "issued" || !key || typeof key.value !== "string" || !/^[\x21-\x7e]{16,1024}$/.test(key.value) || !Array.isArray(key.permissions) || key.permissions.length !== SCOPES.length || !SCOPES.every(scope => key.permissions.includes(scope)))
+        return { reason: "runner_org_key_response_unverified" };
+    if (signal?.aborted)
+        return { reason: "interrupted" };
+    try {
+        return await store(key.value) ? { stored: true } : { reason: "runner_org_key_write_failed" };
+    }
+    catch {
+        return { reason: "runner_org_key_write_failed" };
+    }
+}

package/dist/onboard-runner-egress.js

@@ -0,0 +1,67 @@
+import { createHash } from 'node:crypto';
+import { execFile } from 'node:child_process';
+import { lstatSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { packageRoot } from './config.js';
+export const NATIVE_EGRESS_DIR = '/var/lib/catalyst/session-egress';
+export const EGRESS_ARTIFACTS = [
+    { name: 'session-egress.py', digest: 'a20cedfa1e883127ec461e4b7f9588d379fe1633b8244ecd703c81f589d3f142', path: '/usr/lib/catalyst/session-egress.py', mode: 0o755 },
+    { name: 'catalyst-session-egress.service', digest: '703c150ab23ec87aea47cfc394f63e061b66c4b8c1454a88a9be879c161ce2a5', path: '/etc/systemd/system/catalyst-session-egress.service', mode: 0o644 },
+    { name: 'catalyst-session-egress-attest.service', digest: '94fa75ea0616f6a1172fc20ca637a5727c36456357e4a977d5bdd65f2fad2e8d', path: '/etc/systemd/system/catalyst-session-egress-attest.service', mode: 0o644 },
+    { name: 'catalyst-session-egress-attest.timer', digest: '176622c11c835601b95f36e375ba3c2e993136976c67e5d49559f13a3454fef9', path: '/etc/systemd/system/catalyst-session-egress-attest.timer', mode: 0o644 },
+];
+const nodeReads = {
+    read: readFileSync,
+    stat: path => { const s = lstatSync(path); return { uid: s.uid, mode: s.mode, file: s.isFile(), directory: s.isDirectory(), symlink: s.isSymbolicLink() }; },
+    systemctl: (args, signal) => new Promise(resolve => { execFile('/usr/bin/systemctl', args, { timeout: 10000, signal, maxBuffer: 65536, env: { PATH: '/usr/bin:/usr/sbin:/bin:/sbin', LC_ALL: 'C' } }, (error, stdout) => resolve(error ? null : stdout)); }),
+};
+const hash = (bytes) => createHash('sha256').update(bytes).digest('hex');
+/** Read-only prerequisite. It cannot install units, invoke the producer or synthesize a proof.
+ * The unprivileged supervisor independently validates the same mounted proof before work. */
+export async function nativeEgressReady(now, signal, io = nodeReads) {
+    if (signal?.aborted)
+        return false;
+    try {
+        for (const artifact of EGRESS_ARTIFACTS) {
+            const stat = io.stat(artifact.path);
+            if (stat.symlink || !stat.file || stat.uid !== 0 || (stat.mode & 0o777) !== artifact.mode || hash(io.read(artifact.path)) !== artifact.digest)
+                return false;
+        }
+        const dir = io.stat(NATIVE_EGRESS_DIR), path = join(NATIVE_EGRESS_DIR, 'attestation.json'), stat = io.stat(path);
+        if (dir.symlink || !dir.directory || dir.uid !== 0 || (dir.mode & 0o777) !== 0o755 || stat.symlink || !stat.file || stat.uid !== 0 || (stat.mode & 0o777) !== 0o644)
+            return false;
+        const bytes = io.read(path);
+        if (bytes.length > 4096)
+            return false;
+        const proof = JSON.parse(bytes.toString('utf8'));
+        if (!proof || typeof proof !== 'object' || !('version' in proof) || proof.version !== 1 || !('enforcement' in proof) || proof.enforcement !== 'nftables-docker-forward-v1' || !('bridge' in proof) || proof.bridge !== 'catalyst-sess0' || !('verifiedAtMs' in proof) || typeof proof.verifiedAtMs !== 'number' || !Number.isSafeInteger(proof.verifiedAtMs) || proof.verifiedAtMs > now + 300000 || now - proof.verifiedAtMs > 900000)
+            return false;
+        for (const unit of ['catalyst-session-egress.service', 'catalyst-session-egress-attest.timer'])
+            if ((await io.systemctl(['is-enabled', unit], signal))?.trim() !== 'enabled')
+                return false;
+        const boot = await io.systemctl(['show', 'catalyst-session-egress.service', '--property=ActiveState,SubState,Result'], signal);
+        const timer = await io.systemctl(['show', 'catalyst-session-egress-attest.timer', '--property=ActiveState,SubState,NextElapseUSecMonotonic'], signal);
+        if (!boot || !timer)
+            return false;
+        const fields = (text) => Object.fromEntries(text.trim().split('\n').map(line => line.split('=')));
+        const b = fields(boot), t = fields(timer);
+        return !signal?.aborted && b.ActiveState === 'active' && b.SubState === 'exited' && b.Result === 'success' && t.ActiveState === 'active' && t.SubState === 'waiting' && typeof t.NextElapseUSecMonotonic === 'string' && t.NextElapseUSecMonotonic !== '0' && t.NextElapseUSecMonotonic !== '';
+    }
+    catch {
+        return false;
+    }
+}
+/** Exact bundled bytes are checked before showing the separate, elevated install commands. */
+export function nativeEgressInstallCommands() {
+    const root = join(packageRoot(), 'vendor/self-host/linux-session-egress');
+    try {
+        for (const artifact of EGRESS_ARTIFACTS)
+            if (hash(readFileSync(join(root, artifact.name))) !== artifact.digest)
+                return null;
+    }
+    catch {
+        return null;
+    }
+    const quote = (s) => "'" + s.replaceAll("'", "'\\''") + "'";
+    return EGRESS_ARTIFACTS.map(a => `sudo install ${a.name === 'session-egress.py' ? '-D ' : ''}-o root -g root -m ${a.mode.toString(8)} ${quote(join(root, a.name))} ${quote(a.path)}`).join('\n') + '\nsudo systemctl daemon-reload\nsudo systemctl enable --now catalyst-session-egress.service catalyst-session-egress-attest.timer\nsudo /usr/bin/python3 /usr/lib/catalyst/session-egress.py attest';
+}