Initial Commit
This commit is contained in:
71
packages/api-stack/api/api-secrets/README.md
Normal file
71
packages/api-stack/api/api-secrets/README.md
Normal file
@@ -0,0 +1,71 @@
|
||||
# @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
|
||||
|
||||
Reference in New Issue
Block a user