Define API key Terraform state design

[IlyaasK]

Summary

Defines the Terraform state and lifecycle boundary for future Kernel API-key support.

• Documents plaintext-once, masked-read, sensitive-state, rotation, deletion, project-scope, and metadata-only import semantics.
• Defines deterministic null, empty, lifetime, name-normalization, exact-lookup, and retained-rotation-history behavior.
• Links the accepted state design from the v1 architecture.
• Separates the safe masked kernel_api_key data source from the blocked kernel_api_key resource.

Why this is v1 work

API keys are durable configuration, but their one-time plaintext and ability to authenticate the provider make them higher risk than ordinary metadata resources. v1 requires an accepted state and recovery model before lifecycle code is added.

Resource and data-source scope

This PR is documentation only. It does not register a resource or data source and makes no API, SDK, provider, or state changes.

The masked metadata data source may proceed after a tagged SDK exposes the API's exact-name list filter. The resource remains deferred.

API contract

The latest tagged Go SDK, v0.76.0, exposes API-key Create, Get, Update, List, Delete, and Rotate. Reads are masked; Create and Rotate return plaintext once. Rotate creates a new canonical ID, clamps old-key grace to its existing expiration, and retains the expired old row as non-deleted history. Names are non-unique, and the API's exact filter uses case- and accent-insensitive database collation.

The pending v0.77.0 SDK release generates the exact-name list field. This provider will continue to use the SDK only.

Terraform state semantics

The future resource model distinguishes readable durable metadata from provider-preserved intent:

• key is sensitive computed plaintext preserved after Create or Rotate and null after import.
• masked_key, creator, project metadata, and timestamps come from durable reads.
• rotation_keeper is the only rotation trigger.
• rename occurs before rotation so the new key copies the desired name.
• project scope resolves through resource override, provider default, authenticated-key binding, then organization-wide scope.
• exact-name data-source lookup post-filters byte-for-byte and diagnoses ambiguity.

Sensitive field handling

Terraform sensitivity controls display, not backend encryption. The design requires an encrypted, access-controlled state backend because plaintext remains in state history. Masked reads never replace plaintext state, and import never claims to recover plaintext.

Import behavior

Future resource import accepts the canonical API-key ID and reads masked metadata only. Plaintext, the original relative lifetime, and prior rotation keeper remain unset. A keeper configured after import is an explicit first rotation.

Verification

Passed locally:

• gofmt -l cmd internal
• go test -short -timeout=2m ./...
• go vet ./...
• go mod verify
• go mod tidy -diff
• terraform fmt -check -recursive examples
• bash scripts/check-docs.sh
• bash scripts/check-markdown-links.sh
• git diff --check

Acceptance status

No acceptance test applies to this documentation-only PR. The design records the required future matrix for Create, Read, rename, rotation, import, scope, historical rows, lifetime edges, deletion, and self-use safety.

Deferred concerns

The resource must not ship until all three gates are met:

• replayable Create and Rotate idempotency, including plaintext response replay and a token that survives failed applies;
• a stable current-key self-rotation guard;
• authoritative effective project-scope metadata for the authenticating key.

The masked data source waits only for the tagged exact-name SDK surface.

GitHub issues

This PR does not resolve an existing GitHub issue.

---

Note

Low Risk
Documentation-only changes with no runtime, state, or authentication behavior.

Overview
This PR is documentation only—no provider, SDK, or API code.

It adds docs/api-key-state.md, which accepts the future kernel_api_key Terraform state model (sensitive plaintext preservation, rotation_keeper-driven rotation, project-scope resolution, metadata-only import) and spells out lifecycle, validation, and safety rules aligned with the current Kernel API/SDK (v0.76.0, pending v0.77.0 exact-name list).

It defers the resource until replayable Create/Rotate idempotency and a current-key self-rotation guard with effective project-scope metadata exist, while allowing the masked kernel_api_key data source after a tagged SDK exposes the exact-name filter.

docs/architecture.md now points v1 readers at that design doc and restates the same unblock vs. proceed split for API-key work.

^{Reviewed by Cursor Bugbot for commit 7c330ea. Bugbot is set up for automated code reviews on this repo. Configure here.}

[cursor]

Cursor Bugbot has reviewed your changes using high effort and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

Want fixes drafted automatically? Bugbot Autofix can create code changes for findings. A team admin can enable Autofix in the Cursor dashboard.

^{Reviewed by Cursor Bugbot for commit 12ca1a6. Configure here.}