@shipfox/api-secrets 2.0.0

package/.turbo/turbo-build.log

@@ -0,0 +1,2 @@
+$ shipfox-swc
+Successfully compiled: 51 files with swc (105.96ms)

package/.turbo/turbo-type$colon$emit.log

@@ -0,0 +1 @@
+$ shipfox-tsc-emit

package/.turbo/turbo-type.log

@@ -0,0 +1 @@
+$ shipfox-tsc-check

package/CHANGELOG.md

@@ -0,0 +1,116 @@
+# @shipfox/api-secrets
+
+## 2.0.0
+
+### Minor Changes
+
+- 1b0d344: Publishes the complete API runtime closure with packed-consumer-safe internal imports and records its exact package set in application releases.
+
+### Patch Changes
+
+- Updated dependencies [0cd6dd4]
+- Updated dependencies [1b0d344]
+- Updated dependencies [521e006]
+  - @shipfox/node-module@0.2.0
+  - @shipfox/api-auth-context@2.0.0
+  - @shipfox/api-projects@2.0.0
+  - @shipfox/api-secrets-dto@2.0.0
+  - @shipfox/config@1.2.1
+  - @shipfox/node-drizzle@0.2.1
+  - @shipfox/node-fastify@0.2.1
+  - @shipfox/node-opentelemetry@0.5.0
+  - @shipfox/node-outbox@0.2.1
+  - @shipfox/node-postgres@0.4.1
+
+## 0.1.2
+
+### Patch Changes
+
+- Updated dependencies [705dd43]
+  - @shipfox/node-outbox@0.2.0
+  - @shipfox/api-projects@0.1.2
+  - @shipfox/node-module@0.1.2
+
+## 0.1.1
+
+### Patch Changes
+
+- Updated dependencies [ec75cd5]
+- Updated dependencies [6a1fb54]
+  - @shipfox/node-drizzle@0.2.0
+  - @shipfox/node-postgres@0.4.0
+  - @shipfox/api-projects@0.1.1
+  - @shipfox/node-module@0.1.1
+  - @shipfox/node-outbox@0.1.1
+
+## 0.1.0
+
+### Minor Changes
+
+- 3b45d86: Adds the secrets and variables backend foundation with encrypted secret storage, plaintext variables, and shared DTO contracts.
+- 3ddde91: Adds the secrets and variables management API with DTO contracts, exact-scope storage helpers, outbox events, and workspace-admin route guards.
+
+### Patch Changes
+
+- f66f606: Test suites can create managed secrets and variables through protected setup APIs.
+- e51d464: Add the Secrets & Variables workspace settings UI (S1b).
+  - New `@shipfox/client-secrets` package: transport + React Query hooks (a shared
+    `createStoreApi` factory), a write-only secret form and a readable variable form
+    (TanStack Form + Zod, multiline `Textarea` values, live short-value / sensitive-name
+    advisories), and the workspace secrets/variables sections (single-call list, masked
+    secret values, copy-name, delete with blast-radius warning).
+  - `@shipfox/client-workspace-settings`: new Secrets and Variables settings pages and nav
+    entries.
+  - `@shipfox/api-secrets-dto`: export `SECRETS_MAX_LIST_LIMIT` and raise the list `limit`
+    cap so the settings UI can fetch the whole bounded set in one request; the variable
+    list item now carries `value_truncated`.
+  - `@shipfox/api-secrets`: the variable list returns a bounded single-line preview of each
+    value (the full value is read via `GET /variables/:key` when editing) so a single-call
+    list cannot materialize very large responses; startup fails if `SECRETS_MAX_PER_WORKSPACE`
+    exceeds the list limit.
+  - `@shipfox/client-router`: register the `/workspaces/$wid/settings/secrets` and
+    `/variables` routes.
+
+- 82d22e4: Make the workspace-membership gate stateless. `requireWorkspaceAccess` now lives in `@shipfox/api-auth-context` and authorizes a request purely from the verified session-token claims, replacing the `requireMembership` gate in `@shipfox/api-workspaces` that read the workspace row from the database on every workspace-scoped request. Membership and role already travel in the token, so the check needs no database access.
+
+  This removes the per-request database read and severs the runtime dependency on `@shipfox/api-workspaces` from feature modules that only needed the membership gate (integration providers, secrets, projects, agent, runners). Workspace existence and `active`-status enforcement, which no code path currently exercises, moves off the hot path; enforce it at token issuance when workspace suspension is introduced.
+
+- Updated dependencies [34ba284]
+- Updated dependencies [3b45d86]
+- Updated dependencies [5707d6d]
+- Updated dependencies [b9c3f32]
+- Updated dependencies [a81b68c]
+- Updated dependencies [115655e]
+- Updated dependencies [c0a883c]
+- Updated dependencies [72ce351]
+- Updated dependencies [e47f8da]
+- Updated dependencies [7b175f5]
+- Updated dependencies [ae7a63c]
+- Updated dependencies [5729548]
+- Updated dependencies [f92122b]
+- Updated dependencies [857fd73]
+- Updated dependencies [75520ff]
+- Updated dependencies [f66f606]
+- Updated dependencies [e51d464]
+- Updated dependencies [d6d4862]
+- Updated dependencies [c0a883c]
+- Updated dependencies [6077301]
+- Updated dependencies [3bea87f]
+- Updated dependencies [82d22e4]
+- Updated dependencies [8ecba0f]
+- Updated dependencies [27770eb]
+- Updated dependencies [2933c33]
+- Updated dependencies [43fd0c1]
+- Updated dependencies [6181819]
+- Updated dependencies [3ddde91]
+- Updated dependencies [9c149d1]
+  - @shipfox/node-fastify@0.2.0
+  - @shipfox/api-secrets-dto@0.1.0
+  - @shipfox/node-drizzle@0.1.0
+  - @shipfox/api-auth-context@0.1.0
+  - @shipfox/api-projects@0.1.0
+  - @shipfox/node-opentelemetry@0.4.2
+  - @shipfox/node-postgres@0.3.2
+  - @shipfox/node-module@0.1.0
+  - @shipfox/node-outbox@0.1.0
+  - @shipfox/config@1.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Shipfox
+
+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,207 @@
+# @shipfox/api-secrets
+
+`@shipfox/api-secrets` stores workspace secrets and variables for backend modules.
+
+## What it does
+
+- **`secretsModule`**: Declares the module name and database migrations for the API module loader.
+- **Secret store API**: `setSecrets`, `getSecret`, `getSecretsByNamespace`, and `deleteSecrets` manage encrypted values by scope and namespace.
+- **Variable store API**: `setVariables`, `getVariable`, `getVariablesByNamespace`, and `deleteVariables` manage non-secret config values with the same scope rules.
+- **`rotateWorkspaceDataKeys()`**: Re-wraps workspace data keys under the current KEK. It does not re-encrypt stored values.
+- **Store resolver**: `resolveSecretStore` supports the built-in `local` store and rejects unknown store names with `UnknownSecretStoreError`.
+- **Domain errors**: Typed errors let route layers map validation, cap, crypto, and config failures to client responses.
+
+## Installation / Setup
+
+Install the package from the registry:
+
+```sh
+pnpm add @shipfox/api-secrets
+```
+
+Register `secretsModule` before modules that read or write secrets so its migrations run first.
+
+## Usage
+
+```ts
+import {getSecret, secretsModule, setSecrets, setVariables} from '@shipfox/api-secrets';
+import {initializeModules} from '@shipfox/node-module';
+
+await initializeModules({modules: [secretsModule]});
+
+await setSecrets({
+  workspaceId: '018f1c9c-7c30-7f41-9c32-7668a7f3cc11',
+  projectId: '018f1c9d-1b3c-7d4a-a5a2-8c2fdf4d7a91',
+  namespace: 'system/agent/model-provider/openai',
+  values: {API_KEY: 'sk-live-value'},
+});
+
+await setVariables({
+  workspaceId: '018f1c9c-7c30-7f41-9c32-7668a7f3cc11',
+  namespace: 'agent/defaults',
+  values: {REGION: 'us-east-1'},
+});
+
+const apiKey = await getSecret({
+  workspaceId: '018f1c9c-7c30-7f41-9c32-7668a7f3cc11',
+  projectId: '018f1c9d-1b3c-7d4a-a5a2-8c2fdf4d7a91',
+  namespace: 'system/agent/model-provider/openai',
+  key: 'API_KEY',
+});
+```
+
+## Namespaces
+
+Namespaces group values that belong to one module-owned purpose. Use lowercase
+slug paths in this shape:
+
+```text
+<module>/<entity>/<id>
+```
+
+Use the module name first, then the entity type, then the entity identifier. For
+module-internal records that should not appear in user-facing management lists,
+prefix the namespace with `system/`:
+
+```text
+system/<module>/<entity>/<id>
+```
+
+For example, agent model-provider credentials for OpenAI live under:
+
+```text
+system/agent/model-provider/openai
+```
+
+Keep the namespace specific to the entity that owns the keys. Do not put several
+unrelated entity types under the same namespace; create separate namespaces such
+as `system/agent/model-provider/openai` and `system/agent/<other-entity>/<id>`.
+
+## Environment
+
+| Variable | Default | Purpose |
+| --- | --- | --- |
+| `SECRETS_ENCRYPTION_KEK` | none | Required base64-encoded 32-byte key used to wrap workspace data keys. Generate one per environment. |
+| `SECRETS_ENCRYPTION_KEK_PREVIOUS` | none | Previous KEK needed during rotation and for normal operations until all workspace data keys are re-wrapped. Set it to the old key until data-key rotation completes. |
+| `SECRETS_MAX_PER_WORKSPACE` | `10000` | Maximum total count of secrets and variables in one workspace. The count includes all namespaces and project scopes. |
+| `SECRETS_SHORT_VALUE_WARN_LENGTH` | `12` | Length below which management routes can show a short-secret warning. The core store does not emit the warning itself. |
+
+Startup checks each KEK as a canonical base64 value for a 32-byte key. It also rejects non-positive numeric limits.
+
+## API
+
+| Function | Result |
+| --- | --- |
+| `setSecrets({workspaceId, projectId?, namespace?, values, editedBy?})` | Encrypts and upserts a batch of secret values. |
+| `getSecret({workspaceId, projectId?, namespace?, key, store?})` | Returns one plaintext secret or `null`. Project scope wins over workspace scope. |
+| `getSecretsByNamespace({workspaceId, projectId?, namespace?, store?})` | Returns plaintext secrets in a namespace. Project scope wins over workspace scope. |
+| `deleteSecrets({workspaceId, projectId?, namespace?, keys?})` | Deletes exact-scope secrets. Omitted `keys` deletes the scope namespace. Empty `keys` deletes nothing. |
+| `setVariables({workspaceId, projectId?, namespace?, values, editedBy?})` | Upserts plaintext variables with the same validation and cap rules as secrets. |
+| `getVariable({workspaceId, projectId?, namespace?, key})` | Returns one variable or `null`. Project scope wins over workspace scope. |
+| `getVariablesByNamespace({workspaceId, projectId?, namespace?})` | Returns variables in a namespace. Project scope wins over workspace scope. |
+| `deleteVariables({workspaceId, projectId?, namespace?, keys?})` | Deletes exact-scope variables. Omitted `keys` deletes the scope namespace. Empty `keys` deletes nothing. |
+| `rotateWorkspaceDataKeys()` | Re-wraps stored data keys from the previous KEK to the current KEK. |
+
+Keys must match `^[A-Z_][A-Z0-9_]*$`. Keys and namespaces may be at most 128 characters. Namespaces may be empty or a lowercase slug path.
+
+## Data Model
+
+This module owns tables with the `secrets_` prefix.
+
+| Table | Purpose |
+| --- | --- |
+| `secrets_data_keys` | Stores one wrapped data-encryption key per workspace. The row includes the KEK version used to wrap it. |
+| `secrets_values` | Stores encrypted secret values, a keyed HMAC fingerprint, scope columns, and edit metadata. |
+| `secrets_variables` | Stores plaintext variable values, scope columns, and edit metadata. |
+
+`secrets_values` and `secrets_variables` use partial unique indexes for scope:
+
+- Workspace scope is unique by `(workspace_id, namespace, key)` where `project_id IS NULL`.
+- Project scope is unique by `(workspace_id, project_id, namespace, key)` where `project_id IS NOT NULL`.
+
+The database checks key and namespace patterns. The core layer also validates them before writing.
+
+## Security Model
+
+### Trust boundary
+
+This package is an in-process storage module. It does not perform user authorization.
+
+Callers must derive `workspaceId`, `projectId`, and namespace from trusted context. Do not pass attacker-controlled scope values into the store functions.
+
+Secret management routes should keep secret values write-only at the HTTP boundary. Internal callers may read plaintext secrets only after their own tenancy checks pass.
+
+### Encryption
+
+Secret values use envelope encryption.
+
+- Each workspace has one 32-byte data-encryption key (DEK).
+- The DEK is generated with `crypto.randomBytes(32)` on first use.
+- The DEK is wrapped with the configured key-encryption key (KEK) and stored in `secrets_data_keys`.
+- Secret values are encrypted with AES-256-GCM under the plaintext DEK.
+- Ciphertexts are encoded as `v1:<base64(iv || authTag || ciphertext)>`.
+- AES-GCM uses a fresh 12-byte IV for each seal.
+
+Additional authenticated data binds encrypted values to:
+
+- `workspaceId`
+- scope, either workspace or project ID
+- namespace
+- key
+
+Moving ciphertext to another scope makes decryption fail closed with `SecretDecryptionError`.
+
+### Key handling
+
+`SECRETS_ENCRYPTION_KEK` is the current KEK. It must be a canonical base64-encoded 32-byte value. Startup rejects malformed, unpadded, over-padded, or whitespace-tainted keys.
+
+`SECRETS_ENCRYPTION_KEK_PREVIOUS` supports rotation. During that window, the key provider can unwrap DEKs with the old KEK and wrap them with the new KEK.
+
+KEK versions come from a domain-separated SHA-256 hash of the KEK. The version is stored with each wrapped DEK. Rotation refuses unknown KEK versions.
+
+Plaintext DEKs are cached in memory for hot reads. The cache has a size limit and TTL. The manager stores cache-owned Buffer copies and returns defensive copies. Node cannot promise full memory wipes, so the design limits how long keys stay in memory.
+
+### Rotation
+
+KEK rotation re-wraps DEKs only. It does not re-encrypt `secrets_values`.
+
+Rotation pages over `secrets_data_keys`. It unwraps each DEK with the previous KEK and wraps it with the current KEK. The update uses compare-and-swap on the old version. If two rotations race, one wins and the other skips the row.
+
+After each unwrap in the rotation path, the temporary plaintext DEK Buffer is filled with zeroes.
+
+### Fingerprints
+
+`secrets_values.fingerprint` stores a keyed HMAC-SHA256 digest of the secret value using the workspace DEK. It is not a plaintext suffix.
+
+The fingerprint supports equality and display workflows without storing part of the secret in clear text. A database leak does not reveal the end of a secret through this column.
+
+### Failure behavior
+
+Secret decryption failures collapse to `SecretDecryptionError`. The error does not include secret values, key material, or ciphertext.
+
+Deleting a workspace data key makes existing secrets unreadable. Reads fail closed instead of returning unauthenticated plaintext.
+
+## Behavior Notes
+
+- **Scope precedence:** project-scoped rows override workspace-scoped rows on reads and namespace lists.
+- **Exact deletes:** deletes target only the exact scope passed by the caller. Deleting a project secret does not delete the workspace fallback.
+- **Batch writes:** each write batch must target one scope. Mixed workspace and project rows are rejected by the persistence layer.
+- **Workspace cap:** cap checks count secrets and variables together. The check runs inside the write transaction. It uses a workspace advisory lock and counts only net-new keys.
+- **Variables:** variables are plaintext by design. Use them for non-secret config only.
+- **Stores:** `local` is the only built-in store. Unknown stores throw `UnknownSecretStoreError`.
+
+## Development
+
+The tests use PostgreSQL. Start local services before running package tests:
+
+```sh
+docker compose up -d
+turbo build --filter=@shipfox/api-secrets
+turbo check --filter=@shipfox/api-secrets
+turbo type --filter=@shipfox/api-secrets
+turbo test --filter=@shipfox/api-secrets
+```
+
+## License
+
+MIT

