@git-stunts/git-warp 10.4.2 → 10.8.0

package/SECURITY.md

@@ -25,6 +25,94 @@ The `GitGraphAdapter` validates all ref arguments to prevent injection attacks:
 - **Bitmap Indexing**: Sharded Roaring Bitmap indexes enable O(1) lookups without loading entire graphs
 - **Delimiter Safety**: Uses ASCII Record Separator (`\x1E`) to prevent message collision
 
-## 🐞 Reporting a Vulnerability
+## Sync Authentication (SHIELD)
+
+### Overview
+
+The HTTP sync protocol supports optional HMAC-SHA256 request signing with replay protection. When enabled, every sync request must carry a valid signature computed over a canonical payload that includes the request body, timestamp, and a unique nonce.
+
+### Threat Model
+
+**Protected against:**
+- Unauthorized sync requests from unknown peers
+- Replay attacks (nonce-based, with 5-minute TTL window)
+- Request body tampering (HMAC covers body SHA-256)
+- Timing attacks on signature comparison (`timingSafeEqual`)
+
+**Not protected against:**
+- Compromised shared secrets (rotate keys immediately if leaked)
+- Denial-of-service (body size limits provide basic protection, but no rate limiting)
+- Man-in-the-middle without TLS (use HTTPS in production)
+
+### Authentication Flow
+
+1. Client computes SHA-256 of request body
+2. Client builds canonical payload: `warp-v1|KEY_ID|METHOD|PATH|TIMESTAMP|NONCE|CONTENT_TYPE|BODY_SHA256`
+3. Client computes HMAC-SHA256 of canonical payload using shared secret
+4. Client sends 5 auth headers: `x-warp-sig-version`, `x-warp-key-id`, `x-warp-timestamp`, `x-warp-nonce`, `x-warp-signature`
+5. Server validates header formats (cheap checks first)
+6. Server checks clock skew (default: 5 minutes)
+7. Server reserves nonce atomically (prevents replay)
+8. Server resolves key by key-id
+9. Server recomputes HMAC and compares with constant-time equality
+
+### Enforcement Modes
+
+- **`enforce`** (default): Rejects requests that fail authentication with appropriate HTTP status codes (400/401/403). No request details leak in error responses.
+- **`log-only`**: Logs authentication failures but allows requests through. Use during rollout to identify issues before enforcing.
+
+### Error Response Hygiene
+
+External error responses use coarse status codes and generic reason strings:
+- `400` — Malformed headers (version, timestamp, nonce, signature format)
+- `401` — Missing auth headers, unknown key-id, invalid signature
+- `403` — Expired timestamp, replayed nonce
+
+Detailed diagnostics (exact failure reason, key-id, peer info) are sent to the structured logger only.
+
+### Nonce Cache and Restart Semantics
+
+The nonce cache is an in-memory LRU (default capacity: 100,000 entries). On server restart, the cache is empty. This means:
+- Nonces from before the restart can be replayed within the 5-minute clock skew window
+- This is an accepted trade-off for simplicity; persistent nonce storage is not implemented in v1
+- For higher security, keep the clock skew window small and use TLS
+
+### Key Rotation
+
+Key management uses a key-id system for zero-downtime rotation:
+
+1. Add the new key-id and secret to the server's `keys` map
+2. Deploy the server
+3. Update clients to use the new key-id
+4. Remove the old key-id from the server's `keys` map
+5. Deploy again
+
+Multiple key-ids can coexist indefinitely.
+
+### Configuration
+
+**Server (`serve()`):**
+```js
+await graph.serve({
+  port: 3000,
+  httpPort: new NodeHttpAdapter(),
+  auth: {
+    keys: { default: 'your-shared-secret' },
+    mode: 'enforce', // or 'log-only'
+  },
+});
+```
+
+**Client (`syncWith()`):**
+```js
+await graph.syncWith('http://peer:3000', {
+  auth: {
+    secret: 'your-shared-secret',
+    keyId: 'default',
+  },
+});
+```
+
+## Reporting a Vulnerability
 
 If you discover a security vulnerability, please send an e-mail to [james@flyingrobots.dev](mailto:james@flyingrobots.dev).

package/bin/presenters/index.js

