@happyvertical/secrets 0.107.0 → 0.109.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -358,3 +358,45 @@ and redacted details; underlying provider causes are intentionally not retained.
358
358
  ## License
359
359
 
360
360
  MIT
361
+
362
+ ### Durable custody recovery with SQLite
363
+
364
+ `DatabaseCustodyLedger` persists receipt and lifecycle metadata in an existing
365
+ SDK SQL database. It is validated with local SQLite on Node.js 24+. Keep this
366
+ runtime database outside Git and outside your encrypted credential file; secret
367
+ values continue to belong to the configured secret sink/finalizer.
368
+
369
+ ```typescript
370
+ import { getDatabase } from '@happyvertical/sql';
371
+ import { DatabaseCustodyLedger } from '@happyvertical/secrets';
372
+
373
+ // Provision a current-user-owned 0700 runtime parent first.
374
+ const db = await getDatabase({
375
+ type: 'sqlite',
376
+ url: '/private/runtime/custody.sqlite',
377
+ secureFile: { driver: 'node:sqlite', custody: 'trusted-parent' },
378
+ });
379
+ const ledger = new DatabaseCustodyLedger({ db, ledgerId: 'operator' });
380
+ await ledger.initialize();
381
+ // Pass ledger to CredentialCustody; the caller owns the database lifetime.
382
+ ```
383
+
384
+ Initialization creates a versioned state row per `ledgerId` and validates any
385
+ existing history. Each mutation reads and validates that history, applies the
386
+ same transition checks as `InMemoryCustodyLedger`, then atomically updates the
387
+ row with a revision comparison inside the supplied database transaction. A fresh
388
+ process can list the original receipts and events and run custody recovery.
389
+ Concurrent writers either commit against the current revision or fail; retry
390
+ failed/busy writes after reloading. Exact event retries are idempotent, while
391
+ conflicting event IDs and changed issuance followups fail before mutation. The
392
+ original followup association, including its absence, survives reload. Every
393
+ proposed mutation must replay successfully before it can be committed.
394
+
395
+ Malformed or unsupported state fails closed; initialization never resets an
396
+ existing ledger. Snapshot validation rejects unknown fields, non-data objects
397
+ (including `SecretMaterial`), malformed public fields and recognized credential
398
+ text. All text fields are limited to 4096 characters. Receipt metadata must
399
+ contain only nonsecret strings: arbitrary opaque secrets cannot be distinguished
400
+ from legitimate identifiers. Signatures are preserved as public receipt data;
401
+ ledger loading does not replace receipt attestation verification. Retain the
402
+ private database for recovery and audit; this adapter does not compact history.
@@ -0,0 +1,21 @@
1
+ import type { DatabaseInterface } from '@happyvertical/sql';
2
+ import { type CustodyEvent, type CustodyLedger, type CustodyReceipt } from '../shared/custody.js';
3
+ /**
4
+ * Durable runtime metadata ledger. Validated with the SDK SQLite adapter.
5
+ * Use secureFile trusted-parent acquisition beneath a private runtime directory.
6
+ * The supplied database remains owned by the caller. No credential is stored.
7
+ */
8
+ export declare class DatabaseCustodyLedger implements CustodyLedger {
9
+ #private;
10
+ constructor(options: {
11
+ db: DatabaseInterface;
12
+ ledgerId?: string;
13
+ });
14
+ initialize(): Promise<void>;
15
+ recordIssuance(receipt: CustodyReceipt, event: CustodyEvent): Promise<void>;
16
+ commitIssuance(receiptId: string, event: CustodyEvent, followup?: CustodyEvent): Promise<void>;
17
+ appendEvent(event: CustodyEvent): Promise<void>;
18
+ listReceipts(): Promise<CustodyReceipt[]>;
19
+ listEvents(): Promise<CustodyEvent[]>;
20
+ }
21
+ //# sourceMappingURL=custody-database.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"custody-database.d.ts","sourceRoot":"","sources":["../../src/adapters/custody-database.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAC5D,OAAO,EAEL,KAAK,YAAY,EAEjB,KAAK,aAAa,EAClB,KAAK,cAAc,EAGpB,MAAM,sBAAsB,CAAC;AAU9B;;;;GAIG;AACH,qBAAa,qBAAsB,YAAW,aAAa;;gBAK7C,OAAO,EAAE;QAAE,EAAE,EAAE,iBAAiB,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE;IAe3D,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAsK3B,cAAc,CAClB,OAAO,EAAE,cAAc,EACvB,KAAK,EAAE,YAAY,GAClB,OAAO,CAAC,IAAI,CAAC;IAaV,cAAc,CAClB,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,YAAY,EACnB,QAAQ,CAAC,EAAE,YAAY,GACtB,OAAO,CAAC,IAAI,CAAC;IAYV,WAAW,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC;IAU/C,YAAY,IAAI,OAAO,CAAC,cAAc,EAAE,CAAC;IAKzC,UAAU,IAAI,OAAO,CAAC,YAAY,EAAE,CAAC;CAI5C"}
package/dist/index.d.ts CHANGED
@@ -35,6 +35,7 @@
35
35
  *
36
36
  * @packageDocumentation
37
37
  */
38
+ export { DatabaseCustodyLedger } from './adapters/custody-database.js';
38
39
  export { DatabaseSecretStore } from './adapters/database.js';
39
40
  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';
40
41
  export { CredentialCustody, CustodyError, Ed25519CustodyReceiptAttestor, InMemoryCustodyLedger, redactCredentialText, redactCredentialValues, runCredentialChildProcess, SecretMaterial, verifyCustodyReceiptAttestation, withEnvironmentSecret, } from './shared/custody.js';
@@ -1 +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;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"}
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAEH,OAAO,EAAE,qBAAqB,EAAE,MAAM,gCAAgC,CAAC;AAEvE,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"}