@happyvertical/smrt-secrets 0.30.0

package/AGENTS.md

@@ -0,0 +1,66 @@
+# @happyvertical/smrt-secrets
+
+Envelope encryption for per-tenant secret storage with key rotation and audit logging.
+
+## Encryption Architecture
+
+```
+Secret value → encrypted with TDEK (per-tenant Data Encryption Key)
+  TDEK → wrapped with AMK (Application Master Key, from env SMRT_SECRET_MASTER_KEY)
+```
+
+## Models
+
+- **Secret**: `encryptedValue` (JSON envelope), `category`, `status` (active/disabled/expired), `expiresAt`, `accessCount`, `lastAccessedAt`. **No API/MCP exposure** (security). CLI: list-only.
+- **TenantKey**: per-tenant TDEK in wrapped form. Status: active/rotating/retired/compromised. **Not tenant-scoped itself** — it tracks keys FOR tenants.
+- **SecretAuditLog**: action (create/read/update/delete/rotate_key/disable/enable), result (success/failure/denied), user/IP tracking. CLI: list-only.
+
+## SecretService
+
+| Method | Behavior |
+|--------|----------|
+| `store(name, value, options)` | Encrypt + save. Upsert if exists. Uses `context=tenantId` for per-tenant uniqueness. |
+| `retrieve(name)` | Decrypt + audit + increment accessCount |
+| `diagnoseTenantSecretKeyDrift(tenantId)` | Report active secret/key drift without exposing values. Checks `secrets`, SDK `tenant_encryption_keys`, and SMRT `tenant_keys`. |
+| `repairTenantSecretKeyDrift(tenantId, opts)` | Explicit repair path for unrecoverable drift. Use `dryRun` first; destructive cleanup requires `confirmDeleteUnrecoverableData: true`. |
+| `rotateKey()` | Create new TDEK, mark old as retired |
+| `reencryptAll()` | Decrypt with old TDEK, re-encrypt with new — **must call separately after rotateKey()** |
+| `disable(name)` / `enable(name)` | Toggle status |
+
+## Gotchas
+
+- **Key rotation doesn't auto-re-encrypt**: call `reencryptAll()` separately after `rotateKey()`
+- **retrieve() increments accessCount**: every read is tracked
+- **TenantKey NOT tenant-scoped**: it stores keys for tenants but isn't filtered by tenant context
+- **Two key tables**: `tenant_encryption_keys` is the lower-level SDK table used by `SecretService` encryption; `tenant_keys` is the SMRT model table. Drift diagnosis reports both so an empty `tenant_keys` view is not confused with missing SDK key material.
+- **Repair is destructive only by confirmation**: `repairTenantSecretKeyDrift()` deletes unrecoverable encrypted rows only when `confirmDeleteUnrecoverableData: true` is explicit. Do not silently discard encrypted secrets.
+- **Expired secrets filtered by default**: pass `includeExpired: true` to list them
+- **TenantKeyCollection.cleanupRetiredKeys()**: hard-deletes after 90 days
+- **Audit logging optional but default**: failures logged to console, not thrown
+
+## Known exceptions to monorepo standards
+
+Per `docs/content/standards.md §7`, tenant-aware models should normally apply
+`@TenantScoped({ mode: 'optional' })` from `@happyvertical/smrt-tenancy`. The three
+models in this package deviate intentionally; each `@smrt(...)` block carries an
+inline comment pointing back to this section.
+
+- **`Secret` (`src/models/Secret.ts`)** — uses the inline `tenantScoped: true` form
+  on `@smrt()` instead of the `@TenantScoped` decorator. `SecretService.store()`
+  performs manual scoping by populating `context = tenantId` on each row, so the
+  `(slug, context)` upsert key from the base `SmrtObject` is what isolates secret
+  names per tenant. Switching to the decorator without rethinking the upsert key
+  would surface false-positive name collisions across tenants.
+- **`TenantKey` (`src/models/TenantKey.ts`)** — deliberately NOT tenant-scoped at
+  all. The row carries a `tenantId` column because each TDEK belongs to a tenant,
+  but key-rotation tooling, AMK rewrap jobs, and super-admin audits must query
+  across tenants; the tenancy interceptor would silently filter rows those flows
+  rely on.
+- **`SecretAuditLog` (`src/models/SecretAuditLog.ts`)** — uses the inline
+  `tenantScoped: true` form rather than the decorator. Audit reads run in mixed
+  contexts (tenant-scoped reports vs. super-admin compliance review). Cross-
+  tenant audit queries should be wrapped in `withSuperAdminBypass()` from
+  `@happyvertical/smrt-tenancy` at the call site — there are no such cross-
+  tenant call sites in this package today, but consumers building compliance
+  tooling should adopt that pattern explicitly rather than relying on
+  decorator-implicit filtering.

