arceus-s 1.6.4

package/dist/server/validation.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Server-side input validation helpers.
+ *
+ * Convention: helpers throw BadRequestError (or its 403 subclass ForbiddenError)
+ * when user input fails validation. Existing route handlers wrap their bodies in
+ * try/catch and translate the error to res.status(err.status).json({error: err.message}).
+ * This pattern was chosen over an asyncHandler middleware to stay compatible with
+ * Express 4's non-propagation of async-thrown errors and to match the existing
+ * try/catch shape used throughout api.ts.
+ *
+ * Scope (this PR — U1 of the security remediation plan):
+ *   - assertString:      closes js/type-confusion-through-parameter-tampering (api.ts:1118)
+ *   - assertSafePath:    consolidates the path-traversal guard from api.ts:1067-1077
+ *                        for reuse across other path-injection findings (U2/U3)
+ *   - escapeRegExp:      utility for upcoming regex-injection fix at /api/grep (U5)
+ *
+ * Helpers added in later units (U3 git-clone hardening, U4 rate-limiting) live
+ * in this module too but are introduced with the dependency they require.
+ */
+import { type RateLimitRequestHandler } from 'express-rate-limit';
+/**
+ * Thrown by validation helpers when user input is rejected.
+ * Routes catch via existing try/catch and convert with err.status / err.message.
+ */
+export declare class BadRequestError extends Error {
+    readonly status: number;
+    constructor(message: string, status?: number);
+}
+export declare class ForbiddenError extends BadRequestError {
+    constructor(message: string);
+}
+/**
+ * Type guard for HTTP request parameters that must be a single string.
+ *
+ * Express's req.query and req.body parsers return `string | string[] | ParsedQs`
+ * for any field, but route handlers commonly cast to `string` and operate on
+ * `.length`. When the caller passes the same key twice (?x=a&x=b) the value
+ * arrives as an array, and a `.length` check intended for the string ends up
+ * counting array elements — bypassing length-based guards (CodeQL
+ * js/type-confusion-through-parameter-tampering, alert at api.ts:1118).
+ *
+ * @throws BadRequestError when value is not a string (array, object, undefined, etc.)
+ */
+export declare function assertString(value: unknown, fieldName: string): string;
+/**
+ * Resolve a user-supplied relative path against an allowed root and verify it
+ * stays inside that root. Mirrors the existing guard at api.ts:1067-1077.
+ *
+ * Returns the absolute resolved path. Rejects empty paths, null bytes, and
+ * paths that resolve outside the root (e.g., `../../../etc/passwd`).
+ *
+ * @throws BadRequestError when the path is empty or contains a null byte
+ * @throws ForbiddenError when the resolved path escapes the root
+ */
+export declare function assertSafePath(rawPath: string, root: string): string;
+/**
+ * Escape regex metacharacters in a user-supplied string so it can be safely
+ * embedded as a literal in `new RegExp(...)`. Used by /api/grep's literal mode
+ * and any future endpoint that constructs a regex from caller input.
+ */
+export declare function escapeRegExp(input: string): string;
+/**
+ * Project-specific subset of express-rate-limit options that callers may
+ * override. Intentionally narrow — `Partial<RateLimitOptions>` would let a
+ * caller pass `{ skip: () => true }` and silently disable limiting on a
+ * route. The two knobs below are sufficient for tests and any future
+ * legitimate per-route tuning.
+ */
+export interface RouteLimiterOverrides {
+    windowMs?: number;
+    /** Canonical name in express-rate-limit v8+. `max` is the deprecated alias. */
+    limit?: number;
+}
+/**
+ * Build a per-route rate-limit middleware with project-uniform defaults.
+ *
+ * Each call returns a NEW limiter instance — independent counters per route,
+ * so /api/file traffic doesn't push /api/grep into 429.
+ *
+ * Defaults:
+ *   - 60 requests per IP per minute
+ *   - draft-7 RateLimit-* response headers (no legacy X-RateLimit-* headers)
+ *   - 429 with a JSON body matching the project's `{ error: '...' }` shape
+ *   - passOnStoreError: store failures let the request through rather than
+ *     producing an HTML 500 from Express's default error handler
+ *   - keyGenerator: req.ip with a socket.remoteAddress fallback so abruptly
+ *     closed connections do not trigger ERR_ERL_UNDEFINED_IP_ADDRESS
+ *     (which would 500 the request via Express's default error handler).
+ *     The IP is passed through `ipKeyGenerator` so IPv6 addresses are
+ *     normalised to their /56 subnet — without this, each IPv6 address
+ *     gets its own counter and the limit is trivially bypassed (#1360).
+ *     Caller must wire `app.set('trust proxy', ...)` correctly — see
+ *     createServer in api.ts.
+ *
+ * Tests pass `{ windowMs: 100, limit: 3 }` to keep limiter tests fast and
+ * deterministic.
+ */
+export declare function createRouteLimiter(opts?: RouteLimiterOverrides): RateLimitRequestHandler;

