@itenl/sec 0.0.0-stage → 0.1.0

package/bin/sec.mjs

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+import { main } from '../lib/cli.mjs';
+
+main()
+  .then((code) => {
+    process.exitCode = code;
+  })
+  .catch((error) => {
+    // External command errors can contain captured credentials or source text.
+    const message =
+      error.code || error instanceof SyntaxError || error.message?.startsWith('Command failed')
+        ? 'Operation failed. Run sec doctor and inspect private diagnostics.'
+        : error.message;
+    console.error(`sec: ${message}`);
+    process.exitCode = 2;
+  });

package/lib/aliases.mjs

@@ -0,0 +1,46 @@
+import { copyFileSync, constants, existsSync, lstatSync, readFileSync, writeFileSync } from 'node:fs';
+import { randomUUID } from 'node:crypto';
+import { basename, join } from 'node:path';
+import { homedir } from 'node:os';
+import { commands } from './config.mjs';
+
+const start = '# >>> sec CLI aliases >>>';
+const end = '# <<< sec CLI aliases <<<';
+export function aliasBlock() {
+  return `${start}\n${commands.map((name) => `alias 'sec:${name}'='sec ${name}'`).join('\n')}\n${end}\n`;
+}
+export function updateAliases(previous) {
+  const from = previous.indexOf(start),
+    to = previous.indexOf(end);
+  if (
+    from < 0 !== to < 0 ||
+    (from >= 0 &&
+      (to < from ||
+        previous.indexOf(start, from + start.length) >= 0 ||
+        previous.indexOf(end, to + end.length) >= 0))
+  ) {
+    throw new Error('Incomplete or duplicate sec alias markers; shell file was not changed.');
+  }
+  if (from < 0) return `${previous}${previous && !previous.endsWith('\n') ? '\n' : ''}${aliasBlock()}`;
+  return previous.slice(0, from) + aliasBlock().trimEnd() + previous.slice(to + end.length);
+}
+export function installAliases({
+  env = process.env,
+  shell = basename(env.SHELL || ''),
+  log = console.log
+} = {}) {
+  if (!['zsh', 'bash'].includes(shell))
+    throw new Error('Colon aliases support zsh and bash. Use sec branch in other shells.');
+  const home = env.HOME || homedir();
+  const path = shell === 'zsh' ? join(env.ZDOTDIR || home, '.zshrc') : join(home, '.bashrc');
+  if (existsSync(path) && (lstatSync(path).isSymbolicLink() || !lstatSync(path).isFile()))
+    throw new Error('Shell configuration is not a regular file; install aliases manually.');
+  const previous = existsSync(path) ? readFileSync(path, 'utf8') : '';
+  const next = updateAliases(previous);
+  if (next !== previous) {
+    if (existsSync(path)) copyFileSync(path, `${path}.sec-backup-${randomUUID()}`, constants.COPYFILE_EXCL);
+    writeFileSync(path, next, { mode: 0o600 });
+  }
+  log(`快捷命令已配置：${path}。打开新终端，或在当前终端 source 该文件。`);
+  return path;
+}

package/lib/auth.mjs

