@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 +42 -0
- package/dist/adapters/custody-database.d.ts +21 -0
- package/dist/adapters/custody-database.d.ts.map +1 -0
- package/dist/index.d.ts +1 -0
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +1921 -1584
- package/dist/index.js.map +1 -1
- package/dist/shared/custody-schema.d.ts +9 -0
- package/dist/shared/custody-schema.d.ts.map +1 -0
- package/dist/shared/custody.d.ts +8 -0
- package/dist/shared/custody.d.ts.map +1 -1
- package/package.json +3 -3
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';
|
package/dist/index.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;
|
|
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"}
|