@happyvertical/secrets 0.74.8

package/AGENT.md

@@ -0,0 +1,33 @@
+# @happyvertical/secrets
+
+<!-- BEGIN AGENT:GENERATED -->
+## Purpose
+Envelope encryption for per-tenant secret management with pluggable backends
+
+## Package Map
+- Package: `@happyvertical/secrets`
+- Hierarchy path: `@happyvertical/sdk > packages > secrets`
+- Workspace position: `24 of 30` local packages
+- Internal dependencies: `@happyvertical/sql`, `@happyvertical/utils`
+- Internal dependents: none
+- Knowledge graph files: `AGENT.md`, `metadata.json`, `ecosystem-manifest.json`
+
+## Build & Test
+```bash
+pnpm --filter @happyvertical/secrets build
+pnpm --filter @happyvertical/secrets test
+pnpm --filter @happyvertical/secrets typecheck
+```
+
+## Agent Correction Loops
+- If module resolution or export errors mention a workspace dependency, build the dependency first (`pnpm --filter @happyvertical/sql build`, `pnpm --filter @happyvertical/utils build`) and then rerun `pnpm --filter @happyvertical/secrets build`.
+- If you hit type-only regressions, run `pnpm --filter @happyvertical/secrets typecheck` before rerunning the package build or tests to isolate the failing surface.
+- If failures span multiple packages or Turborepo ordering looks wrong, run `pnpm build` and `pnpm typecheck` from the repo root before retrying package-scoped commands.
+
+## Ecosystem Relationships
+- Provides: Envelope encryption for per-tenant secret management with pluggable backends
+- Implements: none
+- Requires: @happyvertical/sql, @happyvertical/utils
+- Stability: stable (Primary package surface is described as implemented and production-oriented.)
+<!-- END AGENT:GENERATED -->
+

package/LICENSE

