@lornatang/dsh-codex-security 0.1.7 → 0.1.9

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (55) hide show
  1. package/CHANGELOG.md +32 -0
  2. package/README.md +29 -22
  3. package/README.zh.md +28 -21
  4. package/docs/ARCHITECTURE.md +11 -5
  5. package/docs/ARTIFACTS.md +6 -3
  6. package/docs/CODEX-COMPATIBILITY.md +17 -0
  7. package/docs/SPEC.md +6 -6
  8. package/docs/TOOLS.md +34 -11
  9. package/docs/VALIDATION.md +5 -3
  10. package/docs/superpowers/plans/2026-11-16-deep-scan.md +71 -0
  11. package/docs/superpowers/specs/2026-11-16-deep-scan-design.md +31 -0
  12. package/lib/constants.js +3 -3
  13. package/lib/contracts.js +114 -34
  14. package/lib/deep-coordinator.js +599 -0
  15. package/lib/deep-host.js +36 -0
  16. package/lib/deep-worker.js +254 -0
  17. package/lib/git.js +26 -22
  18. package/lib/index.js +23 -1
  19. package/lib/secure-read.js +229 -0
  20. package/lib/service.js +403 -62
  21. package/lib/state-lock.js +71 -0
  22. package/lib/store.js +33 -15
  23. package/lib/target.js +40 -14
  24. package/lib/tools.js +54 -19
  25. package/lib/types/constants.d.ts +1 -1
  26. package/lib/types/contracts.d.ts +5 -2
  27. package/lib/types/deep-coordinator.d.ts +70 -0
  28. package/lib/types/deep-host.d.ts +32 -0
  29. package/lib/types/deep-worker.d.ts +110 -0
  30. package/lib/types/git.d.ts +10 -10
  31. package/lib/types/index.d.ts +1 -1
  32. package/lib/types/secure-read.d.ts +15 -0
  33. package/lib/types/service.d.ts +20 -4
  34. package/lib/types/state-lock.d.ts +9 -0
  35. package/lib/types/store.d.ts +5 -2
  36. package/lib/types/target.d.ts +1 -0
  37. package/lib/types/tools.d.ts +3 -2
  38. package/lib/types/types.d.ts +42 -7
  39. package/lib/types/util.d.ts +4 -0
  40. package/lib/types/worker-preset.d.ts +18 -0
  41. package/lib/util.js +158 -14
  42. package/lib/worker-preset.js +8 -0
  43. package/package.json +9 -1
  44. package/schemas/coverage.schema.json +2 -0
  45. package/skills/README.md +17 -11
  46. package/skills/assess-patch-risk/SKILL.md +10 -0
  47. package/skills/attack-path-analysis/SKILL.md +10 -0
  48. package/skills/deep-security-scan/SKILL.md +8 -109
  49. package/skills/define-security-policy/SKILL.md +10 -0
  50. package/skills/finding-discovery/SKILL.md +10 -0
  51. package/skills/fix-finding/SKILL.md +6 -104
  52. package/skills/propose-security-hardening/SKILL.md +10 -0
  53. package/skills/track-findings/SKILL.md +5 -106
  54. package/skills/validation/SKILL.md +10 -0
  55. package/skills/verify-fix/SKILL.md +6 -100
