# @suaveplan/api-secrets - Abstract Secrets contract for the Suaveplan API plugin system — per-plugin secret access typed against manifest secrets[], canonical redaction marker, conformance harness. Concrete adapters (env/Bun.secrets/vault) live in sibling packages.

Abstract Secrets contract for the Suaveplan API plugin system — per-plugin secret access typed against `manifest.secrets[]`, canonical redaction marker, frozen `SECRETS.*` error-code registry, capability-id pins, and the conformance harness every concrete source must pass. api-plugin-foundation umbrella; concrete sources land  (`api-secrets-env`, `api-secrets-vault`) and Stage 8 (`api-secrets-bun`).

The canonical `SecretsLike` type is owned by `@suaveplan/api-types/secrets`; this package re-exports it and supplies the runtime surface every consumer needs.

<!-- begin:auto-docs -->
## Documentation tree

- [capability-id](./src/capability-id/capability-id.md) — This module pins the two literal capability ids the api-secrets family contributes to the plugin-host `CapabilityId` un…
  - [capability-id](./src/capability-id/capability-id.md) — This module pins the two literal capability ids the api-secrets family contributes to the plugin-host `CapabilityId` un…
- [descriptor](./src/descriptor/descriptor.md) — `SecretDescriptor` is the manifest-side declaration of a secret a plugin needs. The host iterates the manifest's `secre…
  - [descriptor](./src/descriptor/descriptor.md) — `SecretDescriptor` is the manifest-side declaration of a secret a plugin needs. The host iterates the manifest's `secre…
- [error-codes](./src/error-codes/error-codes.md) — `SECRETS_CODES` is the frozen registry of fully-qualified error codes the API plugin system throws when a plugin tr…
  - [error-codes](./src/error-codes/error-codes.md) — `SECRETS_CODES` is the frozen registry of fully-qualified error codes the API plugin system throws when a plugin tr…
- [redaction](./src/redaction/redaction.md) — This module pins the single literal string every logger, audit sink, and OTel exporter in the API plugin system use…
  - [redaction](./src/redaction/redaction.md) — This module pins the single literal string every logger, audit sink, and OTel exporter in the API plugin system use…
- [secrets-like](./src/secrets-like/secrets-like.md) — This module is the runtime entry point for the abstract Secrets contract. The canonical `SecretsLike` interface — `get(…
  - [secrets-like](./src/secrets-like/secrets-like.md) — This module is the runtime entry point for the abstract Secrets contract. The canonical `SecretsLike` interface — `get(…
- [testing](./src/testing/conformance.md) — `runSecretsConformance` is the reusable Vitest suite every concrete `SecretsLike` implementation in the api-secrets fam…
  - [conformance](./src/testing/conformance.md) — `runSecretsConformance` is the reusable Vitest suite every concrete `SecretsLike` implementation in the api-secrets fam…
<!-- end:auto-docs -->

## Subpath modules

| Subpath | Purpose | Docs |
| --- | --- | --- |
| `./capability-id` | `SECRETS_CAPABILITY_ID` (`"secrets"`) + `SECRETS_BUN_CAPABILITY_ID` (`"secrets.bun"`) reservation. | [capability-id.md](./src/capability-id/capability-id.md) |
| `./descriptor` | `SecretDescriptor` interface + strict Zod schemas (`secretDescriptorSchema`, `secretDescriptorListSchema`). | [descriptor.md](./src/descriptor/descriptor.md) |
| `./error-codes` | `SECRETS_CODES` frozen registry + `SecretsError` concrete subclass. | [error-codes.md](./src/error-codes/error-codes.md) |
| `./redaction` | `REDACTED_MARKER` literal + `redactSecret` helper. | [redaction.md](./src/redaction/redaction.md) |
| `./secrets-like` | Re-export of `SecretsLike` + `checkRequiredSecrets` / `enforceRequiredSecrets` host helpers. | [secrets-like.md](./src/secrets-like/secrets-like.md) |
| `./testing` | `runSecretsConformance` reusable suite for every concrete source. | [conformance.md](./src/testing/conformance.md) |

## Installation

```sh
bun add @suaveplan/api-secrets
```

## Quick example

```ts
import {
    SECRETS_CAPABILITY_ID,
    enforceRequiredSecrets,
    secretDescriptorListSchema,
} from "@suaveplan/api-secrets";

const descriptors = secretDescriptorListSchema.parse(manifest.secrets);
await enforceRequiredSecrets(ctx.secrets, descriptors);

if (manifest.requiredCapabilities.includes(SECRETS_CAPABILITY_ID)) {
    // ctx.secrets is guaranteed populated at this point
}
```

## Dependencies

Runtime: `@suaveplan/api-types`, `@suaveplan/error`, `tslib`, `zod`.

## Verification

- `bunx turbo lint typecheck test --filter=@suaveplan/api-secrets` — green.
- `bunx turbo test:coverage --filter=@suaveplan/api-secrets` — 100/100/100/100.
- `bunx turbo build --filter=@suaveplan/api-secrets` — green.

## License

MIT