@@ -0,0 +1,7 @@
+Copyright <2025> <Happy Vertical Corporation>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,220 @@
+# @happyvertical/secrets
+
+Envelope encryption SDK for per-tenant secret management with pluggable backends.
+
+## Installation
+
+```bash
+npm install @happyvertical/secrets
+# or
+pnpm add @happyvertical/secrets
+```
+
+## Claude Code Context
+
+Install Claude Code context files for AI-assisted development:
+
+```bash
+npx have-secrets-context
+```
+
+This copies the package's `AGENT.md` documentation and `metadata.json` metadata to your project's `.claude/` directory, enabling Claude to provide better assistance when working with this package.
+
+## Overview
+
+This package provides envelope encryption primitives for secure, per-tenant secret management. It uses a two-tier key hierarchy:
+
+```
+Application Master Key (AMK) - from environment variable
+    └── wraps → Tenant Data Encryption Keys (TDEKs) - per tenant, stored in DB
+                    └── encrypts → Secret values (AES-256-GCM)
+```
+
+## Quick Start
+
+```typescript
+import { getSecretStore } from '@happyvertical/secrets';
+import { getDatabase } from '@happyvertical/sql';
+
+// Set up database and AMK
+const db = await getDatabase({ type: 'sqlite', url: ':memory:' });
+process.env.MY_SECRET_KEY = crypto.randomBytes(32).toString('hex');
+
+// Create secret store
+const store = await getSecretStore({
+  type: 'database',
+  db,
+  amk: {
+    provider: 'env',
+    keyEnvVar: 'MY_SECRET_KEY',
+    keyId: 'amk-v1',
+  },
+});
+
+// Create tenant key
+await store.createTenantKey('tenant-123');
+
+// Encrypt a secret
+const envelope = await store.encrypt('tenant-123', 'api-key', 'sk_live_xxx');
+
+// Decrypt the secret
+const { value } = await store.decrypt('tenant-123', envelope);
+console.log(value); // 'sk_live_xxx'
+```
+
+## Core Concepts
+
+### Envelope Encryption
+
+Envelope encryption separates data encryption from key management:
+
+1. **Application Master Key (AMK)**: A 32-byte key stored securely (env var, KMS, etc.)
+2. **Tenant Data Encryption Keys (TDEKs)**: Per-tenant keys wrapped by the AMK
+3. **Secret Values**: Encrypted with tenant's TDEK using AES-256-GCM
+
+This architecture enables:
+- Per-tenant key isolation
+- Key rotation without re-encrypting all secrets
+- Secure key storage (only wrapped keys in database)
+
+### SecretStore Interface
+
+```typescript
+interface SecretStore {
+  // Encrypt a secret for a tenant
+  encrypt(tenantId: string, secretName: string, plaintext: string): Promise<EncryptedEnvelope>;
+
+  // Decrypt a secret
+  decrypt(tenantId: string, envelope: EncryptedEnvelope): Promise<DecryptedSecret>;
+
+  // Tenant key management
+  getTenantKey(tenantId: string): Promise<TenantDataEncryptionKey | null>;
+  createTenantKey(tenantId: string): Promise<TenantDataEncryptionKey>;
+  rotateTenantKey(tenantId: string): Promise<TenantDataEncryptionKey>;
+
+  // Event subscription
+  subscribe(listener: SecretStoreEventListener): Unsubscribe;
+}
+```
+
+## API Reference
+
+### getSecretStore(options)
+
+Factory function to create a secret store instance.
+
+```typescript
+const store = await getSecretStore({
+  type: 'database',
+  db: databaseInstance,
+  keysTable: 'tenant_encryption_keys', // optional, default
+  amk: {
+    provider: 'env',
+    keyEnvVar: 'SMRT_SECRET_MASTER_KEY',
+    keyId: 'production-amk-v1',
+  },
+});
+```
+
+### EnvelopeEncryption
+
+Low-level encryption primitives:
+
+```typescript
+import { EnvelopeEncryption } from '@happyvertical/secrets';
+
+// Generate a data key
+const dataKey = EnvelopeEncryption.generateDataKey();
+
+// Wrap the key with AMK
+const wrapped = EnvelopeEncryption.wrapKey(dataKey, amk);
+
+// Encrypt data
+const encrypted = EnvelopeEncryption.encryptData('secret', dataKey);
+
+// Decrypt data
+const plaintext = EnvelopeEncryption.decryptData(
+  encrypted.ciphertext,
+  encrypted.iv,
+  encrypted.authTag,
+  dataKey,
+);
+```
+
+## Key Rotation
+
+Rotate tenant keys without service interruption:
+
+```typescript
+// Old keys are retained for decryption
+const newKey = await store.rotateTenantKey('tenant-123');
+
+// Old envelopes still decrypt (using retained key version)
+const decrypted = await store.decrypt('tenant-123', oldEnvelope);
+
+// New envelopes use the new key
+const newEnvelope = await store.encrypt('tenant-123', 'new-secret', 'value');
+```
+
+## Events
+
+Subscribe to encryption/decryption events:
+
+```typescript
+const unsubscribe = store.subscribe((event) => {
+  console.log(`${event.type} for tenant ${event.tenantId}`);
+});
+
+// Later: unsubscribe
+unsubscribe();
+```
+
+Event types:
+- `secret.encrypted` - Secret was encrypted
+- `secret.decrypted` - Secret was decrypted
+- `key.created` - Tenant key was created
+- `key.rotated` - Tenant key was rotated
+
+## Security Considerations
+
+1. **AMK Protection**: Store the Application Master Key securely
+   - Use environment variables for simple deployments
+   - Use AWS KMS, HashiCorp Vault, or Azure Key Vault for production
+
+2. **Key Isolation**: Each tenant has a unique TDEK
+   - Compromise of one tenant's data doesn't expose others
+   - Keys can be rotated independently
+
+3. **AES-256-GCM**: Authenticated encryption
+   - Provides confidentiality and integrity
+   - 12-byte IV, 16-byte auth tag
+
+4. **Memory Safety**: Key buffers are zeroed after use
+   - Reduces exposure window for sensitive key material
+
+## Error Handling
+
+```typescript
+import {
+  AMKUnavailableError,
+  TenantKeyMissingError,
+  EncryptionError,
+  DecryptionError,
+} from '@happyvertical/secrets';
+
+try {
+  await store.encrypt('tenant-123', 'secret', 'value');
+} catch (error) {
+  if (error instanceof AMKUnavailableError) {
+    // AMK not configured or inaccessible
+  } else if (error instanceof TenantKeyMissingError) {
+    // Tenant doesn't have a key - create one first
+  } else if (error instanceof EncryptionError) {
+    // Encryption failed
+  }
+}
+```
+
+## License
+
+MIT

package/dist/adapters/database.d.ts