@@ -0,0 +1,254 @@
1
+ import { createHash } from 'node:crypto';
2
+ import { setImmediate as yieldEventLoop } from 'node:timers/promises';
3
+ import { digestWorkerSource, readWorkerSource, sourceRootIdentity, workerSourcePath } from './secure-read.js';
4
+ /** Compact adjacent chunks conservatively using their latest model step. */
5
+ export function mergeReceiptRanges(ranges, next) {
6
+ const compare = (a, b) => (a?.turn ?? -1) - (b?.turn ?? -1) || (a?.step ?? -1) - (b?.step ?? -1);
7
+ const sorted = [...ranges, next].sort((a, b) => a.start - b.start || b.end - a.end);
8
+ const merged = [];
9
+ for (const range of sorted) {
10
+ const previous = merged[merged.length - 1];
11
+ if (!previous || previous.total !== range.total || range.start > previous.end) {
12
+ merged.push({ ...range });
13
+ continue;
14
+ }
15
+ if (range.end <= previous.end && compare(previous.position, range.position) <= 0)
16
+ continue;
17
+ if (range.start <= previous.start && range.end >= previous.end && compare(range.position, previous.position) <= 0) {
18
+ merged[merged.length - 1] = { ...range };
19
+ continue;
20
+ }
21
+ previous.end = Math.max(previous.end, range.end);
22
+ if (compare(previous.position, range.position) < 0)
23
+ previous.position = range.position;
24
+ }
25
+ return merged;
26
+ }
27
+ /** Capture exact source bytes without allowing links or paths outside the target. */
28
+ export async function captureWorkerSnapshot(rootPath, paths, maxFileBytes, signal) {
29
+ signal?.throwIfAborted();
30
+ const root = sourceRootIdentity(rootPath);
31
+ const files = Object.create(null);
32
+ const observedDigests = Object.create(null);
33
+ const unavailable = [];
34
+ let visited = 0;
35
+ for (const path of [...new Set(paths)].sort()) {
36
+ if (++visited % 32 === 0)
37
+ await yieldEventLoop();
38
+ signal?.throwIfAborted();
39
+ try {
40
+ const content = readWorkerSource(root.path, path, maxFileBytes, root.identity);
41
+ const digest = createHash('sha256').update(content).digest('hex');
42
+ observedDigests[path] = digest;
43
+ const text = content.toString('utf8');
44
+ if (!Buffer.from(text, 'utf8').equals(content))
45
+ throw new Error('worker source is not valid UTF-8');
46
+ files[path] = { sha256: digest };
47
+ }
48
+ catch (error) {
49
+ signal?.throwIfAborted();
50
+ if (!Object.hasOwn(observedDigests, path)) {
51
+ try {
52
+ observedDigests[path] = await digestWorkerSource(root.path, path, root.identity, signal);
53
+ }
54
+ catch {
55
+ signal?.throwIfAborted();
56
+ }
57
+ }
58
+ unavailable.push({ path, reason: error instanceof Error ? error.message.slice(0, 1000) : 'worker source is unavailable' });
59
+ }
60
+ }
61
+ return {
62
+ rootPath: root.path, rootIdentity: { dev: String(root.identity.dev), ino: String(root.identity.ino) },
63
+ maxFileBytes, files, unavailable, observedDigests,
64
+ };
65
+ }
66
+ /** Verify that the secure per-file capture is exactly the target originally bound. */
67
+ export function assertWorkerSnapshotMatches(target, paths, snapshot) {
68
+ if (target.kind === 'git_diff')
69
+ throw new Error('codex-security: Deep worker snapshots do not support diffs');
70
+ const hash = createHash('sha256');
71
+ hash.update(JSON.stringify({ kind: target.kind, revision: target.revision ?? null, baseRevision: target.baseRevision ?? null, diffFiles: null }));
72
+ for (const path of [...paths].sort()) {
73
+ const digest = snapshot.observedDigests && Object.hasOwn(snapshot.observedDigests, path) ? snapshot.observedDigests[path] : 'unavailable';
74
+ hash.update('\u0000' + path + '\u0000' + digest);
75
+ }
76
+ if ('codex-security-snapshot/v1:sha256:' + hash.digest('hex') !== target.snapshotDigest) {
77
+ throw new Error('codex-security: secure worker snapshot differs from the originally bound target or contains an unverifiable file');
78
+ }
79
+ }
80
+ /** Bind each worker to a fixed target and exact file digests. */
81
+ export class WorkerRegistry {
82
+ workers = new Map();
83
+ reserve(childId, snapshot, options = {}) {
84
+ if (!childId || this.workers.has(childId))
85
+ throw new Error('codex-security: invalid or duplicate worker binding');
86
+ const root = sourceRootIdentity(snapshot.rootPath);
87
+ if (snapshot.rootIdentity && (String(root.identity.dev) !== snapshot.rootIdentity.dev || String(root.identity.ino) !== snapshot.rootIdentity.ino))
88
+ throw new Error('codex-security: worker target directory changed since snapshot');
89
+ const files = Object.create(null);
90
+ for (const [path, item] of Object.entries(snapshot.files)) {
91
+ if (workerSourcePath(path) !== path || !/^[a-f0-9]{64}$/.test(item.sha256))
92
+ throw new Error('codex-security: invalid worker inventory');
93
+ files[path] = { sha256: item.sha256 };
94
+ }
95
+ if (!Number.isSafeInteger(snapshot.maxFileBytes) || snapshot.maxFileBytes < 1)
96
+ throw new Error('codex-security: invalid worker size limit');
97
+ this.workers.set(childId, { rootPath: root.path, rootNode: root.identity, maxFileBytes: snapshot.maxFileBytes, files, receipts: new Set(), ranges: new Map(), allowUnpositioned: options.allowUnpositionedReceipts === true });
98
+ }
99
+ release(childId) { this.workers.delete(childId); }
100
+ has(childId) { return this.workers.has(childId); }
101
+ list(childId) { return Object.keys(this.binding(childId).files).sort(); }
102
+ receipts(childId) {
103
+ const binding = this.binding(childId);
104
+ const complete = new Set(binding.receipts);
105
+ for (const [path, chunks] of binding.ranges) {
106
+ const eligible = chunks.filter((chunk) => chunk.position ? binding.finalStep &&
107
+ (chunk.position.turn < binding.finalStep.turn || (chunk.position.turn === binding.finalStep.turn && chunk.position.step < binding.finalStep.step)) : binding.allowUnpositioned);
108
+ const sorted = eligible.sort((a, b) => a.start - b.start);
109
+ if (!sorted.length)
110
+ continue;
111
+ let covered = 0;
112
+ for (const chunk of sorted) {
113
+ if (chunk.start > covered)
114
+ break;
115
+ covered = Math.max(covered, chunk.end);
116
+ }
117
+ if (covered === sorted[0].total && sorted[0].start === 0)
118
+ complete.add(path);
119
+ }
120
+ return [...complete].sort();
121
+ }
122
+ acceptFinalStep(childId, position) {
123
+ const binding = this.workers.get(childId);
124
+ if (binding)
125
+ binding.finalStep = position;
126
+ }
127
+ async read(childId, path) {
128
+ return this.readText(childId, path);
129
+ }
130
+ readText(childId, path) {
131
+ const binding = this.binding(childId);
132
+ const source = workerSourcePath(path);
133
+ if (!Object.hasOwn(binding.files, source))
134
+ throw new Error('codex-security: worker source path is outside the bound inventory');
135
+ const file = binding.files[source];
136
+ const bytes = readWorkerSource(binding.rootPath, source, binding.maxFileBytes, binding.rootNode, file.sha256);
137
+ const text = bytes.toString('utf8');
138
+ if (!Buffer.from(text, 'utf8').equals(bytes))
139
+ throw new Error('codex-security: worker source is not valid UTF-8');
140
+ return text;
141
+ }
142
+ async readChunk(childId, path, offset) {
143
+ if (!Number.isSafeInteger(offset) || offset < 0)
144
+ throw new Error('codex-security: invalid worker source offset');
145
+ const content = this.readText(childId, path);
146
+ if (offset > content.length)
147
+ throw new Error('codex-security: worker source offset exceeds file length');
148
+ const end = Math.min(offset + 4096, content.length);
149
+ return { path, content: content.slice(offset, end), offset, nextOffset: end === content.length ? null : end, totalLength: content.length };
150
+ }
151
+ /** Verify each delivered chunk against the snapshot before counting its covered range. */
152
+ acceptChunk(childId, value, position) {
153
+ const binding = this.workers.get(childId);
154
+ if (!binding || !Object.hasOwn(binding.files, value.path) || !Number.isSafeInteger(value.offset) || !Number.isSafeInteger(value.totalLength))
155
+ return;
156
+ if (!position && !binding.allowUnpositioned)
157
+ return;
158
+ const end = value.offset + value.content.length;
159
+ if (value.offset < 0 || end > value.totalLength || (value.nextOffset !== null && value.nextOffset !== end) || (value.nextOffset === null && end !== value.totalLength))
160
+ return;
161
+ const original = this.readText(childId, value.path);
162
+ if (original.length !== value.totalLength || original.slice(value.offset, end) !== value.content)
163
+ return;
164
+ const ranges = mergeReceiptRanges(binding.ranges.get(value.path) ?? [], { start: value.offset, end, total: value.totalLength, ...(position ? { position } : {}) });
165
+ if (ranges.length > 16384)
166
+ return;
167
+ binding.ranges.set(value.path, ranges);
168
+ }
169
+ /** Called only after the host accepts the tool's authoritative result. */
170
+ acceptRead(childId, path, content) {
171
+ const binding = this.workers.get(childId);
172
+ if (!binding || !Object.hasOwn(binding.files, path))
173
+ return;
174
+ if (createHash('sha256').update(content, 'utf8').digest('hex') === binding.files[path].sha256)
175
+ binding.receipts.add(path);
176
+ }
177
+ binding(childId) {
178
+ const binding = this.workers.get(childId);
179
+ if (!binding)
180
+ throw new Error('codex-security: worker has no active binding');
181
+ return binding;
182
+ }
183
+ }
184
+ /** Install in the persistent worker preset, so resumed child sessions remain confined. */
185
+ export function installWorkerGuard(ctx) {
186
+ const allowed = new Set(['codex_security_worker_read', 'codex_security_worker_list', 'structured_output']);
187
+ return ctx.tools.guard((execution) => allowed.has(execution.name) ? undefined : 'codex-security: tool is not available to a security review worker');
188
+ }
189
+ /** Register worker-only tools; ordinary agents never receive them in their tool set. */
190
+ export function registerWorkerTools(ctx, registry) {
191
+ const options = { when: ({ agent }) => typeof agent.id === 'string' && registry.has(agent.id) };
192
+ const output = { schema: { type: 'object', additionalProperties: true }, render: (_args, value) => [{ type: 'text', text: JSON.stringify(value) }] };
193
+ const workerId = (exec) => {
194
+ const id = exec.agent?.id;
195
+ if (typeof id !== 'string' || !registry.has(id))
196
+ throw new Error('codex-security: worker has no active binding');
197
+ return id;
198
+ };
199
+ const disposers = [
200
+ ctx.tools.register({
201
+ name: 'codex_security_worker_list', description: 'List files in this worker’s bound review inventory.',
202
+ parameters: { type: 'object', properties: {}, additionalProperties: false }, output, timeoutMs: 60000,
203
+ execute: async (_args, exec) => ({ files: registry.list(workerId(exec)) }),
204
+ }, options),
205
+ ctx.tools.register({
206
+ name: 'codex_security_worker_read', description: 'Read a verified source chunk; repeat with nextOffset until it is null.',
207
+ parameters: { type: 'object', properties: { path: { type: 'string' }, offset: { type: 'integer' } }, required: ['path'], additionalProperties: false }, output, timeoutMs: 60000,
208
+ execute: async (args, exec) => {
209
+ if (!args || typeof args !== 'object' || Array.isArray(args) || typeof args.path !== 'string')
210
+ throw new Error('codex-security: worker source path is required');
211
+ const path = args.path;
212
+ const offset = args.offset ?? 0;
213
+ if (typeof offset !== 'number')
214
+ throw new Error('codex-security: invalid worker source offset');
215
+ return registry.readChunk(workerId(exec), path, offset);
216
+ },
217
+ }, options),
218
+ ];
219
+ const off = ctx.on('tools/result', (execution, result) => {
220
+ if (result.isError || typeof execution.agent?.id !== 'string' || !registry.has(execution.agent.id))
221
+ return;
222
+ const events = execution.agent.session?.snapshotEvents?.() ?? [];
223
+ const call = [...events].reverse().find((event) => event.type === 'tool/call' && event.data?.['callId'] === execution.callId && event.data?.['name'] === execution.name);
224
+ const turn = call?.data?.['turn'];
225
+ const step = call?.data?.['step'];
226
+ const position = typeof turn === 'number' && Number.isSafeInteger(turn) && typeof step === 'number' && Number.isSafeInteger(step) ? { turn, step } : undefined;
227
+ if (execution.name === 'structured_output') {
228
+ if (position)
229
+ registry.acceptFinalStep(execution.agent.id, position);
230
+ return;
231
+ }
232
+ if (execution.name !== 'codex_security_worker_read')
233
+ return;
234
+ const args = execution.arguments;
235
+ const value = result.value;
236
+ if (typeof args?.path !== 'string' || value?.path !== args.path || typeof value.content !== 'string')
237
+ return;
238
+ // The canonical value can survive while a post-execute policy replaces or
239
+ // truncates the actual model-facing content. Count only the delivered JSON.
240
+ if (result.content?.length !== 1 || result.content[0]?.type !== 'text' || typeof result.content[0].text !== 'string')
241
+ return;
242
+ try {
243
+ const delivered = JSON.parse(result.content[0].text);
244
+ if (delivered?.path === value.path && delivered.content === value.content && delivered.offset === value.offset &&
245
+ delivered.nextOffset === value.nextOffset && delivered.totalLength === value.totalLength &&
246
+ typeof value.offset === 'number' && typeof value.totalLength === 'number' && (typeof value.nextOffset === 'number' || value.nextOffset === null)) {
247
+ registry.acceptChunk(execution.agent.id, { path: args.path, content: value.content, offset: value.offset, nextOffset: value.nextOffset, totalLength: value.totalLength }, position);
248
+ }
249
+ }
250
+ catch { /* A replaced, truncated or non-JSON projection is not a receipt. */ }
251
+ });
252
+ return () => { off?.(); for (const dispose of disposers)
253
+ dispose(); };
254
+ }
package/lib/git.js CHANGED
@@ -5,42 +5,45 @@ import { createReadStream } from 'node:fs';
5
5
  import { join } from 'node:path';
