yam-flow 2.8.0 → 2.8.2

package/src/lib/hook-readiness.ts

@@ -0,0 +1,215 @@
+import { spawn } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import fs from 'node:fs';
+import fsp from 'node:fs/promises';
+import path from 'node:path';
+import os from 'node:os';
+
+const MAX_BYTES = 256 * 1024;
+const sha = (text: string) => createHash('sha256').update(text).digest('hex');
+
+/** Select an upgrade-stable alias only when it resolves to the running Node binary. */
+export async function selectHookNode(executable = process.execPath, searchPath = process.env.PATH || '') {
+  const real = await fsp.realpath(executable);
+  const running = await fsp.stat(real);
+  const candidates = searchPath.split(path.delimiter).filter((dir) => path.isAbsolute(dir))
+    .map((dir) => path.join(dir, process.platform === 'win32' ? 'node.exe' : 'node'));
+  for (const candidate of candidates) {
+    try {
+      const canonical = await fsp.realpath(candidate);
+      const stat = await fsp.stat(canonical);
+      await fsp.access(candidate, fs.constants.X_OK);
+      if (stat.isFile() && stat.dev === running.dev && stat.ino === running.ino && canonical === real) {
+        return { executable: candidate, canonical, selection: 'verified_runtime_alias', dev: stat.dev, ino: stat.ino };
+      }
+    } catch { /* An unverified PATH candidate is never executed. */ }
+  }
+  return { executable: real, canonical: real, selection: 'current_runtime_fallback', dev: running.dev, ino: running.ino };
+}
+
+export function summarizeHookDiscovery(value: unknown, cwd: string, commands: Record<string, string[]>, configPath?: string) {
+  const input = value as { data?: Array<{ cwd?: string; hooks?: Array<Record<string, unknown>>; errors?: unknown[]; warnings?: unknown[] }> };
+  if (!Array.isArray(input?.data)) return { state: 'unknown', reason: 'unsupported_response_schema', profiles: {} };
+  const entry = input.data.find((row) => row.cwd === cwd);
+  if (!entry || !Array.isArray(entry.hooks) || !Array.isArray(entry.errors) || !Array.isArray(entry.warnings)) {
+    return { state: 'unknown', reason: 'missing_cwd_or_unsupported_response', profiles: {} };
+  }
+  const profiles = Object.fromEntries(Object.entries(commands).map(([profile, expected]) => {
+    const matches = entry.hooks.filter((hook) => hook.handlerType === 'command' && expected.includes(String(hook.command))
+      && (!configPath || hook.sourcePath === configPath));
+    const approved = matches.filter((hook) => hook.enabled === true && ['trusted', 'managed'].includes(String(hook.trustStatus)));
+    const expectedEvents = profile === 'study-note' ? ['userPromptSubmit', 'stop'] : ['userPromptSubmit'];
+    return [profile, { state: matches.length ? 'discovered' : 'not_discovered', enabled_trusted: approved.length,
+      eligible_event_coverage: expectedEvents.every((event) => approved.filter((hook) => hook.eventName === event).length === 1),
+      discovered_count: matches.length, trust_statuses: [...new Set(matches.map((hook) => String(hook.trustStatus)))],
+      execution_observed: false }];
+  }));
+  return { state: entry.errors.length ? 'partial' : 'queried', reason: entry.errors.length ? 'host_discovery_errors' : '',
+    profiles, warning_count: entry.warnings.length, error_count: entry.errors.length };
+}
+
+/** Opt-in discovery in a new app-server process, not the active desktop session. */
+export async function probeHookDiscovery(options: { executable: string; cwd: string; commands: Record<string, string[]>; configPath?: string; timeoutMs?: number }) {
+  const timeoutMs = Math.min(Math.max(options.timeoutMs || 5000, 100), 10000);
+  return new Promise<Record<string, unknown>>((resolve) => {
+    let finished = false;
+    let stopping = false;
+    let failure = '';
+    let result: Record<string, unknown>;
+    let buffer = '';
+    let total = 0;
+    let timer: NodeJS.Timeout;
+    let killTimer: NodeJS.Timeout;
+    const child = spawn(options.executable, ['app-server'], { cwd: options.cwd, stdio: ['pipe', 'pipe', 'pipe'], shell: false });
+    const stop = (reason = '') => {
+      if (stopping) return;
+      stopping = true;
+      failure = reason;
+      child.stdin.end();
+      child.kill('SIGTERM');
+      killTimer = setTimeout(() => child.kill('SIGKILL'), 500);
+    };
+    const send = (value: unknown) => { if (!stopping) child.stdin.write(`${JSON.stringify(value)}\n`); };
+    child.stdin.on('error', () => stop('protocol_stdin_failed'));
+    child.on('error', () => { failure = 'host_unavailable'; });
+    child.stderr.on('data', (chunk) => { total += chunk.length; if (total > MAX_BYTES) stop('output_limit'); });
+    child.stdout.on('data', (chunk) => {
+      total += chunk.length;
+      if (total > MAX_BYTES) return stop('output_limit');
+      buffer += chunk.toString('utf8');
+      let index: number;
+      while (!stopping && (index = buffer.indexOf('\n')) >= 0) {
+        const line = buffer.slice(0, index); buffer = buffer.slice(index + 1);
+        let message;
+        try { message = JSON.parse(line); } catch { stop('invalid_protocol_json'); break; }
+        if (message.id === 0) {
+          if (message.error) { stop('initialization_rejected'); break; }
+          send({ method: 'initialized', params: {} });
+          send({ method: 'hooks/list', id: 1, params: { cwds: [options.cwd] } });
+        } else if (message.id === 1) {
+          if (message.error) { stop('hooks_list_unsupported_or_rejected'); break; }
+          result = summarizeHookDiscovery(message.result, options.cwd, options.commands, options.configPath);
+          stop();
+        } else if (message.id != null && message.method) {
+          stop('unexpected_server_request');
+        }
+      }
+    });
+    child.on('close', (_code, signal) => {
+      if (finished) return;
+      finished = true;
+      clearTimeout(timer); clearTimeout(killTimer);
+      resolve({ ...(result || { state: 'unknown', profiles: {} }), ...(failure ? { state: 'unknown', reason: failure } : {}),
+        host_context: 'separate_app_server_probe', active_session_loaded: 'not_measured',
+        execution_observed: false, process_exit_observed: true, termination_signal: signal || null,
+        truth_status: 'partial', reason: failure || (result ? result.reason : 'host_exited_before_response') });
+    });
+    timer = setTimeout(() => stop('probe_timeout'), timeoutMs);
+    send({ method: 'initialize', id: 0, params: { clientInfo: { name: 'yam_hook_probe', version: '1' }, capabilities: { experimentalApi: true } } });
+  });
+}
+
+async function safeObservationDirectory(cwd: string, create: boolean) {
+  const root = await fsp.realpath(cwd);
+  let current = root;
+  const identities: Array<{ target: string; dev: number; ino: number }> = [];
+  for (const part of ['', '.yam', 'hooks']) {
+    if (part) current = path.join(current, part);
+    if (create && part) await fsp.mkdir(current, { mode: 0o700 }).catch((error) => { if (error.code !== 'EEXIST') throw error; });
+    const stat = await fsp.lstat(current);
+    if (!stat.isDirectory() || stat.isSymbolicLink()) throw new Error('unsafe_observation_directory');
+    identities.push({ target: current, dev: stat.dev, ino: stat.ino });
+  }
+  return { directory: current, identities };
+}
+
+async function checkParents(identities: Array<{ target: string; dev: number; ino: number }>) {
+  for (const identity of identities) {
+    const stat = await fsp.lstat(identity.target);
+    if (stat.isSymbolicLink() || !stat.isDirectory() || stat.dev !== identity.dev || stat.ino !== identity.ino) throw new Error('observation_parent_changed');
+  }
+}
+
+async function configurationDigest(cwd: string) {
+  const paths = [path.join(process.env.CODEX_HOME || path.join(os.homedir(), '.codex'), 'hooks.json'), path.join(await fsp.realpath(cwd), '.codex', 'hooks.json')];
+  const values = [];
+  for (const target of paths) {
+    try {
+      const before = await fsp.lstat(target);
+      if (!before.isFile() || before.isSymbolicLink() || before.size > MAX_BYTES) throw new Error('unsafe_hook_configuration');
+      const handle = await fsp.open(target, fs.constants.O_RDONLY | (process.platform === 'win32' ? 0 : fs.constants.O_NOFOLLOW || 0));
+      try {
+        const stat = await handle.stat();
+        if (stat.dev !== before.dev || stat.ino !== before.ino || stat.size > MAX_BYTES) throw new Error('hook_configuration_changed');
+        const buffer = Buffer.alloc(MAX_BYTES + 1);
+        const { bytesRead } = await handle.read(buffer, 0, buffer.length, 0);
+        if (bytesRead > MAX_BYTES) throw new Error('hook_configuration_limit');
+        values.push(sha(buffer.subarray(0, bytesRead).toString('utf8')));
+      } finally { await handle.close(); }
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error;
+      values.push('absent');
+    }
+  }
+  return sha(JSON.stringify(values));
+}
+
+export async function recordHookObservation(cwd: string, profile: string, event: string, entrypoint: string) {
+  if (!['lite', 'study-note'].includes(profile) || !['UserPromptSubmit', 'Stop'].includes(event)) throw new Error('unsupported_observation');
+  const { directory, identities } = await safeObservationDirectory(cwd, true);
+  const value = { schema: 'yam.hook-observation.v1', profile, event, observed_at: new Date().toISOString(),
+    cwd_digest: sha(await fsp.realpath(cwd)), entrypoint_digest: sha(await fsp.readFile(entrypoint, 'utf8')),
+    configuration_digest: await configurationDigest(cwd),
+    host_authenticated: false, evidence_kind: 'local_entrypoint_invocation' };
+  const target = path.join(directory, `${profile}.json`);
+  const noFollow = process.platform === 'win32' ? 0 : fs.constants.O_NOFOLLOW || 0;
+  const before = await fsp.lstat(target).catch((error) => { if (error.code === 'ENOENT') return null; throw error; });
+  if (before && (!before.isFile() || before.isSymbolicLink() || before.nlink !== 1)) throw new Error('unsafe_observation_file');
+  const handle = await fsp.open(target, fs.constants.O_WRONLY | noFollow | (before ? 0 : fs.constants.O_CREAT | fs.constants.O_EXCL), 0o600);
+  try {
+    const stat = await handle.stat();
+    const pathname = await fsp.lstat(target);
+    if (!stat.isFile() || stat.nlink !== 1 || pathname.isSymbolicLink() || pathname.dev !== stat.dev || pathname.ino !== stat.ino
+      || (before && (before.dev !== stat.dev || before.ino !== stat.ino))) throw new Error('unsafe_observation_file');
+    await checkParents(identities);
+    await handle.chmod(0o600);
+    await handle.truncate(0);
+    await handle.writeFile(`${JSON.stringify(value)}\n`);
+    await checkParents(identities);
+    const after = await fsp.lstat(target);
+    if (after.isSymbolicLink() || after.dev !== stat.dev || after.ino !== stat.ino) throw new Error('observation_identity_changed');
+  } finally { await handle.close(); }
+}
+
+export async function inspectHookObservation(cwd: string, profile: string, entrypoint: string) {
+  try {
+    if (!['lite', 'study-note'].includes(profile)) throw new Error('unsupported_profile');
+    const { directory, identities } = await safeObservationDirectory(cwd, false);
+    const target = path.join(directory, `${profile}.json`);
+    const before = await fsp.lstat(target);
+    if (!before.isFile() || before.isSymbolicLink() || before.size > 4096 || before.nlink !== 1) throw new Error('unsafe_observation_file');
+    const handle = await fsp.open(target, fs.constants.O_RDONLY | (process.platform === 'win32' ? 0 : fs.constants.O_NOFOLLOW || 0));
+    let value;
+    try {
+      const stat = await handle.stat();
+      if (stat.dev !== before.dev || stat.ino !== before.ino || stat.size > 4096) throw new Error('observation_identity_changed');
+      const data = Buffer.alloc(4097); const { bytesRead } = await handle.read(data, 0, data.length, 0);
+      if (bytesRead > 4096) throw new Error('observation_limit');
+      value = JSON.parse(data.subarray(0, bytesRead).toString('utf8'));
+      await checkParents(identities);
+    } finally { await handle.close(); }
+    const age = Date.now() - Date.parse(value.observed_at);
+    if (value.schema !== 'yam.hook-observation.v1' || value.profile !== profile || !['UserPromptSubmit', 'Stop'].includes(value.event)
+      || value.host_authenticated !== false || value.evidence_kind !== 'local_entrypoint_invocation'
+      || !Number.isFinite(age) || age < 0 || age > 24 * 60 * 60 * 1000
+      || value.cwd_digest !== sha(await fsp.realpath(cwd)) || value.configuration_digest !== await configurationDigest(cwd)
+      || value.entrypoint_digest !== sha(await fsp.readFile(entrypoint, 'utf8'))) {
+      return { state: 'unknown', reason: 'stale_or_mismatched_observation', truth_status: 'partial', host_authenticated: false };
+    }
+    return { state: 'entrypoint_observed', observed_at: value.observed_at, event: value.event,
+      host_authenticated: false, truth_status: 'partial', reason: 'local_same_user_evidence_not_host_attestation' };
+  } catch (error) {
+    return { state: 'not_observed', reason: (error as NodeJS.ErrnoException).code === 'ENOENT' ? 'no_observation' : 'observation_unreadable_or_unsafe',
+      host_authenticated: false, truth_status: 'partial' };
+  }
+}

