feat(utils): linkAuth pure engine and macro vocabulary (#113 slice 1)

[ejdutton]

Summary

Slice 1 of issue #113 (authenticated external link resolution). Adds the pure-logic foundation — config-driven engine + macros + Zod schema — with no consumer wiring yet. The engine resolves an authenticated fetch plan for a URL but doesn't issue requests, doesn't touch the existing ExternalLinkValidator, and doesn't add codes to CODE_REGISTRY. Those land in slice 2.

What's in this PR

Engine — eight modules in packages/utils/src/link-auth/:

Module	Role
transforms.ts	Closed allowlist: base64url, urlencode, lower
template.ts	${name} / ${transform(name)} renderer
rewrite.ts	Ordered when → vars → to pipeline
build-headers.ts	Header rendering + structural Authorization redaction
select-provider.ts	Host-glob match with excludeHost (picomatch)
expand-macro.ts	YAML loader + deep-merge expander (lazy load)
resolve-token.ts	Ordered env / safeExecResult-backed command sources
resolve.ts	Public resolveAuthenticatedUrl(url, config) entry

Returns one of:

• { fetchUrl, headers } — ready to fetch
• { outcome: 'unsupported' } — no provider claims, or rewrite missed
• { outcome: 'unverified', reason } — claimed + rewrote, but no token resolved

Macros — github and sharepoint ship as a YAML data asset (src/link-auth/macros.yaml). New cross-platform post-build asset-copy in packages/dev-tools/src/copy-yaml-assets.ts invoked from utils' build script.

Schema — LinkAuthConfigSchema (Zod, strict) in packages/resources/src/schemas/link-auth.ts. Wired as linkAuth: LinkAuthConfigSchema.optional() on ResourcesConfigSchema. Accepts either { use: <macro>, ...overrides } or full inline providers.

Tests — 140 unit tests in utils + 29 schema tests in resources, all pure-logic (no network, no filesystem dependencies except the loaded macros.yaml asset). Security-load-bearing tests pin:

• Closed-allowlist guarantee against Object.prototype keys (toString, __proto__, constructor, etc.)
• ${__proto__} lookup bypass defense in the template renderer
• Token never leaks into Authorization header (precedence rule when a regex capture is named token)
• shell: false literal-argv handling in token commands (shell operators become literal argv elements, not pipes)
• RFC 4648 §10 known-answer vectors for base64url (guards against lockstep encoder/decoder regression)

What's NOT in this PR (deferred per design)

• Wiring into ExternalLinkValidator health-check branch — slice 2
• The five LINK_AUTH_* entries in CODE_REGISTRY + docs/validation-codes.md — slice 2
• The doc-anchor coverage test for CODE_REGISTRY entries — slice 2 (will audit existing codes for gaps when added)
• Content-fetch primitive + content cache — slice 3
• Cross-platform .cmd-shim system test for token command dispatch — slice 4
• GIT_* env scrubbing for git-backed token commands — slice 4

Notable design decisions

• Lazy macro loading. expand-macro.ts defers readFileSync to first call. Why: other tests in the repo mock node:fs, so eager module-init reads crash unrelated test suites. Module import is now side-effect-free.
• Object.create(null) everywhere. Every map produced by the engine (contexts, captures, headers, expanded macros) uses null prototypes. Belt-and-braces against __proto__-shaped keys from any source (YAML, regex captures, user config).
• The Provider type lives in resolve.ts, the schema in resources. Two sources of truth for the shape, kept in sync by code review. Future option to derive one from the other (probably the TS interface from the Zod schema), but not in this slice.
• use: form overrides are NOT strictly validated. Macro overrides can be any shape per Zod's .passthrough(). Strict validation of the merged result is post-expansion (slice 2 wires that).

Test plan

• bun run validate passes locally (✅ confirmed: 14 steps, 214s)
• CI green
• Spot-check that resources.linkAuth: { providers: [{ use: 'github' }] } in a vibe-agent-toolkit.config.yaml parses without error (manual)
• Spot-check that expandMacro('github') returns the expected shape via a Node REPL (manual)

Implements design doc in #113 (slice 1 of 4).

🤖 Generated with Claude Code

[codecov]

Codecov Report

❌ Patch coverage is 96.17647% with 13 lines in your changes missing coverage. Please review.
✅ Project coverage is 81.78%. Comparing base (2050b5b) to head (268770f).

Files with missing lines	Patch %	Lines
packages/utils/src/link-auth/resolve-token.ts	82.92%	7 Missing ⚠️
packages/utils/src/link-auth/expand-macro.ts	96.15%	3 Missing ⚠️
packages/utils/src/link-auth/template.ts	94.91%	3 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #120      +/-   ##
==========================================
+ Coverage   81.49%   81.78%   +0.29%     
==========================================
  Files         215      223       +8     
  Lines       16795    17135     +340     
  Branches     3214     3326     +112     
==========================================
+ Hits        13687    14014     +327     
- Misses       3108     3121      +13     

Files with missing lines	Coverage Δ
packages/utils/src/link-auth/build-headers.ts	100.00% <100.00%> (ø)
packages/utils/src/link-auth/resolve.ts	100.00% <100.00%> (ø)
packages/utils/src/link-auth/rewrite.ts	100.00% <100.00%> (ø)
packages/utils/src/link-auth/select-provider.ts	100.00% <100.00%> (ø)
packages/utils/src/link-auth/transforms.ts	100.00% <100.00%> (ø)
packages/utils/src/link-auth/expand-macro.ts	96.15% <96.15%> (ø)
packages/utils/src/link-auth/template.ts	94.91% <94.91%> (ø)
packages/utils/src/link-auth/resolve-token.ts	82.92% <82.92%> (ø)

Files with missing lines	Coverage Δ
packages/utils/src/link-auth/build-headers.ts	100.00% <100.00%> (ø)
packages/utils/src/link-auth/resolve.ts	100.00% <100.00%> (ø)
packages/utils/src/link-auth/rewrite.ts	100.00% <100.00%> (ø)
packages/utils/src/link-auth/select-provider.ts	100.00% <100.00%> (ø)
packages/utils/src/link-auth/transforms.ts	100.00% <100.00%> (ø)
packages/utils/src/link-auth/expand-macro.ts	96.15% <96.15%> (ø)
packages/utils/src/link-auth/template.ts	94.91% <94.91%> (ø)
packages/utils/src/link-auth/resolve-token.ts	82.92% <82.92%> (ø)

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[jdutton]

Approve. High-quality, security-conscious foundation slice. Read all 8 engine modules, the schema, build helper, and wiring; ran the 169 isolated unit tests (all green); and independently verified the security-load-bearing properties.

Verified independently

• 169 unit tests pass (140 utils + 29 resources).
• Host-match anchoring is real — ran picomatch directly: github.com rejects evil-github.com and github.com.evil.com; *.sharepoint.com claims subdomains but not the bare apex.
• safeExecResult is shell: false — the §6.1 "shell operators become literal argv" claim holds at the exec layer.
• Token-never-leaks invariant in resolve.ts is correct — resolved token wins over any regex capture named token.

Strengths

• Consistent prototype-pollution discipline (Object.create(null) + Object.hasOwn everywhere; closed allowlist via hasOwn, not in), each pinned by adversarial tests.
• Clean, genuinely-pure slice boundary; thoughtful lazy macro load.
• Postel's law applied correctly (strict inline schema, .passthrough() only on the macro-override branch).

Minor (non-blocking)

1. Comment rot — expand-macro.ts:10 and the CHANGELOG entry reference scripts/copy-yaml-assets.mjs, which doesn't exist; the real helper is packages/dev-tools/src/copy-yaml-assets.ts. Worth fixing both (CHANGELOG is still in [Unreleased]).
2. Test gap — deepMerge is safe against a __proto__-as-override-key attack, but unlike every sibling module it has no adversarial test pinning it. Cheap to add (expandMacro('github', { __proto__: { polluted: true } }) → assert no global pollution).
3. Informational: redactHeaders is implemented/tested but has no production call site until slice 2 — the §8 "tokens never leak" guarantee depends on that wiring landing.

Nice work.

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.8% Duplication on New Code

See analysis details on SonarQube Cloud