@@ -0,0 +1,208 @@
+/**
+ * Unified output dispatcher for CLI commands.
+ *
+ * Replaces the 112-line emit() function in warp-graph.js with clean
+ * format dispatch: text, json, ndjson — plus view mode handling.
+ */
+
+import fs from 'node:fs';
+import process from 'node:process';
+
+import { stripAnsi } from '../../src/visualization/utils/ansi.js';
+import { renderInfoView } from '../../src/visualization/renderers/ascii/info.js';
+import { renderCheckView } from '../../src/visualization/renderers/ascii/check.js';
+import { renderHistoryView } from '../../src/visualization/renderers/ascii/history.js';
+import { renderPathView } from '../../src/visualization/renderers/ascii/path.js';
+import { renderMaterializeView } from '../../src/visualization/renderers/ascii/materialize.js';
+import { renderSeekView } from '../../src/visualization/renderers/ascii/seek.js';
+
+import { stableStringify, compactStringify, sanitizePayload } from './json.js';
+import {
+  renderInfo,
+  renderQuery,
+  renderPath,
+  renderCheck,
+  renderHistory,
+  renderError,
+  renderMaterialize,
+  renderInstallHooks,
+  renderSeek,
+} from './text.js';
+
+// ── Color control ────────────────────────────────────────────────────────────
+
+/**
+ * Determines whether ANSI color codes should be stripped from output.
+ *
+ * Precedence: FORCE_COLOR=0 (strip) > FORCE_COLOR!='' (keep) > NO_COLOR > !isTTY > CI.
+ * @returns {boolean}
+ */
+export function shouldStripColor() {
+  if (process.env.FORCE_COLOR === '0') {
+    return true;
+  }
+  if (process.env.FORCE_COLOR !== undefined && process.env.FORCE_COLOR !== '') {
+    return false;
+  }
+  if (process.env.NO_COLOR !== undefined) {
+    return true;
+  }
+  if (!process.stdout.isTTY) {
+    return true;
+  }
+  if (process.env.CI !== undefined) {
+    return true;
+  }
+  return false;
+}
+
+// ── Text renderer map ────────────────────────────────────────────────────────
+
+/** @type {Map<string, function(*): string>} */
+const TEXT_RENDERERS = new Map(/** @type {[string, function(*): string][]} */ ([
+  ['info', renderInfo],
+  ['query', renderQuery],
+  ['path', renderPath],
+  ['check', renderCheck],
+  ['history', renderHistory],
+  ['materialize', renderMaterialize],
+  ['seek', renderSeek],
+  ['install-hooks', renderInstallHooks],
+]));
+
+/** @type {Map<string, function(*): string>} */
+const VIEW_RENDERERS = new Map(/** @type {[string, function(*): string][]} */ ([
+  ['info', renderInfoView],
+  ['check', renderCheckView],
+  ['history', renderHistoryView],
+  ['path', renderPathView],
+  ['materialize', renderMaterializeView],
+  ['seek', renderSeekView],
+]));
+
+// ── HTML export ──────────────────────────────────────────────────────────────
+
+/**
+ * Wraps SVG content in a minimal HTML document and writes it to disk.
+ * @param {string} filePath
+ * @param {string} svgContent
+ */
+function writeHtmlExport(filePath, svgContent) {
+  const html = `<!DOCTYPE html>\n<html><head><meta charset="utf-8"><title>git-warp</title></head><body>\n${svgContent}\n</body></html>`;
+  fs.writeFileSync(filePath, html);
+}
+
+// ── SVG / HTML file export ───────────────────────────────────────────────────
+
+/**
+ * Handles svg:PATH and html:PATH view modes for commands that carry _renderedSvg.
+ * @param {*} payload
+ * @param {string} view
+ * @returns {boolean} true if handled
+ */
+function handleFileExport(payload, view) {
+  if (typeof view === 'string' && view.startsWith('svg:')) {
+    const svgPath = view.slice(4);
+    if (!payload._renderedSvg) {
+      process.stderr.write('No graph data — skipping SVG export.\n');
+    } else {
+      fs.writeFileSync(svgPath, payload._renderedSvg);
+      process.stderr.write(`SVG written to ${svgPath}\n`);
+    }
+    return true;
+  }
+  if (typeof view === 'string' && view.startsWith('html:')) {
+    const htmlPath = view.slice(5);
+    if (!payload._renderedSvg) {
+      process.stderr.write('No graph data — skipping HTML export.\n');
+    } else {
+      writeHtmlExport(htmlPath, payload._renderedSvg);
+      process.stderr.write(`HTML written to ${htmlPath}\n`);
+    }
+    return true;
+  }
+  return false;
+}
+
+// ── Output helpers ───────────────────────────────────────────────────────────
+
+/**
+ * Writes text to stdout, optionally stripping ANSI codes.
+ * @param {string} text
+ * @param {boolean} strip
+ */
+function writeText(text, strip) {
+  process.stdout.write(strip ? stripAnsi(text) : text);
+}
+
+// ── Main dispatcher ──────────────────────────────────────────────────────────
+
+/**
+ * Writes a command result to stdout/stderr in the requested format.
+ *
+ * @param {*} payload - Command result payload
+ * @param {{format: string, command: string, view: string|null|boolean}} options
+ */
+export function present(payload, { format, command, view }) {
+  // Error payloads always go to stderr as plain text
+  if (payload?.error) {
+    process.stderr.write(renderError(payload));
+    return;
+  }
+
+  // JSON: sanitize + pretty-print
+  if (format === 'json') {
+    process.stdout.write(`${stableStringify(sanitizePayload(payload))}\n`);
+    return;
+  }
+
+  // NDJSON: sanitize + compact single line
+  if (format === 'ndjson') {
+    process.stdout.write(`${compactStringify(sanitizePayload(payload))}\n`);
+    return;
+  }
+
+  // Text with view mode
+  if (view) {
+    presentView(payload, command, view);
+    return;
+  }
+
+  // Plain text
+  const renderer = TEXT_RENDERERS.get(command);
+  if (renderer) {
+    writeText(renderer(payload), shouldStripColor());
+  } else {
+    // Fallback for unknown commands
+    process.stdout.write(`${stableStringify(sanitizePayload(payload))}\n`);
+  }
+}
+
+/**
+ * Handles --view output dispatch (ASCII view, SVG file, HTML file).
+ * @param {*} payload
+ * @param {string} command
+ * @param {string|boolean} view
+ */
+function presentView(payload, command, view) {
+  const strip = shouldStripColor();
+
+  // File exports: svg:PATH, html:PATH
+  if (handleFileExport(payload, /** @type {string} */ (view))) {
+    return;
+  }
+
+  // query is special: uses pre-rendered _renderedAscii
+  if (command === 'query') {
+    writeText(`${payload._renderedAscii ?? ''}\n`, strip);
+    return;
+  }
+
+  // Dispatch to view renderer
+  const viewRenderer = VIEW_RENDERERS.get(command);
+  if (viewRenderer) {
+    writeText(viewRenderer(payload), strip);
+  } else {
+    writeText(`${stableStringify(sanitizePayload(payload))}\n`, strip);
+  }
+}

