@graphorin/cli 0.6.1 → 0.7.0

package/src/commands/audit.ts

@@ -0,0 +1,256 @@
+/**
+ * `graphorin audit` - operate on the tamper-evident audit log
+ * (`audit.db`).
+ *
+ * Surface (per Phase 15 § Audit):
+ *
+ *  - `graphorin audit verify` - full hash chain integrity check.
+ *  - `graphorin audit prune --before <date>` - drop entries older than
+ *    a cutoff while preserving the surviving suffix's chain integrity.
+ *  - `graphorin audit export --to <file>` - stream every entry as JSONL.
+ *
+ * The CLI opens `audit.db` through the framework default binding
+ * registered by `@graphorin/server` (`ensureStoreAuditBinding()`); it
+ * never re-implements the cipher path.
+ *
+ * @packageDocumentation
+ */
+
+import { writeFile } from 'node:fs/promises';
+import { dirname, isAbsolute, resolve } from 'node:path';
+import process from 'node:process';
+
+import {
+  type AuditChainVerifyResult,
+  exportAudit,
+  openAuditDb,
+  type PruneAuditResult,
+  pruneAudit,
+  resolveSecret,
+  type SecretValue,
+  type StoredAuditEntry,
+  verifyAuditChain,
+} from '@graphorin/security';
+import { ensureStoreAuditBinding, parseServerConfig } from '@graphorin/server';
+
+import { EXIT_CODES } from '../internal/exit.js';
+import { loadConfig } from '../internal/load-config.js';
+import {
+  brand,
+  type CommonOutputOptions,
+  defaultPrintSink,
+  emitReport,
+  statusMarker,
+} from '../internal/output.js';
+
+/** @stable */
+export interface AuditCommonOptions extends CommonOutputOptions {
+  readonly config?: string;
+}
+
+/** @stable */
+export interface AuditVerifyResult {
+  readonly ok: boolean;
+  readonly path: string;
+  readonly entries: number;
+  readonly broken?: { readonly seq: number; readonly expected: string; readonly actual: string };
+}
+
+/**
+ * `graphorin audit verify` - replay the chain and report the first
+ * broken link (if any).
+ *
+ * @stable
+ */
+export async function runAuditVerify(options: AuditCommonOptions = {}): Promise<AuditVerifyResult> {
+  const ctx = await openAuditContext(options);
+  try {
+    const result: AuditChainVerifyResult = await verifyAuditChain(ctx.auditDb);
+    const out: AuditVerifyResult = result.ok
+      ? Object.freeze({ ok: true, path: ctx.auditDb.path, entries: result.count })
+      : Object.freeze({
+          ok: false,
+          path: ctx.auditDb.path,
+          entries: 0,
+          broken: Object.freeze({
+            seq: result.brokenAt,
+            expected: result.expected,
+            actual: result.actual,
+          }),
+        });
+    emitReport(options, out, () => {
+      const print = options.print ?? defaultPrintSink;
+      if (out.ok) {
+        print(
+          brand(`audit chain ${statusMarker('ok')} (${out.entries} entries verified, ${out.path})`),
+        );
+        return;
+      }
+      print(brand(`audit chain ${statusMarker('fail')} broken at seq ${out.broken?.seq}`));
+      print(`  expected prevHash=${out.broken?.expected}`);
+      print(`  actual prevHash=${out.broken?.actual}`);
+    });
+    // W-002: the exit code is part of the machine contract - it must be
+    // set OUTSIDE the human() callback (emitReport skips that callback
+    // entirely under --json, so a broken chain exited 0 for exactly the
+    // CI consumers the flag exists for).
+    if (!out.ok) process.exitCode = EXIT_CODES.RECOVERABLE_FAILURE;
+    return out;
+  } finally {
+    await ctx.close();
+  }
+}
+
+/** @stable */
+export interface AuditPruneOptions extends AuditCommonOptions {
+  /**
+   * ISO-8601 date / `YYYY-MM-DD` / millis-since-epoch. The helper
+   * drops entries older than this cutoff.
+   */
+  readonly before: string;
+  /** Minimum number of entries that must survive. Default `1`. */
+  readonly retain?: number;
+}
+
+/** @stable */
+export async function runAuditPrune(options: AuditPruneOptions): Promise<PruneAuditResult> {
+  const cutoff = parseCutoff(options.before);
+  const ctx = await openAuditContext(options);
+  try {
+    const result = await pruneAudit(ctx.auditDb, {
+      before: cutoff,
+      ...(options.retain !== undefined ? { retain: options.retain } : {}),
+    });
+    emitReport(options, result, () => {
+      const print = options.print ?? defaultPrintSink;
+      if (result.deleted === 0) {
+        print(
+          brand(`no audit entries qualified for prune (cutoff=${new Date(cutoff).toISOString()}).`),
+        );
+        return;
+      }
+      print(
+        brand(
+          `pruned ${result.deleted} audit entries (cutoff=${new Date(cutoff).toISOString()}, surviving from seq=${result.firstSurvivingSeq ?? '<empty>'})`,
+        ),
+      );
+      // W-062: the prune re-rooted the chain - every Merkle checkpoint
+      // signed BEFORE it now fails verification by design.
+      print(
+        brand(
+          'note: Merkle checkpoints signed before this prune no longer verify (the chain was re-rooted). ' +
+            'Sign and distribute a fresh checkpoint now (signAuditCheckpoint) and mark the old anchors superseded - ' +
+            'see the "Retention and anchoring" runbook in the security guide.',
+        ),
+      );
+    });
+    return result;
+  } finally {
+    await ctx.close();
+  }
+}
+
+/** @stable */
+export interface AuditExportOptions extends AuditCommonOptions {
+  readonly to: string;
+  readonly fromSeq?: number;
+  readonly toSeq?: number;
+}
+
+/** @stable */
+export interface AuditExportResult {
+  readonly path: string;
+  readonly rows: number;
+}
+
+/**
+ * `graphorin audit export --to <file>` - stream every entry as JSONL.
+ *
+ * @stable
+ */
+export async function runAuditExport(options: AuditExportOptions): Promise<AuditExportResult> {
+  const cwd = process.cwd();
+  const targetPath = isAbsolute(options.to) ? options.to : resolve(cwd, options.to);
+  const ctx = await openAuditContext(options);
+  try {
+    const lines: string[] = [];
+    const { rows } = await exportAudit(ctx.auditDb, {
+      writer: { write: (line: string) => void lines.push(line) },
+      ...(options.fromSeq !== undefined ? { fromSeq: options.fromSeq } : {}),
+      ...(options.toSeq !== undefined ? { toSeq: options.toSeq } : {}),
+    });
+    await writeFile(targetPath, lines.join(''), { mode: 0o600 });
+    const out: AuditExportResult = Object.freeze({ path: targetPath, rows });
+    emitReport(options, out, () => {
+      const print = options.print ?? defaultPrintSink;
+      print(brand(`exported ${rows} audit entries to ${targetPath} (mode 0600).`));
+    });
+    return out;
+  } finally {
+    await ctx.close();
+  }
+}
+
+interface AuditContext {
+  readonly auditDb: Awaited<ReturnType<typeof openAuditDb>>;
+  readonly path: string;
+  readonly close: () => Promise<void>;
+}
+
+async function openAuditContext(options: AuditCommonOptions): Promise<AuditContext> {
+  const loaded = await loadConfig(options.config);
+  const config = parseServerConfig(loaded.config);
+  if (!config.audit.enabled) {
+    throw new Error(
+      '[graphorin/cli] this command requires audit.enabled = true in the resolved config.',
+    );
+  }
+  const passphraseRef = config.audit.passphraseRef ?? config.storage.encryption.passphraseRef;
+  if (passphraseRef === undefined) {
+    throw new Error(
+      `[graphorin/cli] audit.enabled is true but no audit.passphraseRef (or storage.encryption.passphraseRef) is configured. audit.db is mandatory-encrypted by DEC-124.`,
+    );
+  }
+  let passphrase: SecretValue;
+  try {
+    passphrase = await resolveSecret(passphraseRef);
+  } catch (err) {
+    throw new Error(
+      `[graphorin/cli] failed to resolve audit passphrase '${passphraseRef}': ${(err as Error).message}`,
+      { cause: err },
+    );
+  }
+  const auditPath = config.audit.path ?? deriveAuditPath(config.storage.path);
+  ensureStoreAuditBinding();
+  const auditDb = await openAuditDb({
+    path: auditPath,
+    passphrase,
+    ...(config.audit.cipher !== undefined ? { cipher: config.audit.cipher } : {}),
+  });
+  return Object.freeze({
+    auditDb,
+    path: auditPath,
+    close: () => auditDb.close(),
+  });
+}
+
+function deriveAuditPath(storagePath: string): string {
+  const dir = dirname(storagePath);
+  return resolve(dir, 'audit.db');
+}
+
+function parseCutoff(input: string): number {
+  const numeric = Number(input);
+  if (Number.isFinite(numeric) && numeric > 0) return numeric;
+  const ms = Date.parse(input);
+  if (!Number.isFinite(ms)) {
+    throw new Error(
+      `[graphorin/cli] --before '${input}' is not a valid ISO date or epoch-ms value.`,
+    );
+  }
+  return ms;
+}
+
+// Internal type-only consumers - keep in scope so tree-shaking
+// preserves the entry point.
+void ((_e?: StoredAuditEntry) => undefined);