package/dist/server/validation.js

@@ -0,0 +1,142 @@
+/**
+ * Server-side input validation helpers.
+ *
+ * Convention: helpers throw BadRequestError (or its 403 subclass ForbiddenError)
+ * when user input fails validation. Existing route handlers wrap their bodies in
+ * try/catch and translate the error to res.status(err.status).json({error: err.message}).
+ * This pattern was chosen over an asyncHandler middleware to stay compatible with
+ * Express 4's non-propagation of async-thrown errors and to match the existing
+ * try/catch shape used throughout api.ts.
+ *
+ * Scope (this PR — U1 of the security remediation plan):
+ *   - assertString:      closes js/type-confusion-through-parameter-tampering (api.ts:1118)
+ *   - assertSafePath:    consolidates the path-traversal guard from api.ts:1067-1077
+ *                        for reuse across other path-injection findings (U2/U3)
+ *   - escapeRegExp:      utility for upcoming regex-injection fix at /api/grep (U5)
+ *
+ * Helpers added in later units (U3 git-clone hardening, U4 rate-limiting) live
+ * in this module too but are introduced with the dependency they require.
+ */
+import path from 'node:path';
+import rateLimit, { ipKeyGenerator } from 'express-rate-limit';
+/**
+ * Thrown by validation helpers when user input is rejected.
+ * Routes catch via existing try/catch and convert with err.status / err.message.
+ */
+export class BadRequestError extends Error {
+    status;
+    constructor(message, status = 400) {
+        super(message);
+        this.name = 'BadRequestError';
+        this.status = status;
+    }
+}
+export class ForbiddenError extends BadRequestError {
+    constructor(message) {
+        super(message, 403);
+        this.name = 'ForbiddenError';
+    }
+}
+/**
+ * Type guard for HTTP request parameters that must be a single string.
+ *
+ * Express's req.query and req.body parsers return `string | string[] | ParsedQs`
+ * for any field, but route handlers commonly cast to `string` and operate on
+ * `.length`. When the caller passes the same key twice (?x=a&x=b) the value
+ * arrives as an array, and a `.length` check intended for the string ends up
+ * counting array elements — bypassing length-based guards (CodeQL
+ * js/type-confusion-through-parameter-tampering, alert at api.ts:1118).
+ *
+ * @throws BadRequestError when value is not a string (array, object, undefined, etc.)
+ */
+export function assertString(value, fieldName) {
+    if (typeof value !== 'string') {
+        if (Array.isArray(value)) {
+            throw new BadRequestError(`Parameter "${fieldName}" must be a single string, got an array`);
+        }
+        throw new BadRequestError(`Parameter "${fieldName}" must be a string`);
+    }
+    return value;
+}
+/**
+ * Resolve a user-supplied relative path against an allowed root and verify it
+ * stays inside that root. Mirrors the existing guard at api.ts:1067-1077.
+ *
+ * Returns the absolute resolved path. Rejects empty paths, null bytes, and
+ * paths that resolve outside the root (e.g., `../../../etc/passwd`).
+ *
+ * @throws BadRequestError when the path is empty or contains a null byte
+ * @throws ForbiddenError when the resolved path escapes the root
+ */
+export function assertSafePath(rawPath, root) {
+    if (rawPath.length === 0) {
+        throw new BadRequestError('Path must not be empty');
+    }
+    if (rawPath.includes('\0')) {
+        throw new BadRequestError('Path must not contain null bytes');
+    }
+    const resolvedRoot = path.resolve(root);
+    const fullPath = path.resolve(resolvedRoot, rawPath);
+    if (fullPath !== resolvedRoot && !fullPath.startsWith(resolvedRoot + path.sep)) {
+        throw new ForbiddenError('Path traversal denied');
+    }
+    return fullPath;
+}
+/**
+ * Escape regex metacharacters in a user-supplied string so it can be safely
+ * embedded as a literal in `new RegExp(...)`. Used by /api/grep's literal mode
+ * and any future endpoint that constructs a regex from caller input.
+ */
+export function escapeRegExp(input) {
+    return input.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+/**
+ * Default rate-limit policy for FS-touching API routes (CodeQL
+ * js/missing-rate-limiting). Tuned for the local-bound HTTP server's expected
+ * traffic — interactive web UI use stays well under the limit; abusive loops
+ * trip 429.
+ *
+ * Module-internal — not exported. Tests assert the observable behavior
+ * (61st request returns 429), not the literal value, so callers don't grow
+ * a coupling on this number.
+ */
+const DEFAULT_RATE_LIMIT_RPM = 60;
+/**
+ * Build a per-route rate-limit middleware with project-uniform defaults.
+ *
+ * Each call returns a NEW limiter instance — independent counters per route,
+ * so /api/file traffic doesn't push /api/grep into 429.
+ *
+ * Defaults:
+ *   - 60 requests per IP per minute
+ *   - draft-7 RateLimit-* response headers (no legacy X-RateLimit-* headers)
+ *   - 429 with a JSON body matching the project's `{ error: '...' }` shape
+ *   - passOnStoreError: store failures let the request through rather than
+ *     producing an HTML 500 from Express's default error handler
+ *   - keyGenerator: req.ip with a socket.remoteAddress fallback so abruptly
+ *     closed connections do not trigger ERR_ERL_UNDEFINED_IP_ADDRESS
+ *     (which would 500 the request via Express's default error handler).
+ *     The IP is passed through `ipKeyGenerator` so IPv6 addresses are
+ *     normalised to their /56 subnet — without this, each IPv6 address
+ *     gets its own counter and the limit is trivially bypassed (#1360).
+ *     Caller must wire `app.set('trust proxy', ...)` correctly — see
+ *     createServer in api.ts.
+ *
+ * Tests pass `{ windowMs: 100, limit: 3 }` to keep limiter tests fast and
+ * deterministic.
+ */
+export function createRouteLimiter(opts) {
+    return rateLimit({
+        windowMs: 60 * 1000,
+        limit: DEFAULT_RATE_LIMIT_RPM,
+        standardHeaders: 'draft-7',
+        legacyHeaders: false,
+        passOnStoreError: true,
+        keyGenerator: (req) => {
+            const ip = req.ip ?? req.socket?.remoteAddress;
+            return ip ? ipKeyGenerator(ip) : 'unknown';
+        },
+        message: { error: 'Too many requests, please try again later.' },
+        ...opts,
+    });
+}

package/dist/storage/file-hash.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Per-file content hashing for incremental DB writeback.
+ *
+ * On every analyze run we compute SHA-256 of every file's content and
+ * store the map in meta.json. The next run compares disk against the
+ * stored map and produces:
+ *   - `changed` — content differs (re-emit DB rows for this file)
+ *   - `added`   — file is new on disk (insert DB rows)
+ *   - `deleted` — file was in last meta but no longer on disk (drop rows)
+ *
+ * The pipeline still parses every file (correctness invariant: cross-file
+ * resolution needs full data). What this enables is a SELECTIVE DB
+ * writeback: instead of wipe-and-reload of the whole graph (~50s of CSV
+ * COPY on a 25K-node repo), we only delete-and-rewrite rows for the
+ * changed/added/deleted set.
+ *
+ * See docs/superpowers/specs/2026-05-10-incremental-indexing-design.md
+ * (Option B revision).
+ */
+/**
+ * Compute SHA-256 of a single file. Returns null when the file can't be
+ * read — caller treats that as "no signature, assume changed".
+ */
+export declare const computeFileHash: (absPath: string) => Promise<string | null>;
+/**
+ * Compute SHA-256 hashes for many files in parallel batches. Files that
+ * fail to read are omitted from the result map.
+ */
+export declare const computeFileHashes: (repoPath: string, relPaths: readonly string[]) => Promise<Map<string, string>>;
+/** Result of comparing the current on-disk hashes against stored ones. */
+export interface FileHashDiff {
+    /** Files whose content hash differs from stored. */
+    changed: string[];
+    /** Files in the current scan that weren't in the stored map. */
+    added: string[];
+    /** Files in the stored map that aren't in the current scan. */
+    deleted: string[];
+    /** All files whose DB rows must be replaced (changed ∪ added). */
+    toWrite: string[];
+}
+/**
+ * Diff a current hash map against a previously stored one.
+ *
+ * Sorted output so two runs produce identical diff arrays for the same
+ * changes — useful for stable logging / equivalence checks.
+ */
+export declare const diffFileHashes: (current: ReadonlyMap<string, string>, stored: Readonly<Record<string, string>> | undefined) => FileHashDiff;

package/dist/storage/file-hash.js

@@ -0,0 +1,86 @@
+/**
+ * Per-file content hashing for incremental DB writeback.
+ *
+ * On every analyze run we compute SHA-256 of every file's content and
+ * store the map in meta.json. The next run compares disk against the
+ * stored map and produces:
+ *   - `changed` — content differs (re-emit DB rows for this file)
+ *   - `added`   — file is new on disk (insert DB rows)
+ *   - `deleted` — file was in last meta but no longer on disk (drop rows)
+ *
+ * The pipeline still parses every file (correctness invariant: cross-file
+ * resolution needs full data). What this enables is a SELECTIVE DB
+ * writeback: instead of wipe-and-reload of the whole graph (~50s of CSV
+ * COPY on a 25K-node repo), we only delete-and-rewrite rows for the
+ * changed/added/deleted set.
+ *
+ * See docs/superpowers/specs/2026-05-10-incremental-indexing-design.md
+ * (Option B revision).
+ */
+import { createHash } from 'crypto';
+import fs from 'fs/promises';
+import path from 'path';
+/**
+ * Compute SHA-256 of a single file. Returns null when the file can't be
+ * read — caller treats that as "no signature, assume changed".
+ */
+export const computeFileHash = async (absPath) => {
+    try {
+        const buf = await fs.readFile(absPath);
+        return createHash('sha256').update(buf).digest('hex');
+    }
+    catch {
+        return null;
+    }
+};
+/**
+ * Compute SHA-256 hashes for many files in parallel batches. Files that
+ * fail to read are omitted from the result map.
+ */
+export const computeFileHashes = async (repoPath, relPaths) => {
+    const out = new Map();
+    const BATCH = 100;
+    for (let i = 0; i < relPaths.length; i += BATCH) {
+        const batch = relPaths.slice(i, i + BATCH);
+        const results = await Promise.all(batch.map(async (rel) => {
+            const h = await computeFileHash(path.join(repoPath, rel));
+            return h ? [rel, h] : null;
+        }));
+        for (const r of results)
+            if (r)
+                out.set(r[0], r[1]);
+    }
+    return out;
+};
+/**
+ * Diff a current hash map against a previously stored one.
+ *
+ * Sorted output so two runs produce identical diff arrays for the same
+ * changes — useful for stable logging / equivalence checks.
+ */
+export const diffFileHashes = (current, stored) => {
+    const storedMap = new Map(stored ? Object.entries(stored) : []);
+    const changed = [];
+    const added = [];
+    for (const [p, h] of current) {
+        const prev = storedMap.get(p);
+        if (prev === undefined)
+            added.push(p);
+        else if (prev !== h)
+            changed.push(p);
+    }
+    const deleted = [];
+    for (const p of storedMap.keys()) {
+        if (!current.has(p))
+            deleted.push(p);
+    }
+    changed.sort();
+    added.sort();
+    deleted.sort();
+    return {
+        changed,
+        added,
+        deleted,
+        toWrite: [...changed, ...added].sort(),
+    };
+};

package/dist/storage/git.d.ts

@@ -0,0 +1,148 @@
+export declare const isGitRepo: (repoPath: string) => boolean;
+export declare const getCurrentCommit: (repoPath: string) => string;
+/**
+ * Get a stable canonical identifier for the repo's `origin` remote, if any.
+ *
+ * Used to fingerprint two on-disk clones as the same logical repository
+ * (issue #XXX — silent graph drift across sibling clones). `path` alone
+ * is unreliable: worktrees, "clean clone for indexing" hygiene, and
+ * multi-agent workspaces routinely have the same repo at multiple
+ * absolute paths. The remote URL is the only on-disk signal that
+ * survives those conventions.
+ *
+ * Normalisation strategy:
+ *   - Strip a trailing `.git` so `https://x/y` and `https://x/y.git` collapse.
+ *   - Strip a trailing `/` for the same reason.
+ *   - `git@github.com:foo/bar` and `https://github.com/foo/bar` are
+ *     intentionally NOT collapsed — they are different remotes from
+ *     git's perspective and we don't want to assert equivalence.
+ *   - Lower-case the host portion so `GitHub.com` and `github.com`
+ *     don't desync; preserves case in path because some hosts
+ *     (Bitbucket Server) treat repo paths case-sensitively.
+ *
+ * Returns `undefined` when there is no origin remote, the directory
+ * isn't a git repo, or git itself isn't available.
+ */
+export declare const getRemoteUrl: (repoPath: string) => string | undefined;
+/**
+ * Find the git repository root from any path inside the repo
+ */
+export declare const getGitRoot: (fromPath: string) => string | null;
+/**
+ * Get the *canonical* repository root, dereferencing git worktrees.
+ *
+ * Unlike `getGitRoot` (which uses `git rev-parse --show-toplevel` and
+ * returns the WORKTREE's root when called inside a linked worktree),
+ * this uses `git rev-parse --git-common-dir` — the shared `.git`
+ * directory, identical for the main checkout and every linked
+ * worktree — and returns its parent.
+ *
+ * Why it matters (#1259): when `arc analyze` runs inside a
+ * worktree (e.g. `/repo/wt-feature/`), deriving `repoName` from
+ * `path.basename(getGitRoot(cwd))` registers the project under the
+ * worktree's directory slug (`wt-feature`) instead of the canonical
+ * repo's basename (`repo`). Each worktree then re-registers as a
+ * "different" project, AGENTS.md is rewritten with the wrong MCP URI,
+ * and Claude-Code-style worktree workflows silently accumulate
+ * duplicate registry entries.
+ *
+ * Returns `null` when the path is not inside a git repository or
+ * `git` is not available, so callers can chain safely:
+ * `getCanonicalRepoRoot(p) ?? getGitRoot(p) ?? p`.
+ *
+ * `--path-format=absolute` is required because `--git-common-dir`
+ * returns a path *relative to cwd* by default (e.g. `../.git` when
+ * called from a worktree), which would resolve to the wrong absolute
+ * path if the caller later resolved it from a different directory.
+ */
+export declare const getCanonicalRepoRoot: (fromPath: string) => string | null;
+/**
+ * Resolve `fromPath` to the directory whose basename should drive the
+ * registry name (#1259) — the *identity root*. Three outcomes:
+ *
+ *   1. `fromPath` IS the canonical checkout root → returns it unchanged.
+ *   2. `fromPath` is a linked-worktree root (has its own `.git` entry, but
+ *      `git rev-parse --git-common-dir` points at a different `.git`) →
+ *      returns the canonical repo root.
+ *   3. `fromPath` is anything else — an arbitrary subdir under a git repo,
+ *      a non-git folder, a `--skip-git` subdir of an unrelated parent
+ *      checkout — returns `fromPath` unchanged.
+ *
+ * Why not just use `getCanonicalRepoRoot` directly? Because `git rev-parse
+ * --git-common-dir` resolves the same canonical root for ANY path inside
+ * a git repo, including unrelated subdirs. Using it for registry-name
+ * derivation would silently re-key a `--skip-git` subdir analyze under
+ * the parent git's basename, defeating the user's `--skip-git` intent
+ * (regressing the #1232/#1233 fix). The "is this path a tree root"
+ * gate confines the canonical-root collapse to exactly the cases where
+ * #1259 matters: main checkouts and linked worktrees.
+ */
+export declare const resolveRepoIdentityRoot: (fromPath: string) => string;
+/**
+ * Find a git root by checking only `.git` entries on the ancestor chain.
+ *
+ * Unlike `getGitRoot`, this does not spawn `git`, so MCP can cheaply decide
+ * whether a launch cwd is a worktree before running any subprocess there.
+ */
+export declare const findGitRootByDotGit: (fromPath: string) => string | null;
+/**
+ * Check whether a directory contains a .git entry (file or folder).
+ *
+ * This is intentionally a simple filesystem check rather than running
+ * `git rev-parse`, so it works even when git is not installed or when
+ * the directory is a git-worktree root (which has a .git file, not a
+ * directory).  Use `isGitRepo` for a definitive git answer.
+ *
+ * @param dirPath - Absolute path to the directory to inspect.
+ * @returns `true` when `.git` is present, `false` otherwise.
+ */
+export declare const hasGitDir: (dirPath: string) => boolean;
+/**
+ * Read `remote.origin.url` from a git repository, or `null` if not a
+ * git repo, has no `origin` remote, or git is unavailable.
+ *
+ * Used by the registry-name inference path (#979) to recover a
+ * meaningful repo name when `path.basename(repoPath)` is generic
+ * (e.g. monorepo subprojects, git worktrees, Gas-Town-style
+ * `<rig>/refinery/rig/` layouts).
+ */
+export declare const getRemoteOriginUrl: (repoPath: string) => string | null;
+/**
+ * Sanitize a repository name to prevent argument injection and ensure
+ * cross-platform filesystem compatibility.
+ *
+ * 1. Strips leading dashes to prevent git command-line argument injection
+ *    (e.g., --upload-pack=evil).
+ * 2. Replaces characters that are unsafe for directory names across
+ *    platforms (Windows/macOS/Linux) with underscores.
+ * 3. Blocks path traversal segments ("." and "..") and Windows reserved
+ *    names (e.g., CON, NUL) to prevent directory escape.
+ */
+export declare const sanitizeRepoName: (name: string) => string;
+/**
+ * Parse a repository name out of a git remote URL. Handles common shapes
+ * including SSH (git@host:owner/repo.git) and HTTPS (https://host/owner/repo.git).
+ *
+ * Returns a sanitized, filesystem-safe name or null if no name could be inferred.
+ * Returning null (rather than 'unknown') allows callers to use ?? null-coalescing
+ * for fallbacks without risk of registry collisions on 'unknown'.
+ */
+export declare const parseRepoNameFromUrl: (url: string | null | undefined) => string | null;
+/**
+ * Convenience wrapper: derive a registry-friendly name from the repo's
+ * `origin` remote, or `null` when it cannot be inferred.
+ */
+export declare const getInferredRepoName: (repoPath: string) => string | null;
+export interface DiffHunk {
+    startLine: number;
+    endLine: number;
+}
+export interface FileDiff {
+    filePath: string;
+    hunks: DiffHunk[];
+}
+/**
+ * Parse unified diff output (with -U0) into per-file hunk ranges.
+ * Extracts the new-file line ranges from @@ hunk headers.
+ */
+export declare function parseDiffHunks(diffOutput: string): FileDiff[];