package/dist/config.d.ts

@@ -0,0 +1,8 @@
+export declare const MAX_VALUE_BYTES: number;
+export declare const config: Readonly<{
+    SECRETS_ENCRYPTION_KEK: string;
+    SECRETS_ENCRYPTION_KEK_PREVIOUS: string | undefined;
+    SECRETS_MAX_PER_WORKSPACE: number;
+    SECRETS_SHORT_VALUE_WARN_LENGTH: number;
+} & import("@shipfox/config").CleanedEnvAccessors>;
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAIA,eAAO,MAAM,eAAe,QAAY,CAAC;AAEzC,eAAO,MAAM,MAAM;;;;;kDAgBjB,CAAC"}

package/dist/config.js

@@ -0,0 +1,38 @@
+import { SECRETS_MAX_LIST_LIMIT } from '@shipfox/api-secrets-dto';
+import { createConfig, num, str } from '@shipfox/config';
+import { decodeBase64Key } from '#core/crypto.js';
+export const MAX_VALUE_BYTES = 64 * 1024;
+export const config = createConfig({
+    SECRETS_ENCRYPTION_KEK: str({
+        desc: 'Master key used to protect all stored secrets. Required. Generate a unique value per environment with openssl rand -base64 32 and provide it from a secret manager. The committed .env value is only for local development. Losing this key makes stored secrets unrecoverable. To rotate it, set SECRETS_ENCRYPTION_KEK_PREVIOUS to the old value during the rotation window.'
+    }),
+    SECRETS_ENCRYPTION_KEK_PREVIOUS: str({
+        desc: 'Previous master key used only while rotating stored secret data keys. Optional. Set it to the old SECRETS_ENCRYPTION_KEK value until rotation has completed.',
+        default: undefined
+    }),
+    SECRETS_MAX_PER_WORKSPACE: num({
+        desc: 'Maximum number of secrets and variables allowed per workspace across all project scopes and namespaces.',
+        default: 10000
+    }),
+    SECRETS_SHORT_VALUE_WARN_LENGTH: num({
+        desc: 'Secret values shorter than this many characters are classified for a write warning by management routes.',
+        default: 12
+    })
+});
+decodeBase64Key(config.SECRETS_ENCRYPTION_KEK, 'SECRETS_ENCRYPTION_KEK');
+if (config.SECRETS_ENCRYPTION_KEK_PREVIOUS) {
+    decodeBase64Key(config.SECRETS_ENCRYPTION_KEK_PREVIOUS, 'SECRETS_ENCRYPTION_KEK_PREVIOUS');
+}
+if (config.SECRETS_MAX_PER_WORKSPACE < 1) {
+    throw new Error('SECRETS_MAX_PER_WORKSPACE must be greater than 0.');
+}
+if (config.SECRETS_MAX_PER_WORKSPACE > SECRETS_MAX_LIST_LIMIT) {
+    // The settings UI lists the whole bounded set in one call (limit = SECRETS_MAX_LIST_LIMIT).
+    // A cap above that would let the list silently truncate, so fail fast instead.
+    throw new Error(`SECRETS_MAX_PER_WORKSPACE (${config.SECRETS_MAX_PER_WORKSPACE}) cannot exceed SECRETS_MAX_LIST_LIMIT (${SECRETS_MAX_LIST_LIMIT}).`);
+}
+if (config.SECRETS_SHORT_VALUE_WARN_LENGTH < 1) {
+    throw new Error('SECRETS_SHORT_VALUE_WARN_LENGTH must be greater than 0.');
+}
+
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/config.ts"],"sourcesContent":["import {SECRETS_MAX_LIST_LIMIT} from '@shipfox/api-secrets-dto';\nimport {createConfig, num, str} from '@shipfox/config';\nimport {decodeBase64Key} from '#core/crypto.js';\n\nexport const MAX_VALUE_BYTES = 64 * 1024;\n\nexport const config = createConfig({\n  SECRETS_ENCRYPTION_KEK: str({\n    desc: 'Master key used to protect all stored secrets. Required. Generate a unique value per environment with openssl rand -base64 32 and provide it from a secret manager. The committed .env value is only for local development. Losing this key makes stored secrets unrecoverable. To rotate it, set SECRETS_ENCRYPTION_KEK_PREVIOUS to the old value during the rotation window.',\n  }),\n  SECRETS_ENCRYPTION_KEK_PREVIOUS: str({\n    desc: 'Previous master key used only while rotating stored secret data keys. Optional. Set it to the old SECRETS_ENCRYPTION_KEK value until rotation has completed.',\n    default: undefined,\n  }),\n  SECRETS_MAX_PER_WORKSPACE: num({\n    desc: 'Maximum number of secrets and variables allowed per workspace across all project scopes and namespaces.',\n    default: 10000,\n  }),\n  SECRETS_SHORT_VALUE_WARN_LENGTH: num({\n    desc: 'Secret values shorter than this many characters are classified for a write warning by management routes.',\n    default: 12,\n  }),\n});\n\ndecodeBase64Key(config.SECRETS_ENCRYPTION_KEK, 'SECRETS_ENCRYPTION_KEK');\nif (config.SECRETS_ENCRYPTION_KEK_PREVIOUS) {\n  decodeBase64Key(config.SECRETS_ENCRYPTION_KEK_PREVIOUS, 'SECRETS_ENCRYPTION_KEK_PREVIOUS');\n}\nif (config.SECRETS_MAX_PER_WORKSPACE < 1) {\n  throw new Error('SECRETS_MAX_PER_WORKSPACE must be greater than 0.');\n}\nif (config.SECRETS_MAX_PER_WORKSPACE > SECRETS_MAX_LIST_LIMIT) {\n  // The settings UI lists the whole bounded set in one call (limit = SECRETS_MAX_LIST_LIMIT).\n  // A cap above that would let the list silently truncate, so fail fast instead.\n  throw new Error(\n    `SECRETS_MAX_PER_WORKSPACE (${config.SECRETS_MAX_PER_WORKSPACE}) cannot exceed SECRETS_MAX_LIST_LIMIT (${SECRETS_MAX_LIST_LIMIT}).`,\n  );\n}\nif (config.SECRETS_SHORT_VALUE_WARN_LENGTH < 1) {\n  throw new Error('SECRETS_SHORT_VALUE_WARN_LENGTH must be greater than 0.');\n}\n"],"names":["SECRETS_MAX_LIST_LIMIT","createConfig","num","str","decodeBase64Key","MAX_VALUE_BYTES","config","SECRETS_ENCRYPTION_KEK","desc","SECRETS_ENCRYPTION_KEK_PREVIOUS","default","undefined","SECRETS_MAX_PER_WORKSPACE","SECRETS_SHORT_VALUE_WARN_LENGTH","Error"],"mappings":"AAAA,SAAQA,sBAAsB,QAAO,2BAA2B;AAChE,SAAQC,YAAY,EAAEC,GAAG,EAAEC,GAAG,QAAO,kBAAkB;AACvD,SAAQC,eAAe,QAAO,kBAAkB;AAEhD,OAAO,MAAMC,kBAAkB,KAAK,KAAK;AAEzC,OAAO,MAAMC,SAASL,aAAa;IACjCM,wBAAwBJ,IAAI;QAC1BK,MAAM;IACR;IACAC,iCAAiCN,IAAI;QACnCK,MAAM;QACNE,SAASC;IACX;IACAC,2BAA2BV,IAAI;QAC7BM,MAAM;QACNE,SAAS;IACX;IACAG,iCAAiCX,IAAI;QACnCM,MAAM;QACNE,SAAS;IACX;AACF,GAAG;AAEHN,gBAAgBE,OAAOC,sBAAsB,EAAE;AAC/C,IAAID,OAAOG,+BAA+B,EAAE;IAC1CL,gBAAgBE,OAAOG,+BAA+B,EAAE;AAC1D;AACA,IAAIH,OAAOM,yBAAyB,GAAG,GAAG;IACxC,MAAM,IAAIE,MAAM;AAClB;AACA,IAAIR,OAAOM,yBAAyB,GAAGZ,wBAAwB;IAC7D,4FAA4F;IAC5F,+EAA+E;IAC/E,MAAM,IAAIc,MACR,CAAC,2BAA2B,EAAER,OAAOM,yBAAyB,CAAC,wCAAwC,EAAEZ,uBAAuB,EAAE,CAAC;AAEvI;AACA,IAAIM,OAAOO,+BAA+B,GAAG,GAAG;IAC9C,MAAM,IAAIC,MAAM;AAClB"}

package/dist/core/crypto.d.ts

@@ -0,0 +1,25 @@
+export interface AesGcmSealParams {
+    key: Buffer;
+    plaintext: Buffer;
+    aad: string;
+}
+export interface AesGcmOpenParams {
+    key: Buffer;
+    encoded: string;
+    aad: string;
+}
+export interface SecretScope {
+    projectId?: string | null | undefined;
+}
+export interface SecretValueAadParams {
+    workspaceId: string;
+    scope?: SecretScope | undefined;
+    namespace: string;
+    key: string;
+}
+export declare function aesGcmSeal(params: AesGcmSealParams): string;
+export declare function aesGcmOpen(params: AesGcmOpenParams): Buffer;
+export declare function decodeBase64Key(encoded: string | undefined, label: string): Buffer;
+export declare function aadForDek(workspaceId: string, kekVersion: string): string;
+export declare function aadForValue(params: SecretValueAadParams): string;
+//# sourceMappingURL=crypto.d.ts.map

package/dist/core/crypto.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"crypto.d.ts","sourceRoot":"","sources":["../../src/core/crypto.ts"],"names":[],"mappings":"AAWA,MAAM,WAAW,gBAAgB;IAC/B,GAAG,EAAE,MAAM,CAAC;IACZ,SAAS,EAAE,MAAM,CAAC;IAClB,GAAG,EAAE,MAAM,CAAC;CACb;AAED,MAAM,WAAW,gBAAgB;IAC/B,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC;IAChB,GAAG,EAAE,MAAM,CAAC;CACb;AAED,MAAM,WAAW,WAAW;IAC1B,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;CACvC;AAED,MAAM,WAAW,oBAAoB;IACnC,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,WAAW,GAAG,SAAS,CAAC;IAChC,SAAS,EAAE,MAAM,CAAC;IAClB,GAAG,EAAE,MAAM,CAAC;CACb;AAED,wBAAgB,UAAU,CAAC,MAAM,EAAE,gBAAgB,GAAG,MAAM,CAS3D;AAED,wBAAgB,UAAU,CAAC,MAAM,EAAE,gBAAgB,GAAG,MAAM,CA4B3D;AAED,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAelF;AAED,wBAAgB,SAAS,CAAC,WAAW,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,CAEzE;AAED,wBAAgB,WAAW,CAAC,MAAM,EAAE,oBAAoB,GAAG,MAAM,CAIhE"}

