feat(cloudflare/ai): add AI.ProviderKey BYOK composition helper

[agcty]

Cloudflare.AI.ProviderKey — a composition helper that declares a Cloudflare AI Gateway bring-your-own-key (BYOK) provider key as a single resource.

A BYOK key needs two coordinated resources:

• a Secrets Store Secret holding the provider API key — scoped to ai_gateway and named exactly {gatewayId}_{providerSlug}_{alias}, and
• a GatewayProvider config that references that secret on the gateway.

This helper owns that naming contract and wires both, so app stacks declare one resource instead of hand-coupling the two:

const store = yield* Cloudflare.SecretsStore.Store("Store");
const gateway = yield* Cloudflare.AI.Gateway("Gateway", {
  id: "my-gateway",
  storeId: store.storeId,
});

const { secret, gatewayProvider } = yield* Cloudflare.AI.ProviderKey("OpenAiKey", {
  store,
  gatewayId: gateway.gatewayId,
  providerSlug: "openai",
  value: yield* Config.redacted("OPENAI_API_KEY"),
});

It returns { secret, gatewayProvider } so either underlying resource stays addressable.

Notes

• Rebased onto current main and re-ported onto the Cloudflare/AiGateway/ → Cloudflare/AI/ restructure: the helper composes GatewayProvider (formerly AiGatewayProviderConfig), lives at AI/ProviderKey.ts, and surfaces as Cloudflare.AI.ProviderKey.
• Per review: the ProviderKey effect is piped through Namespace.push(id), so the children are plain Secret("Secret") and GatewayProvider("Provider") namespaced under ${id} (drops the secretResourceId escape hatch the old ${id}-secret default needed).
• Updates the GatewayProvider manual-wiring example to use Config.redacted (per the earlier review note) and cross-links this helper.
• ProviderKey is tagged @resource with @section/@example blocks, so docs:gen emits an API reference page for it (untagged exports are skipped).
• Tests cover the {gatewayId}_{providerSlug}_{alias} naming contract, explicit alias, redeploy idempotency, in-place value rotation (stable secretId + providerConfigId), the alias-change replacement cascade (secret renamed, provider config replaced and re-pointed, old secret reclaimed), and a post-destroy check that the BYOK secret is reclaimed from the surviving (adopted) store.
• tsc -b is green. The check job's red is docs:check failing on pre-existing broken links to unrelated Cloudflare provider pages (/providers/cloudflare/email/*, /providers/cloudflare/queue) — not introduced here (no website/ changes).

🤖 Generated with Claude Code

[agcty]

@sam-goodwin rebased and tested with cf resources now

[agcty]

Reworked this onto current main: instead of a standalone Resource, AiGatewayProviderKey is now a thin composition helper over the Secret + AiGatewayProviderConfig resources that landed in main since this was opened — drops ~700 lines, resolves the merge conflict, and addresses your Config.redacted comment in the docs. The test is scoped to the composition + naming contract; happy to add a post-destroy orphaned-secret check if you'd like.

[agcty]

Rebased onto current main and re-ported onto the Cloudflare/AiGateway/ → Cloudflare/AI/ restructure. The helper is now Cloudflare.AI.ProviderKey, composing SecretsStore.Secret + AI.GatewayProvider (the renamed provider config), returning { secret, gatewayProvider }. Added the post-destroy orphaned-secret check you mentioned. tsc -b is green; the check red is docs:check tripping on pre-existing broken links to unrelated Cloudflare provider pages (/providers/cloudflare/email/*, /providers/cloudflare/queue) — no website/ changes here.

[agcty]

@sam-goodwin any feedback on this? would love to use it, or still reworking some internals a bit?

[sam-goodwin]

@sam-goodwin any feedback on this? would love to use it, or still reworking some internals a bit?

Sorry for delay, trying my best to keep up.

[sam-goodwin]

Instead of ${id}-secret, you could instead pipe the Effect.gen (ProviderKey effect) to Namespace.push(id) and then name these Secret("Secret") and GatewayProvider("Provider")and they will be namespaced under${id}`

[sam-goodwin]

Applied in 55e4b0f — the ProviderKey effect is piped through Namespace.push(id) and the children are now Secret("Secret") and GatewayProvider("Provider") (dropped the secretResourceId escape hatch since the ${id}-secret default is gone). Also added a reconciliation test covering in-place value rotation and the alias-change replacement cascade. All 4 live tests pass.