elanous 0.2.0 → 0.2.5

package/src/grounding/sources-cli.ts

@@ -0,0 +1,209 @@
+// `elanous grounding sources` — registry CLI.
+// Does not import src/index.ts. The production entrypoint calls
+// registerGroundingSourcesCli(program).
+
+import type { Command } from 'commander';
+import { homedir } from 'node:os';
+import { basename } from 'node:path';
+import { exportMirrorManifest } from './mirror-export.js';
+import {
+  addGroundingSource,
+  discoverReferenceSources,
+  GroundingSourceError,
+  listGroundingSources,
+  removeGroundingSource,
+  sourceStatus,
+  type GroundingSource,
+  type GroundingSourceKind,
+  type GroundingSourceSync,
+  type GroundingSourcesConfig,
+} from './sources.js';
+import { getUserConfig, saveUserConfig, type UserConfig } from '../user-config.js';
+
+const KINDS: readonly GroundingSourceKind[] = ['local-repo', 'local-docs', 'web', 'dev-index', 'url'];
+
+export function registerGroundingSourcesCli(program: Command): void {
+  const grounding = program
+    .command('grounding')
+    .description('그라운딩 출처 레지스트리');
+  const sources = grounding
+    .command('sources')
+    .description('등록된 그라운딩 출처를 조회·추가·삭제하고 신선도를 본다');
+
+  sources
+    .command('list')
+    .description('등록된 출처 목록')
+    .option('--json', 'JSON 출력')
+    .action((opts: { json?: boolean }) => {
+      const listed = listGroundingSources(load());
+      if (opts.json) printJson(listed);
+      else if (listed.length === 0) console.log('(none)');
+      else for (const source of listed) console.log(formatSource(source));
+    });
+
+  sources
+    .command('add <pathOrUrl>')
+    .description('출처를 등록한다')
+    .option('--kind <kind>', 'local-repo|local-docs|web|dev-index|url')
+    .option('--sync <sync>', 'manual|daily|before-use:<hours>')
+    .option('--tag <tag>', '태그를 반복해서 붙인다', collectTag, [] as string[])
+    .option('--json', 'JSON 출력')
+    .action((pathOrUrl: string, opts: { kind?: string; sync?: string; tag?: string[]; json?: boolean }) => {
+      try {
+        const kind = parseKind(opts.kind);
+        const sync = parseSyncFlag(opts.sync);
+        const input = isUrl(pathOrUrl)
+          ? { url: pathOrUrl, kind: kind ?? 'url', sync, tags: opts.tag, id: idFromUrl(pathOrUrl) }
+          : { path: pathOrUrl, ...(kind ? { kind } : {}), sync, tags: opts.tag, id: basename(pathOrUrl) };
+        const next = addGroundingSource(load(), input);
+        save(next);
+        const added = listGroundingSources(next).at(-1);
+        if (opts.json) printJson(added);
+        else console.log(`added ${added?.id}`);
+      } catch (err) {
+        fail(err);
+      }
+    });
+
+  sources
+    .command('remove <id>')
+    .description('출처를 id 로 삭제한다')
+    .action((id: string) => {
+      try {
+        const next = removeGroundingSource(load(), id);
+        save(next);
+        console.log(`removed ${id}`);
+      } catch (err) {
+        fail(err);
+      }
+    });
+
+  sources
+    .command('discover')
+    .description('~/source/ref 와 ~/docs/ref 후보를 찾는다(등록하지 않는다)')
+    .option('--json', 'JSON 출력')
+    .option('--home <dir>', '홈 디렉터리(기본: os homedir)')
+    .action((opts: { json?: boolean; home?: string }) => {
+      const found = discoverReferenceSources(opts.home ?? homedir());
+      if (opts.json) printJson(found);
+      else if (found.length === 0) console.log('(none)');
+      else for (const source of found) console.log(formatSource(source));
+    });
+
+  sources
+    .command('export')
+    .description('등록된 local-repo 출처로 거울 목록을 만든다')
+    .option('--mirror-manifest', '거울 목록을 내보낸다')
+    .option('--discover', '발견 후보를 등록된 출처에 더한다(대체하지 않는다)')
+    .option('--json', 'JSON 으로 { accepted, refused }')
+    .option('--home <dir>', '발견에 쓸 홈 디렉터리(기본: os homedir)')
+    .action((opts: { mirrorManifest?: boolean; discover?: boolean; json?: boolean; home?: string }) => {
+      if (!opts.mirrorManifest) {
+        console.error('export 는 --mirror-manifest 가 필요하다');
+        process.exitCode = 1;
+        return;
+      }
+      const registered = listGroundingSources(load());
+      const sources = opts.discover
+        ? mergeDiscovered(registered, discoverReferenceSources(opts.home ?? homedir()))
+        : registered;
+      const exported = exportMirrorManifest(sources);
+      const human = humanExportLines(exported);
+      if (human) console.error(human);
+      if (opts.json) printJson({ accepted: exported.accepted, refused: exported.refused });
+      else console.log(exported.list);
+    });
+
+  sources
+    .command('status [id]')
+    .description('local-repo 신선도(로컬 참조만 · fetch/pull 없음)')
+    .option('--json', 'JSON 출력')
+    .action((id: string | undefined, opts: { json?: boolean }) => {
+      const listed = listGroundingSources(load());
+      const targets = id ? listed.filter((source) => source.id === id) : listed;
+      if (id && targets.length === 0) {
+        console.error(`unknown id: ${id}`);
+        process.exitCode = 1;
+        return;
+      }
+      const rows = targets.map((source) => sourceStatus(source));
+      if (opts.json) printJson(id ? rows[0] : rows);
+      else for (const row of rows) {
+        console.log(`${row.id} dirty=${String(row.dirty ?? false)} behind=${String(row.behind ?? 'unknown')}${row.branch ? ` branch=${row.branch}` : ''}`);
+      }
+    });
+}
+
+function load(): UserConfig {
+  return getUserConfig();
+}
+
+function save(next: GroundingSourcesConfig): void {
+  const current = getUserConfig();
+  saveUserConfig({
+    ...current,
+    grounding: { sources: listGroundingSources(next) },
+  });
+}
+
+function collectTag(value: string, previous: string[]): string[] {
+  return [...previous, value];
+}
+
+function parseKind(raw: string | undefined): GroundingSourceKind | undefined {
+  if (!raw) return undefined;
+  if (!(KINDS as readonly string[]).includes(raw)) {
+    throw new GroundingSourceError(`unknown kind: ${raw}`);
+  }
+  return raw as GroundingSourceKind;
+}
+
+function parseSyncFlag(raw: string | undefined): GroundingSourceSync {
+  if (!raw || raw === 'manual') return 'manual';
+  if (raw === 'daily') return 'daily';
+  const match = /^before-use:(\d+(?:\.\d+)?)$/.exec(raw);
+  if (!match) throw new GroundingSourceError(`unknown sync: ${raw}`);
+  const hours = Number(match[1]);
+  if (!Number.isFinite(hours) || hours <= 0) throw new GroundingSourceError(`unknown sync: ${raw}`);
+  return { beforeUse: { maxAgeHours: hours } };
+}
+
+function isUrl(value: string): boolean {
+  return /^https?:\/\//.test(value);
+}
+
+function idFromUrl(value: string): string {
+  try { return new URL(value).hostname || value; } catch { return value; }
+}
+
+/** 등록된 출처를 유지하고, 같은 id 가 없는 발견 후보만 뒤에 붙인다. */
+function mergeDiscovered(registered: GroundingSource[], discovered: GroundingSource[]): GroundingSource[] {
+  const seen = new Set(registered.map((source) => source.id));
+  const extra = discovered.filter((source) => !seen.has(source.id));
+  return [...registered, ...extra];
+}
+
+function humanExportLines(exported: { accepted: readonly { id: string }[]; refused: readonly { id: string; reason: string }[] }): string {
+  const accepted = exported.accepted.map((row) => `accepted ${row.id}`);
+  const refused = exported.refused.map((row) => `refused ${row.id} ${row.reason}`);
+  return [...accepted, ...refused].join('\n');
+}
+
+function formatSource(source: GroundingSource): string {
+  const where = source.path ?? source.url ?? '';
+  const sync = typeof source.sync === 'string'
+    ? source.sync
+    : `before-use:${source.sync.beforeUse.maxAgeHours}`;
+  const tags = source.tags && source.tags.length > 0 ? ` [${source.tags.join(',')}]` : '';
+  return `${source.id}\t${source.kind}\t${sync}\t${where}${tags}`;
+}
+
+function printJson(value: unknown): void {
+  console.log(JSON.stringify(value));
+}
+
+function fail(err: unknown): void {
+  const message = err instanceof Error ? err.message : String(err);
+  console.error(message);
+  process.exitCode = 1;
+}