package/src/lib/memory-records.ts

@@ -0,0 +1,109 @@
+import fsp from 'node:fs/promises';
+import path from 'node:path';
+
+export type MemoryReadState = 'missing' | 'empty' | 'complete' | 'unreadable' | 'invalid' | 'incomplete';
+export interface MemoryRecord {
+  schemaVersion: number;
+  id: string;
+  kind: string;
+  status: string;
+  summary: string;
+  evidence?: string;
+  action?: string;
+  source?: string;
+  createdAt?: string;
+  [key: string]: unknown;
+}
+export interface MemoryReadReport {
+  schema: 'yam.memory-read.v1';
+  state: MemoryReadState;
+  complete: boolean;
+  records: MemoryRecord[];
+  diagnostics: Array<{ operation: string; code: string; record_index?: number }>;
+  diagnostics_truncated: boolean;
+}
+export type MemoryReadIo = Pick<typeof fsp, 'access' | 'readdir' | 'readFile'>;
+const kinds = new Set(['wrong_decision', 'repeat_mistake', 'direction_change', 'lesson', 'risk', 'command']);
+const safeCodes = new Set(['ENOENT', 'EACCES', 'EPERM', 'EIO', 'ENOTDIR', 'EISDIR', 'EMFILE', 'ENFILE', 'ELOOP']);
+
+function errorCode(error: unknown): string {
+  const code = (error as { code?: unknown })?.code;
+  return typeof code === 'string' && safeCodes.has(code) ? code : 'READ_FAILED';
+}
+
+function isMemoryRecord(value: unknown): value is MemoryRecord {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return false;
+  const r = value as Record<string, unknown>;
+  return r.schemaVersion === 1 && typeof r.id === 'string' && r.id.length > 0
+    && typeof r.kind === 'string' && kinds.has(r.kind)
+    && (r.status === 'active' || r.status === 'resolved')
+    && typeof r.summary === 'string' && r.summary.trim().length > 0
+    && ['evidence', 'action', 'source', 'createdAt', 'resolvedAt', 'resolution'].every((key) => r[key] === undefined || typeof r[key] === 'string');
+}
+
+/** Diagnostics intentionally contain no filesystem paths, record text, or exception messages. */
+export async function readMemoryDirectory(recordsDir: string, io: MemoryReadIo = fsp): Promise<MemoryReadReport> {
+  const report: MemoryReadReport = {
+    schema: 'yam.memory-read.v1', state: 'complete', complete: true,
+    records: [], diagnostics: [], diagnostics_truncated: false
+  };
+  const diagnose = (operation: string, code: string, record_index?: number) => {
+    if (report.diagnostics.length < 20) report.diagnostics.push({ operation, code, ...(record_index === undefined ? {} : { record_index }) });
+    else report.diagnostics_truncated = true;
+  };
+  try {
+    await io.access(recordsDir);
+  } catch (error) {
+    const code = errorCode(error);
+    report.state = code === 'ENOENT' ? 'missing' : 'unreadable';
+    report.complete = false;
+    diagnose('access', code);
+    return report;
+  }
+  let entries;
+  try {
+    entries = await io.readdir(recordsDir, { withFileTypes: true });
+  } catch (error) {
+    // An existing directory disappearing mid-read is incomplete, not an empty memory.
+    report.state = errorCode(error) === 'ENOENT' ? 'incomplete' : 'unreadable';
+    report.complete = false;
+    diagnose('readdir', errorCode(error));
+    return report;
+  }
+  let invalid = 0;
+  let unreadable = 0;
+  const candidates = entries.filter((entry) => entry.name.endsWith('.json')).sort((a, b) => a.name.localeCompare(b.name));
+  for (const [index, entry] of candidates.entries()) {
+    if (!entry.isFile()) {
+      unreadable += 1;
+      diagnose('record_type', 'NOT_REGULAR_FILE', index);
+      continue;
+    }
+    let text: string;
+    try {
+      text = await io.readFile(path.join(recordsDir, entry.name), 'utf8');
+    } catch (error) {
+      unreadable += 1;
+      diagnose('read', errorCode(error), index);
+      continue;
+    }
+    let record: unknown;
+    try { record = JSON.parse(text); } catch {
+      invalid += 1;
+      diagnose('parse', 'INVALID_JSON', index);
+      continue;
+    }
+    if (!isMemoryRecord(record)) {
+      invalid += 1;
+      diagnose('validate', 'INVALID_RECORD', index);
+      continue;
+    }
+    report.records.push(record);
+  }
+  report.records.sort((a, b) => String(a.createdAt || '').localeCompare(String(b.createdAt || '')));
+  report.complete = invalid + unreadable === 0;
+  report.state = report.complete ? (report.records.length ? 'complete' : 'empty')
+    : report.records.length || (invalid && unreadable) ? 'incomplete'
+      : unreadable ? 'unreadable' : 'invalid';
+  return report;
+}

