yam-flow 2.8.0 → 2.8.1

package/skills/mission/SKILL.md

@@ -120,6 +120,10 @@ Good mission prompts include:
 
 If the user invokes `$mission` without an approved plan, ask for the plan or propose a compact plan first.
 
+## Commit, push and deployment security gate
+
+Before performing a requested commit, push or deployment, follow `references/security-check.md`: validate stage-bound evidence with `yam security check`, require a successful persisted Security check note, and stop the operation when the gate blocks. If the project is not configured, report that blocker rather than claim security approval. Do not overwrite existing hooks or treat supplied evidence as an automatic vulnerability scan.
+
 ## Final Response
 
 Report:

package/skills/quick/SKILL.md

@@ -74,6 +74,10 @@ Use `references/study-note.md` when any code, config, docs, or project artifact
 Use `references/final-report.md` to close with remaining tasks and fix-first items when useful.
 Use `references/token-budget-reporter.md` when a run needs measured budget feedback.
 
+## Commit, push and deployment security gate
+
+Before performing a requested commit, push or deployment, follow `references/security-check.md`: validate stage-bound evidence with `yam security check`, require a successful persisted Security check note, and stop the operation when the gate blocks. If the project is not configured, report that blocker rather than claim security approval. Do not overwrite existing hooks or treat supplied evidence as an automatic vulnerability scan.
+
 ## Final Response
 
 Keep it compact:

package/skills/ueye/SKILL.md

@@ -182,6 +182,10 @@ Always consider:
 - Interaction affordance.
 - Consistency with the project's visual language.
 
+## Commit, push and deployment security gate
+
+Before performing a requested commit, push or deployment, follow `references/security-check.md`: validate stage-bound evidence with `yam security check`, require a successful persisted Security check note, and stop the operation when the gate blocks. If the project is not configured, report that blocker rather than claim security approval. Do not overwrite existing hooks or treat supplied evidence as an automatic vulnerability scan.
+
 ## Final Response
 
 Report:

package/src/bin/yam.ts

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 import { spawnSync } from 'node:child_process';
+import { runSecurityCommand } from '../lib/security-integration.js';
 import { createHash } from 'node:crypto';
 import fs from 'node:fs';
 import fsp from 'node:fs/promises';
@@ -224,6 +225,7 @@ Usage:
   yam proof [dir|--from file] [--route route] [--truth status] [--command text] [--evidence text]
   yam proof write [dir] [--format json|md] [--out file] [--route route] [--truth status] [--command text]
   yam study-note check [dir] [--report file|--text text] [--json]
+  yam security <init|check|hooks|status> [--stage commit|push|ci|deploy] [--json]
   yam next-step <report|verify> [--spec file|--receipt file] [--json]
   yam loop report [--route route] [--intent text] [--stage id:status:note] [--evidence text] [--json]
   yam scout receipt <create|verify> [options]
@@ -249,7 +251,7 @@ Usage:
   yam safety [text...]
   yam memory <init|add|list|summary|resolve> [dir] [options]
   yam hook <status|enable|disable|run> [lite|study-note] [--global|--project dir]
-  yam template <project|ueye|mission|proof|tuning>
+  yam template <project|ueye|mission|proof|tuning|security|security-ci>
   yam tune-log [dir]
   yam install [--dry-run] [--json] [--replace-user-skill name]
   yam uninstall
@@ -570,6 +572,7 @@ async function verify({ quiet = false } = {}) {
     'context-reuse.md',
     'markdown-management.md',
     'study-note.md',
+    'security-check.md',
     'final-report.md',
     'token-budget-reporter.md',
     'memory.md'
@@ -585,7 +588,7 @@ async function verify({ quiet = false } = {}) {
       if (!hasHeading(projectTemplate, section)) issues.push(`project template missing section: ${section}`);
     }
   }
