@adcp/sdk/lint: build-time credential-discipline detection (eslint plugin)

[bokelley]

Problem

Surfaced during expert DX review of #1535.

The args.<vendor>_access_token pattern in adopter extractContext implementations is widespread — every v5 adapter we ship reads it, and the pattern recurs in adapter-side fan-out paths because extractContext's args: Record<string, unknown> makes the unsafe read trivial.

Runtime rejection via credentialPolicy: 'authInfo-only' (#1535) catches these at dispatch time, but build-time detection beats runtime detection — adopters see the issue when they write the code, not when a buyer's request hits production.

Proposal

Ship @adcp/sdk/lint (or npx adcp-doctor mode) — a static-analysis tool that scans adopter codebases for the extractContext-credential-read antipattern.

Concrete starting rule set:

1. no-credential-read-from-args — flag args.<word>_access_token / args.<word>_secret / args.<word>_password / args.context.<word>_access_token reads in any function whose name matches /^extract(Context|Operational)Context$/ or whose declaring object has OperationalPlatform as a type.
2. require-account-store-resolve-for-credentials — flag any args.access_token read outside a resolveAccount callback or extractContext.
3. prefer-authinfo-credential-channel — suggestion-level: code that reads from args.<credential> should consider ctx.authInfo.token / ctx.authInfo.credential instead.

Distribution:

• (a) ESLint plugin (@adcp/sdk/eslint-plugin) — fits adopter CI, low integration cost
• (b) npx adcp-doctor mode — one-shot scan, useful for adopters not on ESLint

Recommend (a) primary, (b) as wrapper.

Related

• feat(server): credentialPolicy args-bag scan (#1529 L1) #1535 (L1 credentialPolicy) — runtime sibling
• DX review on feat(server): credentialPolicy args-bag scan (#1529 L1) #1535: dx-expert recommended this as the bigger DX win than runtime rejection
• v7 default flip (separate tracking) — lint ships as the migration path

[bokelley]

Triage

Classification: Feature request
Bucket(s): library, dx
Status: ready-for-human

What the experts said:

• code-reviewer: Flag — OperationalPlatform type is not yet in the codebase (rule 1 is unimplementable as described today); rule 2 scope analysis is unreliable without type-graph awareness; the monorepo's existing packages/ workspace is the right home to avoid forcing eslint as a peer dep on all @adcp/sdk runtime consumers.
• security-reviewer: Flag — proposed ESLint pattern set omits api_key, bearer, authorization, and others already in DEFAULT_CREDENTIAL_PATTERNS; a divergent subset creates false confidence on servers running at the default 'lax' policy; name-only extractContext detection has both false-positive and false-negative modes; npx adcp-doctor introduces a typosquatting surface — adcp doctor subcommand is safer.

My take: The concept is sound — build-time detection is strictly better than an opt-in runtime guard that most servers never enable — but four design questions need answers before a PR can land: (a) the correct type name for the operational context extractor interface (not yet in codebase; OperationalPlatform PR #1536 is still open), (b) whether the ESLint pattern set derives from DEFAULT_CREDENTIAL_PATTERNS for parity, (c) packages/eslint-plugin workspace vs. ./eslint-plugin root export path, and (d) adcp doctor subcommand vs. standalone npx adcp-doctor. @bokelley — ready to execute once these are resolved.

---

Triaged by Claude Code. Session: https://claude.ai/code/session_01XQC6h7kfqDcWX74Qo7nQVX

---

Generated by Claude Code

[bokelley]

Decisions on the four design questions, then this needs to land as a bigger separate effort (new package workspace, new tooling scaffold — not a one-PR change like #1538/#1539).

Q-a: Type name for the operational context extractor interface.
OperationalPlatform shipped in 6.10.0 (#1536) — extractContext(args, sessionToken?, requireAuth?) is the method to flag. The method name is what the lint rule keys on, not the interface name (TS-side typing isn't reliable enough alone per the code-reviewer's note).

Lint rule key: MemberExpression.object.name === 'args' AND ancestor is a method named extractContext (or synthesizeFromArgs once #1540 ships).

Q-b: ESLint patterns derive from DEFAULT_CREDENTIAL_PATTERNS?
Yes — the security-reviewer's parity concern is decisive. The lint rule imports DEFAULT_CREDENTIAL_PATTERNS from @adcp/sdk/server and applies the same regex set. This means:

• New patterns added to runtime defaults flow automatically into lint
• Adopters who extend runtime patterns (credentialPolicy.patterns.extend) need to also extend lint via plugin config — document that

Q-c: packages/eslint-plugin workspace vs. ./eslint-plugin root export?
packages/eslint-plugin workspace. The security-reviewer + code-reviewer both flagged "don't force eslint as a peer dep on @adcp/sdk runtime consumers." A separate workspace publishes as @adcp/eslint-plugin independently. Adopters who want the lint rules: npm i -D @adcp/eslint-plugin. Adopters who don't: zero impact.

Q-d: adcp doctor subcommand vs. standalone npx adcp-doctor?
adcp doctor subcommand. Typosquatting risk on npx adcp-doctor is real — anyone can publish adcp-doctor to npm with malicious payload, and npx will fetch it without confirmation. Subcommand on the existing adcp CLI inherits its supply-chain provenance.

Scope note

Implementation is a 3-piece scaffold:

1. packages/eslint-plugin/ — new workspace. ESLint plugin with rules no-credential-read-from-args, prefer-authinfo-credential-channel. Imports DEFAULT_CREDENTIAL_PATTERNS from the SDK.
2. bin/adcp.js — add doctor subcommand that runs the plugin against the adopter's codebase.
3. Docs: how to wire it.

This isn't a one-PR effort — new package, new CI, eslint dep tree. Filing as a multi-PR plan rather than starting today. @bokelley — assign to me when ready and I'll scope a phased implementation.