package/dist/core/crypto.js

@@ -0,0 +1,85 @@
+import crypto from 'node:crypto';
+import { KekConfigurationError, SecretDecryptionError } from './errors.js';
+const CIPHER = 'aes-256-gcm';
+const ENCODED_PREFIX = 'v1:';
+const IV_BYTES = 12;
+const AUTH_TAG_BYTES = 16;
+const KEY_BYTES = 32;
+const BASE64_KEY_PATTERN = /^[A-Za-z0-9+/]+={0,2}$/;
+const BASE64_PADDING_SUFFIX = /=+$/;
+export function aesGcmSeal(params) {
+    const iv = crypto.randomBytes(IV_BYTES);
+    const cipher = crypto.createCipheriv(CIPHER, params.key, iv);
+    cipher.setAAD(Buffer.from(params.aad, 'utf8'));
+    const ciphertext = Buffer.concat([
+        cipher.update(params.plaintext),
+        cipher.final()
+    ]);
+    const authTag = cipher.getAuthTag();
+    return `${ENCODED_PREFIX}${Buffer.concat([
+        iv,
+        authTag,
+        ciphertext
+    ]).toString('base64')}`;
+}
+export function aesGcmOpen(params) {
+    if (!params.encoded.startsWith(ENCODED_PREFIX)) throw new SecretDecryptionError();
+    const encodedPayload = params.encoded.slice(ENCODED_PREFIX.length);
+    const payload = Buffer.from(encodedPayload, 'base64');
+    const canonical = payload.toString('base64');
+    if (!BASE64_KEY_PATTERN.test(encodedPayload) || canonical.replace(BASE64_PADDING_SUFFIX, '') !== encodedPayload.replace(BASE64_PADDING_SUFFIX, '')) {
+        throw new SecretDecryptionError();
+    }
+    if (payload.length < IV_BYTES + AUTH_TAG_BYTES) throw new SecretDecryptionError();
+    try {
+        const iv = payload.subarray(0, IV_BYTES);
+        const authTag = payload.subarray(IV_BYTES, IV_BYTES + AUTH_TAG_BYTES);
+        const ciphertext = payload.subarray(IV_BYTES + AUTH_TAG_BYTES);
+        const decipher = crypto.createDecipheriv(CIPHER, params.key, iv);
+        decipher.setAAD(Buffer.from(params.aad, 'utf8'));
+        decipher.setAuthTag(authTag);
+        return Buffer.concat([
+            decipher.update(ciphertext),
+            decipher.final()
+        ]);
+    } catch (error) {
+        if (error instanceof SecretDecryptionError) throw error;
+        throw new SecretDecryptionError();
+    }
+}
+export function decodeBase64Key(encoded, label) {
+    if (!encoded) {
+        throw new KekConfigurationError(`${label} is required and must be a base64-encoded 32-byte key. Generate one with openssl rand -base64 32.`);
+    }
+    const key = Buffer.from(encoded, 'base64');
+    if (key.length !== KEY_BYTES || !isCanonicalBase64Key(encoded, key)) {
+        throw new KekConfigurationError(`${label} must be a canonical base64-encoded 32-byte key. Strip whitespace and generate a new value with openssl rand -base64 32 if needed.`);
+    }
+    return key;
+}
+export function aadForDek(workspaceId, kekVersion) {
+    return JSON.stringify([
+        workspaceId,
+        kekVersion
+    ]);
+}
+export function aadForValue(params) {
+    const projectId = params.scope?.projectId ?? null;
+    const scopeTuple = projectId !== null ? [
+        'project',
+        projectId
+    ] : [
+        'workspace'
+    ];
+    return JSON.stringify([
+        params.workspaceId,
+        scopeTuple,
+        params.namespace,
+        params.key
+    ]);
+}
+function isCanonicalBase64Key(encoded, key) {
+    return BASE64_KEY_PATTERN.test(encoded) && key.toString('base64') === encoded;
+}
+
+//# sourceMappingURL=crypto.js.map

