feat(worker): add fail-closed reviewed startup config registration

This commit is contained in:
devops committed 2026-10-23 14:38:19 +00:00
1 parent 9d93707848
commit 9c2ca0c415
5 files changed
+182

No files matched your search

@@ -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}
@@ -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); }
}
@@ -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`.
@@ -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 }); }
});
});
@@ -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'); }
}