-  for (const template of ['ueye-review.md', 'ueye-comparison.md', 'mission-plan.md', 'runtime-proof.md', 'tuning-log.md']) {
+  for (const template of ['ueye-review.md', 'ueye-comparison.md', 'mission-plan.md', 'runtime-proof.md', 'tuning-log.md', 'security-check-note.md', 'security-gate.yml']) {
     if (!await exists(path.join(ROOT, 'templates', template))) issues.push(`missing template: ${template}`);
   }
   for (const module of ['trust-kernel.js', 'ueye-artifacts.js']) {
@@ -6069,11 +6072,13 @@ async function printTemplate(name = '') {
     mission: 'mission-plan.md',
     proof: 'runtime-proof.md',
     runtime: 'runtime-proof.md',
-    tuning: 'tuning-log.md'
+    tuning: 'tuning-log.md',
+    security: 'security-check-note.md',
+    'security-ci': 'security-gate.yml'
   };
   const file = map[key];
   if (!file) {
-    console.error('usage: yam template <project|ueye|ueye-comparison|mission|proof|tuning>');
+    console.error('usage: yam template <project|ueye|ueye-comparison|mission|proof|tuning|security|security-ci>');
     process.exitCode = 1;
     return;
   }
@@ -6349,6 +6354,7 @@ function showRequestedHelp(args: string[]) {
   }
 
   const commandUsage: Record<string, () => void> = {
+    security: () => console.log('yam security <init|check|hooks enable|status> [--stage commit|push|ci|deploy] [--policy file --policy-digest sha256 --evidence file --note file]\nSee references/security-check.md for exact bindings and CI/deploy trust configuration.'),
     context: contextUsage,
     cleanup: cleanupUsage,
     'study-note': studyNoteUsage,
@@ -6375,6 +6381,16 @@ async function main() {
   const command = args[0] || 'help';
   if (showRequestedHelp(args)) return;
   if (command === 'help') return usage();
+  if (command === 'security') {
+    if (args.length === 1 || ['help', '--help', '-h'].includes(args[1])) {
+      console.log('yam security <init|check|hooks enable|status> [--stage commit|push|ci|deploy] [--policy file --policy-digest sha256 --evidence file --note file]\nSee references/security-check.md for exact bindings and CI/deploy trust configuration.');
+      return;
+    }
+    const result = await runSecurityCommand(args.slice(1), { cwd: process.cwd(), cliPath: fileURLToPath(import.meta.url) });
+    console.log(JSON.stringify(result, null, 2));
+    if (!result.ok) process.exitCode = 1;
+    return;
+  }
   if (command === 'install') return install(args.slice(1));
   if (command === 'uninstall') return uninstall(args.slice(1));
   if (command === 'version') return console.log(VERSION);

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');
+}

package/src/lib/security-integration.ts

@@ -0,0 +1,299 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { execFileSync } from 'node:child_process';
+import fs from 'node:fs/promises';
+import { constants, readFileSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { createSecurityStarter, validateSecurityCheck, persistSecurityCheck, SECURITY_AREA_IDS } from './security-check.js';
+import type { SecurityCheckInput, SecurityPolicy, SecurityCheckResult } from './security-check.js';
+
+const OID = /^(?:[a-f0-9]{40}|[a-f0-9]{64})$/;
+const DIGEST = /^sha256:[a-f0-9]{64}$/;
+const ZERO = /^0+$/;
+export type SecurityBinding = Record<string, unknown>;
+export interface SecurityCommandOptions { cwd?: string; cliPath?: string; stdin?: string }
+const hash = (text: string | Buffer) => `sha256:${createHash('sha256').update(text).digest('hex')}`;
+function git(cwd: string, args: string[]): string {
+  try { return execFileSync('git', ['-C', cwd, ...args], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], maxBuffer: 8 * 1024 * 1024 }).trim(); }
+  catch { throw new Error('git binding inspection failed'); }
+}
+function revision(cwd: string, ref: string): string {
+  if (!OID.test(ref)) throw new Error('revision must be an exact Git object ID');
+  const result = git(cwd, ['rev-parse', '--verify', `${ref}^{commit}`]);
+  if (!OID.test(result)) throw new Error('invalid source commit');
+  return result;
+}
+function parseArgs(args: string[]): Map<string, string> {
+  const out = new Map<string, string>();
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === '--json') continue;
+    if (!['--policy', '--policy-digest', '--evidence', '--note', '--stage', '--remote', '--destination', '--source', '--base', '--artifact', '--artifact-digest', '--configuration', '--configuration-digest', '--environment', '--cli'].includes(args[i]) || !args[i + 1] || args[i + 1].startsWith('--') || out.has(args[i])) throw new Error('invalid or duplicate security option');
+    out.set(args[i], args[++i]);
+  }
+  return out;
+}
+export function collectSecurityBinding(cwd: string, stage: string, options: Map<string, string>, stdin = ''): SecurityBinding {
+  if (stage === 'commit') {
+    let base: string;
+    try { base = git(cwd, ['rev-parse', '--verify', 'HEAD']); }
+    catch { base = execFileSync('git', ['-C', cwd, 'hash-object', '-t', 'tree', '--stdin'], { input: '', encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] }).trim(); }
+    return { stage, staged_tree: git(cwd, ['write-tree']), base_revision: base };
+  }
+  if (stage === 'push') {
+    const remote = options.get('--remote');
+    if (!remote || /[\r\n\0]/.test(remote)) throw new Error('push requires remote identity');
+    const destination = options.get('--destination');
+    if (!destination || /[\r\n\0]/.test(destination)) throw new Error('push requires actual Git hook destination');
+    const lines = stdin.trim().split('\n').filter(Boolean);
+    if (!lines.length || lines.length > 256) throw new Error('push requires exact outgoing refs from hook stdin');
+    const push_refs = lines.map(line => {
+      const fields = line.trim().split(/\s+/);
+      if (fields.length !== 4 || !OID.test(fields[1]) || !OID.test(fields[3]) || ZERO.test(fields[1]) || !(fields[0] === 'HEAD' || fields[0].startsWith('refs/')) || !fields[2].startsWith('refs/')) throw new Error('invalid push ref or deletion; deletion requires separate reviewed handling');
+      revision(cwd, fields[1]);
+      return { local_ref: fields[0], local_oid: fields[1], remote_ref: fields[2], remote_oid: fields[3] };
+    });
+    if (new Set(push_refs.map(r => r.remote_ref)).size !== push_refs.length) throw new Error('duplicate outgoing destination ref');
+    return { stage, destination_digest: hash(destination), push_refs };
+  }
+  if (stage === 'ci') {
+    const source = revision(cwd, options.get('--source') || '');
+    const base = revision(cwd, options.get('--base') || '');
+    return { stage: 'push', context: 'ci', source_revision: source, base_revision: base, tree: git(cwd, ['rev-parse', `${source}^{tree}`]) };
+  }
+  if (stage === 'deploy') {
+    const source = revision(cwd, options.get('--source') || '');
+    const artifact = options.get('--artifact-digest') || '';
+    const configuration = options.get('--configuration-digest') || '';
+    const environment = options.get('--environment') || '';
+    if (!DIGEST.test(artifact) || !DIGEST.test(configuration) || !/^[A-Za-z0-9][A-Za-z0-9._-]{0,95}$/.test(environment)) throw new Error('deploy requires exact artifact/configuration SHA256 and environment');
+    return { stage, source_revision: source, artifact_digest: artifact, configuration_digest: configuration, environment };
+  }
+  throw new Error('stage must be commit, push, ci or deploy');
+}
+async function readSafe(file: string): Promise<string> {
+  await safeParents(file);
+  const handle = await fs.open(file, constants.O_RDONLY | constants.O_NOFOLLOW);
+  try {
+    const info = await handle.stat();
+    if (!info.isFile() || info.size > 1024 * 1024) throw new Error('invalid security file');
+    return await handle.readFile('utf8');
+  } finally { await handle.close(); }
+}
+function quote(value: string): string { return `'${value.replace(/'/g, `'\\''`)}'`; }
+async function exclusive(file: string, text: string, mode = 0o600): Promise<void> {
+  await safeParents(file);
+  const handle = await fs.open(file, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, mode);
+  try { await handle.writeFile(text, 'utf8'); await handle.sync(); } finally { await handle.close(); }
+}
+async function gitMetadata(cwd: string): Promise<{ root: string; directory: string; hooks: string; config: string }> {
+  const root = git(cwd, ['rev-parse', '--show-toplevel']);
+  const directory = path.resolve(cwd, git(cwd, ['rev-parse', '--git-dir']));
+  const hookOverride = (() => { try { return git(cwd, ['config', '--get', 'core.hooksPath']); } catch { return ''; } })();
+  if (hookOverride) throw new Error('custom hooksPath requires explicit manual integration');
+  return { root, directory, hooks: path.join(directory, 'hooks'), config: path.join(directory, 'yam-security.json') };
+}
+async function enableHooks(cwd: string, options: Map<string, string>, cliPath?: string): Promise<Record<string, unknown>> {
+  if (process.platform === 'win32') throw new Error('automatic hook setup requires a POSIX Git shell; integrate manually on Windows');
+  const metadata = await gitMetadata(cwd);
+  const settings = JSON.parse(await readSafe(metadata.config));
+  if (settings.schema !== 'yam.security-install.v1' || !DIGEST.test(settings.policy_digest)) throw new Error('security init required before hooks enable');
+  const cli = await fs.realpath(cliPath || options.get('--cli') || fileURLToPath(new URL('../bin/yam.js', import.meta.url)));
+  const node = await fs.realpath(process.execPath);
+  if (!(await fs.stat(cli)).isFile()) throw new Error('built CLI path required');
+  const files = ['pre-commit', 'pre-push'].map(name => path.join(metadata.hooks, name));
+  for (const file of files) {
+    try { await fs.lstat(file); throw new Error('existing Git hooks preserved; use manual integration'); }
+    catch (error) { if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error; }
+  }
+  await fs.mkdir(metadata.hooks, { recursive: true });
+  const common = `${quote(node)} ${quote(cli)} security check --policy ${quote(settings.policy)} --policy-digest ${quote(settings.policy_digest)} --evidence ${quote(settings.evidence)} --note ${quote(settings.note)}`;
+  const created: string[] = [];
+  try {
+    for (const [index, file] of files.entries()) {
+      const stage = index === 0 ? 'commit' : 'push';
+      const remote = index === 1 ? ' --remote "$1" --destination "$2"' : '';
+      await exclusive(file, `#!/bin/sh\n# yam.security-hook.v1\nexec ${common} --stage ${stage}${remote}\n`, 0o700);
+      created.push(file);
+    }
+  } catch (error) { for (const file of created) await fs.unlink(file); throw error; }
+  return { ok: true, result: 'ENABLED', hooks: ['pre-commit', 'pre-push'], enforcement: 'local_bypassable', ci_required: true };
+}
+async function safeParents(file: string): Promise<void> {
+  let current = path.dirname(path.resolve(file));
+  while (current !== path.dirname(current)) {
+    try { const info = await fs.lstat(current); if (info.isSymbolicLink() || !info.isDirectory()) throw new Error('unsafe security file parent'); }
+    catch (error) { if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error; }
+    current = path.dirname(current);
+  }
+}
+async function initialize(cwd: string, options: Map<string, string>): Promise<Record<string, unknown>> {
+  const metadata = await gitMetadata(cwd);
+  const base = path.join(metadata.root, '.yam', 'security');
+  const policyPath = path.resolve(metadata.root, options.get('--policy') || '.yam/security/policy.json');
+  const evidencePath = path.resolve(metadata.root, options.get('--evidence') || '.yam/security/check.json');
+  const notePath = path.resolve(metadata.root, options.get('--note') || '.yam/security/notes.md');
+  for (const target of [policyPath, evidencePath, notePath]) {
+    if (!target.startsWith(metadata.root + path.sep)) throw new Error('init files must be inside repository');
+    await safeParents(target);
+  }
+  // All areas have explicit trusted requirements; live environment inspection is deferred to deploy.
+  const policy: SecurityPolicy = { version: 'security-check-v1', required_at: Object.fromEntries(SECURITY_AREA_IDS.map(id => [id, id === 'SEC-05' ? ['deploy'] : ['commit', 'push', 'deploy']])) };
+  const policyText = JSON.stringify(policy, null, 2) + '\n';
+  const binding = collectSecurityBinding(metadata.root, 'commit', options);
+  const starter = createSecurityStarter({ stage: 'commit', policy, binding: binding as any, environment: 'local', scope: ['initial project security assessment'], checker: 'operator-review-required' });
+  starter.policy_digest = hash(policyText);
+  const files = [policyPath, evidencePath, metadata.config];
+  for (const file of files) {
+    try { await fs.lstat(file); throw new Error('security init preserves existing files'); }
+    catch (error) { if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error; }
+  }
+  await safeParents(path.join(base, 'placeholder'));
+  await fs.mkdir(base, { recursive: true });
+  const created: string[] = [];
+  try {
+    for (const [file, content] of [
+      [policyPath, policyText], [evidencePath, JSON.stringify(starter, null, 2) + '\n'],
+      [metadata.config, JSON.stringify({ schema: 'yam.security-install.v1', policy: policyPath, policy_digest: hash(policyText), evidence: evidencePath, note: notePath }, null, 2) + '\n']
+    ]) { await exclusive(file, content); created.push(file); }
+  } catch (error) { for (const file of created) await fs.unlink(file); throw error; }
+  return { ok: true, result: 'INITIALIZED', policy_digest: hash(policyText), evidence: path.relative(metadata.root, evidencePath), hooks_installed: false, evidence_boundary: 'operator_supplied_not_automatic_security_scan' };
+}
+async function verifyReferencedEvidence(cwd: string, input: SecurityCheckInput): Promise<string[]> {
+  const errors: string[] = [];
+  for (const area of input.areas || []) {
+    if (!SECURITY_AREA_IDS.includes(area.id)) { errors.push('invalid_evidence_area'); continue; }
+    if (area.status === 'passed' && !area.evidence?.length) errors.push(`evidence_missing:${area.id}`);
+    for (const evidence of area.evidence || []) {
+      if (typeof evidence.reference !== 'string' || !evidence.reference || path.isAbsolute(evidence.reference) || /^[a-z]+:/i.test(evidence.reference)) { errors.push(`evidence_reference_invalid:${area.id}`); continue; }
+      const file = path.resolve(cwd, evidence.reference);
+      if (!file.startsWith(path.resolve(cwd) + path.sep)) { errors.push(`evidence_outside_repository:${area.id}`); continue; }
+      try { if (await digestFile(file, 16 * 1024 * 1024) !== evidence.sha256) errors.push(`evidence_digest_mismatch:${area.id}`); }
+      catch { errors.push(`evidence_unavailable:${area.id}`); }
+    }
+  }
+  return errors;
+}
+export async function runSecurityCommand(args: string[], settings: SecurityCommandOptions = {}): Promise<Record<string, unknown>> {
+  const cwd = await fs.realpath(path.resolve(settings.cwd || process.cwd()));
+  const subcommand = args[0];
+  try {
+    if (subcommand === 'hooks') {
+      if (args[1] !== 'enable') throw new Error('supported hook operation: enable');
+      return await enableHooks(cwd, parseArgs(args.slice(2)), settings.cliPath);
+    }
+    const options = parseArgs(args.slice(1));
+    if (subcommand === 'init') return await initialize(cwd, options);
+    if (subcommand === 'status') {
+      const metadata = await gitMetadata(cwd);
+      let configured = false;
+      try { const config = JSON.parse(await readSafe(metadata.config)); configured = config.schema === 'yam.security-install.v1'; } catch { /* unavailable is reported */ }
+      const installed: string[] = [];
+      for (const name of ['pre-commit', 'pre-push']) {
+        try { if ((await readSafe(path.join(metadata.hooks, name))).includes('# yam.security-hook.v1')) installed.push(name); } catch { /* unavailable is reported */ }
+      }
+      return { ok: true, configured, local_hooks: installed, local_hooks_bypassable: true, remote_enforcement: 'not_measured', evidence_boundary: 'operator_supplied_not_automatic_security_scan' };
+    }
+    if (subcommand !== 'check') throw new Error('supported commands: init, check, hooks enable, status');
+    return await check(cwd, options, settings);
+  } catch {
+    if (subcommand === 'check') {
+      const input = createSecurityStarter({ stage: 'commit', binding: { stage: 'commit', invalid_binding: true }, environment: 'local', scope: ['rejected security command'], checker: 'yam-security-check' });
+      const result = validateSecurityCheck(input);
+      result.errors.push('security_command_failed'); result.blocking.push('integration:security_command_failed'); result.result = 'BLOCKED';
+      try { const persisted = await persistSecurityCheck(cwd, input, result); return { ok: false, ...persisted, evidence_boundary: 'operator_supplied_not_automatic_security_scan' }; }
+      catch { return { ok: false, result: 'BLOCKED', errors: ['security_command_failed', 'security_note_persistence_failed'] }; }
+    }
+    return { ok: false, result: 'BLOCKED', errors: ['security_command_failed'], evidence_boundary: 'operator_supplied_not_automatic_security_scan' };
+  }
+}
+async function check(cwd: string, options: Map<string, string>, settings: SecurityCommandOptions): Promise<Record<string, unknown>> {
+  const stage = options.get('--stage') || 'commit';
+  const normalizedStage = stage === 'ci' ? 'push' : stage;
+  let config: any = {};
+  try { const metadata = await gitMetadata(cwd); config = JSON.parse(await readSafe(metadata.config)); } catch { /* an explicit trust pin can be provided instead */ }
+  const notePath = path.resolve(cwd, options.get('--note') || config.note || '.yam/security/notes.md');
+  let input: SecurityCheckInput;
+  let binding: SecurityBinding = { stage: normalizedStage, invalid_binding: true };
+  let policy: SecurityPolicy = { version: 'security-check-v1', required_at: Object.fromEntries(SECURITY_AREA_IDS.map(id => [id, ['commit', 'push', 'deploy']])) };
+  let result: SecurityCheckResult;
+  const gateErrors: string[] = [];
+  try {
+    const policyFile = path.resolve(cwd, options.get('--policy') || config.policy || '.yam/security/policy.json');
+    const pin = options.get('--policy-digest') || ((stage !== 'ci' && stage !== 'deploy') ? config.policy_digest : undefined);
+    if (!pin || !DIGEST.test(pin)) throw new Error('policy_pin_missing');
+    const policyText = await readSafe(policyFile);
+    if (hash(policyText) !== pin) throw new Error('policy_pin_mismatch');
+    policy = JSON.parse(policyText);
+    if (!policy || typeof policy.version !== 'string' || !/^[a-zA-Z0-9][a-zA-Z0-9._-]{0,63}$/.test(policy.version) || Object.keys(policy).some(key => !['version', 'required_at'].includes(key)) || !policy.required_at || Object.keys(policy.required_at).some(key => !SECURITY_AREA_IDS.includes(key as any)) || SECURITY_AREA_IDS.some(id => !Array.isArray(policy.required_at[id]))) throw new Error('policy_invalid');
+    for (const id of ['SEC-01', 'SEC-08'] as const) if (!['commit', 'push', 'deploy'].every(s => policy.required_at![id]!.includes(s as any))) throw new Error('mandatory_policy_invalid');
+    for (const id of SECURITY_AREA_IDS) if (!policy.required_at[id].length || policy.required_at[id].some(s => !['commit', 'push', 'deploy'].includes(s))) throw new Error('policy_stage_invalid');
+    const stdin = stage === 'push' ? (settings.stdin ?? await readSafeStdin()) : '';
+    if (stage === 'deploy') {
+      for (const [fileOption, digestOption] of [['--artifact', '--artifact-digest'], ['--configuration', '--configuration-digest']]) {
+        const file = options.get(fileOption);
+        if (!file || await digestFile(path.resolve(cwd, file), 1024 * 1024 * 1024) !== options.get(digestOption)) throw new Error('deployment_file_digest_mismatch');
+      }
+    }
+    binding = collectSecurityBinding(cwd, stage, options, stdin);
+    const evidenceText = await readSafe(path.resolve(cwd, options.get('--evidence') || config.evidence || '.yam/security/check.json'));
+    input = JSON.parse(evidenceText);
+    if (input.policy_digest !== pin) gateErrors.push('policy_digest_mismatch');
+    if (input.stage !== normalizedStage) gateErrors.push('stage_mismatch');
+    if (SECURITY_AREA_IDS.some(id => !input.areas?.some(area => area.id === id))) gateErrors.push('area_coverage_missing');
+    if (input.areas?.some(area => ['SEC-01', 'SEC-08'].includes(area.id) && area.status === 'not_applicable')) gateErrors.push('mandatory_area_not_applicable');
+    gateErrors.push(...await verifyReferencedEvidence(cwd, input));
+    input = { ...input, retry_of: input.run_id, run_id: `security-${randomUUID()}`, time: new Date().toISOString() };
+    result = validateSecurityCheck(input, binding as any, policy);
+    if (result.errors.includes('record_contains_secret')) {
+      input = createSecurityStarter({ stage: normalizedStage as any, binding: binding as any, environment: 'redacted', scope: ['unsafe supplied record rejected'], checker: 'yam-security-check' });
+      result = validateSecurityCheck(input, binding as any);
+      gateErrors.push('unsafe_security_record_rejected');
+    }
+    // Inspect the index/refs once more before persisting so mid-check changes cannot retain PASS.
+    const fresh = collectSecurityBinding(cwd, stage, options, stdin);
+    if (JSON.stringify(fresh) !== JSON.stringify(binding)) gateErrors.push('binding_changed_during_check');
+    if (stage === 'deploy') {
+      for (const [fileOption, digestOption] of [['--artifact', '--artifact-digest'], ['--configuration', '--configuration-digest']]) {
+        if (await digestFile(path.resolve(cwd, options.get(fileOption)!), 1024 * 1024 * 1024) !== options.get(digestOption)) gateErrors.push('deployment_file_changed_during_check');
+      }
+    }
+  } catch {
+    input = createSecurityStarter({ stage: normalizedStage as any, binding: binding as any, environment: stage === 'deploy' ? options.get('--environment') || 'unavailable' : 'local', scope: ['security gate unavailable'], checker: 'yam-security-check' });
+    result = validateSecurityCheck(input, binding as any);
+    gateErrors.push('security_input_or_binding_unavailable');
+  }
+  if (gateErrors.length) {
+    result.result = 'BLOCKED';
+    result.errors = [...new Set([...result.errors, ...gateErrors])];
+    result.blocking = [...new Set([...result.blocking, ...gateErrors.map(e => `integration:${e}`)])];
+  }
+  try {
+    const persisted = await persistSecurityCheck(cwd, input, result, { notePath });
+    return { ok: persisted.result.result === 'PASS', ...persisted, evidence_boundary: 'operator_supplied_not_automatic_security_scan' };
+  } catch { return { ok: false, result: 'BLOCKED', errors: ['security_note_persistence_failed'], evidence_boundary: 'operator_supplied_not_automatic_security_scan' }; }
+}
+async function readSafeStdin(): Promise<string> {
+  const text = readFileSync(0, 'utf8');
+  if (text.length > 128 * 1024) throw new Error('push_ref_input_too_large');
+  return text;
+}
+
+async function digestFile(file: string, limit: number): Promise<string> {
+  await safeParents(file);
+  const handle = await fs.open(file, constants.O_RDONLY | constants.O_NOFOLLOW);
+  try {
+    const info = await handle.stat();
+    if (!info.isFile() || info.size > limit) throw new Error('invalid digest target');
+    const digest = createHash('sha256');
+    const buffer = Buffer.alloc(64 * 1024);
+    let position = 0;
+    while (position < info.size) {
+      const { bytesRead } = await handle.read(buffer, 0, Math.min(buffer.length, info.size - position), position);
+      if (!bytesRead) throw new Error('digest target changed during read');
+      digest.update(buffer.subarray(0, bytesRead)); position += bytesRead;
+    }
+    const after = await handle.stat();
+    if (after.size !== info.size || after.mtimeMs !== info.mtimeMs || after.ctimeMs !== info.ctimeMs) throw new Error('digest target changed during read');
+    return `sha256:${digest.digest('hex')}`;
+  } finally { await handle.close(); }
+}