@happyvertical/secrets 0.87.0 → 0.88.0

package/README.md

@@ -55,11 +55,11 @@ const store = await getSecretStore({
 await store.createTenantKey('tenant-123');
 
 // Encrypt a secret
-const envelope = await store.encrypt('tenant-123', 'api-key', 'sk_live_xxx');
+const envelope = await store.encrypt('tenant-123', 'api-key', 'synthetic-secret');
 
 // Decrypt the secret
 const { value } = await store.decrypt('tenant-123', envelope);
-console.log(value); // 'sk_live_xxx'
+// Use value without logging or retaining plaintext.
 ```
 
 ## Core Concepts
@@ -215,6 +215,146 @@ try {
 }
 ```
 
+## Credential custody orchestration
+
+`CredentialCustody` coordinates a provider-neutral issuer, verifier, optional
+secret sink, and receipt ledger. It supports two explicit modes:
+
+- `ephemeral` keeps opaque `SecretMaterial` in memory for a bounded lifetime,
+  automatically revokes it at expiry, and never stores it in a sink.
+- `durable` requires a `CredentialSecretSink`, then completes
+  issue → store → retrieve → verify before returning a lease. Any failure
+  removes the stored value when present and revokes the issued credential.
+
+```typescript
+import {
+  CredentialCustody,
+  type CredentialReceiptAttestor,
+  type CredentialIssuer,
+  type CredentialCustodyFinalizer,
+  type CredentialSecretSink,
+  type CredentialVerifier,
+  type CustodyLedger,
+} from '@happyvertical/secrets';
+
+const custody = new CredentialCustody({
+  issuer: myIssuer satisfies CredentialIssuer,
+  verifier: myVerifier satisfies CredentialVerifier,
+  sink: mySink satisfies CredentialSecretSink,
+  ledger: myLedger satisfies CustodyLedger,
+  attestor: myAttestor satisfies CredentialReceiptAttestor,
+  finalizer: myFinalizer satisfies CredentialCustodyFinalizer,
+});
+
+const lease = await custody.issue({
+  mode: 'durable',
+  subject: 'deployment-agent',
+  attribution: {
+    actor: 'automation',
+    runtime: 'scheduler',
+    session: 'job-123',
+  },
+  metadata: { purpose: 'repository-maintenance' },
+});
+
+await lease.withEnvironment('SERVICE_CREDENTIAL', async () => {
+  // The variable exists only for this callback and is restored afterward.
+  await runAuthenticatedOperation();
+});
+
+const child = await lease.withChildProcess({
+  trust: 'cooperative-process-group',
+  command: 'service-cli',
+  args: ['verify'],
+  environmentVariable: 'SERVICE_CREDENTIAL',
+  timeoutMs: 30_000,
+});
+```
+
+The returned `CustodyReceipt` contains identifiers, attribution, verification
+state, sink reference, rotation lineage, and an Ed25519 attestation only.
+Plaintext is represented by
+`SecretMaterial`, whose string, JSON, and inspection forms are always redacted.
+Adapters can access it only inside `SecretMaterial.use(...)` and should avoid
+copying or retaining the supplied string. Both `SecretMaterial.use(...)` and
+`withEnvironment(...)` return `Promise<void>` so callback code cannot return
+plaintext through the custody API. Environment callbacks are serialized and
+always restore the prior value. Because JavaScript callbacks cannot be forcibly
+cancelled, expiring credentials fail closed for `withEnvironment(...)`; use
+`withChildProcess(...)` for bounded execution.
+
+Attestation binds every receipt field—including the stable sink tuple
+`sinkName`, `reference`, `version`, and `storedAt`—to an internal SHA-256
+commitment of the credential. The commitment is signed but is not included in
+the receipt. `CredentialCustodyOptions.attestor` is required, so unsigned
+issuance fails closed. `Ed25519CustodyReceiptAttestor` accepts a Node `KeyObject`
+private key; remote signers can implement `CredentialReceiptAttestor` without
+exposing their key.
+
+Consumers verify a presented credential without issuer or sink access by
+constructing its `SecretMaterial` and calling
+`verifyCustodyReceiptAttestation(receipt, material, publicKey)`. Resolve
+`receipt.attestation.keyId` only through trusted configuration, never from
+receipt-supplied key material. Import a trusted PEM/SPKI public key with Node's
+`createPublicKey(...)`; verification requires the resulting public `KeyObject`.
+Always destroy the temporary `SecretMaterial` after verification.
+
+The required `CredentialCustodyFinalizer` is a staged, idempotent transaction.
+The signed receipt is first recorded as `finalization-pending`; `prepare` then
+receives it with bounded `SecretMaterial`. The receipt binds the finalizer name
+and SDK-generated `finalizationId`. `commit` activates the prepared record, and
+the ledger atomically marks it issued while recording any predecessor cleanup.
+Only then does rotation retire the predecessor. Cleanup failure keeps the new
+credential active and is retried by `recoverPendingRollbacks()`. The finalizer's
+`status` resolves crash ambiguity; `abort` and issuer/sink cleanup run
+independently. Implement `prepare`, `commit`, `abort`, and `status` idempotently
+by `finalizationId`. Fresh pending transactions are protected from concurrent
+takeover for `finalizationTakeoverMs` (30 seconds by default); a one-shot
+recovery call schedules takeover automatically at that deadline.
+
+Prefer `withChildProcess(...)` for trusted command-line consumers. It requires
+the explicit `trust: 'cooperative-process-group'` acknowledgement, injects the
+credential into the child environment without mutating the parent, disables
+shell interpretation, bounds runtime and captured output, owns a detached
+process group so descendants are terminated, confirms that group is gone
+before returning, and exact/token-redacts stdout and stderr. The trusted
+command and every credential-bearing descendant must remain in that group;
+daemonizing, calling `setsid`, or spawning a detached child violates this
+boundary because portable POSIX process groups cannot contain a process that
+creates a new session. Use only audited executables that honor this contract.
+Process-group custody fails closed on Windows, where the required POSIX group
+semantics are unavailable. If group cleanup cannot be verified, the lease is
+immediately invalidated and finalizer/issuer/sink cleanup runs through the same
+persisted, restart-safe rollback path used by failed issuance.
+
+Use `rotate(receiptId, request)` to issue and verify a replacement before
+retiring its predecessor. `reconcile()` compares active durable receipts with
+the sink inventory; `recoverOrphans(report)` removes unowned sink records while
+retaining attributable history in the ledger. Missing records can be replaced
+through `rotate`, preserving `replacesReceiptId` and `rotationRootReceiptId`.
+The ledger's `recordIssuance` operation atomically persists the receipt with a
+`finalization-pending` event and rejects duplicate or branching replacements.
+`commitIssuance` idempotently appends the `issued` event and, for rotation, the
+`retirement-pending` event in the same transaction. Issuer revocation
+and exact-version sink removal must be idempotent so failed cleanup can retry.
+`appendEvent` is idempotent by `eventId`: exact replay succeeds, while binding
+the same identifier to different content fails closed.
+Transient finalizer-status or ledger-commit errors retain
+`finalization-pending` state and retry ambiguity resolution; only an explicit
+non-committed finalizer status triggers rollback. Sink identity comparison uses
+the full attested `sinkName`, `reference`, `version`, and `storedAt` tuple.
+Sinks must also implement idempotent `removeByCredentialId(...)` for ambiguous
+store failures, and every inventory entry must identify its credential.
+Orphan recovery re-runs reconciliation and applies a configurable age grace
+before deleting an unchanged sink version. Failed pre-receipt rollback records a
+non-secret pending event, retries automatically, and can be resumed after a
+restart with `recoverPendingRollbacks()`.
+
+`redactCredentialText` and `redactCredentialValues` remove common bearer-token
+shapes and known plaintext values from strings, structured outputs, errors, and
+metadata. `CustodyError` serializes only its safe code, stage, redacted message,
+and redacted details; underlying provider causes are intentionally not retained.
+
 ## License
 
 MIT

package/dist/adapters/database.d.ts

@@ -22,7 +22,7 @@ import { ApplicationMasterKey, DatabaseSecretStoreOptions, DecryptedSecret, Encr
  * await store.initialize();
  *
  * // Encrypt a secret for a tenant
- * const envelope = await store.encrypt('tenant-123', 'api-key', 'sk_live_xxx');
+ * const envelope = await store.encrypt('tenant-123', 'api-key', 'synthetic-secret');
  *
  * // Decrypt
  * const { value } = await store.decrypt('tenant-123', envelope);

package/dist/index.d.ts

@@ -23,11 +23,11 @@
  * });
  *
  * // Encrypt a secret for a tenant
- * const envelope = await store.encrypt('tenant-123', 'api-key', 'sk_live_xxx');
+ * const envelope = await store.encrypt('tenant-123', 'api-key', 'synthetic-secret');
  *
  * // Decrypt the secret
  * const { value } = await store.decrypt('tenant-123', envelope);
- * console.log(value); // 'sk_live_xxx'
+ * // Use value without logging or retaining plaintext.
  *
  * // Rotate tenant's encryption key
  * await store.rotateTenantKey('tenant-123');
@@ -36,6 +36,8 @@
  * @packageDocumentation
  */
 export { DatabaseSecretStore } from './adapters/database.js';
+export type { CredentialChildProcessOptions, CredentialChildProcessResult, CredentialCustodyFinalizer, CredentialCustodyOptions, CredentialIssuanceMode, CredentialIssueRequest, CredentialIssuer, CredentialLease, CredentialReceiptAttestor, CredentialSecretSink, CredentialVerifier, CustodyAttribution, CustodyEvent, CustodyEventType, CustodyIssuanceRequest, CustodyLedger, CustodyReceipt, CustodyReceiptAttestation, CustodyReconciliation, CustodyStage, IssuedCredential, SecretSinkInventoryEntry, SecretSinkRecord, } from './shared/custody.js';
+export { CredentialCustody, CustodyError, Ed25519CustodyReceiptAttestor, InMemoryCustodyLedger, redactCredentialText, redactCredentialValues, runCredentialChildProcess, SecretMaterial, verifyCustodyReceiptAttestation, withEnvironmentSecret, } from './shared/custody.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';

package/dist/index.d.ts.map

@@ -1 +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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAGH,OAAO,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AAC7D,YAAY,EACV,6BAA6B,EAC7B,4BAA4B,EAC5B,0BAA0B,EAC1B,wBAAwB,EACxB,sBAAsB,EACtB,sBAAsB,EACtB,gBAAgB,EAChB,eAAe,EACf,yBAAyB,EACzB,oBAAoB,EACpB,kBAAkB,EAClB,kBAAkB,EAClB,YAAY,EACZ,gBAAgB,EAChB,sBAAsB,EACtB,aAAa,EACb,cAAc,EACd,yBAAyB,EACzB,qBAAqB,EACrB,YAAY,EACZ,gBAAgB,EAChB,wBAAwB,EACxB,gBAAgB,GACjB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACL,iBAAiB,EACjB,YAAY,EACZ,6BAA6B,EAC7B,qBAAqB,EACrB,oBAAoB,EACpB,sBAAsB,EACtB,yBAAyB,EACzB,cAAc,EACd,+BAA+B,EAC/B,qBAAqB,GACtB,MAAM,qBAAqB,CAAC;AAE7B,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;AAE5B,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"}