package/src/grounding/sources.ts

@@ -0,0 +1,333 @@
+// Grounding source registry — pure config-object helpers.
+//
+// These functions update and return a config object. They do not write
+// ~/.elanous. Discovery returns candidates only; it does not register them.
+// sourceStatus reads local git refs only — never fetch or pull.
+
+import { spawnSync } from 'node:child_process';
+import { existsSync, readdirSync, statSync } from 'node:fs';
+import { basename, join } from 'node:path';
+import { debug } from '../debug/log.js';
+
+export const GROUNDING_SOURCE_KINDS = ['local-repo', 'local-docs', 'web', 'dev-index', 'url'] as const;
+export type GroundingSourceKind = (typeof GROUNDING_SOURCE_KINDS)[number];
+
+export interface GroundingSourceBeforeUse {
+  maxAgeHours: number;
+}
+
+export type GroundingSourceSync = 'manual' | 'daily' | { beforeUse: GroundingSourceBeforeUse };
+
+export interface GroundingSource {
+  id: string;
+  kind: GroundingSourceKind;
+  path?: string;
+  url?: string;
+  sync: GroundingSourceSync;
+  tags?: string[];
+  /** 로컬 전용 출처를 거울에 올릴지. upstream 이 있으면 이 칸과 무관하게 후보가 된다. */
+  mirror?: boolean;
+}
+
+export interface GroundingSourcesConfig {
+  grounding?: { sources?: GroundingSource[] };
+}
+
+export interface GroundingSourceInput {
+  id?: string;
+  kind?: GroundingSourceKind;
+  path?: string;
+  url?: string;
+  sync?: GroundingSourceSync;
+  tags?: string[];
+  mirror?: boolean;
+}
+
+export interface GroundingSourceStatus {
+  id: string;
+  kind: GroundingSourceKind;
+  branch?: string;
+  lastCommitAt?: string;
+  dirty?: boolean;
+  behind?: number | 'unknown';
+  measured: boolean;
+}
+
+export class GroundingSourceError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'GroundingSourceError';
+  }
+}
+
+const PATH_KINDS = new Set<GroundingSourceKind>(['local-repo', 'local-docs', 'dev-index']);
+
+export interface GroundingConfig {
+  sources: GroundingSource[];
+}
+
+/** Keep valid items. Skip invalid items with a warning. Never throws. */
+export function parseGroundingSources(raw: unknown): GroundingConfig {
+  if (raw === undefined) return { sources: [] };
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+    warnSkip('grounding', '섹션이 객체가 아니다 — 버림');
+    return { sources: [] };
+  }
+  const sources = (raw as Record<string, unknown>).sources;
+  if (sources === undefined) return { sources: [] };
+  if (!Array.isArray(sources)) {
+    warnSkip('grounding.sources', '배열이 아니다 — 버림');
+    return { sources: [] };
+  }
+  const kept: GroundingSource[] = [];
+  for (const item of sources) {
+    const parsed = parseGroundingSourceItem(item);
+    if (parsed) kept.push(parsed);
+  }
+  return { sources: kept };
+}
+
+function parseGroundingSourceItem(raw: unknown): GroundingSource | undefined {
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+    warnSkip('grounding.sources[]', '객체가 아니다 — 건너뜀');
+    return undefined;
+  }
+  const v = raw as Record<string, unknown>;
+  if (typeof v.id !== 'string' || !v.id.trim()) {
+    warnSkip('grounding.sources[]', 'id 가 없다 — 건너뜀');
+    return undefined;
+  }
+  if (typeof v.kind !== 'string' || !(GROUNDING_SOURCE_KINDS as readonly string[]).includes(v.kind)) {
+    warnSkip('grounding.sources[]', `kind 가 허용값이 아니다(${JSON.stringify(v.kind)}) — 건너뜀`);
+    return undefined;
+  }
+  const sync = parseSync(v.sync);
+  if (!sync) {
+    warnSkip('grounding.sources[]', `sync 가 허용값이 아니다(${JSON.stringify(v.sync)}) — 건너뜀`);
+    return undefined;
+  }
+  const path = typeof v.path === 'string' && v.path.trim() ? v.path.trim() : undefined;
+  const url = typeof v.url === 'string' && v.url.trim() ? v.url.trim() : undefined;
+  const tags = Array.isArray(v.tags)
+    ? v.tags.filter((tag): tag is string => typeof tag === 'string' && tag.trim().length > 0)
+    : undefined;
+  const mirror = v.mirror === true ? true : undefined;
+  return {
+    id: v.id.trim(),
+    kind: v.kind as GroundingSourceKind,
+    sync,
+    ...(path ? { path } : {}),
+    ...(url ? { url } : {}),
+    ...(tags && tags.length > 0 ? { tags } : {}),
+    ...(mirror ? { mirror } : {}),
+  };
+}
+
+function parseSync(raw: unknown): GroundingSourceSync | undefined {
+  if (raw === 'manual' || raw === 'daily') return raw;
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return undefined;
+  const beforeUse = (raw as Record<string, unknown>).beforeUse;
+  if (!beforeUse || typeof beforeUse !== 'object' || Array.isArray(beforeUse)) return undefined;
+  const hours = (beforeUse as Record<string, unknown>).maxAgeHours;
+  if (typeof hours !== 'number' || !Number.isFinite(hours) || hours <= 0) return undefined;
+  return { beforeUse: { maxAgeHours: hours } };
+}
+
+function warnSkip(section: string, detail: string): void {
+  try { process.stderr.write(`[user-config] ${section} ${detail}\n`); } catch { /* stderr closed */ }
+}
+
+export function listGroundingSources(config: GroundingSourcesConfig): GroundingSource[] {
+  const sources = config.grounding?.sources;
+  return Array.isArray(sources) ? sources.map(cloneSource) : [];
+}
+
+export function addGroundingSource(
+  config: GroundingSourcesConfig,
+  input: GroundingSourceInput,
+): GroundingSourcesConfig {
+  const source = normalizeInput(input);
+  const existing = listGroundingSources(config);
+  if (existing.some((item) => item.id === source.id)) {
+    throw new GroundingSourceError(`duplicate id: ${source.id}`);
+  }
+  if (PATH_KINDS.has(source.kind)) {
+    if (!source.path) throw new GroundingSourceError(`missing path: ${source.id}`);
+    if (!existsSync(source.path)) throw new GroundingSourceError(`missing path: ${source.path}`);
+  }
+  debug.log('grounding.sources', 'added', { id: source.id, kind: source.kind });
+  return {
+    ...config,
+    grounding: { ...(config.grounding ?? {}), sources: [...existing, source] },
+  };
+}
+
+export function removeGroundingSource(
+  config: GroundingSourcesConfig,
+  id: string,
+): GroundingSourcesConfig {
+  const existing = listGroundingSources(config);
+  const hit = existing.find((item) => item.id === id);
+  if (!hit) throw new GroundingSourceError(`unknown id: ${id}`);
+  debug.log('grounding.sources', 'removed', { id: hit.id, kind: hit.kind });
+  return {
+    ...config,
+    grounding: { ...(config.grounding ?? {}), sources: existing.filter((item) => item.id !== id) },
+  };
+}
+
+/** Candidates only. Does not register them into config. */
+export function discoverReferenceSources(home: string): GroundingSource[] {
+  const repos = listChildDirs(join(home, 'source', 'ref'))
+    .filter((dir) => isGitRepo(dir))
+    .map((dir) => candidate(dir, 'local-repo'));
+  const docs = listChildDirs(join(home, 'docs', 'ref'))
+    .map((dir) => candidate(dir, 'local-docs'));
+  return [...repos, ...docs];
+}
+
+export function sourceStatus(source: GroundingSource): GroundingSourceStatus {
+  if (source.kind !== 'local-repo' || !source.path) {
+    const status: GroundingSourceStatus = { id: source.id, kind: source.kind, measured: false };
+    debug.log('grounding.sources', 'status', { id: source.id, behind: 'unknown', dirty: false });
+    return status;
+  }
+  const measured = measureLocalRepo(source.path);
+  if (!measured) {
+    const status: GroundingSourceStatus = {
+      id: source.id,
+      kind: source.kind,
+      behind: 'unknown',
+      dirty: false,
+      measured: false,
+    };
+    debug.log('grounding.sources', 'status', { id: source.id, behind: 'unknown', dirty: false });
+    return status;
+  }
+  const status: GroundingSourceStatus = {
+    id: source.id,
+    kind: source.kind,
+    branch: measured.branch,
+    lastCommitAt: measured.lastCommitAt,
+    dirty: measured.dirty,
+    behind: measured.behind,
+    measured: true,
+  };
+  debug.log('grounding.sources', 'status', {
+    id: source.id,
+    behind: measured.behind,
+    dirty: measured.dirty,
+  });
+  return status;
+}
+
+function candidate(dir: string, kind: 'local-repo' | 'local-docs'): GroundingSource {
+  return { id: basename(dir), kind, path: dir, sync: 'manual' };
+}
+
+function listChildDirs(root: string): string[] {
+  if (!existsSync(root)) return [];
+  let names: string[];
+  try {
+    names = readdirSync(root);
+  } catch {
+    return [];
+  }
+  return names
+    .map((name) => join(root, name))
+    .filter((dir) => {
+      try { return statSync(dir).isDirectory(); } catch { return false; }
+    })
+    .sort();
+}
+
+function isGitRepo(dir: string): boolean {
+  return existsSync(join(dir, '.git'));
+}
+
+function normalizeInput(input: GroundingSourceInput): GroundingSource {
+  const path = input.path?.trim() || undefined;
+  const url = input.url?.trim() || undefined;
+  const kind = input.kind ?? inferKind(path, url);
+  const id = (input.id?.trim() || defaultId(path, url));
+  if (!id) throw new GroundingSourceError('missing id');
+  if (!GROUNDING_SOURCE_KINDS.includes(kind)) throw new GroundingSourceError(`unknown kind: ${String(kind)}`);
+  const source: GroundingSource = {
+    id,
+    kind,
+    sync: input.sync ?? 'manual',
+    ...(path ? { path } : {}),
+    ...(url ? { url } : {}),
+    ...(input.tags && input.tags.length > 0 ? { tags: [...input.tags] } : {}),
+    ...(input.mirror === true ? { mirror: true } : {}),
+  };
+  return source;
+}
+
+function inferKind(path: string | undefined, url: string | undefined): GroundingSourceKind {
+  if (url && !path) return 'url';
+  if (path && isGitRepo(path)) return 'local-repo';
+  if (path) return 'local-docs';
+  return 'url';
+}
+
+function defaultId(path: string | undefined, url: string | undefined): string {
+  if (path) return basename(path);
+  if (url) {
+    try { return new URL(url).hostname || url; } catch { return url; }
+  }
+  return '';
+}
+
+function cloneSource(source: GroundingSource): GroundingSource {
+  return {
+    ...source,
+    ...(source.sync && typeof source.sync === 'object'
+      ? { sync: { beforeUse: { maxAgeHours: source.sync.beforeUse.maxAgeHours } } }
+      : {}),
+    ...(source.tags ? { tags: [...source.tags] } : {}),
+    ...(source.mirror === true ? { mirror: true } : {}),
+  };
+}
+
+interface MeasuredRepo {
+  branch?: string;
+  lastCommitAt?: string;
+  dirty: boolean;
+  behind: number | 'unknown';
+}
+
+function measureLocalRepo(repoPath: string): MeasuredRepo | undefined {
+  if (!existsSync(repoPath)) return undefined;
+  const branch = git(repoPath, ['rev-parse', '--abbrev-ref', 'HEAD']);
+  const committedAt = git(repoPath, ['log', '-1', '--format=%cI']);
+  const porcelain = git(repoPath, ['status', '--porcelain']);
+  if (branch === undefined && committedAt === undefined && porcelain === undefined) return undefined;
+  const dirty = (porcelain ?? '').trim().length > 0;
+  return {
+    ...(branch?.trim() ? { branch: branch.trim() } : {}),
+    ...(committedAt?.trim() ? { lastCommitAt: committedAt.trim() } : {}),
+    dirty,
+    behind: commitsBehind(repoPath, branch?.trim()),
+  };
+}
+
+/** Local refs only. `git rev-list` does not contact a remote. */
+function commitsBehind(repoPath: string, branch: string | undefined): number | 'unknown' {
+  if (!branch || branch === 'HEAD') return 'unknown';
+  const upstream = git(repoPath, ['rev-parse', '--abbrev-ref', '--symbolic-full-name', '@{upstream}']);
+  if (!upstream?.trim()) return 'unknown';
+  const count = git(repoPath, ['rev-list', '--count', `HEAD..${upstream.trim()}`]);
+  if (count === undefined) return 'unknown';
+  const n = Number(count.trim());
+  return Number.isFinite(n) ? n : 'unknown';
+}
+
+function git(repoPath: string, args: string[]): string | undefined {
+  const result = spawnSync('git', ['-C', repoPath, ...args], {
+    encoding: 'utf8',
+    timeout: 10_000,
+  });
+  if (result.status !== 0) return undefined;
+  return result.stdout ?? '';
+}