package/src/commands/auth.ts

@@ -0,0 +1,238 @@
+/**
+ * `graphorin auth` - outbound OAuth subsystem (e.g. for MCP servers).
+ *
+ * Surface (per Phase 15 § Auth):
+ *
+ *  - `graphorin auth login --server <url> [--device-flow]`
+ *  - `graphorin auth list`
+ *  - `graphorin auth refresh <id>`
+ *  - `graphorin auth revoke <id>`
+ *  - `graphorin auth status`
+ *
+ * Honours `GRAPHORIN_OFFLINE=1` - when set, every subcommand short-
+ * circuits with an explanatory message and exits `1` so CI pipelines
+ * see the failure.
+ *
+ * @packageDocumentation
+ */
+
+import {
+  getOAuthStatus,
+  type LoginInteractiveResult,
+  listOAuthSessions,
+  loginInteractive,
+  refreshOAuthSession,
+  revokeOAuthSession,
+} from '@graphorin/security';
+import { createSecretsStore, getActiveSecretsStore } from '@graphorin/security/secrets';
+import { EXIT_CODES } from '../internal/exit.js';
+import { checkOfflineModeBlocked } from '../internal/offline.js';
+import {
+  brand,
+  type CommonOutputOptions,
+  defaultPrintSink,
+  emitReport,
+  statusMarker,
+} from '../internal/output.js';
+import { openStoreContext } from '../internal/store-context.js';
+
+/**
+ * Resolve the CLI's secrets store for OAuth token persistence (SPL-1):
+ * the already-active store when one exists, else the default auto
+ * chain (keyring → encrypted-file → env). Best-effort - a store
+ * failure degrades to the in-memory-only pre-SPL-1 behavior instead of
+ * blocking the auth command.
+ */
+async function resolveAuthSecretsStore(): Promise<
+  import('@graphorin/core/contracts').SecretsStore | undefined
+> {
+  try {
+    return getActiveSecretsStore() ?? (await createSecretsStore({}));
+  } catch {
+    return undefined;
+  }
+}
+
+/** @stable */
+export interface AuthCommonOptions extends CommonOutputOptions {
+  readonly config?: string;
+}
+
+/** @stable */
+export interface AuthLoginOptions extends AuthCommonOptions {
+  readonly serverUrl: string;
+  readonly serverId?: string;
+  readonly scope?: string;
+  readonly deviceFlow?: boolean;
+  /**
+   * Optional pre-existing client identifier - skips Dynamic Client
+   * Registration when supplied.
+   */
+  readonly clientId?: string;
+}
+
+/** @stable */
+export async function runAuthLogin(options: AuthLoginOptions): Promise<LoginInteractiveResult> {
+  if (
+    !checkOfflineModeBlocked('auth login', {
+      ...(options.print !== undefined ? { print: options.print } : {}),
+    })
+  ) {
+    process.exit(EXIT_CODES.RECOVERABLE_FAILURE);
+  }
+  const ctx = await openStoreContext({
+    ...(options.config !== undefined ? { config: options.config } : {}),
+  });
+  try {
+    const serverId = options.serverId ?? deriveServerId(options.serverUrl);
+    const secretsStore = await resolveAuthSecretsStore();
+    const result = await loginInteractive({
+      serverId,
+      serverUrl: options.serverUrl,
+      storage: ctx.store.oauthServers,
+      ...(secretsStore === undefined ? {} : { secretsStore }),
+      ...(options.deviceFlow !== undefined ? { deviceFlow: options.deviceFlow } : {}),
+      ...(options.scope !== undefined ? { scope: options.scope } : {}),
+      ...(options.clientId !== undefined ? { clientId: options.clientId } : {}),
+    });
+    emitReport(options, result.status, () => {
+      const print = options.print ?? defaultPrintSink;
+      print(brand(`oauth login ${statusMarker('ok')} (server=${result.status.serverId})`));
+      print(`  status: ${result.status.status}`);
+      print(`  expiresAt: ${result.status.expiresAt ?? '-'}`);
+    });
+    return result;
+  } finally {
+    await ctx.close();
+  }
+}
+
+/** @stable */
+export interface AuthListOptions extends AuthCommonOptions {}
+
+/** @stable */
+export async function runAuthList(options: AuthListOptions = {}) {
+  const ctx = await openStoreContext({
+    ...(options.config !== undefined ? { config: options.config } : {}),
+  });
+  try {
+    const secretsStore = await resolveAuthSecretsStore();
+    const list = await listOAuthSessions(ctx.store.oauthServers, {
+      ...(secretsStore === undefined ? {} : { secretsStore }),
+    });
+    emitReport(options, list, () => {
+      const print = options.print ?? defaultPrintSink;
+      if (list.length === 0) {
+        print(brand('no OAuth sessions persisted.'));
+        return;
+      }
+      print(brand(`${list.length} OAuth session(s):`));
+      for (const s of list) {
+        const mark = s.status === 'expired' ? statusMarker('warn') : statusMarker('ok');
+        print(`  ${mark} ${s.serverId} (status=${s.status}, scope=${s.scope ?? '-'})`);
+      }
+    });
+    return list;
+  } finally {
+    await ctx.close();
+  }
+}
+
+/** @stable */
+export interface AuthRefreshOptions extends AuthCommonOptions {
+  readonly id: string;
+}
+
+/** @stable */
+export async function runAuthRefresh(options: AuthRefreshOptions) {
+  if (
+    !checkOfflineModeBlocked('auth refresh', {
+      ...(options.print !== undefined ? { print: options.print } : {}),
+    })
+  ) {
+    process.exit(EXIT_CODES.RECOVERABLE_FAILURE);
+  }
+  const ctx = await openStoreContext({
+    ...(options.config !== undefined ? { config: options.config } : {}),
+  });
+  try {
+    const secretsStore = await resolveAuthSecretsStore();
+    const session = await refreshOAuthSession(ctx.store.oauthServers, options.id, {
+      ...(secretsStore === undefined ? {} : { secretsStore }),
+    });
+    emitReport(options, { ok: true, id: options.id }, () => {
+      const print = options.print ?? defaultPrintSink;
+      print(
+        brand(
+          `oauth session '${options.id}' refreshed (expiresAt=${new Date(session.expiresAt ?? Date.now()).toISOString()})`,
+        ),
+      );
+    });
+    return session;
+  } finally {
+    await ctx.close();
+  }
+}
+
+/** @stable */
+export interface AuthRevokeOptions extends AuthCommonOptions {
+  readonly id: string;
+  readonly reason?: string;
+}
+
+/** @stable */
+export async function runAuthRevoke(options: AuthRevokeOptions): Promise<{ readonly ok: true }> {
+  const ctx = await openStoreContext({
+    ...(options.config !== undefined ? { config: options.config } : {}),
+  });
+  try {
+    const secretsStore = await resolveAuthSecretsStore();
+    await revokeOAuthSession(ctx.store.oauthServers, options.id, {
+      ...(secretsStore === undefined ? {} : { secretsStore }),
+      ...(options.reason !== undefined ? { reason: options.reason } : {}),
+    });
+    emitReport(options, { ok: true } as const, () => {
+      const print = options.print ?? defaultPrintSink;
+      print(brand(`oauth session '${options.id}' revoked.`));
+    });
+    return { ok: true };
+  } finally {
+    await ctx.close();
+  }
+}
+
+/** @stable */
+export async function runAuthStatus(options: AuthCommonOptions = {}) {
+  const ctx = await openStoreContext({
+    ...(options.config !== undefined ? { config: options.config } : {}),
+  });
+  try {
+    const secretsStore = await resolveAuthSecretsStore();
+    const status = await getOAuthStatus(ctx.store.oauthServers, {
+      ...(secretsStore === undefined ? {} : { secretsStore }),
+    });
+    emitReport(options, status, () => {
+      const print = options.print ?? defaultPrintSink;
+      print(
+        brand(
+          `oauth subsystem status: ${status.sessions.length} session(s), ${status.providers.length} strategy(ies)`,
+        ),
+      );
+      if (status.defaultStrategy !== null) {
+        print(brand(`default strategy: ${status.defaultStrategy.id}`));
+      }
+    });
+    return status;
+  } finally {
+    await ctx.close();
+  }
+}
+
+function deriveServerId(serverUrl: string): string {
+  try {
+    const u = new URL(serverUrl);
+    return u.host;
+  } catch {
+    return serverUrl;
+  }
+}