fix(oci): per-vault secret names, KMS ENABLED state, and Vault persistence

Address review findings on the OCI Vault branch.

Snapshot: providers/oci/vault had no snapshot.go, so vault.Mock was the only
providers/oci package that was not Snapshottable and TestSnapshotCompleteness
failed. Add it over all four stores, carrying the portable driver's default
vault and key so a restored mock does not mint a second one and orphan the
secrets it just restored.

KMS lifecycle: keys and key versions reported ACTIVE. Per the SDK's
KeyLifecycleStateEnum they are ENABLED and never ACTIVE — ACTIVE belongs to
vaults and secrets — and terraform-provider-oci's oci_kms_key waits on ENABLED,
so an ACTIVE key hangs the apply.

Secret names: uniqueness was enforced across every vault, so the same name in
two vaults was refused and CancelOCISecretDeletion could wrongly refuse a
restore. Scope it to the vault, as OCI does. The portable driver keys by bare
name, so it now resolves across vaults and rejects an ambiguous name naming
both, rather than silently picking one; its create refuses a name another vault
already holds. getByName prefers the live secret over a namesake pending
deletion.

Also document the Vault surface in docs/services.md, repair the garbled
VaultManagement doc comment, record why a secret's deletion actions answer 204
where a key's and a vault's answer 200, and raise coverage on both changed
packages (providers 96.9%, wire 79.7% -> 94.1%).

Author: arunesh-j

docs/coverage/README.md

@@ -133,7 +133,7 @@ code does not implement. Machine-readable: [`coverage.json`](./coverage.json).
 | `sagemaker` | [SageMaker](./aws/sagemaker.md) | — | — | — | 121 |
 | `savingsplans` | [SavingsPlans](./aws/savingsplans.md) | — | — | — | 9 |
 | `scheduler` | — | — | [Scheduler](./gcp/scheduler.md) | — | 8 |
-| `secrets` | [SecretsManager](./aws/secretsmanager.md) | [KeyVault](./azure/keyvault.md) | [SecretManager](./gcp/secretmanager.md) | — | 7 |
+| `secrets` | [SecretsManager](./aws/secretsmanager.md) | [KeyVault](./azure/keyvault.md) | [SecretManager](./gcp/secretmanager.md) | [Vault](./oci/vault.md) | 7 |
 | `serverless` | [Lambda](./aws/lambda.md) | [Functions](./azure/functions.md) | [CloudFunctions](./gcp/cloudfunctions.md) | — | 27 |
 | `servicedirectory` | — | — | [ServiceDirectory](./gcp/servicedirectory.md) | — | 15 |
 | `servicenetworking` | — | — | [Servicenetworking](./gcp/servicenetworking.md) | — | 3 |

docs/coverage/oci/README.md

