# @ssot/secrets ## 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. ## 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. ## 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). ## 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"); ``` ## API - `function detectedKinds(value: string, detectors: readonly Detector[]): readonly string[]` - `interface Detector` - `enum DetectorKind` - `enum ExclusionReason` - `function loadDetectors(): Promise` - `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. ## 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. ## Dependencies - `@govlab/constants` - `@ssot/paths` ## 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 -- ` 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. ## 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 ## 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. --- stable · 11 exports · 2 deps · 0 principles · 0 concepts