@@ -0,0 +1,74 @@
+import { ApplicationMasterKey, DatabaseSecretStoreOptions, DecryptedSecret, EncryptedEnvelope, EncryptOptions, SecretStore, SecretStoreEventListener, TenantDataEncryptionKey, Unsubscribe } from '../shared/types.js';
+/**
+ * Database-backed secret store
+ *
+ * Uses envelope encryption with AES-256-GCM:
+ * - Application Master Key (AMK) from environment variable
+ * - Per-tenant Data Encryption Keys (TDEKs) wrapped by AMK
+ * - Secrets encrypted by unwrapped TDEKs
+ *
+ * @example
+ * ```typescript
+ * const store = new DatabaseSecretStore({
+ *   type: 'database',
+ *   db,
+ *   amk: {
+ *     provider: 'env',
+ *     keyEnvVar: 'SECRET_MASTER_KEY',
+ *     keyId: 'amk-v1'
+ *   }
+ * });
+ *
+ * await store.initialize();
+ *
+ * // Encrypt a secret for a tenant
+ * const envelope = await store.encrypt('tenant-123', 'api-key', 'sk_live_xxx');
+ *
+ * // Decrypt
+ * const { value } = await store.decrypt('tenant-123', envelope);
+ * ```
+ */
+export declare class DatabaseSecretStore implements SecretStore {
+    private db;
+    private keysTable;
+    private amkConfig;
+    private cachedAmk;
+    private initialized;
+    private listeners;
+    constructor(options: DatabaseSecretStoreOptions);
+    /**
+     * Initialize the store (create schema if needed)
+     */
+    initialize(): Promise<void>;
+    /**
+     * Get the Application Master Key from environment
+     */
+    private getAMK;
+    /**
+     * Ensure the store is initialized
+     */
+    private ensureInitialized;
+    /**
+     * Emit an event to all listeners
+     */
+    private emitEvent;
+    /**
+     * Subscribe to store events
+     */
+    subscribe(listener: SecretStoreEventListener): Unsubscribe;
+    encrypt(tenantId: string, secretName: string, plaintext: string, options?: EncryptOptions): Promise<EncryptedEnvelope>;
+    decrypt(tenantId: string, envelope: EncryptedEnvelope): Promise<DecryptedSecret>;
+    getTenantKey(tenantId: string): Promise<TenantDataEncryptionKey | null>;
+    createTenantKey(tenantId: string): Promise<TenantDataEncryptionKey>;
+    rotateTenantKey(tenantId: string): Promise<TenantDataEncryptionKey>;
+    retireTenantKey(tenantId: string, keyId: string): Promise<void>;
+    getActiveAMK(): Promise<ApplicationMasterKey>;
+    rewrapTenantKey(_tenantId: string, _newAmkKeyId: string): Promise<TenantDataEncryptionKey>;
+    listKeyVersions(tenantId: string): Promise<TenantDataEncryptionKey[]>;
+    /**
+     * Parse a database row into a TenantDataEncryptionKey
+     */
+    private parseKeyRow;
+}
+export default DatabaseSecretStore;
+//# sourceMappingURL=database.d.ts.map

package/dist/adapters/database.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"database.d.ts","sourceRoot":"","sources":["../../src/adapters/database.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EACV,oBAAoB,EACpB,0BAA0B,EAC1B,eAAe,EACf,iBAAiB,EACjB,cAAc,EACd,WAAW,EAEX,wBAAwB,EACxB,uBAAuB,EACvB,WAAW,EACZ,MAAM,oBAAoB,CAAC;AAO5B;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,qBAAa,mBAAoB,YAAW,WAAW;IACrD,OAAO,CAAC,EAAE,CAAoB;IAC9B,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,SAAS,CAAoC;IACrD,OAAO,CAAC,SAAS,CAAuB;IACxC,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,SAAS,CAAkC;gBAEvC,OAAO,EAAE,0BAA0B;IAe/C;;OAEG;IACG,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IA+BjC;;OAEG;IACH,OAAO,CAAC,MAAM;IAuBd;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAMzB;;OAEG;YACW,SAAS;IAMvB;;OAEG;IACH,SAAS,CAAC,QAAQ,EAAE,wBAAwB,GAAG,WAAW;IAUpD,OAAO,CACX,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,MAAM,EACjB,OAAO,CAAC,EAAE,cAAc,GACvB,OAAO,CAAC,iBAAiB,CAAC;IA8EvB,OAAO,CACX,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,iBAAiB,GAC1B,OAAO,CAAC,eAAe,CAAC;IAiErB,YAAY,CAChB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,uBAAuB,GAAG,IAAI,CAAC;IAapC,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,uBAAuB,CAAC;IA6CnE,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,uBAAuB,CAAC;IA6EnE,eAAe,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAwB/D,YAAY,IAAI,OAAO,CAAC,oBAAoB,CAAC;IAc7C,eAAe,CACnB,SAAS,EAAE,MAAM,EACjB,YAAY,EAAE,MAAM,GACnB,OAAO,CAAC,uBAAuB,CAAC;IAY7B,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,uBAAuB,EAAE,CAAC;IAW3E;;OAEG;IACH,OAAO,CAAC,WAAW;CAiBpB;AAED,eAAe,mBAAmB,CAAC"}

