72 lines
4.7 KiB
Markdown
72 lines
4.7 KiB
Markdown
# @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
|
|
|