package/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

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,144 @@
+# @happyvertical/smrt-secrets
+
+Per-tenant secret management with envelope encryption for the SMRT framework. Uses a three-layer encryption chain: Application Master Key (AMK) wraps per-tenant Data Encryption Keys (TDEK), which encrypt individual secret values.
+
+## Installation
+
+```bash
+pnpm add @happyvertical/smrt-secrets
+```
+
+Requires the `SMRT_SECRET_MASTER_KEY` environment variable (64 hex characters) as the AMK.
+
+## Usage
+
+```typescript
+import { SecretService } from '@happyvertical/smrt-secrets';
+import { withTenant } from '@happyvertical/smrt-tenancy';
+
+// Create the service (reads AMK from env by default)
+const service = await SecretService.create({ db });
+
+await withTenant({ tenantId: 'tenant-123' }, async () => {
+  // Store a secret (upserts if name already exists)
+  await service.store('stripe-api-key', 'sk_live_xxx', {
+    category: 'api-keys',
+    description: 'Stripe production key',
+    expiresAt: new Date('2027-01-01'),
+  });
+
+  // Retrieve and decrypt
+  const { value, accessCount } = await service.retrieve('stripe-api-key');
+
+  // List secret names (values never included)
+  const secrets = await service.list({ category: 'api-keys' });
+
+  // Disable/enable without deleting
+  await service.disable('stripe-api-key');
+  await service.enable('stripe-api-key');
+
+  // Rotate the tenant's encryption key
+  await service.rotateKey();
+  // Re-encrypt all secrets with the new key (separate step)
+  await service.reencryptAll();
+
+  // Query audit logs
+  const logs = await service.getAuditLogs({ secretName: 'stripe-api-key' });
+
+  // Diagnose tenant secret/key drift without exposing values
+  const drift = await service.diagnoseTenantSecretKeyDrift('tenant-123');
+
+  // Preview and then explicitly repair unrecoverable drifted rows
+  await service.repairTenantSecretKeyDrift('tenant-123', { dryRun: true });
+  await service.repairTenantSecretKeyDrift('tenant-123', {
+    confirmDeleteUnrecoverableData: true,
+  });
+
+  // Hard delete
+  await service.delete('stripe-api-key');
+});
+```
+
+### Encryption chain
+
+```
+AMK (env var, 256-bit)
+  └─ wraps TDEK (per-tenant, auto-generated)
+       └─ encrypts secret value (stored as JSON envelope)
+```
+
+The AMK is loaded from `SMRT_SECRET_MASTER_KEY` (configurable via `amkEnvVar` option). Each tenant gets its own TDEK on first secret storage. TDEKs are stored in wrapped form -- they can only be unwrapped using the AMK. Secret values are encrypted by the unwrapped TDEK and persisted as `EncryptedEnvelope` JSON.
+
+### Key rotation
+
+`rotateKey()` creates a new TDEK version and retires the old one. Existing secrets remain readable because retired keys are kept for decryption. Call `reencryptAll()` separately after rotation to re-encrypt all secrets with the new key. The method returns `{ success, failed }` counts.
+
+TenantKey statuses: `active` (current encryption key), `rotating` (transitional), `retired` (kept for decryption), `compromised` (should not be used).
+
+### Drift diagnosis and repair
+
+`diagnoseTenantSecretKeyDrift(tenantId)` reports tenant secret/key drift without
+returning secret values. It checks active `secrets` rows, lower-level
+`tenant_encryption_keys` rows used by `@happyvertical/secrets`, and SMRT-visible
+`tenant_keys` rows so operators can distinguish missing secrets from stale or
+unusable key material.
+
+`repairTenantSecretKeyDrift(tenantId, { dryRun: true })` previews rows that would
+be deleted. A destructive repair requires
+`confirmDeleteUnrecoverableData: true`; it deletes only encrypted secret/key rows
+identified as unrecoverable with the currently configured AMK. After repair,
+store fresh secret values with `storeForTenant()` or `store()`.
+
+### Audit logging
+
+Every secret operation (create, read, update, delete, rotate_key, disable, enable) is logged to `SecretAuditLog` with user ID, action, result (success/failure/denied), and optional IP/user-agent. Audit logging is enabled by default; failures are logged to console rather than thrown so they do not block secret operations.
+
+### Security model
+
+The `Secret` and `TenantKey` models have no API or MCP exposure to prevent accidental leakage. CLI access is limited to listing names. The `TenantKey` model is deliberately not tenant-scoped -- it tracks keys FOR tenants rather than being owned BY them.
+
+## API
+
+### Models
+
+| Export | Description |
+|--------|------------|
+| `Secret` | Encrypted secret record with status, expiration, and access tracking |
+| `SecretAuditLog` | Immutable audit trail for all secret operations |
+| `TenantKey` | Per-tenant data encryption key in wrapped form |
+
+### Collections
+
+| Export | Description |
+|--------|------------|
+| `SecretCollection` | Secret queries with tenant filtering and category support |
+| `SecretAuditLogCollection` | Audit log queries with filtering and pagination |
+| `TenantKeyCollection` | Key management including retired key cleanup |
+
+### Services
+
+| Export | Description |
+|--------|------------|
+| `SecretService` | High-level API: store, retrieve, rotate, delete, audit, diagnose and repair key drift |
+
+### Functions
+
+| Export | Description |
+|--------|------------|
+| `createAuditEntry` | Build an audit log entry for a secret operation |
+
+### Error Classes (re-exported from `@happyvertical/secrets`)
+
+`SecretError`, `AMKUnavailableError`, `DecryptionError`, `EncryptionError`, `InvalidKeyFormatError`, `KeyNotFoundError`, `KeyRotationError`, `StoreNotInitializedError`, `TenantKeyMissingError`
+
+### Key Types
+
+`SecretServiceOptions`, `StoreSecretOptions`, `RetrievedSecret`, `DiagnoseTenantSecretKeyDriftOptions`, `SecretKeyDriftReport`, `SecretKeyDriftIssue`, `RepairTenantSecretKeyDriftOptions`, `SecretKeyDriftRepairResult`, `ListSecretsOptions`, `ListAuditLogsOptions`, `SecretStatus`, `SecretAuditAction`, `SecretAuditResult`, `TenantKeyStatus`, `ApplicationMasterKey`, `EncryptedEnvelope`, `TenantDataEncryptionKey`, `SecretStore`
+
+## Dependencies
+
+- `@happyvertical/smrt-core` -- ORM and code generation
+- `@happyvertical/smrt-tenancy` -- tenant context for scoped operations
+- `@happyvertical/secrets` -- envelope encryption primitives
+- `@happyvertical/sql` -- database interface
+- `@happyvertical/utils` -- shared utilities

package/dist/__smrt-register__.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=__smrt-register__.d.ts.map

package/dist/__smrt-register__.d.ts.map

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