package/dist/cli/claude-context.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=claude-context.d.ts.map

package/dist/cli/claude-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"claude-context.d.ts","sourceRoot":"","sources":["../../src/cli/claude-context.ts"],"names":[],"mappings":""}

package/dist/cli/claude-context.js

@@ -0,0 +1,21 @@
+#!/usr/bin/env node
+import { existsSync, mkdirSync, copyFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+const Dirname = dirname(fileURLToPath(import.meta.url));
+const pkgRoot = join(Dirname, "../..");
+const targetDir = join(process.cwd(), ".claude");
+if (!existsSync(targetDir)) {
+  mkdirSync(targetDir, { recursive: true });
+}
+const pkgName = "secrets";
+const agentMdSrc = existsSync(join(pkgRoot, "AGENT.md")) ? join(pkgRoot, "AGENT.md") : join(pkgRoot, "CLAUDE.md");
+const metaSrc = existsSync(join(pkgRoot, "metadata.json")) ? join(pkgRoot, "metadata.json") : join(pkgRoot, ".claude-meta.json");
+if (existsSync(agentMdSrc)) {
+  copyFileSync(agentMdSrc, join(targetDir, `have-${pkgName}.md`));
+}
+if (existsSync(metaSrc)) {
+  copyFileSync(metaSrc, join(targetDir, `have-${pkgName}.meta.json`));
+}
+console.log(`✓ Installed @happyvertical/${pkgName} context to .claude/`);
+//# sourceMappingURL=claude-context.js.map

package/dist/cli/claude-context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"claude-context.js","sources":["../../src/cli/claude-context.ts"],"sourcesContent":["#!/usr/bin/env node\n/**\n * CLI script to install agent context for @happyvertical/secrets\n * Run the published context installer binary for this package.\n */\nimport { copyFileSync, existsSync, mkdirSync } from 'node:fs';\nimport { dirname, join } from 'node:path';\nimport { fileURLToPath } from 'node:url';\n\nconst Dirname = dirname(fileURLToPath(import.meta.url));\nconst pkgRoot = join(Dirname, '../..');\nconst targetDir = join(process.cwd(), '.claude');\n\nif (!existsSync(targetDir)) {\n  mkdirSync(targetDir, { recursive: true });\n}\n\nconst pkgName = 'secrets';\nconst agentMdSrc = existsSync(join(pkgRoot, 'AGENT.md'))\n  ? join(pkgRoot, 'AGENT.md')\n  : join(pkgRoot, 'CLAUDE.md');\nconst metaSrc = existsSync(join(pkgRoot, 'metadata.json'))\n  ? join(pkgRoot, 'metadata.json')\n  : join(pkgRoot, '.claude-meta.json');\n\nif (existsSync(agentMdSrc)) {\n  copyFileSync(agentMdSrc, join(targetDir, `have-${pkgName}.md`));\n}\n\nif (existsSync(metaSrc)) {\n  copyFileSync(metaSrc, join(targetDir, `have-${pkgName}.meta.json`));\n}\n\nconsole.log(`✓ Installed @happyvertical/${pkgName} context to .claude/`);\n"],"names":[],"mappings":";;;;AASA,MAAM,UAAU,QAAQ,cAAc,YAAY,GAAG,CAAC;AACtD,MAAM,UAAU,KAAK,SAAS,OAAO;AACrC,MAAM,YAAY,KAAK,QAAQ,IAAA,GAAO,SAAS;AAE/C,IAAI,CAAC,WAAW,SAAS,GAAG;AAC1B,YAAU,WAAW,EAAE,WAAW,KAAA,CAAM;AAC1C;AAEA,MAAM,UAAU;AAChB,MAAM,aAAa,WAAW,KAAK,SAAS,UAAU,CAAC,IACnD,KAAK,SAAS,UAAU,IACxB,KAAK,SAAS,WAAW;AAC7B,MAAM,UAAU,WAAW,KAAK,SAAS,eAAe,CAAC,IACrD,KAAK,SAAS,eAAe,IAC7B,KAAK,SAAS,mBAAmB;AAErC,IAAI,WAAW,UAAU,GAAG;AAC1B,eAAa,YAAY,KAAK,WAAW,QAAQ,OAAO,KAAK,CAAC;AAChE;AAEA,IAAI,WAAW,OAAO,GAAG;AACvB,eAAa,SAAS,KAAK,WAAW,QAAQ,OAAO,YAAY,CAAC;AACpE;AAEA,QAAQ,IAAI,8BAA8B,OAAO,sBAAsB;"}

