From 9c2ca0c41517db49d724312527c309b1aae60252 Mon Sep 17 00:00:00 2001 From: devops Date: Fri, 23 Oct 2026 14:38:19 +0000 Subject: [PATCH] feat(worker): add fail-closed reviewed startup config registration --- .../compose.prepare-worker.fragment.yml | 19 +++++ .../src/orchestration-worker/worker-config.ts | 48 +++++++++++ .../worker-registration.md | 21 +++++ .../worker-registration.spec.ts | 84 +++++++++++++++++++ .../worker-registration.ts | 10 +++ 5 files changed, 182 insertions(+) create mode 100644 backend/src/orchestration-worker/compose.prepare-worker.fragment.yml create mode 100644 backend/src/orchestration-worker/worker-config.ts create mode 100644 backend/src/orchestration-worker/worker-registration.md create mode 100644 backend/src/orchestration-worker/worker-registration.spec.ts create mode 100644 backend/src/orchestration-worker/worker-registration.ts diff --git a/backend/src/orchestration-worker/compose.prepare-worker.fragment.yml b/backend/src/orchestration-worker/compose.prepare-worker.fragment.yml new file mode 100644 index 00000000..2c1ad6fe --- /dev/null +++ b/backend/src/orchestration-worker/compose.prepare-worker.fragment.yml @@ -0,0 +1,19 @@ +# Opt-in fragment ONLY: merge into the reviewed Stage backend service definition. +# Not a standalone compose file; does not enable the worker automatically. +# Host files/dirs must already exist, with reviewed ownership and modes. +x-prepare-worker-backend: + environment: + PREPARE_WORKER_ENABLED: "${PREPARE_WORKER_ENABLED:-false}" + secrets: + - source: prepare_worker_grants + target: prepare_worker_grants + mode: 0400 + volumes: + - type: bind + source: ${PREPARE_WORKER_ARTIFACT_HOST_DIRECTORY:?review private artifact directory} + target: /var/lib/canina/prepare-artifacts + bind: + create_host_path: false +secrets: + prepare_worker_grants: + file: ${PREPARE_WORKER_GRANTS_FILE:?review mounted grants JSON file} diff --git a/backend/src/orchestration-worker/worker-config.ts b/backend/src/orchestration-worker/worker-config.ts new file mode 100644 index 00000000..d0dc1caf --- /dev/null +++ b/backend/src/orchestration-worker/worker-config.ts @@ -0,0 +1,48 @@ +import { constants, openSync, closeSync, fstatSync, readSync } from 'fs'; +import { WorkerTransportConfig, WorkerTransportModule } from './worker-transport.module'; + +export const PREPARE_WORKER_CONFIG_PATH = '/run/secrets/prepare_worker_grants'; +export const PREPARE_WORKER_ARTIFACT_DIRECTORY = '/var/lib/canina/prepare-artifacts'; +const MAX_BYTES = 16384; +const fail = () => { throw new Error('Prepare worker startup configuration rejected'); }; +function exact(value: any, keys: string[]): boolean { + return value !== null && typeof value === 'object' && !Array.isArray(value) && + Object.keys(value).length === keys.length && keys.every(k => Object.hasOwn(value, k)); +} + +/** Fixed-path, descriptor-pinned, bounded startup read; never logs file contents. */ +export function loadPrepareWorkerConfig(): WorkerTransportConfig { + let dir: number | undefined, file: number | undefined; + try { + dir = openSync('/', constants.O_RDONLY | constants.O_DIRECTORY); + for (const part of ['run', 'secrets']) { + const next = openSync(`/proc/self/fd/${dir}/${part}`, constants.O_RDONLY | constants.O_DIRECTORY | constants.O_NOFOLLOW); + closeSync(dir); dir = next; + if ((fstatSync(dir).mode & 0o022) !== 0) fail(); + } + file = openSync(`/proc/self/fd/${dir}/prepare_worker_grants`, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK); + const stat = fstatSync(file); + if (!stat.isFile() || stat.nlink !== 1 || (stat.mode & 0o022) !== 0 || stat.size > MAX_BYTES || + (stat.uid !== 0 && stat.uid !== process.getuid!())) fail(); + const bytes = Buffer.alloc(MAX_BYTES + 1); + let length = 0, n: number; + do { n = readSync(file, bytes, length, bytes.length - length, length); length += n; } + while (n > 0 && length < bytes.length); + if (length > MAX_BYTES) fail(); + const input = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(bytes.subarray(0, length))); + if (!exact(input, ['grants', 'workerIds', 'stageCiIds', 'artifactBaseUrl']) || + !Array.isArray(input.grants) || input.grants.length < 1 || input.grants.length > 32 || + !Array.isArray(input.workerIds) || !Array.isArray(input.stageCiIds) || + input.workerIds.length < 1 || input.stageCiIds.length < 1 || + input.workerIds.length + input.stageCiIds.length !== input.grants.length || + typeof input.artifactBaseUrl !== 'string' || input.artifactBaseUrl.length > 2048 || + input.grants.some((g: any) => !exact(g, ['id', 'role', 'credentialSha256']))) fail(); + // Transport registration performs shared role, SHA256, ID, overlap and HTTPS validation. + const config: WorkerTransportConfig = { ...input, enabled: true, artifactDirectory: PREPARE_WORKER_ARTIFACT_DIRECTORY }; + WorkerTransportModule.register(config); // Reuse the real transport's reviewed validation, no IO. + config.grants.forEach(Object.freeze); + Object.freeze(config.grants); Object.freeze(config.workerIds); Object.freeze(config.stageCiIds); + return Object.freeze(config); + } catch { return fail(); } + finally { if (file !== undefined) closeSync(file); if (dir !== undefined) closeSync(dir); } +} diff --git a/backend/src/orchestration-worker/worker-registration.md b/backend/src/orchestration-worker/worker-registration.md new file mode 100644 index 00000000..a9c1b7c1 --- /dev/null +++ b/backend/src/orchestration-worker/worker-registration.md @@ -0,0 +1,21 @@ +# Prepare worker startup boundary + +Parent integration API (AppModule remains untouched here): + +```ts +import { registerPrepareWorker } from './orchestration-worker/worker-registration'; +// In AppModule imports: +...registerPrepareWorker(), +``` + +Only literal `PREPARE_WORKER_ENABLED=true` registers the transport. Missing or other values register nothing (404 routes), do not read configuration, and do not instantiate Prisma. Enabled malformed/missing configuration throws synchronously before Nest starts, with one generic error and no secret logging. + +The fixed mount `/run/secrets/prepare_worker_grants` contains JSON with exactly `grants`, `workerIds`, `stageCiIds`, `artifactBaseUrl`. Each grant contains exactly `id`, `role` (`WORKFLOW_WORKER` or `STAGE_CI`), `credentialSha256` (64 lowercase hexadecimal characters; never the bearer credential). Require at least one worker and CI, distinct role-bound IDs/digests, exact allowlist coverage, and at most 32 grants. No enabled flag, directory, token, user, or request-derived fields accepted in JSON. + +`artifactBaseUrl` must be explicitly reviewed by the operator: canonical public-DNS HTTPS origin plus `/internal/prepare-worker/artifacts`, no credentials, IP, alternate port, query or fragment. Shared transport validation is authoritative. This loader does not fetch the URL or perform DNS resolution. Directory is always `/var/lib/canina/prepare-artifacts`. + +Descriptor-relative Linux `/proc/self/fd` traversal refuses symlink directories/files, nonregular files, hardlinks, files over 16 KiB, group/world writable files/directories, and foreign-owned files (root/runtime UID only). Reads are bounded even on concurrent growth. Configuration is frozen recursively and transport takes its own frozen snapshot. Trusted operator owns mounted configuration; edits require restart and review. + +`compose.prepare-worker.fragment.yml` is an extension fragment, not a deployable compose file. Parent must merge its `x-prepare-worker-backend` into the correct reviewed Stage backend service and merge `secrets`. Compose bind-backed secrets may ignore mode/UID declarations: provision actual host grants file as root/runtime-owned mode 0400 and artifact directory runtime-owned mode 0700 first. No mounts or live configuration are created by this change. + +Tests deliberately use the fixed `/run/secrets` path. Run ONLY in a fresh disposable container with source and donor dependencies read-only, private dependency copy, and private `prisma generate`; never on a live service. Tests need a disposable Linux root filesystem and do not require DB credentials. Registration test uses a real Nest HTTP listener to prove disabled routes are absent. Existing DB-backed transport tracer remains separately gated by `WORKER_TRANSPORT_DB=1`. diff --git a/backend/src/orchestration-worker/worker-registration.spec.ts b/backend/src/orchestration-worker/worker-registration.spec.ts new file mode 100644 index 00000000..b4dd9c47 --- /dev/null +++ b/backend/src/orchestration-worker/worker-registration.spec.ts @@ -0,0 +1,84 @@ +import { Test } from '@nestjs/testing'; +import { writeFileSync, chmodSync, symlinkSync, mkdirSync, rmSync } from 'fs'; +import { execFileSync } from 'child_process'; +import { registerPrepareWorker } from './worker-registration'; +import { loadPrepareWorkerConfig } from './worker-config'; +import { linkSync } from 'fs'; + + +describe('reviewed prepare-worker startup registration', () => { + const path = '/run/secrets/prepare_worker_grants'; + const valid = () => ({ grants: [{ id: 'worker', role: 'WORKFLOW_WORKER', credentialSha256: 'a'.repeat(64) }, { id: 'ci', role: 'STAGE_CI', credentialSha256: 'b'.repeat(64) }], workerIds: ['worker'], stageCiIds: ['ci'], artifactBaseUrl: 'https://stage.example.com/internal/prepare-worker/artifacts' }); + it('loader itself rejects malformed SHA grants', () => { + mkdirSync('/run/secrets', { recursive: true }); + const c = valid(); c.grants[0].credentialSha256 = 'secret-not-a-sha'; + writeFileSync(path, JSON.stringify(c), { mode: 0o400 }); + try { expect(() => loadPrepareWorkerConfig()).toThrow('Prepare worker startup configuration rejected'); } + finally { rmSync(path, { force: true }); } + }); + it.each(['1', 'TRUE', 'yes', ' true', 'false', ''])('does not opt in for %s', value => { + expect(registerPrepareWorker({ PREPARE_WORKER_ENABLED: value })).toEqual([]); + }); + it.each(['missing', 'symlink', 'directory', 'fifo', 'oversize', 'group-write', 'world-write', 'hardlink'])('fails startup on unsafe file: %s', kind => { + mkdirSync('/run/secrets', { recursive: true }); + const other = '/run/secrets/test-other'; + try { + if (kind === 'fifo') execFileSync('mkfifo', [path]); + else if (kind === 'directory') mkdirSync(path); + else if (kind === 'symlink') symlinkSync(other, path); + else if (kind !== 'missing') { + writeFileSync(path, kind === 'oversize' ? ' '.repeat(16385) : JSON.stringify(valid()), { mode: 0o400 }); + if (kind === 'group-write') chmodSync(path, 0o420); + if (kind === 'world-write') chmodSync(path, 0o402); + if (kind === 'hardlink') linkSync(path, other); + } + expect(() => registerPrepareWorker({ PREPARE_WORKER_ENABLED: 'true' })).toThrow('Prepare worker startup configuration rejected'); + } finally { rmSync(path, { recursive: true, force: true }); rmSync(other, { force: true }); } + }); + it.each(['extra', 'raw-token', 'wrong-role', 'overlap', 'duplicate-sha', 'missing-grant', 'http', 'credentials', 'localhost', 'query', 'bad-json', 'null'])('rejects unreviewed JSON: %s without leaking contents or logging', kind => { + mkdirSync('/run/secrets', { recursive: true }); + const c: any = valid(); + if (kind === 'extra') c.artifactDirectory = '/user-selected'; + if (kind === 'raw-token') c.grants[0].token = 'DO_NOT_LOG_THIS_SECRET'; + if (kind === 'wrong-role') c.grants[0].role = 'Admin'; + if (kind === 'overlap') c.stageCiIds = ['worker']; + if (kind === 'duplicate-sha') c.grants[1].credentialSha256 = c.grants[0].credentialSha256; + if (kind === 'missing-grant') c.workerIds.push('unbound'); + if (kind === 'http') c.artifactBaseUrl = 'http://stage.example.com/internal/prepare-worker/artifacts'; + if (kind === 'credentials') c.artifactBaseUrl = 'https://DO_NOT_LOG_THIS_SECRET@stage.example.com/internal/prepare-worker/artifacts'; + if (kind === 'localhost') c.artifactBaseUrl = 'https://127.0.0.1/internal/prepare-worker/artifacts'; + if (kind === 'query') c.artifactBaseUrl += '?secret=DO_NOT_LOG_THIS_SECRET'; + writeFileSync(path, kind === 'bad-json' ? 'DO_NOT_LOG_THIS_SECRET' : kind === 'null' ? 'null' : JSON.stringify(c), { mode: 0o400 }); + const logs = [jest.spyOn(console, 'log'), jest.spyOn(console, 'warn'), jest.spyOn(console, 'error')]; + try { + expect(() => registerPrepareWorker({ PREPARE_WORKER_ENABLED: 'true' })).toThrow(/^Prepare worker startup configuration rejected$/); + logs.forEach(log => expect(log).not.toHaveBeenCalled()); + } finally { logs.forEach(log => log.mockRestore()); rmSync(path, { force: true }); } + }); + it('defaults to no module/no config IO and exposes no worker routes', async () => { + expect(registerPrepareWorker({})).toEqual([]); + expect(registerPrepareWorker({ PREPARE_WORKER_ENABLED: 'false' })).toEqual([]); + const module = await Test.createTestingModule({ imports: registerPrepareWorker({}) }).compile(); + const app = module.createNestApplication(); + await app.listen(0, '127.0.0.1'); + try { + const response = await fetch((await app.getUrl()) + '/internal/prepare-worker/claim', { method: 'POST' }); + expect(response.status).toBe(404); + } finally { await app.close(); } + }); + it('loads immutable reviewed JSON into the real transport registration', async () => { + mkdirSync('/run/secrets', { recursive: true }); + const file = '/run/secrets/prepare_worker_grants'; + const config = { grants: [{ id: 'worker', role: 'WORKFLOW_WORKER', credentialSha256: 'a'.repeat(64) }, { id: 'ci', role: 'STAGE_CI', credentialSha256: 'b'.repeat(64) }], workerIds: ['worker'], stageCiIds: ['ci'], artifactBaseUrl: 'https://stage.example.com/internal/prepare-worker/artifacts' }; + writeFileSync(file, JSON.stringify(config), { mode: 0o400 }); + try { + const [registered] = registerPrepareWorker({ PREPARE_WORKER_ENABLED: 'true' }); + expect(registered.module.name).toBe('WorkerTransportModule'); + expect(registered.controllers?.length).toBe(1); + const snapshot = (registered.providers as any[]).find(p => p.useValue?.artifactDirectory)?.useValue; + expect(snapshot).toEqual({ ...config, enabled: true, artifactDirectory: '/var/lib/canina/prepare-artifacts' }); + expect(Object.isFrozen(snapshot)).toBe(true); + expect(Object.isFrozen(snapshot.grants[0])).toBe(true); + } finally { rmSync(file, { force: true }); } + }); +}); diff --git a/backend/src/orchestration-worker/worker-registration.ts b/backend/src/orchestration-worker/worker-registration.ts new file mode 100644 index 00000000..bb81d8d8 --- /dev/null +++ b/backend/src/orchestration-worker/worker-registration.ts @@ -0,0 +1,10 @@ +import { DynamicModule } from '@nestjs/common'; +import { loadPrepareWorkerConfig } from './worker-config'; +import { WorkerTransportModule } from './worker-transport.module'; + +/** AppModule imports: ...registerPrepareWorker(); disabled means no module or IO. */ +export function registerPrepareWorker(env: NodeJS.ProcessEnv = process.env): DynamicModule[] { + if (env.PREPARE_WORKER_ENABLED !== 'true') return []; + try { return [WorkerTransportModule.register(loadPrepareWorkerConfig())]; } + catch { throw new Error('Prepare worker startup configuration rejected'); } +}