From 3cf5c714a212ac220262a7858aab7d7f92d296f0 Mon Sep 17 00:00:00 2001 From: Kjell Tore Guttormsen Date: Fri, 26 Jun 2026 15:15:14 +0200 Subject: [PATCH] fix(acr): SET typo-gates unknown-key false positives (M-BUG-10) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The CC settings schema is passthrough (verified against the 2.1.193 binary): it forwards unrecognized keys unchanged rather than rejecting them, so an arbitrary unknown key is valid/forward-compatible, not an error — the finding's "silently ignored" claim was factually wrong. The only real risk is a TYPO of a real key (the intended setting then silently has no effect). Fix: flag an unknown key only when it closely matches a known key (new levenshtein helper; edit distance <= 2, both keys >= 4 chars); severity medium -> low; honest passthrough framing in the scanner + humanizer. Also refreshed KNOWN_KEYS with 6 binary-verified keys (agentPushNotifEnabled, remoteControlAtStartup, skipAutoPermissionPrompt, skipDangerousModePermissionPrompt, skipWorkflowUsageWarning, tui). Suite 1341/0 (+12). Frozen v5.0.0 snapshots untouched (0 CA-SET findings there), no re-seed. Dogfood ~/.claude/settings.json 6->0 (all 6 keys above were false unknown-key findings; 0 typo flags introduced across 167 walked files). --- scanners/lib/humanizer-data.mjs | 8 +-- scanners/lib/string-utils.mjs | 35 ++++++++++++ scanners/settings-validator.mjs | 44 ++++++++++++--- tests/lib/string-utils.test.mjs | 38 ++++++++++++- tests/scanners/settings-validator.test.mjs | 65 +++++++++++++++++++++- 5 files changed, 174 insertions(+), 16 deletions(-) diff --git a/scanners/lib/humanizer-data.mjs b/scanners/lib/humanizer-data.mjs index 2356547..adf6802 100644 --- a/scanners/lib/humanizer-data.mjs +++ b/scanners/lib/humanizer-data.mjs @@ -96,10 +96,10 @@ export const TRANSLATIONS = { // ───────────────────────────────────────────────────────────── SET: { static: { - 'Unknown settings key': { - title: 'A settings key isn\'t recognized', - description: 'A key in your settings file isn\'t one Claude Code understands. It will be ignored.', - recommendation: 'Check the key name for typos, or remove the key if it\'s no longer in use.', + 'Possible typo in settings key': { + title: 'A settings key looks like a typo', + description: 'A key in your settings file isn\'t recognized, but it\'s very close to a real one — likely a typo. Claude Code forwards unrecognized keys unchanged rather than rejecting them, so a misspelled key silently has no effect.', + recommendation: 'Check the suggested key name. Fix the spelling, or keep the key if it\'s intentional (e.g. a newer key this audit doesn\'t know yet).', }, 'Deprecated settings key': { title: 'A settings key is no longer supported', diff --git a/scanners/lib/string-utils.mjs b/scanners/lib/string-utils.mjs index e0e14cf..0f27bf1 100644 --- a/scanners/lib/string-utils.mjs +++ b/scanners/lib/string-utils.mjs @@ -43,6 +43,41 @@ export function isSimilar(a, b, threshold = 0.8) { return similarity >= threshold; } +/** + * Levenshtein edit distance between two strings (insertions, deletions, + * substitutions; a transposition counts as 2). Used for typo detection on + * settings keys. Zero external dependencies, O(a*b) with two rolling rows. + * @param {string} a + * @param {string} b + * @returns {number} + */ +export function levenshtein(a, b) { + if (a === b) return 0; + const al = a.length; + const bl = b.length; + if (al === 0) return bl; + if (bl === 0) return al; + let prev = new Array(bl + 1); + let curr = new Array(bl + 1); + for (let j = 0; j <= bl; j++) prev[j] = j; + for (let i = 1; i <= al; i++) { + curr[0] = i; + const ac = a.charCodeAt(i - 1); + for (let j = 1; j <= bl; j++) { + const cost = ac === b.charCodeAt(j - 1) ? 0 : 1; + curr[j] = Math.min( + prev[j] + 1, // deletion + curr[j - 1] + 1, // insertion + prev[j - 1] + cost, // substitution + ); + } + const tmp = prev; + prev = curr; + curr = tmp; + } + return prev[bl]; +} + /** * Extract all key-like patterns from a settings.json or similar config. * @param {object} obj diff --git a/scanners/settings-validator.mjs b/scanners/settings-validator.mjs index 03a52ec..bf84de8 100644 --- a/scanners/settings-validator.mjs +++ b/scanners/settings-validator.mjs @@ -8,11 +8,11 @@ import { readTextFile } from './lib/file-discovery.mjs'; import { finding, scannerResult } from './lib/output.mjs'; import { SEVERITY } from './lib/severity.mjs'; import { parseJson } from './lib/yaml-parser.mjs'; -import { extractKeys } from './lib/string-utils.mjs'; +import { extractKeys, levenshtein } from './lib/string-utils.mjs'; const SCANNER = 'SET'; -/** Known top-level settings.json keys (as of CC 2.1.181 / June 2026) */ +/** Known top-level settings.json keys (as of CC 2.1.193 / June 2026) */ const KNOWN_KEYS = new Set([ 'additionalDirectories', 'agent', 'allowAllClaudeAiMcps', 'allowedChannelPlugins', 'allowedHttpHookUrls', @@ -37,6 +37,9 @@ const KNOWN_KEYS = new Set([ 'spinnerTipsOverride', 'spinnerVerbs', 'statusLine', 'strictKnownMarketplaces', 'useAutoModeDuringPlan', 'voiceEnabled', 'wheelScrollAccelerationEnabled', 'worktree', '$schema', + // CC 2.1.193 binary-verified (M-BUG-10): present as quoted string literals in the binary + 'agentPushNotifEnabled', 'remoteControlAtStartup', 'skipAutoPermissionPrompt', + 'skipDangerousModePermissionPrompt', 'skipWorkflowUsageWarning', 'tui', ]); /** Deprecated keys with migration info */ @@ -75,6 +78,16 @@ const VALID_EFFORT_LEVELS = new Set(['low', 'medium', 'high', 'xhigh', 'max']); * a project root to walks/discovery, inflating per-turn cost and confusing scope. */ const ADDITIONAL_DIRS_THRESHOLD = 2; +/** M-BUG-10: the CC settings schema is passthrough — it forwards unrecognized + * keys unchanged rather than rejecting them, so an arbitrary unknown key is + * valid/forward-compatible, not an error. The only real risk is a TYPO of a + * real key (the intended setting silently does nothing), so an unknown key is + * flagged ONLY when it closely matches a known key: edit distance within + * TYPO_MAX_DISTANCE and both keys at least TYPO_MIN_LEN chars (short keys are + * too noisy for reliable edit-distance matching). */ +const TYPO_MAX_DISTANCE = 2; +const TYPO_MIN_LEN = 4; + /** The only valid sub-keys of `autoMode`, each a prose-rule string array * (the literal "$defaults" is a valid entry). Verified against * code.claude.com/docs/en/auto-mode-config. */ @@ -115,17 +128,32 @@ export async function scan(targetPath, discovery) { continue; } - // Check for unknown keys + // Check for unknown keys — typo gate (M-BUG-10). The CC settings schema is + // passthrough, so an unrecognized key is NOT an error; only a typo of a real + // key is (the intended setting silently does nothing). Flag a key only when + // it closely matches a known key; an unknown key far from every known key is + // treated as valid/forward-compatible and emitted nothing. for (const key of Object.keys(parsed)) { - if (!KNOWN_KEYS.has(key)) { + if (KNOWN_KEYS.has(key)) continue; + let nearest = null; + let best = Infinity; + for (const known of KNOWN_KEYS) { + if (Math.min(key.length, known.length) < TYPO_MIN_LEN) continue; + const d = levenshtein(key, known); + if (d <= TYPO_MAX_DISTANCE && d < best) { + best = d; + nearest = known; + } + } + if (nearest) { findings.push(finding({ scanner: SCANNER, - severity: SEVERITY.medium, - title: 'Unknown settings key', - description: `${file.relPath}: "${key}" is not a recognized settings.json key. It will be silently ignored.`, + severity: SEVERITY.low, + title: 'Possible typo in settings key', + description: `${file.relPath}: "${key}" is not a recognized settings.json key, but it closely matches "${nearest}". Claude Code forwards unrecognized keys unchanged (it does not reject them), so if "${key}" is a typo of "${nearest}" the intended setting silently has no effect.`, file: file.absPath, evidence: key, - recommendation: 'Check spelling. See https://json.schemastore.org/claude-code-settings.json for valid keys.', + recommendation: `Did you mean "${nearest}"? Fix the spelling, or keep "${key}" if it is intentional (e.g. a newer settings key this audit does not recognize yet).`, autoFixable: false, })); } diff --git a/tests/lib/string-utils.test.mjs b/tests/lib/string-utils.test.mjs index 9855b2d..2629bff 100644 --- a/tests/lib/string-utils.test.mjs +++ b/tests/lib/string-utils.test.mjs @@ -1,6 +1,6 @@ import { describe, it } from 'node:test'; import assert from 'node:assert/strict'; -import { lineCount, truncate, isSimilar, extractKeys, normalizePath } from '../../scanners/lib/string-utils.mjs'; +import { lineCount, truncate, isSimilar, extractKeys, normalizePath, levenshtein } from '../../scanners/lib/string-utils.mjs'; describe('lineCount', () => { it('counts lines correctly', () => { @@ -90,6 +90,42 @@ describe('extractKeys', () => { }); }); +describe('levenshtein', () => { + it('returns 0 for identical strings', () => { + assert.strictEqual(levenshtein('permissions', 'permissions'), 0); + }); + + it('counts a single substitution as 1', () => { + assert.strictEqual(levenshtein('model', 'modet'), 1); + }); + + it('counts a single deletion as 1 (permisions → permissions)', () => { + assert.strictEqual(levenshtein('permisions', 'permissions'), 1); + }); + + it('counts a single insertion as 1', () => { + assert.strictEqual(levenshtein('hooks', 'hooks2'), 1); + }); + + it('counts a transposition as 2 (standard Levenshtein)', () => { + assert.strictEqual(levenshtein('import', 'improt'), 2); + }); + + it('returns the other length when one string is empty', () => { + assert.strictEqual(levenshtein('', 'abc'), 3); + assert.strictEqual(levenshtein('abc', ''), 3); + assert.strictEqual(levenshtein('', ''), 0); + }); + + it('is symmetric', () => { + assert.strictEqual(levenshtein('effortLevel', 'efortLevel'), levenshtein('efortLevel', 'effortLevel')); + }); + + it('gives a large distance for unrelated keys', () => { + assert.ok(levenshtein('unknownKey123', 'permissions') > 2); + }); +}); + describe('normalizePath', () => { it('expands ~ to HOME', () => { const home = process.env.HOME; diff --git a/tests/scanners/settings-validator.test.mjs b/tests/scanners/settings-validator.test.mjs index 5aac01a..2612e10 100644 --- a/tests/scanners/settings-validator.test.mjs +++ b/tests/scanners/settings-validator.test.mjs @@ -47,10 +47,12 @@ describe('SET scanner — broken project', () => { result = await scan(resolve(FIXTURES, 'broken-project'), discovery); }); - it('detects unknown settings key', () => { - // CA-SET-001 in broken-project, evidence='unknownKey123'. + it('does NOT flag an arbitrary unknown key (CC schema is passthrough)', () => { + // M-BUG-10: "unknownKey123" is not close to any known key, so it is a + // valid forward-compatible / passthrough key — NOT a typo. Claude Code + // forwards unrecognized keys unchanged, so flagging it is a false positive. const found = result.findings.some(f => f.scanner === 'SET' && /unknownKey123/.test(f.evidence || '')); - assert.ok(found, 'Should detect unknownKey123'); + assert.ok(!found, 'unknownKey123 is far from every known key → must not be flagged'); }); it('detects deprecated key (includeCoAuthoredBy)', () => { @@ -192,6 +194,63 @@ describe('SET scanner — CC 2.1.114→181 valid keys (Batch 1 false-positive fi }); }); +describe('SET scanner — unknown-key typo gate (M-BUG-10)', () => { + // The CC settings schema is passthrough: it forwards unrecognized keys + // unchanged rather than rejecting them, so an arbitrary unknown key is + // valid/forward-compatible and must NOT be flagged. The only real risk is a + // TYPO of a real key (the intended setting silently has no effect), so the + // scanner flags ONLY unknown keys that closely match a known key. + // Path-guard blocks committing settings.json fixtures → materialize a temp one. + let tmpRoot; + let result; + const TYPO_TITLE = 'Possible typo in settings key'; + + beforeEach(async () => { + resetCounter(); + tmpRoot = await mkdtemp(join(tmpdir(), 'ca-set-typo-')); + await mkdir(join(tmpRoot, '.claude'), { recursive: true }); + const settings = { + $schema: 'https://json.schemastore.org/claude-code-settings.json', + permisions: { deny: ['Read(./.env)'] }, // TYPO of "permissions" (edit distance 1) + someNewKey2027: true, // forward-compat / passthrough — far from every known key + permissions: { deny: ['Read(./.env)'], allow: ['Bash(npm run *)'] }, + }; + await writeFile( + join(tmpRoot, '.claude', 'settings.json'), + JSON.stringify(settings, null, 2) + '\n', + 'utf8', + ); + const discovery = await discoverConfigFiles(tmpRoot); + result = await scan(tmpRoot, discovery); + }); + + afterEach(async () => { + if (tmpRoot) await rm(tmpRoot, { recursive: true, force: true }); + }); + + it('flags a likely typo ("permisions") and suggests the nearest known key', () => { + const typo = result.findings.find(f => f.scanner === 'SET' && f.evidence === 'permisions'); + assert.ok(typo, `expected a typo finding for "permisions"; got: ${result.findings.map(f => `${f.title}:${f.evidence || ''}`).join(' | ')}`); + assert.equal(typo.title, TYPO_TITLE); + assert.match(typo.recommendation, /permissions/, 'recommendation suggests the nearest known key'); + }); + + it('marks the typo finding as low severity (passthrough → not a hard error)', () => { + const typo = result.findings.find(f => f.scanner === 'SET' && f.evidence === 'permisions'); + assert.equal(typo.severity, 'low'); + }); + + it('does NOT flag a forward-compatible key far from any known key', () => { + const fwd = result.findings.find(f => f.scanner === 'SET' && f.evidence === 'someNewKey2027'); + assert.equal(fwd, undefined, 'someNewKey2027 is far from every known key → passthrough, not flagged'); + }); + + it('emits exactly one typo finding for this file', () => { + const typos = result.findings.filter(f => f.scanner === 'SET' && f.title === TYPO_TITLE); + assert.equal(typos.length, 1, `expected exactly one typo finding; got: ${typos.map(f => f.evidence).join(', ')}`); + }); +}); + describe('SET scanner — empty project', () => { let result; beforeEach(async () => {