@@ -0,0 +1,94 @@
+import { spawnSync } from 'node:child_process';
+import { join } from 'node:path';
+import { parseArgs } from 'node:util';
+import { readConfig } from './config.mjs';
+import { engineCommand, engineEnvironment, ensureEngine } from './engine.mjs';
+
+// Only classify known status messages. Never return raw subprocess output: even
+// successful status output may contain a partially masked API key or account data.
+export function savedLoginStatus(result) {
+  if (result.error || result.signal) return 'unknown';
+  const output = `${result.stdout || ''}\n${result.stderr || ''}`.replace(/\x1b\[[0-?]*[ -/]*[@-~]/g, '');
+  if (result.status === 0) {
+    const apiKey = /^(?:Logged in using an API key|API key configured)(?:\s|$)/im.test(output);
+    const chatgpt = /^Logged in using ChatGPT(?:\s|$)/im.test(output);
+    if (/^Not logged in\s*$/im.test(output)) return 'unknown';
+    if (apiKey && !chatgpt) return 'api_key';
+    if (chatgpt && !apiKey) return 'chatgpt';
+  }
+  if (result.status === 1 && /^Not logged in\s*$/im.test(output)) return 'none';
+  return 'unknown';
+}
+
+export function authenticationStatus({ env = process.env, run = spawnSync, check = ensureEngine } = {}) {
+  const config = readConfig(env);
+  const childEnv = engineEnvironment(env);
+  const environmentApiKeys = ['OPENAI_API_KEY', 'CODEX_API_KEY'].filter((name) => env[name]?.trim());
+  // Ask specifically about the saved login. Environment key precedence is
+  // calculated separately using the engine's documented noninteractive order.
+  delete childEnv.OPENAI_API_KEY;
+  delete childEnv.CODEX_API_KEY;
+  let savedLogin = 'unknown';
+  let diagnostic = null;
+  try {
+    check(childEnv);
+    const result = run(engineCommand(childEnv), ['login', 'status'], {
+      env: childEnv,
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'pipe'],
+      timeout: 10000,
+      killSignal: 'SIGKILL',
+      maxBuffer: 64 * 1024
+    });
+    savedLogin = savedLoginStatus(result);
+    if (savedLogin === 'unknown') diagnostic = 'status_unavailable';
+  } catch {
+    // Errors can contain credentials. Return a fixed diagnostic, never error.message.
+    diagnostic = 'engine_unavailable';
+  }
+  const source =
+    environmentApiKeys[0] || (['api_key', 'chatgpt'].includes(savedLogin) ? 'saved_login' : null);
+  return {
+    savedLogin,
+    environmentApiKeys,
+    noninteractiveDefault: {
+      method: environmentApiKeys.length ? 'api_key' : savedLogin,
+      source
+    },
+    credentialHome: join(childEnv.CODEX_SECURITY_STATE_DIR, 'codex-home'),
+    provider: config.baseUrl ? 'custom' : 'openai',
+    diagnostic
+  };
+}
+
+export function main(args = [], dependencies = {}) {
+  const { values } = parseArgs({ args, options: { json: { type: 'boolean' } }, allowPositionals: false });
+  const status = authenticationStatus(dependencies);
+  const log = dependencies.log || console.log;
+  if (values.json) log(JSON.stringify(status, null, 2));
+  else {
+    const labels = {
+      api_key: 'API key',
+      chatgpt: 'ChatGPT 账号登录（可能使用账号的 Codex 权益）',
+      none: '未登录',
+      unknown: '无法确认'
+    };
+    log(`已保存的 sec 登录：${labels[status.savedLogin]}`);
+    log(`环境 API key：${status.environmentApiKeys.join('、') || '未设置'}（不显示值）`);
+    log(`非交互扫描默认认证：${labels[status.noninteractiveDefault.method]}`);
+    log(`凭据来源：${status.noninteractiveDefault.source || '无'}`);
+    log(`sec 独立认证目录：${status.credentialHome}`);
+    log(`服务：${status.provider === 'custom' ? '自定义 provider' : 'OpenAI'}`);
+    if (status.environmentApiKeys.length)
+      log('环境 API key 优先于保存的登录；交互式扫描若引擎提示选择，以当次选择为准。');
+    if (status.provider === 'custom' && status.savedLogin === 'chatgpt')
+      log('自定义 provider 不保证接受 ChatGPT 账号登录；需使用该服务支持的凭据。');
+    if (status.diagnostic)
+      log(
+        '未能确认保存的登录状态。检查 sec doctor；登录状态查询与引擎检查各有 10 秒上限，不自动登录或覆盖凭据。'
+      );
+    log('仅查询认证来源，不请求模型；不验证 key 有效性、账号订阅权益、剩余额度或最终计费。');
+    log('官方状态查询可能初始化或同步 sec 认证缓存；不修改业务仓库或日常 Codex 登录。');
+  }
+  return status.savedLogin === 'unknown' || status.noninteractiveDefault.method === 'none' ? 2 : 0;
+}

package/lib/cli.mjs

