skills/plugins/document-navigator/docs/api-stack/api/api-secrets/README.md

@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.

Documentation tree

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

Subpath modules

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

Installation

bun add @suaveplan/api-secrets

Quick example

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