README.md
README.md is a file in Secrets. 76 lines of code and 0 definitions.
<!-- Auto-generated 2026-10-04T23:07Z v2 -->
# @ssot/secrets
<!-- concern:overview -->
## Purpose
`@ssot/secrets` is the one place the workspace reads a value it keeps out of its source: dev ports, the deploy host, webhook addresses, credentials and test fixture values. The values live in the Cerberus vault under the folder `banes-lab.com`, in one entry per scope (`Runtime` and `Tests`), each field labeled by its key. `configuration/schemas/environment.schema.ts` declares every key with its kind, its scope and whether it is required. An accessor lists the entry's field labels, reveals the one it needs through the `cerberus` command line, and checks the value against the kind's rule before returning it. A missing required key, a malformed value and a locked vault each stop the caller with a message that names the key and never the value.
<!-- /concern:overview -->
<!-- concern:use -->
## When to use
- Code needs a port, a host, an address, a login user, a remote path or a credential. Declare its key in the schema and read it with `portOf`, `textOf` or `optionalTextOf`.
- A test needs a value that must not appear in published source. Declare it with the `test` scope, so it lives in the `Tests` entry.
## When NOT to use
- A value that is part of the published product, such as a public site address or a route. Those stay in the members' own constants and assets.
- A runtime with no `cerberus` binary on its path, such as a browser bundle. The accessors run the vault's command line and are Node-only.
- A process that must start while the vault is locked. Every read fails until the vault is unlocked.
<!-- /concern:use -->
<!-- concern:charts -->
## Architecture charts
The structure, logical-flow and dependency diagrams derived from the source AST live in [_code.info.generated/mermaid-charts.generated.md](./_code.info.generated/mermaid-charts.generated.md).
<!-- /concern:charts -->
<!-- concern:install -->
## Install
`@ssot/secrets` is a private workspace package, resolved through the root `package.json` `workspaces` entry `project.secrets`. A consumer declares it as a dependency and imports from the bare specifier `@ssot/secrets`. It runs the `cerberus` binary that banes-lab.config's toolchains install, and reads only while the vault is open.
## Quick start
```js EXAMPLE: Read a required port, a required text value and an optional secret from the vault
import { optionalTextOf, portOf, textOf } from "@ssot/secrets";
const port = portOf("SITE_DEV_PORT");
const host = textOf("DEPLOY_HOST");
const passphrase = optionalTextOf("SSH_PASSPHRASE");
```
<!-- /concern:install -->
<!-- concern:api -->
## API
- `function detectedKinds(value: string, detectors: readonly Detector[]): readonly string[]`
- `interface Detector`
- `enum DetectorKind`
- `enum ExclusionReason`
- `function loadDetectors(): Promise<readonly Detector[]>`
- `enum OptionalKey`
- `function optionalTextOf(key: OptionalKey): string | null` — takes a key declared not required and returns its value, or null when the entry holds no field of that label.
- `enum PortKey`
- `function portOf(key: PortKey): number` — takes a required port key and returns its value as a number from 0 to 65535.
- `enum TextKey`
- `function textOf(key: TextKey): string` — takes a required key of any other kind and returns its value.
<!-- /concern:api -->
<!-- concern:config -->
## Configuration
- `configuration/schemas/environment.schema.ts` — every key with its kind (port, host, url, secret, user or path), its scope (runtime or test) and whether it is required.
- `configuration/constants/environment.constants.ts` — the vault folder, the entry of each scope and the rule each kind's value must meet.
<!-- /concern:config -->
<!-- concern:deps -->
## Dependencies
- `@govlab/constants`
- `@ssot/paths`
<!-- /concern:deps -->
<!-- concern:ai-context -->
## AI context
- The model never reads a value. A value moves into the vault only through a script that pipes it to `cerberus field add … --secret` on standard input and compares the readback inside the script.
- A key exists once, in `configuration/schemas/environment.schema.ts`. Its label in the vault is the key itself, and its variable name is the same key, so `cerberus run banes-lab.com/Runtime -- <command>` sets the same names.
- An accessor's key type is derived from the schema, so a misspelled key or a port read as text fails to compile.
- No accessor has a default. A missing required key throws, and an optional key returns null.
<!-- /concern:ai-context -->
<!-- concern:domains -->
## Domains
This package serves these software domains, which `_manifest.json` declares in `domains` from the two-tier software-domain vocabulary (`meta → sub`):
- **security** — secrets-management
<!-- /concern:domains -->
<!-- concern:disposal -->
## Disposal
- Move every consumer's reads to another store and remove its `@ssot/secrets` dependency.
- Remove the `project.secrets` entry from the root `package.json` `workspaces`, its member registration and its taxonomy root.
- Delete the `project.secrets` directory and its test mirror, reinstall to refresh the workspace links, then run the codebase verification gate.
<!-- /concern:disposal -->
<!-- concern:metrics -->
---
stable · 11 exports · 2 deps · 0 principles · 0 concepts
<!-- /concern:metrics -->