@@ -0,0 +1,169 @@
+import { execFileSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import { parseArgs } from 'node:util';
+import { readProjectConfig, projectConfigFile, findingId } from './project.mjs';
+import {
+  configFile,
+  repositoryConfigFile,
+  repositoryDirectory,
+  trackerFile,
+  userDirectories,
+  commands
+} from './config.mjs';
+import { readTracker, renderFindings } from './tracker.mjs';
+import { aliasBlock, installAliases } from './aliases.mjs';
+
+export function help() {
+  console.log(`sec — 全局安全扫描工作流
+
+首次使用：sec setup（用户级配置、隐藏输入 API key，可安装 sec:xxx 快捷命令）
+项目接入：sec init project [--dry-run]  创建通用规范、模板、共享台账、sec.config.json
+sec scan [--knowledge-base <path>]     全仓当前工作区
+sec diff [--knowledge-base <path>]     HEAD 到 index 的差异，保留部分暂存
+sec branch [--base <ref>] [--dry-run] [--knowledge-base <path>]
+                                      目标：--base → 本机仓库配置 → 项目共享配置 → 用户配置 → origin/HEAD
+                                      仅扫描共同祖先到 HEAD 的已提交差异
+sec list [--severity <level>] [--all]   读取当前有效台账，无模型请求
+sec update SEC-001 [SEC-002 ...]        将指定编号追加到待验证队列，编号前缀可由项目配置
+sec verify [--model <model>] [--effort <effort>]
+                                      仅复核队列，静态检查，不执行线上验证
+sec paths                             显示项目配置、有效台账与私有数据位置
+sec doctor                            检查工具依赖及有效模型，不运行扫描
+sec auth [--json]                      查询 sec 保存的登录方式与环境 key 优先级
+sec config [get|set|unset <key> [<value>]] [--local|--project]
+                                      默认用户级与 --local 只支持 baseRef
+                                      --project 管理仓库根 sec.config.json，路径均相对仓库根
+                                      项目项：policyFile/reportTemplate/trackerFile/summaryDir/reviewDir
+                                      knowledgeBase(JSON数组)/idPrefix/baseRef/model/effort/failOnSeverity
+sec aliases [--install] [--shell zsh|bash]
+                                      输出或安装 sec:xxx shell 快捷命令（含 sec:init project）
+sec setup [--api-key] [--base-url <url>] [--model <model>] [--effort <effort>] [--base <ref>] [--no-aliases]
+sec --version
+
+--api-key 不接收 key 值；不要把凭据放在命令行。
+scan/diff/branch/verify 均支持 --model <model> 和 --effort <effort> 单次覆盖。
+默认 gpt-6.1-sol + high；优先级：单次参数 → 项目共享设置 → setup 个人设置 → 工具默认值。
+默认中危及以上退出 1，低危警告放行；项目可用 failOnSeverity 调整门禁。
+错误或证据不足退出 2，取消保留非零状态。退出 0 不代表整个项目无漏洞。
+正式 scan/diff/branch 与非空 verify 队列会请求模型并消耗额度。
+init（含 dry-run）、branch --dry-run、list、update、paths、doctor、auth、config、help 不请求模型。
+init 创建缺失文件并补充 .gitignore，已有规范、模板和台账保留；--dry-run 不写文件。
+启用项目配置后，扫描可更新共享台账及忽略的脱敏摘要；不自动修改业务源码、暂存、提交、推送或 fetch。
+未配置共享文件时沿用本机私有台账与报告；完整原始证据及凭据始终保存在仓库外。
+项目规范和 knowledgeBase 自动提供扫描上下文；显式 --knowledge-base 可追加本次材料。
+项目路径以 Git 仓库根为基准；显式 --knowledge-base 相对当前工作目录。项目内容不随 npm 包分发。
+`);
+}
+const rootDirectory = () =>
+  execFileSync('git', ['rev-parse', '--show-toplevel'], {
+    encoding: 'utf8',
+    stdio: 'pipe'
+  }).trim();
+export async function main(args = process.argv.slice(2)) {
+  if (args.length === 1 && ['--version', '-v'].includes(args[0])) {
+    console.log(JSON.parse(readFileSync(new URL('../package.json', import.meta.url))).version);
+    return 0;
+  }
+  let [command = 'help', ...rest] = args;
+  if (command.startsWith('sec:')) command = command.slice(4);
+  if (command === '--help' || command === '-h') command = 'help';
+  if (!commands.includes(command)) throw new Error('Unknown command. Run sec help.');
+  if (command === 'help' || rest.includes('--help')) {
+    help();
+    return 0;
+  }
+  if (command === 'setup') return (await import('./setup.mjs')).main(rest);
+  if (command === 'auth') return (await import('./auth.mjs')).main(rest);
+  if (command === 'init') return (await import('./project-init.mjs')).main(rest);
+  if (command === 'config') return (await import('./config-command.mjs')).main(rest);
+  if (['scan', 'diff', 'branch'].includes(command))
+    return (await import('./scan.mjs')).main(
+      { scan: 'full', diff: 'staged', branch: 'branch' }[command],
+      rest
+    );
+  if (command === 'verify') return (await import('./verify.mjs')).main(rest);
+  if (command === 'update') {
+    if (!rest.length) {
+      console.log('用法：sec update SEC-001 [SEC-002 ...]；只排队，不代表修复。');
+      return 0;
+    }
+    const ids = rest.flatMap((arg) => arg.trim().split(/\s+/)).filter(Boolean);
+    if (!ids.length || ids.some((id) => !findingId(id)))
+      throw new Error('Use complete finding IDs such as SEC-001.');
+    return (await import('./verify.mjs')).main(['--pending', ...ids]);
+  }
+  if (command === 'aliases') {
+    const { values } = parseArgs({
+      args: rest,
+      options: { install: { type: 'boolean' }, shell: { type: 'string' } }
+    });
+    if (values.install) installAliases({ shell: values.shell });
+    else console.log(aliasBlock());
+    return 0;
+  }
+  if (command === 'list') {
+    const { values } = parseArgs({
+      args: rest,
+      options: { severity: { type: 'string' }, all: { type: 'boolean' } }
+    });
+    console.log(
+      renderFindings(
+        readTracker(
+          trackerFile(rootDirectory()),
+          true,
+          readProjectConfig(rootDirectory())?.idPrefix ?? 'SEC'
+        ).tracker,
+        {
+          severity: values.severity,
+          all: values.all
+        }
+      )
+    );
+    return 0;
+  }
+  if (rest.length) throw new Error('Unknown arguments. Run sec help.');
+  if (command === 'paths') {
+    const root = rootDirectory();
+    console.log(
+      JSON.stringify(
+        {
+          config: configFile(),
+          repositoryConfig: repositoryConfigFile(root),
+          projectConfig: projectConfigFile(root),
+          project: readProjectConfig(root),
+          repositoryState: repositoryDirectory(root),
+          ledger: trackerFile(root),
+          runs: `${repositoryDirectory(root)}/runs`
+        },
+        null,
+        2
+      )
+    );
+    return 0;
+  }
+  if (command === 'doctor') {
+    const { engineEnvironment, ensureEngine } = await import('./engine.mjs');
+    const { readConfig, modelSettings, repositoryModelSettings } = await import('./config.mjs');
+    const { findPython } = await import('./runtime.mjs');
+    const env = engineEnvironment();
+    let root;
+    try {
+      root = rootDirectory();
+    } catch {
+      /* doctor also works outside Git. */
+    }
+    const settings = root
+      ? repositoryModelSettings(root, readConfig())
+      : modelSettings(readConfig());
+    console.log(
+      `Git: ${execFileSync('git', ['--version'], { encoding: 'utf8', stdio: 'pipe' }).trim()}`
+    );
+    console.log(`Python: ${findPython(env)}`);
+    console.log(`扫描引擎: ${ensureEngine(env)}`);
+    console.log(`配置目录: ${userDirectories().config}`);
+    console.log(`默认模型: ${settings.model}；推理强度: ${settings.effort}`);
+    console.log('依赖可用；未检查真实认证、额度或模型权限。');
+    return 0;
+  }
+  return 0;
+}

package/lib/config-command.mjs

@@ -0,0 +1,133 @@
+import { execFileSync } from 'node:child_process';
+import { parseArgs } from 'node:util';
+import { existsSync, readFileSync } from 'node:fs';
+import {
+  projectConfigFile,
+  readProjectConfig,
+  saveProjectConfig,
+  projectKeys,
+  validateProjectConfig,
+  projectPath
+} from './project.mjs';
+import { readTracker } from './tracker.mjs';
+import {
+  assertOutsideRepository,
+  configFile,
+  readConfig,
+  readRepositoryConfig,
+  repositoryConfigFile,
+  saveConfig,
+  saveRepositoryConfig,
+  validateConfig
+} from './config.mjs';
+
+export function main(
+  args = [],
+  { env = process.env, cwd = process.cwd(), log = console.log } = {}
+) {
+  const { values, positionals } = parseArgs({
+    args,
+    options: { local: { type: 'boolean' }, project: { type: 'boolean' } },
+    allowPositionals: true
+  });
+  const [action, key, value] = positionals;
+  if (values.local && values.project) throw new Error('Choose --local or --project, not both.');
+  if (
+    positionals.length &&
+    (!['get', 'set', 'unset'].includes(action) ||
+      !(values.project ? projectKeys : ['baseRef']).includes(key) ||
+      positionals.length !== (action === 'set' ? 3 : 2))
+  )
+    throw new Error(
+      'Use sec config [get|set|unset <key> [<value>]] [--local|--project]. User/local scope supports baseRef; project scope supports shared workflow settings.'
+    );
+  if (action === 'set' && !values.project) validateConfig({ schemaVersion: 1, baseRef: value });
+  let root;
+  try {
+    root = execFileSync('git', ['-C', cwd, 'rev-parse', '--show-toplevel'], {
+      env,
+      encoding: 'utf8',
+      stdio: 'pipe'
+    }).trim();
+  } catch {
+    if (values.local || values.project)
+      throw new Error('Run sec config --local/--project inside the target Git repository.');
+  }
+  const user = readConfig(env);
+  if (values.project) {
+    const path = projectConfigFile(root);
+    const previous = existsSync(path)
+      ? readFileSync(projectPath(root, 'sec.config.json', { kind: 'file' }), 'utf8')
+      : null;
+    const project = readProjectConfig(root) ?? { schemaVersion: 1 };
+    const fallback =
+      key === 'baseRef'
+        ? (user.baseRef ?? 'origin/HEAD')
+        : key === 'model'
+          ? (user.model ?? 'gpt-6.1-sol')
+          : key === 'effort'
+            ? (user.effort ?? 'high')
+            : undefined;
+    if (action === 'get') {
+      const result = project[key] ?? fallback;
+      log(typeof result === 'object' ? JSON.stringify(result) : (result ?? '未设置'));
+      return 0;
+    }
+    if (action === 'set' || action === 'unset') {
+      if (action === 'set') {
+        if (key === 'knowledgeBase') {
+          try {
+            project[key] = JSON.parse(value);
+          } catch {
+            throw new Error('knowledgeBase expects a JSON array, for example ["docs/context.md"].');
+          }
+        } else project[key] = value;
+      } else delete project[key];
+      validateProjectConfig(project, root);
+      if (project.trackerFile) {
+        const tracker = projectPath(root, project.trackerFile, { kind: 'file' });
+        if (existsSync(tracker)) readTracker(tracker, false, project.idPrefix ?? 'SEC');
+      }
+      if (action === 'set' || previous !== null) saveProjectConfig(root, project, previous);
+      log(`项目共享配置：${path}。未调用模型；请检查后自行提交。`);
+      return 0;
+    }
+    log(
+      `项目共享配置：${path}${previous === null ? '（未创建；sec init project 可生成通用模板）' : ''}`
+    );
+    log(JSON.stringify(project, null, 2));
+    return 0;
+  }
+
+  const config = values.local ? readRepositoryConfig(root, env) : user;
+  const path = values.local ? repositoryConfigFile(root, env) : configFile(env);
+  const inherited = values.local
+    ? (readProjectConfig(root)?.baseRef ?? user.baseRef ?? 'origin/HEAD')
+    : 'origin/HEAD';
+  const scope = values.local ? '当前仓库' : '用户级（影响所有未单独配置的仓库）';
+  if (action === 'get') {
+    log(config.baseRef ?? inherited);
+    return 0;
+  }
+  if (action === 'set' || action === 'unset') {
+    const changed = action === 'set' ? config.baseRef !== value : Object.hasOwn(config, 'baseRef');
+    if (changed) {
+      if (root) assertOutsideRepository(root, path);
+      if (action === 'set') config.baseRef = value;
+      else delete config.baseRef;
+      if (values.local) saveRepositoryConfig(root, config, env);
+      else saveConfig(config, env);
+    }
+    log(
+      `${scope}默认比较目标：${config.baseRef ?? inherited}${config.baseRef == null ? '（继承/回退）' : ''}`
+    );
+    log(`配置文件：${path}。未调用模型、fetch 或改动 Git 引用。`);
+    return 0;
+  }
+  log(`作用域：${scope}`);
+  log(`配置文件：${path}`);
+  log(`已保存 baseRef：${config.baseRef ?? '未设置'}`);
+  log(`本作用域默认比较目标：${config.baseRef ?? inherited}`);
+  if (!values.local) log('当前仓库覆盖请用 sec config --local 查看；单次 --base 优先于所有配置。');
+  return 0;
+}

package/lib/config.mjs

@@ -0,0 +1,207 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { readProjectConfig, projectPath } from './project.mjs';
+import {
+  existsSync,
+  lstatSync,
+  mkdirSync,
+  readFileSync,
+  realpathSync,
+  renameSync,
+  writeFileSync
+} from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, isAbsolute, join, relative, resolve } from 'node:path';
+
+export const engineVersion = '0.8.3';
+export const defaultModel = 'gpt-6.1-sol';
+export const defaultEffort = 'high';
+export const commands = [
+  'setup',
+  'doctor',
+  'auth',
+  'config',
+  'init',
+  'scan',
+  'diff',
+  'branch',
+  'list',
+  'update',
+  'verify',
+  'paths',
+  'aliases',
+  'help'
+];
+export function userDirectories(env = process.env) {
+  const home = env.HOME || homedir();
+  return {
+    config: resolve(env.XDG_CONFIG_HOME || join(home, '.config'), 'sec'),
+    state: resolve(
+      env.SEC_STATE_DIR || join(env.XDG_STATE_HOME || join(home, '.local/state'), 'sec')
+    )
+  };
+}
+export const configFile = (env = process.env) => join(userDirectories(env).config, 'config.json');
+export function readConfig(env = process.env) {
+  const path = configFile(env);
+  if (!existsSync(path)) return { schemaVersion: 1 };
+  const stat = lstatSync(path);
+  if (!stat.isFile() || stat.isSymbolicLink())
+    throw new Error('User configuration must be a regular file.');
+  let config;
+  try {
+    config = JSON.parse(readFileSync(path, 'utf8'));
+  } catch {
+    throw new Error('Cannot parse user configuration. Run sec setup to inspect or replace it.');
+  }
+  validateConfig(config);
+  return config;
+}
+export function validateConfig(config) {
+  if (
+    !config ||
+    config.schemaVersion !== 1 ||
+    Object.keys(config).some(
+      (key) => !['schemaVersion', 'baseUrl', 'model', 'effort', 'baseRef'].includes(key)
+    )
+  ) {
+    throw new Error(
+      'Unsupported user configuration fields or version. API keys belong in the engine login store.'
+    );
+  }
+  for (const key of ['model', 'effort', 'baseRef']) {
+    if (
+      config[key] != null &&
+      (typeof config[key] !== 'string' ||
+        !config[key].trim() ||
+        /[\x00-\x20\x7f]/.test(config[key]) ||
+        config[key].startsWith('-'))
+    ) {
+      throw new Error(`Invalid ${key} in user configuration.`);
+    }
+  }
+  if (config.baseUrl != null) {
+    if (typeof config.baseUrl !== 'string') throw new Error('Invalid provider URL.');
+    const url = new URL(config.baseUrl);
+    if (
+      !['https:', 'http:'].includes(url.protocol) ||
+      url.username ||
+      url.password ||
+      url.search ||
+      url.hash
+    ) {
+      throw new Error(
+        'Provider URL must use HTTP(S) without credentials, query parameters or fragments.'
+      );
+    }
+    if (!config.model) throw new Error('A custom provider URL requires an explicit model.');
+  }
+}
+export function modelSettings(config, overrides = {}) {
+  validateConfig(config);
+  const settings = {
+    model: overrides.model ?? config.model ?? defaultModel,
+    effort: overrides.effort ?? config.effort ?? defaultEffort
+  };
+  validateConfig({ schemaVersion: 1, ...settings });
+  return settings;
+}
+const within = (root, path) => {
+  const rel = relative(root, path);
+  return !rel || (!isAbsolute(rel) && rel !== '..' && !rel.startsWith('../'));
+};
+export function assertOutsideRepository(root, path) {
+  const canonicalRoot = realpathSync(root);
+  let existing = resolve(path);
+  while (!existsSync(existing)) existing = dirname(existing);
+  const canonical = resolve(realpathSync(existing), relative(existing, resolve(path)));
+  if (within(canonicalRoot, canonical))
+    throw new Error('Private configuration and state must stay outside the scanned repository.');
+}
+export function repositoryDirectory(root, env = process.env) {
+  const canonical = realpathSync(root);
+  const id = createHash('sha256').update(canonical).digest('hex').slice(0, 24);
+  const result = join(userDirectories(env).state, 'repositories', id);
+  assertOutsideRepository(canonical, result);
+  return result;
+}
+export const repositoryConfigFile = (root, env = process.env) =>
+  join(repositoryDirectory(root, env), 'config.json');
+function validateRepositoryConfig(config) {
+  validateConfig(config);
+  if (Object.keys(config).some((key) => !['schemaVersion', 'baseRef'].includes(key)))
+    throw new Error('Repository configuration only supports baseRef.');
+}
+export function readRepositoryConfig(root, env = process.env) {
+  const path = repositoryConfigFile(root, env);
+  if (!existsSync(path)) return { schemaVersion: 1 };
+  const stat = lstatSync(path);
+  if (!stat.isFile() || stat.isSymbolicLink())
+    throw new Error('Repository configuration must be a regular file.');
+  let config;
+  try {
+    config = JSON.parse(readFileSync(path, 'utf8'));
+  } catch {
+    throw new Error('Cannot parse repository configuration. Inspect the file shown by sec paths.');
+  }
+  validateRepositoryConfig(config);
+  return config;
+}
+export function branchBaseRef(root, config, override, env = process.env) {
+  // An explicit one-shot target does not depend on a repository default.
+  if (override !== undefined) return override;
+  return (
+    readRepositoryConfig(root, env).baseRef ??
+    readProjectConfig(root)?.baseRef ??
+    config.baseRef ??
+    'origin/HEAD'
+  );
+}
+export const trackerFile = (root, env = process.env) => {
+  const project = readProjectConfig(root);
+  return project?.trackerFile
+    ? projectPath(root, project.trackerFile, { kind: 'file' })
+    : join(repositoryDirectory(root, env), 'ledger.json');
+};
+export function repositoryModelSettings(root, config, overrides = {}) {
+  const project = readProjectConfig(root);
+  return modelSettings(config, {
+    model: project?.model,
+    effort: project?.effort,
+    ...Object.fromEntries(Object.entries(overrides).filter(([, value]) => value !== undefined))
+  });
+}
+export function privateDirectory(path) {
+  // Validate before creating anything, including a dangling symlink.
+  for (
+    let current = resolve(path), depth = 0;
+    current !== dirname(current) && depth < 3;
+    current = dirname(current), depth++
+  ) {
+    try {
+      if (lstatSync(current).isSymbolicLink())
+        throw new Error('Private directories must not contain symlinks.');
+    } catch (error) {
+      if (error.code !== 'ENOENT') throw error;
+    }
+  }
+  mkdirSync(path, { recursive: true, mode: 0o700 });
+}
+export function saveConfig(config, env = process.env) {
+  validateConfig(config);
+  saveSettingsFile(configFile(env), config);
+}
+export function saveRepositoryConfig(root, config, env = process.env) {
+  validateRepositoryConfig(config);
+  saveSettingsFile(repositoryConfigFile(root, env), config);
+}
+function saveSettingsFile(path, config) {
+  privateDirectory(dirname(path));
+  if (existsSync(path) && (lstatSync(path).isSymbolicLink() || !lstatSync(path).isFile()))
+    throw new Error('Refusing to replace a nonregular configuration file.');
+  const temporary = `${path}.${randomUUID()}.tmp`;
+  writeFileSync(temporary, `${JSON.stringify(config, null, 2)}\n`, {
+    flag: 'wx',
+    mode: 0o600
+  });
+  renameSync(temporary, path);
+}