package/dist/index.d.ts

@@ -0,0 +1,45 @@
+/**
+ * @happyvertical/secrets
+ *
+ * Envelope encryption for per-tenant secret management with pluggable backends.
+ *
+ * @example
+ * ```typescript
+ * import { getSecretStore } from '@happyvertical/secrets';
+ * import { getDatabase } from '@happyvertical/sql';
+ *
+ * // Get a database connection
+ * const db = await getDatabase({ type: 'sqlite', url: ':memory:' });
+ *
+ * // Create a secret store
+ * const store = await getSecretStore({
+ *   type: 'database',
+ *   db,
+ *   amk: {
+ *     provider: 'env',
+ *     keyEnvVar: 'SECRET_MASTER_KEY',  // 64 hex chars (32 bytes)
+ *     keyId: 'amk-v1'
+ *   }
+ * });
+ *
+ * // Encrypt a secret for a tenant
+ * const envelope = await store.encrypt('tenant-123', 'api-key', 'sk_live_xxx');
+ *
+ * // Decrypt the secret
+ * const { value } = await store.decrypt('tenant-123', envelope);
+ * console.log(value); // 'sk_live_xxx'
+ *
+ * // Rotate tenant's encryption key
+ * await store.rotateTenantKey('tenant-123');
+ * ```
+ *
+ * @packageDocumentation
+ */
+export { DatabaseSecretStore } from './adapters/database.js';
+export { EnvelopeEncryption } from './shared/envelope.js';
+export { AMKUnavailableError, DecryptionError, EncryptionError, InvalidKeyFormatError, KeyNotFoundError, KeyRotationError, SecretError, StoreNotInitializedError, TenantKeyMissingError, } from './shared/errors.js';
+export { getSecretStore, isAWSKMSOptions, isAzureKeyVaultOptions, isDatabaseOptions, isVaultOptions, } from './shared/factory.js';
+export type { AMKConfig, ApplicationMasterKey, AWSKMSSecretStoreOptions, AzureKeyVaultSecretStoreOptions, DatabaseSecretStoreOptions, DecryptedSecret, EncryptedEnvelope, EncryptOptions, GetSecretStoreOptions, SecretAdapterType, SecretStore, SecretStoreEvent, SecretStoreEventListener, SecretStoreEventType, TenantDataEncryptionKey, Unsubscribe, VaultSecretStoreOptions, } from './shared/types.js';
+/** @internal */
+export declare const PACKAGE_VERSION_INITIALIZED = true;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAGH,OAAO,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AAE7D,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAE1D,OAAO,EACL,mBAAmB,EACnB,eAAe,EACf,eAAe,EACf,qBAAqB,EACrB,gBAAgB,EAChB,gBAAgB,EAChB,WAAW,EACX,wBAAwB,EACxB,qBAAqB,GACtB,MAAM,oBAAoB,CAAC;AAG5B,OAAO,EACL,cAAc,EACd,eAAe,EACf,sBAAsB,EACtB,iBAAiB,EACjB,cAAc,GACf,MAAM,qBAAqB,CAAC;AAE7B,YAAY,EAEV,SAAS,EACT,oBAAoB,EACpB,wBAAwB,EACxB,+BAA+B,EAC/B,0BAA0B,EAC1B,eAAe,EACf,iBAAiB,EACjB,cAAc,EACd,qBAAqB,EACrB,iBAAiB,EACjB,WAAW,EACX,gBAAgB,EAChB,wBAAwB,EACxB,oBAAoB,EACpB,uBAAuB,EACvB,WAAW,EACX,uBAAuB,GACxB,MAAM,mBAAmB,CAAC;AAE3B,gBAAgB;AAChB,eAAO,MAAM,2BAA2B,OAAO,CAAC"}