package/dist/core/crypto.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/core/crypto.ts"],"sourcesContent":["import crypto from 'node:crypto';\nimport {KekConfigurationError, SecretDecryptionError} from './errors.js';\n\nconst CIPHER = 'aes-256-gcm';\nconst ENCODED_PREFIX = 'v1:';\nconst IV_BYTES = 12;\nconst AUTH_TAG_BYTES = 16;\nconst KEY_BYTES = 32;\nconst BASE64_KEY_PATTERN = /^[A-Za-z0-9+/]+={0,2}$/;\nconst BASE64_PADDING_SUFFIX = /=+$/;\n\nexport interface AesGcmSealParams {\n  key: Buffer;\n  plaintext: Buffer;\n  aad: string;\n}\n\nexport interface AesGcmOpenParams {\n  key: Buffer;\n  encoded: string;\n  aad: string;\n}\n\nexport interface SecretScope {\n  projectId?: string | null | undefined;\n}\n\nexport interface SecretValueAadParams {\n  workspaceId: string;\n  scope?: SecretScope | undefined;\n  namespace: string;\n  key: string;\n}\n\nexport function aesGcmSeal(params: AesGcmSealParams): string {\n  const iv = crypto.randomBytes(IV_BYTES);\n  const cipher = crypto.createCipheriv(CIPHER, params.key, iv);\n  cipher.setAAD(Buffer.from(params.aad, 'utf8'));\n\n  const ciphertext = Buffer.concat([cipher.update(params.plaintext), cipher.final()]);\n  const authTag = cipher.getAuthTag();\n\n  return `${ENCODED_PREFIX}${Buffer.concat([iv, authTag, ciphertext]).toString('base64')}`;\n}\n\nexport function aesGcmOpen(params: AesGcmOpenParams): Buffer {\n  if (!params.encoded.startsWith(ENCODED_PREFIX)) throw new SecretDecryptionError();\n\n  const encodedPayload = params.encoded.slice(ENCODED_PREFIX.length);\n  const payload = Buffer.from(encodedPayload, 'base64');\n  const canonical = payload.toString('base64');\n  if (\n    !BASE64_KEY_PATTERN.test(encodedPayload) ||\n    canonical.replace(BASE64_PADDING_SUFFIX, '') !==\n      encodedPayload.replace(BASE64_PADDING_SUFFIX, '')\n  ) {\n    throw new SecretDecryptionError();\n  }\n  if (payload.length < IV_BYTES + AUTH_TAG_BYTES) throw new SecretDecryptionError();\n\n  try {\n    const iv = payload.subarray(0, IV_BYTES);\n    const authTag = payload.subarray(IV_BYTES, IV_BYTES + AUTH_TAG_BYTES);\n    const ciphertext = payload.subarray(IV_BYTES + AUTH_TAG_BYTES);\n    const decipher = crypto.createDecipheriv(CIPHER, params.key, iv);\n    decipher.setAAD(Buffer.from(params.aad, 'utf8'));\n    decipher.setAuthTag(authTag);\n\n    return Buffer.concat([decipher.update(ciphertext), decipher.final()]);\n  } catch (error) {\n    if (error instanceof SecretDecryptionError) throw error;\n    throw new SecretDecryptionError();\n  }\n}\n\nexport function decodeBase64Key(encoded: string | undefined, label: string): Buffer {\n  if (!encoded) {\n    throw new KekConfigurationError(\n      `${label} is required and must be a base64-encoded 32-byte key. Generate one with openssl rand -base64 32.`,\n    );\n  }\n\n  const key = Buffer.from(encoded, 'base64');\n  if (key.length !== KEY_BYTES || !isCanonicalBase64Key(encoded, key)) {\n    throw new KekConfigurationError(\n      `${label} must be a canonical base64-encoded 32-byte key. Strip whitespace and generate a new value with openssl rand -base64 32 if needed.`,\n    );\n  }\n\n  return key;\n}\n\nexport function aadForDek(workspaceId: string, kekVersion: string): string {\n  return JSON.stringify([workspaceId, kekVersion]);\n}\n\nexport function aadForValue(params: SecretValueAadParams): string {\n  const projectId = params.scope?.projectId ?? null;\n  const scopeTuple = projectId !== null ? ['project', projectId] : ['workspace'];\n  return JSON.stringify([params.workspaceId, scopeTuple, params.namespace, params.key]);\n}\n\nfunction isCanonicalBase64Key(encoded: string, key: Buffer): boolean {\n  return BASE64_KEY_PATTERN.test(encoded) && key.toString('base64') === encoded;\n}\n"],"names":["crypto","KekConfigurationError","SecretDecryptionError","CIPHER","ENCODED_PREFIX","IV_BYTES","AUTH_TAG_BYTES","KEY_BYTES","BASE64_KEY_PATTERN","BASE64_PADDING_SUFFIX","aesGcmSeal","params","iv","randomBytes","cipher","createCipheriv","key","setAAD","Buffer","from","aad","ciphertext","concat","update","plaintext","final","authTag","getAuthTag","toString","aesGcmOpen","encoded","startsWith","encodedPayload","slice","length","payload","canonical","test","replace","subarray","decipher","createDecipheriv","setAuthTag","error","decodeBase64Key","label","isCanonicalBase64Key","aadForDek","workspaceId","kekVersion","JSON","stringify","aadForValue","projectId","scope","scopeTuple","namespace"],"mappings":"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"}