package/src/lib/security-check.ts

@@ -0,0 +1,184 @@
+import { createHash, randomUUID } from 'node:crypto';
+import fsp from 'node:fs/promises';
+import fs from 'node:fs';
+import path from 'node:path';
+
+export const SECURITY_STATUSES = ['passed', 'needs_improvement', 'failed', 'unverified', 'not_applicable'] as const;
+export type SecurityStatus = typeof SECURITY_STATUSES[number];
+export type SecurityStage = 'commit' | 'push' | 'deploy';
+export const SEC_AREAS = {
+  'SEC-01': '사용자·관리자·외부 서비스·DB·파일 사이의 신뢰 경계와 보호할 데이터·작업을 식별한다.',
+  'SEC-02': '명시적으로 허용한 접근만 열고, 사용자·서비스 계정에 필요한 최소 권한만 부여한다.',
+  'SEC-03': '화면을 우회한 API·서버 함수·DB·파일·백그라운드 작업에서도 사용자·조직·대상별 권한을 확인한다.',
+  'SEC-04': '계정 정지·승인 철회·탈퇴·소속 변경 후 기존 세션·토큰·캐시에서도 권한 회수가 반영된다.',
+  'SEC-05': '코드의 보안 정책·migration·ACL·환경 설정이 대상 배포 환경의 실제 상태와 일치한다.',
+  'SEC-06': '로그인·관리자 인증·세션 만료·로그아웃·비밀번호 재설정·계정 복구가 계정 탈취를 막도록 동작한다.',
+  'SEC-07': '외부 입력·파일 업로드·출력의 형식·크기·경로를 검증하고 SQL 주입·XSS·SSRF·CSRF 등 해당 공격을 방어한다.',
+  'SEC-08': 'API 키·토큰·개인키·개인정보가 코드·브라우저 번들·로그·점검 기록에 불필요하게 노출되지 않는다.',
+  'SEC-09': '의존성·CI/CD 권한·배포 자격증명·릴리스 산출물의 출처와 무결성을 확인해 공급망 위험을 통제한다.'
+} as const;
+export const SECURITY_AREA_IDS = Object.keys(SEC_AREAS) as Array<keyof typeof SEC_AREAS>;
+export const STATUS_KO: Record<SecurityStatus, string> = {
+  passed: '점검 완료 - 이상 없음', needs_improvement: '점검 완료 - 보완 필요', failed: '점검 실패',
+  unverified: '미검증', not_applicable: '해당 없음'
+};
+
+export interface SecurityPolicy { version?: string; required_at?: Partial<Record<keyof typeof SEC_AREAS, SecurityStage[]>>; required?: string[]; digest?: string; }
+export interface SecurityBinding { stage: SecurityStage; [key: string]: unknown }
+export interface SecurityEvidence { reference: string; sha256: string; checker: string; checked_at: string; result?: string; }
+export interface SecurityAreaRecord { id: keyof typeof SEC_AREAS; explanation: string; status: SecurityStatus; required_at: SecurityStage[]; evidence?: SecurityEvidence[]; reason?: string; finding?: string; severity?: string; owner?: string; follow_up?: string; mitigation?: string; }
+export interface SecurityCheckInput { run_id?: string; time?: string; stage: SecurityStage; policy?: SecurityPolicy; policy_digest?: string; binding: SecurityBinding; environment: string; scope: string[]; checker: string; areas?: SecurityAreaRecord[]; evidence?: SecurityEvidence[]; retry_of?: string; }
+export interface SecurityCheckResult { schema: 'yam.security-check-result.v1'; run_id: string; time: string; stage: SecurityStage; policy: SecurityPolicy; policy_digest: string; binding: SecurityBinding; environment: string; scope: string[]; checker: string; areas: SecurityAreaRecord[]; result: 'PASS' | 'BLOCKED'; blocking: string[]; deferred: string[]; errors: string[]; digest: string; retry_of?: string; }
+
+const secretPatterns = [/https?:\/\/[^\s/]+:[^\s/]+@/i, /[?&](?:token|key|secret|password)=[^\s&]+/i, /\bgh[pousr]_[A-Za-z0-9]{20,}\b/i, /\bnpm_[A-Za-z0-9]{20,}\b/i, /\bsk-[A-Za-z0-9_-]{20,}\b/i, /\bAKIA[A-Z0-9]{16}\b/, /-----BEGIN (?:RSA |EC |OPENSSH )?PRIVATE KEY-----/, /(?:password|secret|token|api[_-]?key)\s*[:=]\s*[^\s,}]{8,}/i];
+const SHA256 = /^sha256:[a-f0-9]{64}$/;
+const unsafeText = (x: unknown): boolean => typeof x === 'string' && (/[\r\n\x00-\x1f\x7f<>]/.test(x) || x.length > 2048);
+const iso = (x: unknown) => typeof x === 'string' && !Number.isNaN(Date.parse(x));
+const obj = (x: unknown): x is Record<string, any> => !!x && typeof x === 'object' && !Array.isArray(x);
+const stable = (x: unknown): string => {
+  if (Array.isArray(x)) return `[${x.map(stable).join(',')}]`;
+  if (x && typeof x === 'object') return `{${Object.keys(x as Record<string, unknown>).filter(k => (x as Record<string, unknown>)[k] !== undefined).sort().map((k) => `${JSON.stringify(k)}:${stable((x as Record<string, unknown>)[k])}`).join(',')}}`;
+  return JSON.stringify(x);
+};
+const digest = (x: unknown) => `sha256:${createHash('sha256').update(stable(x)).digest('hex')}`;
+const clone = <T>(x: T): T => JSON.parse(JSON.stringify(x));
+const hasSecret = (x: unknown): boolean => secretPatterns.some((p) => p.test(typeof x === 'string' ? x : JSON.stringify(x)));
+
+export function createSecurityStarter(input: { stage: SecurityStage; policy?: SecurityPolicy; binding: SecurityBinding; environment: string; scope?: string[]; checker?: string; now?: Date; run_id?: string }): SecurityCheckInput {
+  const policy = clone(input.policy || { version: 'security-check-v1', required_at: {} });
+  const requiredAt = policy.required_at || {};
+  return { run_id: input.run_id || `security-${randomUUID()}`, time: (input.now || new Date()).toISOString(), stage: input.stage, policy, policy_digest: policy.digest || digest(policy), binding: clone(input.binding), environment: input.environment, scope: input.scope || [], checker: input.checker || 'yam-security-check', areas: SECURITY_AREA_IDS.map((id) => ({ id, explanation: SEC_AREAS[id], status: 'unverified', required_at: requiredAt[id] || [input.stage] })) };
+}
+
+function evidenceErrors(e: SecurityEvidence, index: number): string[] {
+  const out: string[] = [];
+  if (!obj(e)) return [`evidence_invalid:${index}`];
+  if (typeof e.reference !== 'string' || !e.reference.trim() || e.reference.includes('\0')) out.push(`evidence_reference_invalid:${index}`);
+  if (!SHA256.test(String(e.sha256 || ''))) out.push(`evidence_sha256_invalid:${index}`);
+  if (typeof e.checker !== 'string' || !e.checker.trim() || hasSecret(e.checker)) out.push(`evidence_checker_invalid:${index}`);
+  if (!iso(e.checked_at)) out.push(`evidence_time_invalid:${index}`);
+  if (Object.values(e).some(unsafeText)) out.push(`evidence_text_invalid:${index}`);
+  if (hasSecret(e)) out.push(`evidence_secret:${index}`);
+  return out;
+}
+
+export function validateSecurityCheck(input: unknown, expectedBinding?: SecurityBinding, expectedPolicy?: SecurityPolicy): SecurityCheckResult {
+  const errors: string[] = [];
+  const x = obj(input) ? input as SecurityCheckInput : {} as SecurityCheckInput;
+  const validRun = typeof x.run_id === 'string' && /^[A-Za-z0-9][A-Za-z0-9_-]{0,95}$/.test(x.run_id);
+  const runId = validRun ? x.run_id : `invalid-${randomUUID()}`;
+  if (!validRun) errors.push('run_id_invalid');
+  if (!['commit', 'push', 'deploy'].includes(x.stage)) errors.push('stage_invalid');
+  if (!iso(x.time)) errors.push('time_invalid');
+  if (!obj(x.binding)) errors.push('binding_missing');
+  if (x.binding?.stage !== x.stage) errors.push('binding_stage_mismatch');
+  if (x.stage === 'deploy' && x.environment !== x.binding?.environment) errors.push('environment_binding_mismatch');
+  if (Object.values(x).filter(v => typeof v === 'string').some(unsafeText)) errors.push('record_text_invalid');
+  if (expectedBinding && stable(x.binding) !== stable(expectedBinding)) errors.push('binding_mismatch');
+  if (typeof x.environment !== 'string' || !x.environment.trim()) errors.push('environment_invalid');
+  if (!Array.isArray(x.scope) || !x.scope.length || x.scope.some(v => typeof v !== 'string' || !v.trim() || unsafeText(v))) errors.push('scope_invalid');
+  if (typeof x.checker !== 'string' || !x.checker.trim()) errors.push('checker_invalid');
+  const policy = obj(x.policy) ? clone(x.policy) : { version: 'security-check-v1', required_at: {} };
+  const policyDigest = x.policy_digest || policy.digest || digest(policy);
+  if (expectedPolicy && stable(policy) !== stable(expectedPolicy)) errors.push('policy_mismatch');
+  if (typeof x.policy_digest === 'string' && !SHA256.test(x.policy_digest)) errors.push('policy_digest_invalid');
+  if (!Array.isArray(x.areas)) errors.push('areas_missing');
+  const supplied = Array.isArray(x.areas) ? x.areas : [];
+  const byId = new Map<string, SecurityAreaRecord>();
+  supplied.forEach((a, i) => { if (!obj(a) || !Object.prototype.hasOwnProperty.call(SEC_AREAS, a.id)) errors.push(`area_invalid:${i}`); else if (byId.has(a.id)) errors.push(`area_duplicate:${a.id}`); else byId.set(a.id, clone(a)); });
+  const requiredAt = (expectedPolicy || policy).required_at || {};
+  if (!policy.version || unsafeText(policy.version)) errors.push('policy_version_invalid');
+  for (const id of SECURITY_AREA_IDS) {
+    const stages = requiredAt[id];
+    if (!Array.isArray(stages) || !stages.length || stages.some(v => !['commit','push','deploy'].includes(v))) errors.push(`policy_requirement_invalid:${id}`);
+  }
+  for (const id of SECURITY_AREA_IDS) if (!byId.has(id)) errors.push(`area_missing:${id}`);
+  const areas = SECURITY_AREA_IDS.map((id) => {
+    const a = byId.get(id) || { id, explanation: SEC_AREAS[id], status: 'unverified' as const, required_at: requiredAt[id] || [x.stage] };
+    if (a.explanation !== SEC_AREAS[id]) errors.push(`explanation_mismatch:${id}`);
+    if (!SECURITY_STATUSES.includes(a.status)) errors.push(`status_invalid:${id}`);
+    const trustedRequired = Array.isArray(requiredAt[id]) && requiredAt[id].length ? requiredAt[id] : ['commit','push','deploy'] as SecurityStage[];
+    if (Object.values(a).filter(v => typeof v === 'string').some(unsafeText)) errors.push(`area_text_invalid:${id}`);
+    if (a.status === 'passed' && Array.isArray(a.evidence) && a.evidence.some(e => e?.result !== 'passed')) errors.push(`evidence_result_mismatch:${id}`);
+    if (a.status === 'passed' && (!Array.isArray(a.evidence) || !a.evidence.length)) errors.push(`evidence_missing:${id}`);
+    if (['SEC-01','SEC-08'].includes(id) && (a.status === 'not_applicable' || !trustedRequired.includes(x.stage))) errors.push(`mandatory_area_invalid:${id}`);
+    if (JSON.stringify(a.required_at) !== JSON.stringify(trustedRequired)) errors.push(`required_at_tampered:${id}`);
+    if (a.status === 'not_applicable' && (!a.reason || !a.reason.trim())) errors.push(`not_applicable_reason_missing:${id}`);
+    if (a.status === 'needs_improvement' && (!a.finding || !a.severity || !a.owner || !a.follow_up || !a.mitigation)) errors.push(`improvement_details_missing:${id}`);
+    if (a.status === 'failed' && (!a.finding || !a.severity || !a.owner || !a.follow_up || !a.mitigation || !a.evidence?.length)) errors.push(`failure_details_missing:${id}`);
+    if (a.evidence && !Array.isArray(a.evidence)) errors.push(`evidence_array_invalid:${id}`);
+    (Array.isArray(a.evidence) ? a.evidence : []).forEach((e, i) => errors.push(...evidenceErrors(e, i).map((z) => `${id}:${z}`)));
+    return { ...a, explanation: SEC_AREAS[id], required_at: trustedRequired };
+  });
+  if (areas.filter((a) => a.id === 'SEC-01').length !== 1 || areas.filter((a) => a.id === 'SEC-08').length !== 1) errors.push('mandatory_areas_missing');
+  if (hasSecret(x)) errors.push('record_contains_secret');
+  const blocking = areas.filter((a) => (a.required_at || []).includes(x.stage) && !['passed', 'not_applicable'].includes(a.status)).map((a) => `${a.id}:${a.status}`);
+  const allErrors = [...new Set(errors)];
+  const finalBlocking = [...new Set([...blocking, ...allErrors.map((e) => `contract:${e}`)])];
+  const result = finalBlocking.length ? 'BLOCKED' as const : 'PASS' as const;
+  const canonical = { schema: 'yam.security-check-result.v1' as const, retry_of: x.retry_of || 'none', run_id: runId, time: x.time, stage: x.stage, policy, policy_digest: policyDigest, binding: x.binding, environment: x.environment, scope: x.scope || [], checker: x.checker, areas, result, blocking: finalBlocking, deferred: areas.filter((a) => !(a.required_at || []).includes(x.stage) && a.status === 'unverified').map((a) => a.id), errors: allErrors };
+  return { ...canonical, digest: digest(canonical) };
+}
+
+function ensureSafePath(root: string, target: string): string {
+  const r = path.resolve(root); const t = path.resolve(target); if (t !== r && !t.startsWith(`${r}${path.sep}`)) throw new Error('path_outside_root'); return t;
+}
+async function noSymlinkComponents(root: string, target: string) {
+  const rel = path.relative(root, target); let cur = root;
+  for (const part of rel.split(path.sep).filter(Boolean)) { cur = path.join(cur, part); try { if ((await fsp.lstat(cur)).isSymbolicLink()) throw new Error('symlink_path_rejected'); } catch (e: any) { if (e.code !== 'ENOENT') throw e; } }
+}
+async function withLock(lock: string, fn: () => Promise<void>) { for (let i = 0; i < 50; i++) { try { await fsp.mkdir(lock); break; } catch (e: any) { if (e.code !== 'EEXIST') throw e; await new Promise((r) => setTimeout(r, 10)); } if (i === 49) throw new Error('security_note_lock_timeout'); } try { await fn(); } finally { await fsp.rm(lock, { recursive: true, force: true }); } }
+
+export async function persistSecurityCheck(dir: string, input: SecurityCheckInput, result?: SecurityCheckResult, options: { notePath?: string } = {}) {
+  const root = await fsp.realpath(dir);
+  let checked = validateSecurityCheck(input);
+  // Integration may only add blocking findings; it cannot promote a failed contract.
+  if (result?.result === 'BLOCKED') {
+    checked = { ...checked, result: 'BLOCKED', errors: [...new Set([...checked.errors, ...result.errors])], blocking: [...new Set([...checked.blocking, ...result.blocking])] };
+  }
+  if (hasSecret(checked) || checked.errors.some(e => /text_invalid|secret/.test(e))) {
+    const sanitized = createSecurityStarter({ stage: ['commit','push','deploy'].includes(input?.stage) ? input.stage : 'commit', binding: { stage: input?.stage || 'commit', withheld: true }, environment: 'withheld', scope: ['unsafe input omitted'], checker: 'yam-security-check' });
+    checked = validateSecurityCheck(sanitized);
+    checked.errors.push('unsafe_input_redacted'); checked.blocking.push('contract:unsafe_input_redacted');
+  }
+  checked.digest = digest({ ...checked, digest: undefined });
+  const base = ensureSafePath(root, path.join(root, '.yam', 'security'));
+  await noSymlinkComponents(root, base);
+  await fsp.mkdir(base, { recursive: true, mode: 0o700 });
+  const runs = ensureSafePath(root, path.join(base, 'runs'));
+  const originalRoot = path.resolve(dir);
+  const requestedNote = options.notePath ? path.resolve(originalRoot, options.notePath) : path.join(originalRoot, '.yam', 'security', 'notes.md');
+  ensureSafePath(originalRoot, requestedNote);
+  const note = ensureSafePath(root, path.resolve(root, path.relative(originalRoot, requestedNote)));
+  const lock = path.join(base, '.lock');
+  await noSymlinkComponents(root, note);
+  await noSymlinkComponents(root, runs);
+  let runPath = '';
+  await withLock(lock, async () => {
+    await noSymlinkComponents(root, note);
+    await fsp.mkdir(path.dirname(note), { recursive: true, mode: 0o700 });
+    await fsp.mkdir(runs, { recursive: true, mode: 0o700 });
+    runPath = ensureSafePath(runs, path.join(runs, `${checked.run_id}.json`));
+    await noSymlinkComponents(root, runPath);
+    try { await fsp.lstat(runPath); throw new Error('security_run_exists'); } catch (e: any) { if (e.code !== 'ENOENT') throw e; }
+    const handle = await fsp.open(note, fs.constants.O_WRONLY | fs.constants.O_APPEND | fs.constants.O_CREAT | fs.constants.O_NOFOLLOW, 0o600);
+    try {
+      const info = await handle.stat(); if (!info.isFile() || info.nlink !== 1) throw new Error('unsafe_note_file');
+      await fsp.writeFile(runPath, JSON.stringify(checked, null, 2) + '\n', { encoding: 'utf8', mode: 0o600, flag: 'wx' });
+      await handle.writeFile(renderSecurityNote(checked), 'utf8'); await handle.sync();
+    } finally { await handle.close(); }
+  });
+  return { run_path: path.relative(root, runPath), note_path: path.relative(root, note), result: checked };
+}
+
+export function renderSecurityNote(result: SecurityCheckResult): string {
+  const clean = (x: unknown) => String(x ?? '').replace(/[\r\n\x00-\x1f\x7f]/g, ' ');
+  const lines = ['-- Security check --', '', 'Contract: security-check-v1', `Run: ${clean(result.run_id)}; Time: ${clean(result.time)}`, `Stage: ${result.stage}; Policy: ${clean(result.policy_digest)}`, `Environment: ${clean(result.environment)}`, `Binding: ${clean(JSON.stringify(result.binding))}`, `Scope: ${result.scope.map(clean).join(', ')}`, `Checker: ${clean(result.checker)}`, ''];
+  result.areas.forEach((a, i) => {
+    lines.push(`${i + 1}. ${a.id} : "${SEC_AREAS[a.id]}" : ${STATUS_KO[a.status] || '미검증'}`);
+    lines.push(`   - Required at: ${a.required_at.join(', ')}`);
+    if (Array.isArray(a.evidence) && a.evidence.length) lines.push(`   - Evidence: ${a.evidence.map(e => `${clean(e.reference)} (${clean(e.sha256)}) by ${clean(e.checker)} at ${clean(e.checked_at)}`).join('; ')}`);
+    for (const field of ['reason','finding','severity','owner','follow_up','mitigation'] as const) if (a[field]) lines.push(`   - ${field}: ${clean(a[field])}`);
+  });
+  lines.push('', `Retry of: ${clean(result.retry_of || 'none')}`, `Result: ${result.result}`, `Blocking: ${result.blocking.map(clean).join(', ') || 'none'}`, `Deferred: ${result.deferred.join(', ') || 'none'}`, '-- End Security check --', ''); return lines.join('\n');
+}