@deloitte-digital-il/fred-policy
v0.2.1
Published
Implements `fred-policy`: the pack-neutral decision table of ADR-0007 D8 (`evaluate`), `classifyCore`, `resolveTarget`, `approvalStands`, `isWithinAllowedPaths`, `validatePolicy`, and `isCertified()` / `reviewApproves()` with condition 4 read from targets
Readme
Implements fred-policy: the pack-neutral decision table of ADR-0007 D8 (evaluate), classifyCore, resolveTarget, approvalStands, isWithinAllowedPaths, validatePolicy, and isCertified() / reviewApproves() with condition 4 read from targets (FRED-237). Pure functions, no runtime dependency but @fred/fred-core.
Public exports (nine): evaluate, classifyCore, resolveTarget, approvalStands, isWithinAllowedPaths, validatePolicy, isCertified, reviewApproves, REASONS.
resolveTarget called without packs (or with a non-array) honours no ephemeral line, so every live line resolves { unregistered: true } (fail closed; ADR-0007 D2 F2).
isCertified(changeSet, records) takes records.packs (the loadPack results the engagement loads). Without usable packs it never certifies (validation-target-not-bound). A call admitted only by a target-auth Approval returns approval: null: that record has no id yet (a stable reference is for the architect before plan T8).
What the raw-line check is, and is not
evaluate reads a shell line lexically, the same on every host. It is a bounded best-effort layer, not a shell: it denies what it can read as a hidden executable, an auth command or a protected path, and fails closed on syntax it cannot read (brace sequences, expansions of more than 64 words, POSIX classes, $'). What it cannot see stays the accepted residual of ADR-0007 D10 and D11: variable expansion, eval, base64 or rev | sh pipelines, and script files. Verified: bash(1) QUOTING and EXPANSION. Verify in spike: PowerShell and cmd.exe quoting (FRED-019).
It denies, with a named reason: ANSI-C and locale quoting ($', $"), ${/$IFS in role runs, a NUL byte, brace and glob forms that can spell a hidden name or .fred or the run-token store (env {fred,x}, fre?, .fr*/x, run-tok*/key), \<newline> joins, and an expansion at a command position or glued to a hidden name (f$(:)red).
Residual, accepted (ADR-0007 D10): a command built by F=fred sh -c '$F approve', eval "$C", export F=fred; ..., base64 or rev | sh, an alias or function, or a script file is outside the layer. Also accepted (PM ruling, D10): cwd-relative and recursive reads of the token store (cd ~/.local/state && cat $PWD/*/*/key, $X/*/*/key, for loops over *, stepwise cd *, grep -r SECRET . from an ancestor, find ~ -name key | xargs cat), reads through a symlink (symlink resolution is not done here), and a leading */ in an agent session. Any agent with a file tool can read the key; the real control is a TTY challenge inside fred approve (follow-up below). In an agent session an unknown typed tool is allowed (criterion 9 skips the typed lookup), and ${ is allowed.
Deliberate false positives and their remedies. First, in plain words: in a role run ls */, du -sh */, cat */package.json and wc -l */*.js are refused, because a leading */ could reach the run-token store; name the directory instead (ls src/, du -sh src docs). An agent session is not refused for these. Also, a token that is fred, gh or a pack executable, or that holds one next to =, !, : or , (FOO=fred, core.pager=gh), is refused. A token that is fred, gh, a pack executable, or holds fred-core, fred-policy, fred-cli, fred-broker, @fred/ or a pack's hidden name is denied wherever it stands (grep fred-core docs/, git commit -m 'fix fred bug'); so are a glob that can match a hidden name (ls f*, rm gh*, ls ??), .* and *s globs that can match .fred or run-tokens, a $X as a command, brace sequences ({a..b}), a bracket negation or class in a glob, a */dir or <store parent>/* wildcard, and git commit -m 'fix push -d bug'. Remedies: rephrase the line, use the host's own search tool (Grep), or use a typed operation. A command or expansion that is built at run time is refused too: eval "$(ssh-agent)", eval "$(direnv hook bash)" and bash -c "echo $(date)" (the message says to run it yourself outside the agent, or write the command out). A name inside list or splat syntax (["fred", ...], %w[fred ...]) is refused as well. ls src/* and echo $(date) are allowed. The run-token store clause also denies any path segment equal to the last segment of the configured tokenStore (the default ends in run-tokens; a generic directory name there denies every path with that segment).
Agent sessions: deny-by-default, then frozen (owner decision D1, 2026-11-03; ADR-0007 rev 10). An agent session's raw line (src/agent.js) is allowed only when it holds no shell metacharacter, quote or backslash, and every segment (split at &&, ||, ;, |) is a fred read form, one of the closed git read forms (status, diff, log, show, rev-parse, ls-files, and the list forms of branch, tag and remote), each with an allow-list of flags and only plain relative paths or refs as operands (git grep is not allowed; use the host's search tool), a pack's untargeted form, or a pack form on a live ephemeral target. Every token also meets the protected-path check (row 3). Everything else is raw-not-allowed. Role runs keep the lexer. The lexer is frozen: no new case is added to tokenize.js, lexical.js or the raw path of evaluate.js; a newly found bypass of the role-run lexer goes to D10's accepted residual or to a typed operation. Accepted residual: a git read can run a command named in repository config (core.fsmonitor, diff.external); an agent that can write .git/config with a file tool is already in D10's file-tool residual.
Tests share one stub pack table, test/stub-pack.js; the certification scenarios are the table in test/certification-table.js.
The deny-by-default grammar protects agent sessions. Hosts must not give roles a bash tool, and must set FRED_AGENT_SESSION and call evaluate with session 'agent' for the main session.