package/src/grounding/token.ts

@@ -0,0 +1,121 @@
+/** ⭐ 원격 그라운딩 토큰(P13 · 🅢 토큰·주입 / 🅣 엔드포인트 · 채널 합의 2026-09-26).
+ *
+ *  Pod 는 호스트 우주를 «직접» 읽지 않는다(4우주·최소 자격). 대신 호스트 `POST /v1/grounding/query` 에
+ *  «질의 → 인용»만 묻는다. 그 문을 여는 것이 이 토큰이다.
+ *  - 모양: `base64url(payload).base64url(HMAC-SHA256)` · payload = `{v:1, runId, job, scope, exp}`.
+ *    scope 는 `'grounding'` · `'llm-credential'` · `'gh-credential'` — 같은 서명·검증·회수. 문은 scope 를 엄격히 가른다.
+ *  - 상태 없는 검증 — 엔드포인트는 `verifyGroundingToken` 하나만 부른다.
+ *  - 키: 비밀 백엔드 `grounding/hmac`(없으면 처음 발급 때 무작위 32바이트로 만든다) — 호스트 밖으로 안 나간다.
+ *  - 수명: `exp`(Job 기한) ⊕ 조기 회수 `revokeGroundingRun(runId)`(Job 이 끝나면 호스트가 부른다).
+ *  ⛔ 토큰·키 값은 로그·원장에 싣지 않는다 — runId·job·exp·거절 사유만.
+ */
+import { createHmac, randomBytes, timingSafeEqual } from 'node:crypto';
+import { appendFileSync, existsSync, mkdirSync, readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { debug } from '../debug/log.js';
+import { getElanousConfigDir } from '../elanous-config-dir.js';
+
+export const GROUNDING_TOKEN_ENV = 'ELANOUS_GROUNDING_TOKEN';
+export const GROUNDING_URL_ENV = 'ELANOUS_GROUNDING_URL';
+export const GROUNDING_HMAC_SECRET_ID = 'grounding/hmac';
+
+export const GROUNDING_TOKEN_SCOPES = ['grounding', 'llm-credential', 'gh-credential'] as const;
+export type GroundingTokenScope = (typeof GROUNDING_TOKEN_SCOPES)[number];
+
+export interface GroundingClaims {
+  readonly runId: string;
+  readonly job: string;
+  readonly scope: GroundingTokenScope;
+  /** GitHub credential relay only: full owner/repository bound by the host at issuance. */
+  readonly repository?: string;
+  readonly exp: number;
+}
+
+export type GroundingVerifyResult =
+  | ({ readonly ok: true } & GroundingClaims)
+  | { readonly ok: false; readonly reason: 'malformed' | 'bad-signature' | 'expired' | 'revoked' | 'scope' | 'no-key' };
+
+export interface GroundingTokenDeps {
+  /** 서명 키(원문). 생략하면 비밀 백엔드에서 읽고, 없으면 만든다(발급 쪽만). */
+  readonly key?: () => Promise<string | undefined>;
+  readonly now?: () => number;
+  readonly revokedPath?: string;
+}
+
+function revokedPathOf(deps: GroundingTokenDeps): string {
+  return deps.revokedPath ?? join(getElanousConfigDir(), 'grounding', 'revoked.jsonl');
+}
+
+async function readKey(create: boolean): Promise<string | undefined> {
+  const { getSecretAsync, setSecretAsync } = await import('../nexus/config/secrets/index.js');
+  const existing = await getSecretAsync(GROUNDING_HMAC_SECRET_ID);
+  if (existing || !create) return existing;
+  const fresh = randomBytes(32).toString('base64url');
+  await setSecretAsync(GROUNDING_HMAC_SECRET_ID, fresh);
+  debug.log('grounding.token', 'key-created', { secretId: GROUNDING_HMAC_SECRET_ID });
+  return fresh;
+}
+
+function sign(payload: string, key: string): string {
+  return createHmac('sha256', key).update(payload).digest('base64url');
+}
+
+export async function mintGroundingToken(
+  claims: { runId: string; job: string; ttlMs: number; scope?: GroundingTokenScope; repository?: string },
+  deps: GroundingTokenDeps = {},
+): Promise<{ token: string; exp: number }> {
+  const key = await (deps.key ?? (() => readKey(true)))();
+  if (!key) throw new Error('grounding: 서명 키를 만들 수 없다(비밀 백엔드)');
+  const scope: GroundingTokenScope = claims.scope ?? 'grounding';
+  if (claims.repository !== undefined && (scope !== 'gh-credential' || !/^[a-zA-Z0-9_.-]+\/[a-zA-Z0-9_.-]+$/.test(claims.repository) || claims.repository.split('/').some((part) => part === '.' || part === '..'))) {
+    throw new Error('grounding: invalid credential repository');
+  }
+  const exp = (deps.now ?? Date.now)() + claims.ttlMs;
+  const payload = Buffer.from(JSON.stringify({ v: 1, runId: claims.runId, job: claims.job, scope, ...(scope === 'gh-credential' ? { repository: claims.repository } : {}), exp })).toString('base64url');
+  debug.log('grounding.token', 'minted', { runId: claims.runId, job: claims.job, scope, exp });
+  return { token: `${payload}.${sign(payload, key)}`, exp };
+}
+
+/** 그라운딩 문은 scope `'grounding'` 만 받는다. 자격 증명 scope 는 `expectedScope` 로 따로 연다. */
+export async function verifyGroundingToken(
+  token: string,
+  deps: GroundingTokenDeps & { readonly expectedScope?: GroundingTokenScope } = {},
+): Promise<GroundingVerifyResult> {
+  const reject = (reason: Extract<GroundingVerifyResult, { ok: false }>['reason'], runId?: string): GroundingVerifyResult => {
+    debug.log('grounding.token', 'rejected', { reason, ...(runId ? { runId } : {}) });
+    return { ok: false, reason };
+  };
+  const parts = token.trim().split('.');
+  if (parts.length !== 2 || !parts[0] || !parts[1]) return reject('malformed');
+  const key = await (deps.key ?? (() => readKey(false)))();
+  if (!key) return reject('no-key');
+  const want = Buffer.from(sign(parts[0], key));
+  const got = Buffer.from(parts[1]);
+  if (want.length !== got.length || !timingSafeEqual(want, got)) return reject('bad-signature');
+  let claims: Partial<GroundingClaims> & { v?: number };
+  try { claims = JSON.parse(Buffer.from(parts[0], 'base64url').toString('utf8')); } catch { return reject('malformed'); }
+  if (claims.v !== 1 || typeof claims.runId !== 'string' || typeof claims.job !== 'string' || typeof claims.exp !== 'number') return reject('malformed');
+  const expected: GroundingTokenScope = deps.expectedScope ?? 'grounding';
+  if (claims.scope !== expected) return reject('scope', claims.runId);
+  if (expected === 'gh-credential' && claims.repository !== undefined && (typeof claims.repository !== 'string' || !/^[a-zA-Z0-9_.-]+\/[a-zA-Z0-9_.-]+$/.test(claims.repository) || claims.repository.split('/').some((part) => part === '.' || part === '..'))) return reject('malformed', claims.runId);
+  if ((deps.now ?? Date.now)() >= claims.exp) return reject('expired', claims.runId);
+  if (isRevoked(claims.runId, deps)) return reject('revoked', claims.runId);
+  return { ok: true, runId: claims.runId, job: claims.job, scope: expected, ...(expected === 'gh-credential' && claims.repository !== undefined ? { repository: claims.repository } : {}), exp: claims.exp };
+}
+
+/** Job 이 끝나면 호스트가 부른다 — 그 런의 토큰은 기한 전이라도 더는 안 통한다. */
+export function revokeGroundingRun(runId: string, deps: GroundingTokenDeps = {}): void {
+  const path = revokedPathOf(deps);
+  mkdirSync(dirname(path), { recursive: true });
+  appendFileSync(path, `${JSON.stringify({ runId, at: (deps.now ?? Date.now)() })}\n`, { mode: 0o600 });
+  debug.log('grounding.token', 'revoked', { runId });
+}
+
+function isRevoked(runId: string, deps: GroundingTokenDeps): boolean {
+  const path = revokedPathOf(deps);
+  if (!existsSync(path)) return false;
+  return readFileSync(path, 'utf8').split('\n').some((line) => {
+    if (!line) return false;
+    try { return (JSON.parse(line) as { runId?: string }).runId === runId; } catch { return false; }
+  });
+}