@rmyndharis/aimhooman 0.1.8 → 0.3.0

package/src/report.mjs

@@ -21,6 +21,7 @@ export function human(findings, tone) {
     // while bounding stderr for repeated-rule scans.
     const shown = findings.slice(0, HUMAN_FINDING_CAP);
     const hidden = findings.length - shown.length;
+    const fixesPrinted = new Set();
     for (const f of shown) {
         const loc = f.path
             ? `${visible(f.path)}${f.line ? `:${f.line}` : ''}`
@@ -34,9 +35,17 @@ export function human(findings, tone) {
         }
         // Render the whole remediation array, not just the first entry. Several
         // rules carry a second line (e.g. "rotate the key if it was ever exposed")
-        // that the previous single-index render dropped silently.
-        for (const remedy of (f.remediation || [])) {
-            out += `       fix: ${remedy}\n`;
+        // that the previous single-index render dropped silently. UT-08: print a
+        // rule's fix once — a repeated rule (20 hits of the same secret rule)
+        // used to reprint the identical fix block for every finding.
+        const remedies = f.remediation || [];
+        if (remedies.length && fixesPrinted.has(f.ruleId)) {
+            out += `       fix: as above for ${f.ruleId}\n`;
+        } else {
+            if (remedies.length) fixesPrinted.add(f.ruleId);
+            for (const remedy of remedies) {
+                out += `       fix: ${remedy}\n`;
+            }
         }
         out += '\n';
     }
@@ -68,13 +77,22 @@ export function jsonReport(findings, metadata = {}) {
     return JSON.stringify({ schema_version: 1, ...metadata, findings: safe }, null, 2);
 }
 
+// Built-in secret scanning is gone, but a local rule pack can still declare
+// category "secret"; findings from such a rule keep their matched text out of
+// every report, the same courtesy the built-in rules got.
 function isSensitive(finding) {
     return finding?.category === 'secret'
         || finding?.matchedRules?.some((match) => match.category === 'secret') === true;
 }
 
 // Exit codes: 0 clean, 10 blocked, 11 review required, 31 incomplete scan.
-export function exitCode(findings, profile, complete = true) {
+// An incomplete scan stops the operation only where no later guard can vouch
+// for the skipped content: on the strict profile, or when the caller is the
+// final ref boundary (failClosedIncomplete). Frictionless profiles warn and
+// continue — the reference-transaction guard still scans introduced commits
+// with failClosedIncomplete set, so the skipped content is checked before any
+// ref moves.
+export function exitCode(findings, profile, complete = true, { failClosedIncomplete = false } = {}) {
     let block = false;
     let review = false;
     for (const f of findings) {
@@ -82,7 +100,7 @@ export function exitCode(findings, profile, complete = true) {
         else if (f.decision === 'review') review = true;
     }
     if (block) return 10;
-    if (!complete) return 31;
+    if (!complete && (profile === 'strict' || failClosedIncomplete)) return 31;
     if (review && findings.some((finding) => (finding.scanProfile || profile) !== 'clean')) return 11;
     return 0;
 }

package/src/scan-session.mjs

@@ -52,10 +52,10 @@ export function scanEntries(repo, engine, entries, options = {}) {
     }
 
     // Oversized files: probe the first 8 KB to separate binary from text.
-    // A binary file (PSD, WOFF, PNG) can't hide text-pattern secrets that
-    // the full content scan would find, so it skips as 'binary' (complete).
-    // A text file that exceeds the budget is a genuine 'size-limit' skip
-    // (incomplete) and the caller must raise the limit to cover it.
+    // A binary file (PSD, WOFF, PNG) holds no text lines the content rules
+    // could match, so it skips as 'binary' (complete). A text file that
+    // exceeds the budget is a genuine 'size-limit' skip (incomplete) and the
+    // caller must raise the limit to cover it.
     // Cap probing at 16 MiB: cat-file --batch reads the full blob into memory,
     // so probing a 500 MB file just to check for NULs is wasteful. Files above
     // the cap are classified as size-limit without probing.
@@ -100,25 +100,18 @@ export function scanEntries(repo, engine, entries, options = {}) {
         // Binary detection still reads the blob. Count every examined byte so
         // later commits cannot reset the total budget merely by using NUL data.
         stats.bytes_scanned += blob.length;
-        let matched;
         if (isBinary(blob)) {
+            // Content rules match text lines, so a binary blob carries nothing
+            // they could fire on. Skipping it loses no coverage: the skip is
+            // recorded as 'binary', which does not mark the scan incomplete.
             increment(stats.skipped, 'binary');
             appendPath(stats.skippedPaths, 'binary', entry.path, blob.length);
-            // Binary classification only skips text-oriented policy rules. Secret
-            // signatures are ASCII byte sequences, so latin1 preserves a
-            // one-byte-to-one-code-unit view and keeps the existing byte limits.
-            // Stripping NULs is what defeats hiding credential material behind
-            // them: one injected NUL breaks a signature, and a multi-byte
-            // encoding like UTF-16 injects one per character.
-            matched = engine.checkContent(entry.path, blob.toString('latin1').replace(/\0/g, ''), {
-                categories: ['secret'],
-            });
-        } else {
-            stats.files_scanned += 1;
-            const ranges = lineRanges.get(entry.path);
-            matched = engine.checkContent(entry.path, blob.toString('utf8'),
-                ranges && ranges.length ? { lineRanges: ranges } : {});
+            continue;
         }
+        stats.files_scanned += 1;
+        const ranges = lineRanges.get(entry.path);
+        const matched = engine.checkContent(entry.path, blob.toString('utf8'),
+            ranges && ranges.length ? { lineRanges: ranges } : {});
         stats.findings_total += matched.length;
         for (const finding of matched) {
             if (findings.length >= limits.maxFindings) continue;
@@ -253,8 +246,8 @@ function isBinary(buffer) {
 //
 // Entries without commit/parents (tracked snapshots, staged views, root
 // commits) are omitted from the map; the caller treats a missing key as "scan
-// the whole blob" — the safe side for a secret scanner is to scan MORE, not
-// less, so a failure to compute hunks falls back to the pre-W4 behaviour.
+// the whole blob" — the safe side is to scan MORE, not less, so a failure to
+// compute hunks falls back to the pre-W4 behaviour.
 function collectLineRanges(repo, entries) {
     // Group text-candidate entries by their first parent to batch the diffs.
     // Key by `${commit}\0${parent}` so a merge with multiple parents produces

package/src/scan-target.mjs

@@ -389,8 +389,8 @@ function scanEntryGroup(repo, engine, entries, policy, accumulator, options = {}
     // Content scanning can target a narrower set than the path check. When
     // contentEntries is provided (e.g. only changed files in a commit), read
     // blobs only for those entries instead of the full snapshot. Path-based
-    // rules already ran on the full tree above, so secrets like .env are still
-    // caught even when their blob isn't re-read.
+    // rules already ran on the full tree above, so a path-only finding still
+    // fires even when its blob isn't re-read.
     const contentScannable = (options.contentEntries ?? entries)
         .filter((entry) => entry.status !== 'D' && entry.type !== 'deleted');
     const remaining = accumulator.remaining();
@@ -405,14 +405,14 @@ function scanEntryGroup(repo, engine, entries, policy, accumulator, options = {}
 function scanReviewPathChanges(engine, entries, policy, accumulator, options = {}) {
     for (const entry of entries) {
         // A deleted path is gone, so only structural policy rules (agent
-        // instructions, project policy) can still matter: deleting a secret or a
-        // session file is hygiene, not a violation. A renamed-away path is
-        // different — its content survives under a new name, so a path-only
-        // secret (e.g. .env) must still fire or a `git mv` to a neutral name
-        // would slip past the destination scan, which only catches content-shaped
-        // secrets. That finding is reported on the destination path (where the
-        // bytes now live) so clean-profile repair unstages the blob that carries
-        // the secret rather than the old name.
+        // instructions, project policy) can still matter: deleting a flagged
+        // file is hygiene, not a violation. A renamed-away path is different —
+        // its content survives under a new name, so a path-only secret-category
+        // rule from a local pack must still fire or a `git mv` to a neutral
+        // name would slip past the destination scan, which only catches
+        // content-shaped matches. That finding is reported on the destination
+        // path (where the bytes now live) so clean-profile repair unstages the
+        // blob that carries the match rather than the old name.
         const deleted = entry.status === 'D' || entry.type === 'deleted';
         const renamed = entry.status === 'R' && entry.sourcePath && entry.sourcePath !== entry.path;
         if (!deleted && !renamed) continue;

package/src/scan.mjs

@@ -19,7 +19,6 @@ export class Engine {
         this.rules = rules;
         this.allowPaths = new Set();
         this.allowRules = new Set();
-        this.allowSecretPaths = new Set();
         this.denyPaths = new Set();
         this.denyRules = new Set();
         this.scopedAllow = [];
@@ -33,7 +32,6 @@ export class Engine {
         const denied = this.#splitOverrides(deny);
         this.allowPaths = allowed.paths;
         this.allowRules = allowed.rules;
-        this.allowSecretPaths = allowed.secretPaths;
         this.denyPaths = denied.paths;
         this.denyRules = denied.rules;
         this.scopedAllow = scopedAllow.filter((entry) => (
@@ -59,8 +57,8 @@ export class Engine {
         //   - clean/compliance: review is ADVISORY (a stderr message, exit 0),
         //     so re-surfacing it on every edit of a reviewed agent-instruction
         //     file (CLAUDE.md, AGENTS.md) is pure friction with no security
-        //     payoff — the security boundary is secret scanning, strict blocks,
-        //     and reference-transaction. A LIVE-FILE review (newObjectId set)
+        //     payoff — the security boundary is strict blocks and the
+        //     reference-transaction guard. A LIVE-FILE review (newObjectId set)
         //     therefore persists per path + rule across edits. A TOMBSTONE
         //     review (newObjectId null — a reviewed deletion) keeps the exact
         //     match in every profile: a deletion review must not silently cover
@@ -80,20 +78,13 @@ export class Engine {
                     && entry.newObjectId === context.objectId
                     && entry.newMode === context.mode);
         })) return 'allow';
-        // A rule-level allow cannot bypass the secret-category guard that the
-        // path-level allow below enforces: secret rules require an explicit
-        // --scope secret-path override on a specific path, never a blanket rule allow.
-        if (this.allowRules.has(rule.id) && rule.category !== 'secret') return 'allow';
-        // A --scope secret-path allow is the explicit override for secret-category
-        // rules only; it must not also suppress a non-secret rule that happens to
-        // match the same path (principle of least privilege).
-        if (this.allowSecretPaths.has(target) && rule.category === 'secret') return 'allow';
-        if (this.allowPaths.has(target) && rule.category !== 'secret') return 'allow';
+        if (this.allowRules.has(rule.id)) return 'allow';
+        if (this.allowPaths.has(target)) return 'allow';
         return base;
     }
 
     #splitOverrides(entries) {
-        const result = { paths: new Set(), rules: new Set(), secretPaths: new Set() };
+        const result = { paths: new Set(), rules: new Set() };
         for (const entry of entries || []) {
             const target = typeof entry === 'string' ? entry : entry?.target;
             if (!target) continue;
@@ -101,7 +92,6 @@ export class Engine {
                 ? (this.lookup(target) ? 'rule' : 'path')
                 : (entry.scope ?? (this.lookup(target) ? 'rule' : 'path'));
             if (scope === 'rule') result.rules.add(target);
-            else if (scope === 'secret-path') result.secretPaths.add(target);
             else if (scope === 'path') result.paths.add(target);
         }
         return result;
@@ -138,13 +128,10 @@ export class Engine {
     checkContent(path, content, options = {}) {
         const out = [];
         const p = normalize(path);
-        const categories = Array.isArray(options.categories)
-            ? new Set(options.categories)
-            : null;
         // lineRanges narrows content scanning to changed hunks (W4, bug 12d-F1).
         // When provided (an array of inclusive 1-based {start,end} ranges), only
         // lines falling in a range are evaluated; this stops a file that contains
-        // a secret-bearing line ELSEWHERE (a PEM header inside a test string on
+        // a flagged line ELSEWHERE (a marker phrase inside a test fixture on
         // line 200) from blocking a commit that only edited line 50. Findings
         // keep their real line numbers because lineRecords already anchors them.
         // Absent = scan every line (the pre-W4 behaviour).
@@ -153,8 +140,8 @@ export class Engine {
             : null;
         for (const record of lineRecords(String(content))) {
             if (ranges && !ranges.some((range) => record.line >= range.start && record.line <= range.end)) continue;
-            this.#markLocalInputSkip('code', p, record.text, categories);
-            const result = this.#evaluate('code', p, record.text, { categories });
+            this.#markLocalInputSkip('code', p, record.text);
+            const result = this.#evaluate('code', p, record.text);
             if (result) out.push(finding(result, { path: p, line: record.line, text: record.text }));
         }
         return out;
@@ -198,11 +185,10 @@ export class Engine {
         return skipped;
     }
 
-    #markLocalInputSkip(kind, target, text, categories = null) {
+    #markLocalInputSkip(kind, target, text) {
         if (text.length <= MAX_LOCAL_MATCH_INPUT) return;
         const applicable = this.rules.some((rule) => {
             if (rule.source !== 'local' || rule.kind !== kind) return false;
-            if (categories && !categories.has(rule.category)) return false;
             if (kind !== 'code') return true;
             const candidate = rule.pathCaseInsensitive ? target.toLowerCase() : target;
             if (rule.pathRes.length && !rule.pathRes.some((regexp) => regexp.test(candidate))) return false;
@@ -216,7 +202,6 @@ export class Engine {
         for (const rule of this.rules) {
             if (rule.kind !== kind) continue;
             if (context.excludedRuleIds?.has(rule.id)) continue;
-            if (context.categories && !context.categories.has(rule.category)) continue;
             const matched = kind === 'path'
                 ? matchesPath(rule, target)
                 : matchesContent(rule, text, kind === 'code' ? target : undefined);

package/src/state.mjs

@@ -11,7 +11,7 @@ import { normalizeGitPath } from './git-path.mjs';
 
 const PROFILES = new Set(['clean', 'strict', 'compliance']);
 const OVERRIDE_SCOPES = new Set([
-    'path', 'rule', 'secret-path', 'reviewed-instruction', 'reviewed-policy-file', 'policy-migration',
+    'path', 'rule', 'reviewed-instruction', 'reviewed-policy-file', 'policy-migration',
 ]);
 const OVERRIDE_FIELDS = new Set([
     'target', 'scope', 'reason', 'actor', 'at', 'head', 'transition', 'oldObjectId', 'newObjectId', 'newMode',
@@ -121,20 +121,29 @@ export function loadConfig(stateDir, root) {
         throw new LocalConfigError(file, `invalid JSON: ${error.message}`, error);
     }
     const normalized = normalizeLocalConfig(config, file);
-    return { profile: normalized.profile, source: 'local', file };
+    return {
+        profile: normalized.profile,
+        source: 'local',
+        file,
+        ...(normalized.gitignore ? { gitignore: normalized.gitignore } : {}),
+    };
 }
 
 export function saveConfig(stateDir, config) {
     const file = join(stateDir, 'config.json');
     const normalized = normalizeLocalConfig(config, file);
-    atomicWriteJson(file, { schema_version: 1, profile: normalized.profile });
+    atomicWriteJson(file, {
+        schema_version: 1,
+        profile: normalized.profile,
+        ...(normalized.gitignore ? { gitignore: normalized.gitignore } : {}),
+    });
 }
 
 function normalizeLocalConfig(config, file) {
     if (!config || typeof config !== 'object' || Array.isArray(config)) {
         throw new LocalConfigError(file, 'root must be a JSON object');
     }
-    const unknown = Object.keys(config).filter((key) => !['schema_version', 'profile'].includes(key));
+    const unknown = Object.keys(config).filter((key) => !['schema_version', 'profile', 'gitignore'].includes(key));
     if (unknown.length) {
         throw new LocalConfigError(file, `unsupported field${unknown.length === 1 ? '' : 's'}: ${unknown.join(', ')}`);
     }
@@ -147,7 +156,32 @@ function normalizeLocalConfig(config, file) {
     if (!PROFILES.has(config.profile)) {
         throw new LocalConfigError(file, 'profile must be clean, strict, or compliance');
     }
-    return { profile: config.profile };
+    const gitignore = normalizeGitignoreConfig(config.gitignore, file);
+    return { profile: config.profile, ...(gitignore ? { gitignore } : {}) };
+}
+
+// The gitignore field records an `init --gitignore` opt-in for this clone:
+// enabled says the worktree .gitignore carries our managed block, created says
+// the file did not exist before we wrote it (so uninstall may delete a file we
+// introduced once the block leaves it empty). It stays out of the project
+// policy on purpose — whether this clone created its .gitignore is per-clone
+// state, never team policy. Absent means disabled, and a disabled record
+// normalizes away so the two spellings cannot drift apart.
+function normalizeGitignoreConfig(value, file) {
+    if (value === undefined) return undefined;
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        throw new LocalConfigError(file, 'gitignore must be an object');
+    }
+    const unknown = Object.keys(value).filter((key) => !['enabled', 'created'].includes(key));
+    if (unknown.length) {
+        throw new LocalConfigError(file, `gitignore has unsupported field${unknown.length === 1 ? '' : 's'}: ${unknown.join(', ')}`);
+    }
+    for (const field of ['enabled', 'created']) {
+        if (typeof value[field] !== 'boolean') {
+            throw new LocalConfigError(file, `gitignore.${field} must be a boolean`);
+        }
+    }
+    return value.enabled ? { enabled: true, created: value.created } : undefined;
 }
 
 export function loadOverrides(stateDir) {
@@ -196,18 +230,33 @@ function normalizeOverrides(value, file) {
     if (value.schema_version !== undefined && value.schema_version !== 1) {
         throw new LocalOverridesError(file, 'schema_version must be 1');
     }
-    return {
-        allow: overrideEntries(value.allow, 'allow', file),
-        deny: overrideEntries(value.deny, 'deny', file),
+    const dropped = { count: 0 };
+    const normalized = {
+        allow: overrideEntries(value.allow, 'allow', file, dropped),
+        deny: overrideEntries(value.deny, 'deny', file, dropped),
     };
+    if (dropped.count) {
+        process.stderr.write(
+            `aimhooman: warning: ${file}: dropped ${dropped.count} override(s) with retired scope "secret-path"; built-in secret scanning was removed in v0.3.0\n`
+        );
+    }
+    return normalized;
 }
 
-function overrideEntries(value, key, file) {
+function overrideEntries(value, key, file, dropped = { count: 0 }) {
     if (value === undefined) return [];
     if (!Array.isArray(value)) {
         throw new LocalOverridesError(file, `${key} must be an array`);
     }
     return value.map((entry, index) => {
+        // Built-in secret scanning and its secret-path override scope were
+        // removed in v0.3.0. An overrides file written by an older version may
+        // still carry such entries; drop them (one warning per file, below)
+        // instead of failing the whole load.
+        if (entry && typeof entry === 'object' && !Array.isArray(entry) && entry.scope === 'secret-path') {
+            dropped.count += 1;
+            return null;
+        }
         if (!entry || typeof entry !== 'object' || Array.isArray(entry)) {
             throw new LocalOverridesError(file, `${key}[${index}] must be an object`);
         }
@@ -260,7 +309,7 @@ function overrideEntries(value, key, file) {
             normalized.transition = normalized.transition.toLowerCase();
         }
         return normalized;
-    });
+    }).filter((entry) => entry !== null);
 }
 
 function isRfc3339DateTime(value) {

package/rules/secrets.json

@@ -1,92 +0,0 @@
-[
-    {
-        "id": "secret.private-key-content",
-        "version": 1,
-        "provider": "generic",
-        "category": "secret",
-        "confidence": "high",
-        "kind": "code",
-        "match": {
-            "content": [
-                "-----BEGIN (?:ENCRYPTED |RSA |DSA |EC |OPENSSH |PGP )?PRIVATE KEY(?: BLOCK)?-----"
-            ]
-        },
-        "actions": {
-            "clean": "block",
-            "strict": "block",
-            "compliance": "block"
-        },
-        "reason": "Private-key material must not enter Git history.",
-        "remediation": [
-            "Remove the key from the index, rotate it if exposed, and store it outside the repository."
-        ]
-    },
-    {
-        "id": "secret.service-account-key",
-        "version": 1,
-        "provider": "generic",
-        "category": "secret",
-        "confidence": "high",
-        "kind": "code",
-        "match": {
-            "content": [
-                "(?i)\\\"private_key\\\"\\s*:\\s*\\\"-----BEGIN (?:RSA )?PRIVATE KEY-----"
-            ]
-        },
-        "actions": {
-            "clean": "block",
-            "strict": "block",
-            "compliance": "block"
-        },
-        "reason": "A service-account credential must not enter Git history.",
-        "remediation": [
-            "Remove the credential from the index, rotate it if exposed, and use the service's secret store."
-        ]
-    },
-    {
-        "id": "secret.aws-key-content",
-        "version": 3,
-        "provider": "aws",
-        "category": "secret",
-        "confidence": "high",
-        "kind": "code",
-        "match": {
-            "content": [
-                "(?i)\\baws_(?:secret_access_key|session_token)\\b\\s*[:=]\\s*[\\\"']?[A-Za-z0-9/+=]{32,}(?<!EXAMPLEKEY)(?![A-Za-z0-9/+=])",
-                "\\b(?:AKIA|ASIA)(?![A-Z0-9]{9}EXAMPLE\\b)[A-Z0-9]{16}\\b"
-            ]
-        },
-        "actions": {
-            "clean": "block",
-            "strict": "block",
-            "compliance": "block"
-        },
-        "reason": "AWS credential material must not enter Git history.",
-        "remediation": [
-            "Remove the credential from the index, rotate it if exposed, and use an AWS credential provider."
-        ]
-    },
-    {
-        "id": "secret.provider-token",
-        "version": 1,
-        "provider": "generic",
-        "category": "secret",
-        "confidence": "high",
-        "kind": "code",
-        "match": {
-            "content": [
-                "\\b(?:gh[pousr]_[A-Za-z0-9]{36,255}|github_pat_[A-Za-z0-9_]{60,255}|glpat-[A-Za-z0-9_-]{20,255}|npm_[A-Za-z0-9]{36,255}|xox[baprs]-[A-Za-z0-9-]{20,255})\\b",
-                "\\b(?:sk-ant-api[0-9]{2}-[A-Za-z0-9_-]{80,255}|sk-proj-[A-Za-z0-9_-]{40,255}|AIza[A-Za-z0-9_-]{35}|(?:sk|rk)_live_[A-Za-z0-9]{20,255}|hf_[A-Za-z0-9]{34}|SG\\.[A-Za-z0-9_-]{20,255}\\.[A-Za-z0-9_-]{40,255})\\b"
-            ]
-        },
-        "actions": {
-            "clean": "block",
-            "strict": "block",
-            "compliance": "block"
-        },
-        "reason": "A provider access token must not enter Git history.",
-        "remediation": [
-            "Remove the token from the index, revoke or rotate it, and use the provider's secret store."
-        ]
-    }
-]