@@ -8,4 +8,5 @@ Services cloudemu emulates for OCI, by native name. Back to the [cross-provider
 | [Identity](./identity.md) | `iam` | 40 |
 | [Monitoring](./monitoring.md) | `monitoring` | 12 |
 | [VCN](./vcn.md) | `networking` | 57 |
+| [Vault](./vault.md) | `secrets` | 7 |
 | [Workrequest](./workrequest.md) | — (provider-native) | 4 |

docs/services.md

@@ -1396,7 +1396,8 @@ a source cluster and detach on promote; clone-on-read on every path.
 ## 12. Secrets
 
 **Driver interface:** `services/secrets/driver/driver.go`
-**AWS:** Secrets Manager | **Azure:** Key Vault | **GCP:** Secret Manager
+**AWS:** Secrets Manager | **Azure:** Key Vault | **GCP:** Secret Manager |
+**OCI:** Vault
 
 ### Secret Operations
 
@@ -1417,6 +1418,134 @@ a source cluster and detach on promote; clone-on-read on every path.
 
 **Total: 7 operations**
 
+### OCI Vault
+
+**Optional capability:** `server/oci/vault.Extras` — OCI keeps secret storage
+and key management in one service, addresses everything by OCID, scopes it to a
+compartment and a vault, and only ever *schedules* a deletion. None of that fits
+the portable seven. Its value types live in `providers/oci/vault`.
+**Provider:** `providers/oci/vault` | **Wire:** `server/oci/vault`
+
+OCI publishes Vault under two API versions and CloudEmu claims both, because one
+HTTP server stands in for every OCI endpoint: `/20180608` carries KMS and secret
+management, `/20190301` the secret-retrieval data plane.
+
+#### Vaults (`/20180608`)
+
+| Operation | Route |
+|-----------|-------|
+| `CreateVault` | `POST /vaults` |
+| `ListVaults` | `GET /vaults` |
+| `GetVault` | `GET /vaults/{vaultId}` |
+| `UpdateVault` | `PUT /vaults/{vaultId}` |
+| `ScheduleVaultDeletion` | `POST /vaults/{vaultId}/actions/scheduleDeletion` |
+| `CancelVaultDeletion` | `POST /vaults/{vaultId}/actions/cancelDeletion` |
+| `ChangeVaultCompartment` | `POST /vaults/{vaultId}/actions/changeCompartment` |
+
+#### Master encryption keys (`/20180608`)
+
+| Operation | Route |
+|-----------|-------|
+| `CreateKey` | `POST /keys` |
+| `ListKeys` | `GET /keys` |
+| `GetKey` | `GET /keys/{keyId}` |
+| `UpdateKey` | `PUT /keys/{keyId}` |
+| `ScheduleKeyDeletion` | `POST /keys/{keyId}/actions/scheduleDeletion` |
+| `CancelKeyDeletion` | `POST /keys/{keyId}/actions/cancelDeletion` |
+| `ChangeKeyCompartment` | `POST /keys/{keyId}/actions/changeCompartment` |
+| `CreateKeyVersion` | `POST /keys/{keyId}/keyVersions` |
+| `ListKeyVersions` | `GET /keys/{keyId}/keyVersions` |
+| `GetKeyVersion` | `GET /keys/{keyId}/keyVersions/{keyVersionId}` |
+
+The KMS management endpoint is per-vault in real OCI, where the vault is
+addressed by host. CloudEmu serves every vault from one host, so `/keys` takes
+`vaultId` as a query parameter instead.
+
+#### Secrets (`/20180608`)
+
+| Operation | Route |
+|-----------|-------|
+| `CreateSecret` | `POST /secrets` |
+| `ListSecrets` | `GET /secrets` |
+| `GetSecret` | `GET /secrets/{secretId}` |
+| `UpdateSecret` | `PUT /secrets/{secretId}` |
+| `GetSecretByName` | `GET /secrets/actions/getByName` |
+| `ScheduleSecretDeletion` | `POST /secrets/{secretId}/actions/scheduleDeletion` |
+| `CancelSecretDeletion` | `POST /secrets/{secretId}/actions/cancelDeletion` |
+| `ChangeSecretCompartment` | `POST /secrets/{secretId}/actions/changeCompartment` |
+| `ListSecretVersions` | `GET /secrets/{secretId}/versions` |
+| `GetSecretVersion` | `GET /secrets/{secretId}/versions/{versionNumber}` |
+| `ScheduleSecretVersionDeletion` | `POST /secrets/{secretId}/versions/{n}/actions/scheduleDeletion` |
+| `CancelSecretVersionDeletion` | `POST /secrets/{secretId}/versions/{n}/actions/cancelDeletion` |
+
+#### Secret bundles — the retrieval data plane (`/20190301`)
+
+| Operation | Route |
+|-----------|-------|
+| `GetSecretBundle` | `GET /secretbundles/{secretId}` |
+| `ListSecretBundleVersions` | `GET /secretbundles/{secretId}/versions` |
+| `GetSecretBundleByName` | `GET /secretbundles/actions/getByName` |
+
+A bundle read is the only way to get a secret's *value* back; the management
+routes above return metadata only. The version is named by exactly one of
+`versionNumber`, `secretVersionName` or `stage` — more than one is rejected
+rather than silently ranked.
+
+**Total: 32 operations**
+
+#### Behavior
+
+There is no secret outside a vault, and no secret without a master encryption
+key, so the portable `CreateSecret` mints a default vault and AES key on first
+use and puts every portable secret there. Portable *reads*, though, reach every
+vault, so a secret created through the OCI-shaped surface is addressable
+portably too.
+
+OCI scopes secret names to the vault, so the same name in two vaults is two
+different secrets and that reach makes a bare name ambiguous. Rather than
+silently picking one, every portable operation that keys by name fails with
+`InvalidArgument` naming both vaults, and `CreateSecret` refuses to mint a name
+another vault already holds. `ListSecrets` is unaffected — it addresses nothing
+by name. With one vault in play, which is all the AWS, Azure and GCP secret
+mocks can have, none of this is observable.
+
+The KMS surface and the secret surface report different live states, as real
+OCI does: a key or key version is `ENABLED` and never `ACTIVE`, while a vault or
+secret is `ACTIVE` and never `ENABLED`. This matters to consumers —
+`terraform-provider-oci`'s `oci_kms_key` waits for `ENABLED` after a create or
+rotate. `enableKey` / `disableKey` and the `ENABLING` / `DISABLING` / `DISABLED`
+states are not served, so a key's lifecycle here is `ENABLED ⇄ PENDING_DELETION`.
+
+Deletion is scheduled, never immediate. A vault, key, secret or secret version
+moves to `PENDING_DELETION` and stays there — nothing reaps it — until the
+deletion is cancelled. A secret pending deletion releases its name, so the same
+name can be taken again in that vault; cancelling then fails rather than
+producing two live secrets alike. The portable `DeleteSecret` schedules at the
+soonest OCI permits, one day out, and the portable operations treat the secret
+as gone from that moment, which is the same soft-delete the AWS Secrets Manager
+mock exposes.
+
+Secret versions are numbered, and each carries a stage: `CURRENT`, `PENDING`,
+`PREVIOUS`, `LATEST` or `DEPRECATED`. Adding a version stages it, and promoting
+one to `CURRENT` — via `UpdateSecret`'s `currentVersionNumber` — is how OCI
+finishes a rotation staged as `PENDING`. The portable version identifier is
+OCI's version number, so a non-numeric one is rejected.
+
+Every list route requires `compartmentId` except the key-version, secret-version
+and bundle routes, whose parent already names one. All paginate with `limit` /
+`page`, returning the cursor as `opc-next-page`. The mutations real OCI runs
+asynchronously record a work request and stamp `opc-work-request-id`;
+`changeCompartment` answers `202` with nothing else, so a waiter must poll.
+
+`definedTags` is rejected rather than accepted and dropped, since CloudEmu
+models no tag namespaces — use `freeformTags`. `autoKeyRotationDetails`,
+`externalKeyReference` and `desiredState` are rejected the same way.
+
+The KMS crypto endpoint — `encrypt`, `decrypt`, `sign`, `verify`, `exportKey`
+and `generateDataEncryptionKey` — is claimed only to answer `501` naming the
+gap rather than leaving a caller with a bare `404`. CloudEmu records master
+encryption keys but stores no key material, so there is no ciphertext to invent.
+
 ---
 
 ## 13. Logging

providers/oci/vault/key.go

@@ -139,7 +139,7 @@ func (m *Mock) newKeyLocked(spec *KeySpec, mode string) *keyData {
 		DisplayName:    spec.DisplayName,
 		Shape:          spec.Shape,
 		ProtectionMode: mode,
-		LifecycleState: StateActive,
+		LifecycleState: StateEnabled,
 		TimeCreated:    m.now(),
 		Scope:          scope.Scope{Compartment: m.compartmentOr(spec.CompartmentID)},
 		FreeformTags:   copyTags(spec.FreeformTags),
@@ -266,7 +266,7 @@ func (m *Mock) CancelKeyDeletion(id string) (*KeyInfo, error) {
 		return nil, cerrors.Newf(cerrors.FailedPrecondition, "key %s is not scheduled for deletion", id)
 	}
 
-	k.LifecycleState = StateActive
+	k.LifecycleState = StateEnabled
 	k.TimeOfDeletion = ""
 
 	info := toKeyInfo(k)
@@ -318,7 +318,7 @@ func (m *Mock) CreateKeyVersion(keyID string) (*KeyVersionInfo, error) {
 		return nil, err
 	}
 
-	if k.LifecycleState != StateActive {
+	if k.LifecycleState != StateEnabled {
 		return nil, cerrors.Newf(cerrors.FailedPrecondition, "key %s is %s", keyID, k.LifecycleState)
 	}
 
@@ -442,7 +442,7 @@ func toKeyVersionInfo(kv *keyVersionData) KeyVersionInfo {
 		KeyID:          kv.KeyID,
 		VaultID:        kv.VaultID,
 		CompartmentID:  kv.Scope.Compartment,
-		LifecycleState: StateActive,
+		LifecycleState: StateEnabled,
 		TimeCreated:    kv.TimeCreated,
 	}
 }

providers/oci/vault/key_test.go

@@ -85,7 +85,7 @@ func TestCreateKey(t *testing.T) {
 
 			require.NoError(t, err)
 			assert.Equal(t, tc.expectMode, info.ProtectionMode)
-			assert.Equal(t, StateActive, info.LifecycleState)
+			assert.Equal(t, StateEnabled, info.LifecycleState)
 			assert.True(t, strings.HasPrefix(info.ID, "ocid1.key.oc1.iad."), "got %q", info.ID)
 			assert.True(t, strings.HasPrefix(info.CurrentKeyVersion, "ocid1.keyversion.oc1.iad."),
 				"got %q", info.CurrentKeyVersion)
@@ -155,7 +155,7 @@ func TestKeyScheduledDeletionAndCancellation(t *testing.T) {
 
 	restored, err := m.CancelKeyDeletion(keyID)
 	require.NoError(t, err)
-	assert.Equal(t, StateActive, restored.LifecycleState)
+	assert.Equal(t, StateEnabled, restored.LifecycleState)
 
 	_, err = m.CancelKeyDeletion(keyID)
 	assert.Equal(t, cerrors.FailedPrecondition, cerrors.GetCode(err))
@@ -217,3 +217,41 @@ func TestUpdateAndMoveKey(t *testing.T) {
 	_, err = m.GetKey("ocid1.key.oc1.iad.x")
 	assert.Equal(t, cerrors.NotFound, cerrors.GetCode(err))
 }
+
+// The KMS surface and the secret surface report different live states. Per the
+// SDK's KeyLifecycleStateEnum a key and a key version are ENABLED and never
+// ACTIVE, while a vault and a secret are ACTIVE and never ENABLED —
+// terraform-provider-oci's oci_kms_key waits on ENABLED, so a key reporting
+// ACTIVE hangs the apply.
+func TestKeyStatesAreEnabledAndResourceStatesAreActive(t *testing.T) {
+	m := newTestMock()
+
+	v, err := m.CreateVault(&VaultSpec{CompartmentID: testCompartment, DisplayName: "v"})
+	require.NoError(t, err)
+	assert.Equal(t, StateActive, v.LifecycleState, "a vault is ACTIVE")
+
+	k, err := m.CreateKey(&KeySpec{
+		CompartmentID: testCompartment, VaultID: v.ID, DisplayName: "k",
+		Shape: KeyShape{Algorithm: AlgorithmAES, Length: 32},
+	})
+	require.NoError(t, err)
+	assert.Equal(t, StateEnabled, k.LifecycleState, "a key is ENABLED, never ACTIVE")
+
+	kv, err := m.GetKeyVersion(k.ID, k.CurrentKeyVersion)
+	require.NoError(t, err)
+	assert.Equal(t, StateEnabled, kv.LifecycleState, "a key version is ENABLED, never ACTIVE")
+
+	rotated, err := m.CreateKeyVersion(k.ID)
+	require.NoError(t, err)
+	assert.Equal(t, StateEnabled, rotated.LifecycleState, "a rotated key version is ENABLED")
+
+	s, err := m.CreateOCISecret(&SecretSpec{
+		CompartmentID: testCompartment, VaultID: v.ID, KeyID: k.ID,
+		Name: "s", Content: []byte("v"),
+	})
+	require.NoError(t, err)
+	assert.Equal(t, StateActive, s.LifecycleState, "a secret is ACTIVE")
+
+	// The two vocabularies stay distinct.
+	assert.NotEqual(t, StateActive, StateEnabled)
+}