6
6
  const run = promisify(execFile);
7
7
  const MAX_BUFFER = 64 * 1024 * 1024;
8
- export async function git(root, args, timeoutMs = 60000) {
8
+ export async function git(root, args, timeoutMs = 60000, signal) {
9
9
  try {
10
- const result = await run('git', args, { cwd: root, timeout: timeoutMs, maxBuffer: MAX_BUFFER, windowsHide: true });
10
+ const result = await run('git', args, { cwd: root, timeout: timeoutMs, maxBuffer: MAX_BUFFER, windowsHide: true, signal });
11
11
  return { ok: true, stdout: String(result.stdout), stderr: String(result.stderr) };
12
12
  }
13
13
  catch (error) {
14
+ signal?.throwIfAborted();
14
15
  const failed = error;
15
16
  return { ok: false, stdout: String(failed.stdout ?? ''), stderr: String(failed.stderr ?? failed.message ?? 'git failed') };
16
17
  }
17
18
  }
18
- export async function gitString(root, args, timeoutMs) {
19
- const result = await git(root, args, timeoutMs);
19
+ export async function gitString(root, args, timeoutMs, signal) {
20
+ const result = await git(root, args, timeoutMs, signal);
20
21
  return result.ok ? result.stdout.trim() : undefined;
21
22
  }
22
23
  export async function isGitRepo(root) {
23
24
  return (await gitString(root, ['rev-parse', '--is-inside-work-tree'])) === 'true';
24
25
  }
25
- export async function repoRoot(path) {
26
- return gitString(path, ['rev-parse', '--show-toplevel']);
26
+ export async function repoRoot(path, signal) {
27
+ return gitString(path, ['rev-parse', '--show-toplevel'], undefined, signal);
27
28
  }
28
- export async function headRevision(root) {
29
- return gitString(root, ['rev-parse', 'HEAD']);
29
+ export async function headRevision(root, signal) {
30
+ return gitString(root, ['rev-parse', 'HEAD'], undefined, signal);
30
31
  }
31
- export async function currentBranch(root) {
32
- return gitString(root, ['rev-parse', '--abbrev-ref', 'HEAD']);
32
+ export async function currentBranch(root, signal) {
33
+ return gitString(root, ['rev-parse', '--abbrev-ref', 'HEAD'], undefined, signal);
33
34
  }
34
- export async function remoteUrl(root) {
35
- return gitString(root, ['config', '--get', 'remote.origin.url']);
35
+ export async function remoteUrl(root, signal) {
36
+ return gitString(root, ['config', '--get', 'remote.origin.url'], undefined, signal);
36
37
  }
37
- export async function resolveRevision(root, ref) {
38
- return gitString(root, ['rev-parse', '--verify', ref + '^{commit}']);
38
+ export async function resolveRevision(root, ref, signal) {
39
+ if (typeof ref !== 'string' || ref.length === 0 || ref.startsWith('-'))
40
+ throw new Error('codex-security: invalid git revision: ' + ref);
41
+ return gitString(root, ['rev-parse', '--verify', ref + '^{commit}'], undefined, signal);
39
42
  }
40
- export async function statusEntries(root) {
41
- const result = await git(root, ['status', '--porcelain=v1', '-z', '--untracked-files=all']);
43
+ export async function statusEntries(root, signal) {
44
+ const result = await git(root, ['status', '--porcelain=v1', '-z', '--untracked-files=all'], undefined, signal);
42
45
  if (!result.ok)
43
- return [];
46
+ throw new Error('codex-security: git status failed: ' + result.stderr.trim());
44
47
  const items = [];
45
48
  const parts = result.stdout.split('\u0000').filter(Boolean);
46
49
  for (let i = 0; i < parts.length; i++) {
@@ -56,10 +59,10 @@ export async function statusEntries(root) {
56
59
  }
57
60
  return items;
58
61
  }
59
- export async function trackedFiles(root) {
60
- const result = await git(root, ['ls-files', '-z']);
62
+ export async function trackedFiles(root, signal) {
63
+ const result = await git(root, ['ls-files', '-z'], undefined, signal);
61
64
  if (!result.ok)
62
- return [];
65
+ throw new Error('codex-security: git file inventory failed: ' + result.stderr.trim());
63
66
  return result.stdout.split('\u0000').filter(Boolean);
64
67
  }
65
68
  export async function changedFiles(root, options) {
@@ -129,14 +132,15 @@ export async function worktreeDigest(root) {
129
132
  }
130
133
  return hash.digest('hex');
131
134
  }
132
- export async function fileDigest(path) {
135
+ export async function fileDigest(path, signal) {
133
136
  try {
134
137
  const hash = createHash('sha256');
135
- for await (const chunk of createReadStream(path))
138
+ for await (const chunk of createReadStream(path, { signal }))
136
139
  hash.update(chunk);
137
140
  return hash.digest('hex');
138
141
  }
139
142
  catch {
143
+ signal?.throwIfAborted();
140
144
  return undefined;
141
145
  }
142
146
  }
package/lib/index.js CHANGED
@@ -6,6 +6,9 @@ import { Config } from './config.js';
6
6
  import { SecurityService } from './service.js';
7
7
  import { bindRoutes } from './routes.js';
8
8
  import { registerSecurityTools } from './tools.js';
9
+ import { DeepCoordinator } from './deep-coordinator.js';
10
+ import { WorkerRegistry, registerWorkerTools } from './deep-worker.js';
11
+ import { DshWorkerHost } from './deep-host.js';
9
12
  export const name = PLUGIN_NAME;
10
13
  export const inject = ['tools', 'skills'];
11
14
  export { Config };
@@ -113,7 +116,26 @@ function registerSkills(ctx, packageRoot) {
113
116
  export function apply(ctx, config = {}) {
114
117
  const packageRoot = join(dirname(fileURLToPath(import.meta.url)), '..');
115
118
  const service = new SecurityService(ctx, { config });
116
- ctx.effect(() => registerSecurityTools(ctx, service), 'codex-security: tools');
119
+ let coordinator;
120
+ ctx.effect(() => registerSecurityTools(ctx, service, () => coordinator), 'codex-security: tools');
121
+ ctx.inject?.(['subagents', 'agentPresets'], (child) => {
122
+ if (!child.on)
123
+ return;
124
+ const registry = new WorkerRegistry();
125
+ const host = new DshWorkerHost(child['subagents'], child['agentPresets']);
126
+ const runtime = new DeepCoordinator(service, registry, host);
127
+ child.effect(() => {
128
+ const unregister = registerWorkerTools(child, registry);
129
+ coordinator = runtime;
130
+ return async () => {
131
+ if (coordinator === runtime)
132
+ coordinator = undefined;
133
+ await runtime.dispose();
134
+ unregister();
135
+ await host.dispose();
136
+ };
137
+ }, 'codex-security: Deep workers');
138
+ });
117
139
  ctx.effect(() => registerSkills(ctx, packageRoot), 'codex-security: skills');
118
140
  ctx.effect(() => bindRoutes(ctx, service), 'codex-security: routes');
119
141
  ctx.logger.info('codex-security: ready (state dir will resolve on first scan)');
@@ -0,0 +1,229 @@
1
+ import { createHash } from 'node:crypto';
2
+ import { closeSync, constants, fstatSync, lstatSync, openSync, readSync, realpathSync, statSync } from 'node:fs';
3
+ import { createRequire } from 'node:module';
4
+ import { isAbsolute, parse, relative, resolve, sep, toNamespacedPath } from 'node:path';
5
+ import { setImmediate as yieldEventLoop } from 'node:timers/promises';
6
+ const require = createRequire(import.meta.url);
7
+ function nativeApi() {
8
+ try {
9
+ const value = require(`@koromix/koffi-${process.platform}-${process.arch}`);
10
+ if (value.version !== '3.3.8' || typeof value.load !== 'function')
11
+ throw new Error('incompatible native module');
12
+ return value;
13
+ }
14
+ catch (error) {
15
+ throw new Error('codex-security: secure worker reads require native filesystem support', { cause: error });
16
+ }
17
+ }
18
+ /** Require an exact portable relative path; never normalize away traversal. */
19
+ export function workerSourcePath(value) {
20
+ if (typeof value !== 'string' || !value || isAbsolute(value) || value.includes('\\') || value.includes('\0'))
21
+ throw new Error('codex-security: invalid worker source path');
22
+ const parts = value.split('/');
23
+ if (parts.some((part) => !part || part === '.' || part === '..'))
24
+ throw new Error('codex-security: invalid worker source path');
25
+ if (process.platform === 'win32' && parts.some((part) => part.includes(':') || /[. ]$/.test(part) || /^(con|prn|aux|nul|com[1-9]|lpt[1-9])(?:\.|$)/i.test(part))) {
26
+ throw new Error('codex-security: invalid worker source path');
27
+ }
28
+ return parts.join('/');
29
+ }
30
+ export function sourceRootIdentity(root) {
31
+ const path = realpathSync(root);
32
+ const info = statSync(path, { bigint: true });
33
+ if (!info.isDirectory())
34
+ throw new Error('codex-security: worker target must be a directory');
35
+ return { path, identity: { dev: info.dev, ino: info.ino } };
36
+ }
37
+ function assertIdentity(value, expected) {
38
+ if (value.dev !== expected.dev || value.ino !== expected.ino)
39
+ throw new Error('codex-security: worker target directory changed');
40
+ }
41
+ function validateContent(data, expectedHash) {
42
+ if (expectedHash && createHash('sha256').update(data).digest('hex') !== expectedHash)
43
+ throw new Error('codex-security: worker source changed since snapshot');
44
+ return data;
45
+ }
46
+ function openPosix(root, source, rootIdentity) {
47
+ const api = nativeApi();
48
+ if (!constants.O_DIRECTORY || !constants.O_NOFOLLOW)
49
+ throw new Error('codex-security: secure worker reads are unavailable');
50
+ const rawOpenat = api.load(null).func('int openat(int, const char *, int, ...)');
51
+ const flags = constants.O_RDONLY | constants.O_DIRECTORY | constants.O_NOFOLLOW;
52
+ const paths = [];
53
+ const fds = [];
54
+ const volume = parse(root).root;
55
+ const close = () => { for (const fd of fds.reverse()) {
56
+ try {
57
+ closeSync(fd);
58
+ }
59
+ catch { /* Continue closing remaining handles. */ }
60
+ } ; fds.length = 0; };
61
+ try {
62
+ let fd = openSync(volume, flags);
63
+ fds.push(fd);
64
+ const volumeInfo = fstatSync(fd, { bigint: true });
65
+ paths.push({ path: volume, fd, identity: { dev: volumeInfo.dev, ino: volumeInfo.ino } });
66
+ let current = volume;
67
+ for (const component of relative(volume, root).split(sep).filter(Boolean)) {
68
+ current = resolve(current, component);
69
+ fd = rawOpenat(fd, component, flags, 'unsigned int', 0);
70
+ if (fd < 0)
71
+ throw new Error('codex-security: secure worker directory open failed (errno ' + api.errno() + ')');
72
+ fds.push(fd);
73
+ const info = fstatSync(fd, { bigint: true });
74
+ if (!info.isDirectory())
75
+ throw new Error('codex-security: worker source parent is not a directory');
76
+ paths.push({ path: current, fd, identity: { dev: info.dev, ino: info.ino } });
77
+ }
78
+ assertIdentity(paths[paths.length - 1].identity, rootIdentity);
79
+ const parts = source.split('/');
80
+ for (const component of parts.slice(0, -1)) {
81
+ current = resolve(current, component);
82
+ fd = rawOpenat(fd, component, flags, 'unsigned int', 0);
83
+ if (fd < 0)
84
+ throw new Error('codex-security: secure worker directory open failed (errno ' + api.errno() + ')');
85
+ fds.push(fd);
86
+ const info = fstatSync(fd, { bigint: true });
87
+ if (!info.isDirectory())
88
+ throw new Error('codex-security: worker source parent is not a directory');
89
+ paths.push({ path: current, fd, identity: { dev: info.dev, ino: info.ino } });
90
+ }
91
+ const file = rawOpenat(fd, parts[parts.length - 1], constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK, 'unsigned int', 0);
92
+ if (file < 0)
93
+ throw new Error('codex-security: secure worker file open failed (errno ' + api.errno() + ')');
94
+ fds.push(file);
95
+ const before = fstatSync(file, { bigint: true });
96
+ if (!before.isFile())
97
+ throw new Error('codex-security: worker source is not a regular file');
98
+ return { size: before.size, close,
99
+ read: (block) => readSync(file, block, 0, block.length, null),
100
+ verify: () => {
101
+ const after = fstatSync(file, { bigint: true });
102
+ if (before.dev !== after.dev || before.ino !== after.ino || before.size !== after.size || before.mtimeNs !== after.mtimeNs || before.ctimeNs !== after.ctimeNs)
103
+ throw new Error('codex-security: worker source changed while reading');
104
+ for (const directory of paths) {
105
+ const currentInfo = lstatSync(directory.path, { bigint: true });
106
+ if (!currentInfo.isDirectory() || currentInfo.isSymbolicLink())
107
+ throw new Error('codex-security: worker source directory changed');
108
+ assertIdentity(currentInfo, directory.identity);
109
+ }
110
+ } };
111
+ }
112
+ catch (error) {
113
+ close();
114
+ throw error;
115
+ }
116
+ }
117
+ function openWindows(root, source, rootIdentity) {
118
+ const kernel = nativeApi().load('kernel32.dll');
119
+ const native = {
120
+ create: kernel.func('void * __stdcall CreateFileW(const char16_t *, uint32_t, uint32_t, void *, uint32_t, uint32_t, void *)'),
121
+ attributes: kernel.func('uint32_t __stdcall GetFileAttributesW(const char16_t *)'),
122
+ close: kernel.func('int __stdcall CloseHandle(void *)'),
123
+ lastError: kernel.func('uint32_t __stdcall GetLastError(void)'),
124
+ read: kernel.func('int __stdcall ReadFile(void *, void *, uint32_t, _Out_ uint32_t *, void *)'),
125
+ };
126
+ const handles = [];
127
+ const close = () => { for (const handle of handles.reverse())
128
+ native.close(handle); handles.length = 0; };
129
+ const invalid = (handle) => !handle || handle === -1n || handle === 0xffffffffffffffffn || handle === 0xffffffffn;
130
+ const pinDirectory = (path) => {
131
+ const name = toNamespacedPath(path);
132
+ const handle = native.create(name, 0x20, 1, null, 3, 0x02200000, null);
133
+ if (invalid(handle))
134
+ throw new Error('codex-security: secure worker directory open failed (' + native.lastError() + ')');
135
+ handles.push(handle);
136
+ const attr = native.attributes(name);
137
+ if (attr === 0xffffffff || !(attr & 0x10) || (attr & 0x400))
138
+ throw new Error('codex-security: worker source directory is a reparse point or changed');
139
+ };
140
+ const volume = parse(root).root;
141
+ try {
142
+ pinDirectory(volume);
143
+ let current = volume;
144
+ for (const component of relative(volume, root).split(sep).filter(Boolean)) {
145
+ current = resolve(current, component);
146
+ pinDirectory(current);
147
+ }
148
+ assertIdentity(statSync(root, { bigint: true }), rootIdentity);
149
+ const parts = source.split('/');
150
+ for (const component of parts.slice(0, -1)) {
151
+ current = resolve(current, component);
152
+ pinDirectory(current);
153
+ }
154
+ const path = toNamespacedPath(resolve(current, parts[parts.length - 1]));
155
+ const handle = native.create(path, 0x80000000, 1, null, 3, 0x00200080, null);
156
+ if (invalid(handle))
157
+ throw new Error('codex-security: secure worker file open failed (' + native.lastError() + ')');
158
+ handles.push(handle);
159
+ const attributes = native.attributes(path);
160
+ if (attributes === 0xffffffff || (attributes & 0x10) || (attributes & 0x400))
161
+ throw new Error('codex-security: worker source file is a reparse point or changed');
162
+ return { close,
163
+ read: (block) => {
164
+ const read = [0];
165
+ if (!native.read(handle, block, block.length, read, null))
166
+ throw new Error('codex-security: secure worker read failed (' + native.lastError() + ')');
167
+ return read[0] ?? 0;
168
+ },
169
+ verify: () => assertIdentity(statSync(root, { bigint: true }), rootIdentity) };
170
+ }
171
+ catch (error) {
172
+ close();
173
+ throw error;
174
+ }
175
+ }
176
+ /** Read through pinned handles, then verify the exact bytes against the bound snapshot. */
177
+ export function readWorkerSource(root, path, maxBytes, identity, expectedHash) {
178
+ const source = workerSourcePath(path);
179
+ if (!Number.isSafeInteger(maxBytes) || maxBytes < 1)
180
+ throw new Error('codex-security: invalid worker source size limit');
181
+ const file = process.platform === 'win32' ? openWindows(root, source, identity) : openPosix(root, source, identity);
182
+ try {
183
+ if (file.size !== undefined && file.size > BigInt(maxBytes))
184
+ throw new Error('codex-security: worker source exceeds the size limit');
185
+ const pieces = [];
186
+ let total = 0;
187
+ for (;;) {
188
+ const block = Buffer.alloc(Math.min(65536, maxBytes - total + 1));
189
+ const count = file.read(block);
190
+ if (!count)
191
+ break;
192
+ total += count;
193
+ if (total > maxBytes)
194
+ throw new Error('codex-security: worker source exceeds the size limit');
195
+ pieces.push(block.subarray(0, count));
196
+ }
197
+ file.verify();
198
+ return validateContent(Buffer.concat(pieces), expectedHash);
199
+ }
200
+ finally {
201
+ file.close();
202
+ }
203
+ }
204
+ /** Hash oversized files through the same pinned handles without exposing their contents. */
205
+ export async function digestWorkerSource(root, path, identity, signal) {
206
+ const source = workerSourcePath(path);
207
+ signal?.throwIfAborted();
208
+ const file = process.platform === 'win32' ? openWindows(root, source, identity) : openPosix(root, source, identity);
209
+ try {
210
+ const hash = createHash('sha256');
211
+ let blocks = 0;
212
+ for (;;) {
213
+ signal?.throwIfAborted();
214
+ const block = Buffer.alloc(65536);
215
+ const count = file.read(block);
216
+ if (!count)
217
+ break;
218
+ hash.update(block.subarray(0, count));
219
+ if (++blocks % 16 === 0)
220
+ await yieldEventLoop();
221
+ }
222
+ signal?.throwIfAborted();
223
+ file.verify();
224
+ return hash.digest('hex');
225
+ }
226
+ finally {
227
+ file.close();
228
+ }
229
+ }