From f23f952dad6ddfdc6658c6c13f258018dddd9170 Mon Sep 17 00:00:00 2001 From: Dan Draper Date: Thu, 9 Jul 2026 16:20:53 +1000 Subject: [PATCH] chore: remove the secrets skill and the leftovers from the secrets removal `1929c8fe feat: remove secrets and mark as coming soon` deleted `packages/stack/src/secrets/` but left the export, the build entry, the agent skill, and the documentation behind. Secrets tooling is a while from ready; none of what's removed here was functional. - Drop the dead `@cipherstash/stack/secrets` subpath export. It resolved to `./dist/secrets/index.js`, which has no source and is absent from the tarball, so `import '@cipherstash/stack/secrets'` has thrown ERR_MODULE_NOT_FOUND in every published version since the source was removed (confirmed against 0.19.0). Removing an export that cannot resolve breaks no working code; the failure mode just becomes an honest ERR_PACKAGE_PATH_NOT_EXPORTED. Also drops the dangling `src/secrets/index.ts` entry from `tsup.config.ts`. - Remove `skills/stash-secrets/`. It was never installed into a user project -- it is absent from `SKILL_MAP` in `init/lib/install-skills.ts` -- so no handoff ever copied it. Also removes its entries from `AGENTS.md` and the init setup-prompt skill index. - Remove the secrets documentation from both published READMEs: the `Secrets` class API and the `npx stash secrets` command reference in `packages/stack/README.md`, and the `npx stash secrets` section in `packages/cli/README.md`. The CLI command does not exist -- `stash secrets` returns `Unknown command`. - Fix `skills/stash-encryption/SKILL.md`, which listed both `@cipherstash/stack/secrets` and a `Secrets` class re-exported from the main entry. Neither exists. This skill ships to user projects. `packages/protect` keeps its own secrets implementation and bin -- that code is real and is out of scope here. Verified: `@cipherstash/stack` ESM/CJS entries still build without the secrets entry; the pre-existing `EncryptionError`/`FailureOption` dts error reproduces on a clean `main` and is unrelated. `pnpm --filter stash test` passes (406). --- .changeset/remove-secrets-leftovers.md | 22 ++ AGENTS.md | 7 +- packages/cli/README.md | 39 +-- .../cli/src/commands/init/lib/setup-prompt.ts | 2 - packages/stack/README.md | 77 +---- packages/stack/package.json | 10 - packages/stack/tsup.config.ts | 1 - skills/stash-encryption/SKILL.md | 3 +- skills/stash-secrets/SKILL.md | 273 ------------------ 9 files changed, 29 insertions(+), 405 deletions(-) create mode 100644 .changeset/remove-secrets-leftovers.md delete mode 100644 skills/stash-secrets/SKILL.md diff --git a/.changeset/remove-secrets-leftovers.md b/.changeset/remove-secrets-leftovers.md new file mode 100644 index 000000000..84033d4e4 --- /dev/null +++ b/.changeset/remove-secrets-leftovers.md @@ -0,0 +1,22 @@ +--- +"@cipherstash/stack": patch +"stash": patch +--- + +Remove the leftovers from the secrets removal (`1929c8fe`), which deleted +`packages/stack/src/secrets/` but left its export, build entry, skill, and docs +behind. Secrets tooling is not ready; nothing here was functional. + +- **Drop the dead `@cipherstash/stack/secrets` subpath export.** It pointed at + `./dist/secrets/index.js`, which has no source and is not in the tarball, so + `import '@cipherstash/stack/secrets'` has been throwing `ERR_MODULE_NOT_FOUND` + for every consumer since the source was removed. Also drops the dangling + `src/secrets/index.ts` entry from `tsup.config.ts`. Removing an export that + cannot resolve breaks nothing. +- **Remove the `stash-secrets` agent skill** and its references in `AGENTS.md` + and the init setup-prompt skill index. It was never installed by `stash init` + (it is absent from `SKILL_MAP`), so no user project ever received it. +- **Remove the secrets documentation** from both published READMEs: the + `Secrets` class API and the `npx stash secrets` command reference in + `@cipherstash/stack`, and the `npx stash secrets` section in `stash`. The CLI + command does not exist — `stash secrets` returns `Unknown command`. diff --git a/AGENTS.md b/AGENTS.md index 5a664f562..84bba6555 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -72,13 +72,13 @@ If these variables are missing, tests that require live encryption will fail or ## Repository Layout - `packages/stack`: Main package (`@cipherstash/stack`) containing the encryption client and all integrations - - Subpath exports: `@cipherstash/stack`, `@cipherstash/stack/client`, `@cipherstash/stack/identity`, `@cipherstash/stack/secrets`, `@cipherstash/stack/schema`, `@cipherstash/stack/types`, `@cipherstash/stack/drizzle`, `@cipherstash/stack/dynamodb`, `@cipherstash/stack/supabase`, `@cipherstash/stack/encryption`, `@cipherstash/stack/errors`, `@cipherstash/stack/wasm-inline` + - Subpath exports: `@cipherstash/stack`, `@cipherstash/stack/client`, `@cipherstash/stack/identity`, `@cipherstash/stack/schema`, `@cipherstash/stack/types`, `@cipherstash/stack/drizzle`, `@cipherstash/stack/dynamodb`, `@cipherstash/stack/supabase`, `@cipherstash/stack/encryption`, `@cipherstash/stack/errors`, `@cipherstash/stack/wasm-inline` - `packages/protect`: Core encryption library (internal, re-exported via `@cipherstash/stack`) - `src/index.ts`: Public API (`Encryption`, exports) - `src/ffi/index.ts`: `EncryptionClient` implementation, bridges to `@cipherstash/protect-ffi` - `src/ffi/operations/*`: Encrypt/decrypt/model/bulk/query operations (thenable pattern with optional `.withLockContext()`) - `__tests__/*`: End-to-end and API contract tests (Vitest) -- `packages/cli`: The `stash` CLI — auth, init, encryption schema, database setup (`stash eql install`), and secrets. Has its own `AGENTS.md`. +- `packages/cli`: The `stash` CLI — auth, init, encryption schema, and database setup (`stash eql install`). Has its own `AGENTS.md`. - `packages/wizard`: AI-powered encryption setup (`@cipherstash/wizard`) - `packages/migrate`: Plaintext-to-encrypted column migration (`@cipherstash/migrate`) — resumable backfill, per-column state - `packages/prisma-next`: Prisma Next integration (`@cipherstash/prisma-next`) — searchable field-level encryption for Postgres @@ -91,7 +91,7 @@ If these variables are missing, tests that require live encryption will fail or - `e2e/*`: Cross-package end-to-end tests (package managers, supply chain, Prisma example README) - `examples/*`: Working apps (basic, prisma, supabase-worker) - `docs/plans/*`: Internal design plans. User-facing documentation lives at https://cipherstash.com/docs (not in this repo). -- `skills/*`: Agent skills (`stash-cli`, `stash-encryption`, `stash-drizzle`, `stash-dynamodb`, `stash-secrets`, `stash-supabase`, `stash-supply-chain-security`) +- `skills/*`: Agent skills (`stash-cli`, `stash-encryption`, `stash-drizzle`, `stash-dynamodb`, `stash-supabase`, `stash-supply-chain-security`) ## Supply Chain Security @@ -120,7 +120,6 @@ Three rules to remember when editing CI or pnpm config: - **Drizzle ORM**: `encryptedType`, `extractEncryptionSchema`, `createEncryptionOperators` from `@cipherstash/stack/drizzle` - **Supabase**: `encryptedSupabase` from `@cipherstash/stack/supabase` - **DynamoDB**: `encryptedDynamoDB` from `@cipherstash/stack/dynamodb` -- **Secrets management**: `Secrets` class from `@cipherstash/stack/secrets` for encrypted secret storage and retrieval. ## Critical Gotchas (read before coding) diff --git a/packages/cli/README.md b/packages/cli/README.md index 3f7230076..f0da70861 100644 --- a/packages/cli/README.md +++ b/packages/cli/README.md @@ -3,7 +3,7 @@ [![npm version](https://img.shields.io/npm/v/stash.svg?style=for-the-badge&labelColor=000000)](https://www.npmjs.com/package/stash) [![License: MIT](https://img.shields.io/npm/l/stash.svg?style=for-the-badge&labelColor=000000)](https://github.com/cipherstash/stack/blob/main/LICENSE.md) -The single CLI for CipherStash. It handles authentication, project initialization, EQL database lifecycle (install, upgrade, validate, push, migrate), schema building, and encrypted secrets management. Install it as a devDependency alongside the runtime SDK `@cipherstash/stack`. +The single CLI for CipherStash. It handles authentication, project initialization, EQL database lifecycle (install, upgrade, validate, push, migrate), and schema building. Install it as a devDependency alongside the runtime SDK `@cipherstash/stack`. --- @@ -169,43 +169,6 @@ Any flags after `wizard` are forwarded verbatim to the wizard package. On the fi --- -### `npx stash secrets` - -Manage end-to-end encrypted secrets. - -```bash -npx stash secrets [options] -``` - -| Subcommand | Description | -|------------|-------------| -| `set` | Store an encrypted secret | -| `get` | Retrieve and decrypt a secret | -| `get-many` | Retrieve and decrypt multiple secrets (2–100) | -| `list` | List all secrets in an environment | -| `delete` | Delete a secret | - -**Flags:** - -| Flag | Alias | Description | -|------|-------|-------------| -| `--name` | `-n` | Secret name (comma-separated for `get-many`) | -| `--value` | `-V` | Secret value (`set` only) | -| `--environment` | `-e` | Environment name | -| `--yes` | `-y` | Skip confirmation (`delete` only) | - -**Examples:** - -```bash -npx stash secrets set -n DATABASE_URL -V "postgres://..." -e production -npx stash secrets get -n DATABASE_URL -e production -npx stash secrets get-many -n DATABASE_URL,API_KEY -e production -npx stash secrets list -e production -npx stash secrets delete -n DATABASE_URL -e production -y -``` - ---- - ### `npx stash eql install` Configure your database and install CipherStash EQL extensions in a single command. Run this after `npx stash init`. (`npx stash db install` is a deprecated alias — it still works but prints a warning.) diff --git a/packages/cli/src/commands/init/lib/setup-prompt.ts b/packages/cli/src/commands/init/lib/setup-prompt.ts index 98b40c58d..73dec4d01 100644 --- a/packages/cli/src/commands/init/lib/setup-prompt.ts +++ b/packages/cli/src/commands/init/lib/setup-prompt.ts @@ -130,8 +130,6 @@ const SKILL_PURPOSES: Record = { 'DynamoDB encryption: per-item encrypt/decrypt, HMAC attribute keys, audit logging', 'stash-cli': '`stash` command reference — `status`, `plan`, `impl`, `eql install`, `encrypt {backfill,cutover,drop}`, etc.', - 'stash-secrets': - 'storing and retrieving encrypted secrets (separate concern from column encryption)', 'stash-supply-chain-security': 'supply-chain controls (post-install policy, lockfile integrity, etc.)', } diff --git a/packages/stack/README.md b/packages/stack/README.md index 37548764e..f3e289bb6 100644 --- a/packages/stack/README.md +++ b/packages/stack/README.md @@ -17,7 +17,6 @@ The all-in-one TypeScript SDK for the CipherStash data security stack. - [Encryption and Decryption](#encryption-and-decryption) - [Searchable Encryption](#searchable-encryption) - [Identity-Aware Encryption](#identity-aware-encryption) -- [Secrets Management](#secrets-management) - [CLI Reference](#cli-reference) - [Configuration](#configuration) - [Error Handling](#error-handling) @@ -94,8 +93,7 @@ if (decrypted.failure) { - **Searchable encryption** - Exact match, free-text search, order/range queries, and encrypted JSONB queries in PostgreSQL. - **Bulk operations** - Encrypt or decrypt thousands of values in a single ZeroKMS call (`bulkEncrypt`, `bulkDecrypt`, `bulkEncryptModels`, `bulkDecryptModels`). - **Identity-aware encryption** - Tie encryption to a user's JWT via `LockContext`, so only that user can decrypt. -- **Secrets management** - Store, retrieve, list, and delete encrypted secrets with the `Secrets` class. -- **CLI (`stash`)** - Initialize projects, manage secrets, and set up encryption from the terminal. +- **CLI (`stash`)** - Initialize projects and set up encryption from the terminal. - **TypeScript-first** - Strongly typed schemas, results, and model operations with full generics support. ## Schema Definition @@ -398,44 +396,6 @@ const decrypted = await client Lock contexts work with all operations: `encrypt`, `decrypt`, `encryptModel`, `decryptModel`, `bulkEncryptModels`, `bulkDecryptModels`, `bulkEncrypt`, `bulkDecrypt`. -## Secrets Management - -The `Secrets` class provides end-to-end encrypted secret storage. Values are encrypted locally before being sent to the CipherStash API. - -```typescript -import { Secrets } from "@cipherstash/stack/secrets" - -const secrets = new Secrets({ - workspaceCRN: process.env.CS_WORKSPACE_CRN!, - clientId: process.env.CS_CLIENT_ID!, - clientKey: process.env.CS_CLIENT_KEY!, - apiKey: process.env.CS_CLIENT_ACCESS_KEY!, - environment: "production", -}) - -// Store a secret -await secrets.set("DATABASE_URL", "postgres://user:pass@host:5432/db") - -// Retrieve and decrypt a single secret -const result = await secrets.get("DATABASE_URL") -if (!result.failure) { - console.log(result.data) // "postgres://user:pass@host:5432/db" -} - -// Retrieve multiple secrets in one call -const many = await secrets.getMany(["DATABASE_URL", "API_KEY"]) -if (!many.failure) { - console.log(many.data.DATABASE_URL) - console.log(many.data.API_KEY) -} - -// List secret names (values stay encrypted) -const list = await secrets.list() - -// Delete a secret -await secrets.delete("DATABASE_URL") -``` - ## CLI Reference The CLI is available via `npx stash` after install. @@ -472,24 +432,6 @@ After init, run `npx stash db setup` to configure your database. |------|-------------| | `--supabase` | Use Supabase-specific setup flow | -### `npx stash secrets` - -Manage encrypted secrets from the terminal. - -```bash -npx stash secrets set -name DATABASE_URL -value "postgres://..." -environment production -npx stash secrets get -name DATABASE_URL -environment production -npx stash secrets list -environment production -npx stash secrets delete -name DATABASE_URL -environment production -``` - -| Command | Flags | Aliases | Description | -|-----|----|-----|-------| -| `npx stash secrets set` | `-name`, `-value`, `-environment` | `-n`, `-V`, `-e` | Encrypt and store a secret | -| `npx stash secrets get` | `-name`, `-environment` | `-n`, `-e` | Retrieve and decrypt a secret | -| `npx stash secrets list` | `-environment` | `-e` | List all secret names in an environment | -| `npx stash secrets delete` | `-name`, `-environment`, `-yes` | `-n`, `-e`, `-y` | Delete a secret (prompts for confirmation unless `-yes`) | - ## Configuration ### Local Development @@ -552,7 +494,7 @@ const client2 = await Encryption({ ### Logging -The SDK uses structured logging across all interfaces (Encryption, Secrets, Supabase, DynamoDB). Each operation emits a single wide event with context such as the operation type, table, column, lock context status, and duration. +The SDK uses structured logging across all interfaces (Encryption, Supabase, DynamoDB). Each operation emits a single wide event with context such as the operation type, table, column, lock context status, and duration. Configure the log level with the `STASH_STACK_LOG` environment variable: @@ -631,19 +573,6 @@ const lc = new LockContext(options?) const result = await lc.identify(jwtToken) ``` -### `Secrets` - -```typescript -import { Secrets } from "@cipherstash/stack/secrets" - -const secrets = new Secrets(config) -await secrets.set(name, value) -await secrets.get(name) -await secrets.getMany(names) -await secrets.list() -await secrets.delete(name) -``` - ### Schema Builders ```typescript @@ -661,7 +590,6 @@ csValue(valueName) // returns ProtectValue (for nested values) | `@cipherstash/stack` | `Encryption` function (main entry point) | | `@cipherstash/stack/schema` | `encryptedTable`, `encryptedColumn`, `csValue`, schema types | | `@cipherstash/stack/identity` | `LockContext` class and identity types | -| `@cipherstash/stack/secrets` | `Secrets` class and secrets types | | `@cipherstash/stack/client` | Client-safe exports (schema builders and types only - no native FFI) | | `@cipherstash/stack/types` | All TypeScript types (`Encrypted`, `Decrypted`, `ClientConfig`, `EncryptionClientConfig`, query types, etc.) | @@ -675,7 +603,6 @@ If you are migrating from `@cipherstash/protect`, the following table maps the o | `csTable(name, cols)` | `encryptedTable(name, cols)` | `@cipherstash/stack/schema` | | `csColumn(name)` | `encryptedColumn(name)` | `@cipherstash/stack/schema` | | `import { LockContext } from "@cipherstash/protect/identify"` | `import { LockContext } from "@cipherstash/stack/identity"` | `@cipherstash/stack/identity` | -| N/A | `Secrets` class | `@cipherstash/stack/secrets` | | N/A | CLI | `npx stash` | All method signatures on the encryption client (`encrypt`, `decrypt`, `encryptModel`, etc.) remain the same. The `Result` pattern (`data` / `failure`) is unchanged. diff --git a/packages/stack/package.json b/packages/stack/package.json index d73f60b18..51ab9b44b 100644 --- a/packages/stack/package.json +++ b/packages/stack/package.json @@ -105,16 +105,6 @@ "default": "./dist/identity/index.cjs" } }, - "./secrets": { - "import": { - "types": "./dist/secrets/index.d.ts", - "default": "./dist/secrets/index.js" - }, - "require": { - "types": "./dist/secrets/index.d.cts", - "default": "./dist/secrets/index.cjs" - } - }, "./schema": { "import": { "types": "./dist/schema/index.d.ts", diff --git a/packages/stack/tsup.config.ts b/packages/stack/tsup.config.ts index 2380c8c49..100065f0c 100644 --- a/packages/stack/tsup.config.ts +++ b/packages/stack/tsup.config.ts @@ -13,7 +13,6 @@ export default defineConfig([ 'src/client.ts', 'src/types-public.ts', 'src/identity/index.ts', - 'src/secrets/index.ts', 'src/schema/index.ts', 'src/eql/v3/index.ts', 'src/drizzle/index.ts', diff --git a/skills/stash-encryption/SKILL.md b/skills/stash-encryption/SKILL.md index f5164bb05..f890f3eab 100644 --- a/skills/stash-encryption/SKILL.md +++ b/skills/stash-encryption/SKILL.md @@ -114,10 +114,9 @@ The SDK never logs plaintext data. | Import Path | Provides | |---|---| -| `@cipherstash/stack` | `Encryption` function, `Secrets` class, `encryptedTable`, `encryptedColumn`, `encryptedField` (convenience re-exports) | +| `@cipherstash/stack` | `Encryption` function, `encryptedTable`, `encryptedColumn`, `encryptedField` (convenience re-exports) | | `@cipherstash/stack/schema` | `encryptedTable`, `encryptedColumn`, `encryptedField`, schema types | | `@cipherstash/stack/identity` | `LockContext` class and identity types | -| `@cipherstash/stack/secrets` | `Secrets` class and secrets types | | `@cipherstash/stack/drizzle` | `encryptedType`, `extractEncryptionSchema`, `createEncryptionOperators` for Drizzle ORM | | `@cipherstash/stack/supabase` | `encryptedSupabase` wrapper for Supabase | | `@cipherstash/stack/dynamodb` | `encryptedDynamoDB` helper for DynamoDB | diff --git a/skills/stash-secrets/SKILL.md b/skills/stash-secrets/SKILL.md deleted file mode 100644 index c25b4cea3..000000000 --- a/skills/stash-secrets/SKILL.md +++ /dev/null @@ -1,273 +0,0 @@ ---- -name: stash-secrets -description: Manage encrypted secrets with @cipherstash/stack. Covers the Secrets API for storing, retrieving, listing, and deleting end-to-end encrypted secrets, the stash CLI for terminal-based secret management, environment-based isolation, and bulk secret retrieval. Use when implementing secret management, storing API keys or database URLs, or working with the CipherStash Secrets API or CLI. ---- - -# CipherStash Stack - Secrets Management - -Guide for managing end-to-end encrypted secrets with `@cipherstash/stack`. Values are encrypted locally before being sent to the CipherStash API - your plaintext never leaves your machine unencrypted. - -## When to Use This Skill - -- Storing sensitive credentials (database URLs, API keys, tokens) -- Retrieving secrets at runtime in application code -- Managing secrets across environments (production, staging, development) -- Using the `stash` CLI for terminal-based secret management -- Bulk-retrieving multiple secrets efficiently - -## Installation - -```bash -npm install @cipherstash/stack -``` - -## Configuration - -### Environment Variables - -```bash -CS_WORKSPACE_CRN=crn:ap-southeast-2.aws:your-workspace-id -CS_CLIENT_ID=your-client-id -CS_CLIENT_KEY=your-client-key -CS_CLIENT_ACCESS_KEY=your-access-key -``` - -Sign up at [cipherstash.com/signup](https://cipherstash.com/signup) to generate credentials. - -## SDK Usage - -### Initialize - -```typescript -import { Secrets } from "@cipherstash/stack/secrets" - -const secrets = new Secrets({ - workspaceCRN: process.env.CS_WORKSPACE_CRN!, - clientId: process.env.CS_CLIENT_ID!, - clientKey: process.env.CS_CLIENT_KEY!, - accessKey: process.env.CS_CLIENT_ACCESS_KEY!, - environment: "production", -}) -``` - -```typescript -// Minimal form (credentials from environment variables): -const secrets = new Secrets({ environment: "production" }) -``` - -The `environment` parameter isolates secrets - each environment gets its own encryption keyset. - -### Store a Secret - -Encrypts the value locally, then sends the ciphertext to the API: - -```typescript -const result = await secrets.set("DATABASE_URL", "postgres://user:pass@host:5432/db") - -if (result.failure) { - console.error("Failed:", result.failure.message) - // result.failure.type: "ApiError" | "NetworkError" | "ClientError" | "EncryptionError" | "DecryptionError" -} else { - console.log(result.data.message) // success message -} -``` - -### Retrieve a Single Secret - -Fetches the encrypted value from the API, decrypts locally: - -```typescript -const result = await secrets.get("DATABASE_URL") - -if (!result.failure) { - console.log(result.data) // "postgres://user:pass@host:5432/db" -} -``` - -### Retrieve Multiple Secrets (Efficient) - -Fetches all secrets in one API call and decrypts in a single ZeroKMS call: - -```typescript -const result = await secrets.getMany(["DATABASE_URL", "API_KEY", "JWT_SECRET"]) - -if (!result.failure) { - console.log(result.data.DATABASE_URL) - console.log(result.data.API_KEY) - console.log(result.data.JWT_SECRET) -} -``` - -**Constraints:** `getMany` requires a minimum of 2 secret names and a maximum of 100 names per request. - -**Use `getMany` over multiple `get` calls** - it's significantly more efficient because it batches the decryption into a single ZeroKMS operation. - -### List Secret Names - -Returns metadata only - values remain encrypted on the server: - -```typescript -const result = await secrets.list() - -if (!result.failure) { - for (const secret of result.data) { - console.log(secret.name) - // Also available: secret.createdAt, secret.updatedAt, secret.environment - } -} -``` - -### Delete a Secret - -```typescript -const result = await secrets.delete("OLD_API_KEY") - -if (result.failure) { - console.error("Failed:", result.failure.message) -} -``` - -## CLI Usage - -`stash init` adds `stash` to the project as a dev dependency, so `stash ` runs through whichever package manager the project uses (Bun / pnpm / Yarn / npm). Examples below show the bare `stash` form. Before init has run, prefix with your package manager's runner — `bunx`, `pnpm dlx`, `yarn dlx`, or `npx` — whichever matches your project. - -### Set a Secret - -```bash -stash secrets set --name DATABASE_URL --value "postgres://..." --environment production -stash secrets set -n DATABASE_URL -V "postgres://..." -e production -``` - -### Get a Secret - -```bash -stash secrets get --name DATABASE_URL --environment production -stash secrets get -n DATABASE_URL -e production -``` - -### Get Many Secrets - -```bash -stash secrets get-many --name DATABASE_URL,API_KEY --environment production -stash secrets get-many -n DATABASE_URL,API_KEY,JWT_SECRET -e production -``` - -### List Secrets - -```bash -stash secrets list --environment production -stash secrets list -e production -``` - -### Delete a Secret - -```bash -stash secrets delete --name DATABASE_URL --environment production -stash secrets delete -n DATABASE_URL -e production --yes # skip confirmation -``` - -### CLI Flag Reference - -| Flag | Alias | Description | -|---|---|---| -| `--name` | `-n` | Secret name (comma-separated for get-many) | -| `--value` | `-V` | Secret value (set only) | -| `--environment` | `-e` | Environment name | -| `--yes` | `-y` | Skip confirmation (delete only) | - -The CLI reads credentials from the same `CS_*` environment variables. Use a `.env` file for convenience. - -## Complete Type Reference - -### SecretsConfig - -```typescript -interface SecretsConfig { - environment: string // Environment name (required) - workspaceCRN?: string // Cloud Resource Name (defaults to CS_WORKSPACE_CRN env var) - clientId?: string // Client identifier (defaults to CS_CLIENT_ID env var) - clientKey?: string // Client key material (defaults to CS_CLIENT_KEY env var) - accessKey?: string // API access key (defaults to CS_CLIENT_ACCESS_KEY env var) -} -``` - -### SecretMetadata - -```typescript -interface SecretMetadata { - id: string - name: string - environment: string - createdAt: string - updatedAt: string -} -``` - -### Error Types - -```typescript -type SecretsErrorType = - | "ApiError" // HTTP/API failures - | "NetworkError" // Network connectivity issues - | "ClientError" // Client initialization failures - | "EncryptionError" // Encryption operation failed - | "DecryptionError" // Decryption operation failed -``` - -```typescript -interface SecretsError { - type: SecretsErrorType - message: string -} -``` - -All operations return `Result` with either `data` or `failure`. - -### Secrets Class Methods - -| Method | Signature | Returns | -|---|---|---| -| `set` | `(name: string, value: string)` | `Promise>` | -| `get` | `(name: string)` | `Promise>` | -| `getMany` | `(names: string[])` (min 2, max 100) | `Promise, SecretsError>>` | -| `list` | `()` | `Promise>` | -| `delete` | `(name: string)` | `Promise>` | - -## Patterns - -### Loading Secrets at Startup - -```typescript -import { Secrets } from "@cipherstash/stack/secrets" - -const secrets = new Secrets({ - workspaceCRN: process.env.CS_WORKSPACE_CRN!, - clientId: process.env.CS_CLIENT_ID!, - clientKey: process.env.CS_CLIENT_KEY!, - accessKey: process.env.CS_CLIENT_ACCESS_KEY!, - environment: process.env.NODE_ENV || "development", -}) - -// Load all needed secrets in one efficient call -const result = await secrets.getMany(["DATABASE_URL", "STRIPE_KEY", "SENDGRID_KEY"]) -if (result.failure) { - throw new Error(`Failed to load secrets: ${result.failure.message}`) -} - -const config = result.data -// Use config.DATABASE_URL, config.STRIPE_KEY, etc. -``` - -### Environment Isolation - -Each environment has its own encryption keyset, providing cryptographic isolation: - -```typescript -// Production secrets -const prodSecrets = new Secrets({ ...creds, environment: "production" }) - -// Staging secrets (completely isolated keys) -const stagingSecrets = new Secrets({ ...creds, environment: "staging" }) -``` - -A secret set in one environment cannot be decrypted with credentials from another environment.