Groundwork: generalize per-provider credentials and the providers config block

[gfargo]

Split out of the #156 roadmap spike (Tier 2: extensibility groundwork). Blocks every candidate third adapter. Pairs with #181.

Problem

Two closed, flat, provider-specific shapes that every new provider has to widen.

1. ProviderOptions — flat credential fields

// src/lib/utils/providerHelper.ts
export interface ProviderOptions {
  provider?: ProviderType
  config?: ...
  interactive?: boolean

  // Vercel-specific
  token?: string
  projectId?: string
  teamId?: string

  // Cloudflare-specific
  apiToken?: string
  zoneId?: string
  accountId?: string
}

These same fields are then threaded individually through WithCredentialsOptions, every command's options interface, and every command's yargs builder. AWS WAF alone would add accessKeyId, secretAccessKey, sessionToken, region, scope, webAclArn; GCP adds a service-account/OAuth2 shape that doesn't resemble a flat token at all. Continuing to flatten produces a ~20-field union where most fields are meaningless for any given provider.

2. ProvidersConfig — closed 2-key interface

// src/lib/types/common.ts
export interface ProvidersConfig {
  vercel?: { projectId?: string; teamId?: string }
  cloudflare?: { zoneId?: string; accountId?: string }
}

Mirrored by an equally closed zod schema in commonSchemas.ts. Also encodes the one-provider-one-target assumption called out separately in the multi-resource-targeting issue.

Proposed approach

• Introduce a per-provider credential descriptor owned by each adapter: which env vars it reads, which CLI flags it accepts, which are required, and how to prompt for them. getProviderInstance resolves generically against the descriptor instead of branching per provider.
• Replace ProviderOptions' flat fields with a credentials?: Record<string, string | undefined> bag plus the descriptor for validation/prompting. Keep the existing flags working as aliases so this isn't a breaking CLI change.
• Make ProvidersConfig an index-signature type (Record<string, ProviderSettings>) with per-provider zod schemas contributed by each adapter, rather than one closed interface + one closed schema.

Constraints

• Not a breaking change for users. --token/--projectId/--teamId/--apiToken/--zoneId/--accountId and their env vars must keep working exactly as they do today.
• ProviderDetector currently keys off providers.vercel.projectId / providers.cloudflare.zoneId — its detection signals need to come from the same descriptors rather than hardcoded paths.
• The generated JSON schema (schema/firewall-config.schema.json) must still validate real configs; check pnpm build:schema output.

Acceptance criteria

• A new provider declares its credentials once, in its own adapter directory
• No provider-specific credential field remains in ProviderOptions / WithCredentialsOptions / command option interfaces
• ProvidersConfig accepts an arbitrary provider key with a provider-supplied schema
• Existing configs and existing CLI flags/env vars work unchanged (full suite green + manual run against demos/mock-server.mjs)

[gfargo]

Partially addressed — status

Done (#192, #193):

• Credential precedence pinned first (test: pin credential precedence (flag > config > env) before refactoring it #192) — nothing asserted the flag > config > env chain before, per credential. Landed as its own PR ahead of any refactor, and mutation-verified (inverting precedence fails the suite) so it's a real net rather than tests that pass regardless.
• Per-provider credential descriptors (fix: resolve Cloudflare zoneId/accountId from config; add credential descriptors #193) — each adapter now declares its credentials once in its own directory: flag key, env var, label, required, secret, and whether it may live in a config file. resolveCredentials applies the precedence chain from the descriptor instead of every call site spelling it out per credential. Env-var names are no longer bare literals scattered across six-plus files.
• A real bug this surfaced (fix: resolve Cloudflare zoneId/accountId from config; add credential descriptors #193) — getCloudflareProvider never read the config file at all, so providers.cloudflare.zoneId was silently ignored and users got "Cloudflare credentials missing" despite declaring it. Same bug fix: resolve Vercel projectId/teamId from config in both legacy and unified shapes #171 fixed for Vercel; Cloudflare sat three lines below it and was never fixed. Confirmed against the real CLI, not just tests. The duplication this issue is about is precisely what let it hide.

Still open — the two API-shape changes, deliberately not folded into a bug fix:

1. ProviderOptions' flat per-provider fields. Now that descriptors exist, the flat token/projectId/teamId/apiToken/zoneId/accountId fields could collapse into a credentials bag validated against the descriptor. Mechanical but wide — the fields thread through WithCredentialsOptions and every command's options interface, and must keep working as aliases so it isn't a breaking CLI change.

2. ProvidersConfig as an index-signature type. Flagging a trade-off I hit while scoping this: making it Record<string, ProviderSettings> loses typo-safety on the two real providers (providers.clodflare would typecheck) in exchange for a benefit that only materialises when provider chore: updates pnpm-lock.yaml #3 lands — and Epic: Fastly Next-Gen WAF adapter #186 would add fastly?: {...} as a one-line change to the existing interface anyway. Worth a deliberate decision rather than doing it because the issue said so. Possibly best deferred until Epic: Fastly Next-Gen WAF adapter #186 is actually being built.

Recommend keeping this open for (1) and (2), with (2) explicitly gated on a decision about whether the typo-safety trade is worth making before a third provider exists.

[gfargo]

Related structural findings, filed as their own issues since they're adjacent but distinct from this one's remaining scope (the `ProviderOptions`/`ProvidersConfig` shape changes):

• Split RuleTranslator's per-provider translation logic out of one 782-line file #196 — `RuleTranslator.ts` has the same "logic that should live per-adapter is accumulating in one shared file" shape as the credential duplication this issue addressed, just for rule translation instead of credentials.
• Add a shared conformance test suite that every IFirewallProvider must pass #197 — no conformance suite runs automatically across registered providers, which is part of why the fix: resolve Cloudflare zoneId/accountId from config; add credential descriptors #193 Cloudflare bug wasn't caught earlier: nothing forced Cloudflare's credential resolution to be checked against the same test as Vercel's.

Both slotted ahead of #186 in the roadmap.

[gfargo]

Progress update: 2 of 3 acceptance criteria are done, landed as two separate PRs:

• refactor: drive ProviderDetector from CREDENTIAL_DESCRIPTORS #229 — generalized ProviderDetector to derive auto-detection from CREDENTIAL_DESCRIPTORS instead of hardcoding each provider's field names.
• refactor: flatten provider credential fields to a generic bag #230 — flattened ProviderOptions/WithCredentialsOptions/every command's local options interface to a generic credentials?: Record<string, string | undefined> bag resolved against a provider's CredentialDescriptor, plus a shared credentialOptions.ts yargs builder so the 7 credential flags are declared once instead of 8×. Not a breaking change — every existing flag/env var still works identically.

Remaining, deliberately not attempted in either PR: making ProvidersConfig (src/lib/types/common.ts) an index-signature type with per-provider-contributed zod schemas, instead of the closed interface it is today. I looked at this while scoping #230 — there's no existing composition pattern in the codebase for "a schema that grows per-adapter," and inventing one speculatively, ahead of a second real need for it, felt like the wrong tradeoff versus just adding Cloud Armor's block to ProvidersConfig by hand the same way Fastly's was added (#186). That's a real gap this issue correctly identifies, but I don't think it should block starting the GCP epic (#187) — flagging here rather than closing this issue outright, in case a third data point (AWS, #188) makes the composition-mechanism case stronger than it is with just three providers.