package/dist/core/dek-manager.d.ts

@@ -0,0 +1,16 @@
+import type { KeyProvider } from './key-provider.js';
+/**
+ * Plaintext DEKs live in memory by design so hot secret reads avoid unwrapping on
+ * every access. Node cannot reliably zeroize Buffers, so residency is bounded by
+ * LRU size and lazy TTL instead of pretending wipes are a complete mitigation.
+ */
+export declare class DekManager {
+    #private;
+    constructor(keyProvider: KeyProvider, options: {
+        maxEntries: number;
+        ttlMs: number;
+    });
+    getPlaintextDek(workspaceId: string): Promise<Buffer>;
+    invalidate(workspaceId: string): void;
+}
+//# sourceMappingURL=dek-manager.d.ts.map

package/dist/core/dek-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dek-manager.d.ts","sourceRoot":"","sources":["../../src/core/dek-manager.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAC,WAAW,EAAC,MAAM,mBAAmB,CAAC;AAInD;;;;GAIG;AACH,qBAAa,UAAU;;gBAKT,WAAW,EAAE,WAAW,EAAE,OAAO,EAAE;QAAC,UAAU,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAC;IAK5E,eAAe,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IA4D3D,UAAU,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI;CAetC"}

package/dist/core/dek-manager.js

@@ -0,0 +1,85 @@
+import crypto from 'node:crypto';
+import { getDataKey, insertDataKeyIfAbsent } from '#db/index.js';
+import { classifyDekAccessError, recordSecretsDekAccess } from '#metrics/instance.js';
+const DEK_BYTES = 32;
+/**
+ * Plaintext DEKs live in memory by design so hot secret reads avoid unwrapping on
+ * every access. Node cannot reliably zeroize Buffers, so residency is bounded by
+ * LRU size and lazy TTL instead of pretending wipes are a complete mitigation.
+ */ export class DekManager {
+    #cache;
+    #keyProvider;
+    #options;
+    constructor(keyProvider, options){
+        this.#cache = new Map();
+        this.#keyProvider = keyProvider;
+        this.#options = options;
+    }
+    async getPlaintextDek(workspaceId) {
+        const startedAt = Date.now();
+        try {
+            const cached = this.#cache.get(workspaceId);
+            if (cached && cached.expiresAt > Date.now()) {
+                this.#cache.delete(workspaceId);
+                this.#cache.set(workspaceId, cached);
+                recordSecretsDekAccess({
+                    outcome: 'cache_hit',
+                    durationMs: Date.now() - startedAt
+                });
+                return Buffer.from(cached.dek);
+            }
+            const hadExpiredCache = Boolean(cached);
+            if (cached) this.#cache.delete(workspaceId);
+            const existing = await getDataKey(workspaceId);
+            if (existing) {
+                const dek = this.#keyProvider.unwrapDek(workspaceId, existing.wrappedDek, existing.kekVersion);
+                this.#set(workspaceId, dek);
+                recordSecretsDekAccess({
+                    outcome: hadExpiredCache ? 'cache_expired' : 'db_unwrapped',
+                    durationMs: Date.now() - startedAt
+                });
+                return Buffer.from(dek);
+            }
+            const generatedDek = crypto.randomBytes(DEK_BYTES);
+            const wrapped = this.#keyProvider.wrapDek(workspaceId, generatedDek);
+            const inserted = await insertDataKeyIfAbsent({
+                workspaceId,
+                wrappedDek: wrapped.wrappedDek,
+                kekVersion: wrapped.kekVersion
+            });
+            // The DEK row commits before value writes. If concurrent first-use inserts race,
+            // the primary key decides the winner and every caller re-reads the persisted row.
+            const persisted = await getDataKey(workspaceId);
+            if (!persisted) throw new Error(`Data key was not persisted for workspace ${workspaceId}`);
+            const dek = this.#keyProvider.unwrapDek(workspaceId, persisted.wrappedDek, persisted.kekVersion);
+            this.#set(workspaceId, dek);
+            recordSecretsDekAccess({
+                outcome: inserted ? 'generated' : 'db_unwrapped',
+                durationMs: Date.now() - startedAt
+            });
+            return Buffer.from(dek);
+        } catch (error) {
+            recordSecretsDekAccess({
+                outcome: classifyDekAccessError(error),
+                durationMs: Date.now() - startedAt
+            });
+            throw error;
+        }
+    }
+    invalidate(workspaceId) {
+        this.#cache.delete(workspaceId);
+    }
+    #set(workspaceId, dek) {
+        this.#cache.set(workspaceId, {
+            dek: Buffer.from(dek),
+            expiresAt: Date.now() + this.#options.ttlMs
+        });
+        while(this.#cache.size > this.#options.maxEntries){
+            const oldest = this.#cache.keys().next().value;
+            if (!oldest) break;
+            this.#cache.delete(oldest);
+        }
+    }
+}
+
+//# sourceMappingURL=dek-manager.js.map