package/bin/presenters/json.js

@@ -0,0 +1,66 @@
+/**
+ * JSON / NDJSON serialization utilities for CLI output.
+ *
+ * - stableStringify: pretty-printed, sorted-key JSON (--json)
+ * - compactStringify: single-line, sorted-key JSON (--ndjson)
+ * - sanitizePayload: strips internal _-prefixed keys before serialization
+ */
+
+/**
+ * Recursively sorts object keys for deterministic JSON output.
+ * @param {*} input
+ * @returns {*}
+ */
+function normalize(input) {
+  if (Array.isArray(input)) {
+    return input.map(normalize);
+  }
+  if (input && typeof input === 'object') {
+    /** @type {Record<string, *>} */
+    const sorted = {};
+    for (const key of Object.keys(input).sort()) {
+      sorted[key] = normalize(input[key]);
+    }
+    return sorted;
+  }
+  return input;
+}
+
+/**
+ * Pretty-printed JSON with sorted keys (2-space indent).
+ * @param {*} value
+ * @returns {string}
+ */
+export function stableStringify(value) {
+  return JSON.stringify(normalize(value), null, 2);
+}
+
+/**
+ * Single-line JSON with sorted keys (no indent).
+ * @param {*} value
+ * @returns {string}
+ */
+export function compactStringify(value) {
+  return JSON.stringify(normalize(value));
+}
+
+/**
+ * Shallow-clones a payload, removing all top-level underscore-prefixed keys.
+ * These are internal rendering artifacts (e.g. _renderedSvg, _renderedAscii)
+ * that should not leak into JSON/NDJSON output.
+ * @param {*} payload
+ * @returns {*}
+ */
+export function sanitizePayload(payload) {
+  if (!payload || typeof payload !== 'object' || Array.isArray(payload)) {
+    return payload;
+  }
+  /** @type {Record<string, *>} */
+  const clean = {};
+  for (const key of Object.keys(payload)) {
+    if (!key.startsWith('_')) {
+      clean[key] = payload[key];
+    }
+  }
+  return clean;
+}