@degenerate/generic 0.2.7 → 0.4.0

package/dist/models/share-data/share-data-persistence-models.d.ts

@@ -0,0 +1,165 @@
+import z from 'zod';
+import { EllipticalCurvesSigning } from '../../_settings/cryptography-settings';
+import { ShareBlockType } from '../shareblock/shareblock-models';
+/**
+ * The signing curve a persisted block was created with. Mirrors the values of
+ * {@link EllipticalCurvesSigning}; stored for forward-compatibility even
+ * though every shipped factory currently uses the `Curve25519` default.
+ */
+export declare const PersistedSigningCurveSchema: z.ZodEnum<{
+    ed25519: EllipticalCurvesSigning.Curve25519;
+    p521: EllipticalCurvesSigning.P521;
+}>;
+/**
+ * The factory creation input needed to replay construction, minus the
+ * `proofFor` callback (which is reconstructed from the stored
+ * `structuralProofs` + `initialCrypto` at load time). `initialState` is the
+ * *partial* state the factory was given — the factory deterministically
+ * assembles the full state from it, so storing the partial form is both
+ * sufficient and forward-stable.
+ */
+export declare const PersistedCreationConfigSchema: z.ZodObject<{
+    metadata: z.ZodObject<{
+        shareBlockId: z.ZodString;
+        blockType: z.ZodEnum<{
+            Clearing: "Clearing";
+            Funding: "Funding";
+            Distribution: "Distribution";
+            GraceRepayment: "GraceRepayment";
+        }>;
+        relatedLoanApplicationId: z.ZodOptional<z.ZodString>;
+        description: z.ZodOptional<z.ZodString>;
+        createdAt: z.ZodNumber;
+        createdBy: z.ZodString;
+    }, z.core.$strip>;
+    creationPublicKey: z.ZodString;
+    initialState: z.ZodRecord<z.ZodString, z.ZodAny>;
+}, z.core.$strip>;
+export type PersistedCreationConfig = z.infer<typeof PersistedCreationConfigSchema>;
+/**
+ * The two facts a {@link ShareDataManager} must retain about a block to keep
+ * persisting it after creation: which factory built it and the creation input
+ * that factory was given. A live block retains neither — `serializeShareData`
+ * needs both supplied — so the manager captures them at `addShareData` time and
+ * carries them alongside the accumulating transaction log for every subsequent
+ * write-through. Supplied by the caller that created the block (e.g. the HTTP
+ * create route).
+ */
+export interface ShareDataCreationRecord {
+    blockType: ShareBlockType;
+    creationConfig: PersistedCreationConfig;
+}
+/**
+ * One post-creation transaction, captured at apply time. The live
+ * `transactionHistory` does NOT retain a transaction's input or proposed
+ * state, so these must be recorded when the transaction is applied rather
+ * than recovered from a finished block.
+ *
+ *   - `functionId` re-resolves the live function on the rebuilt block (same
+ *     id-based lookup `createIdBasedFunctionResolver` uses).
+ *   - `proposedState` is the state written when the transaction was accepted;
+ *     it is what replay re-applies.
+ *   - `proof` is the transaction proposal proof that authorized the change. It
+ *     is re-verified against the rebuilt block + `proposedState` during replay,
+ *     so a snapshot whose proposed state or proof was edited fails the load.
+ *     Recording it also keeps the rebuilt block byte-faithful: the live history
+ *     entry carries its proof, and the canonical share-data hash folds the
+ *     history in, so replay must reproduce the proof to hash identically.
+ *   - `transactionTime` is stored so the replayed history hashes identically.
+ *   - `ruleOutcome` records whether the original proposal was accepted.
+ */
+export declare const PersistedTransactionSchema: z.ZodObject<{
+    functionId: z.ZodString;
+    input: z.ZodOptional<z.ZodAny>;
+    proposedState: z.ZodRecord<z.ZodString, z.ZodAny>;
+    proof: z.ZodObject<{
+        publicKey: z.ZodString;
+        shareDataHash: z.ZodString;
+        shareDataPreviousHash: z.ZodString;
+        shareDataSignature: z.ZodString;
+        timestamp: z.ZodNumber;
+        purpose: z.ZodString;
+    }, z.core.$strip>;
+    transactionTime: z.ZodNumber;
+    ruleOutcome: z.ZodBoolean;
+}, z.core.$strip>;
+export type PersistedTransaction = z.infer<typeof PersistedTransactionSchema>;
+/**
+ * A durable snapshot of a ShareData. Versioned via `schemaVersion` so a future
+ * format change can be gated cleanly. The `expected*` fields are NOT trusted
+ * on load — they are cross-checked against the independently replayed block so
+ * a snapshot whose state was edited without re-signing fails loudly.
+ */
+export declare const PersistedShareDataSchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<3>;
+    id: z.ZodString;
+    blockType: z.ZodEnum<{
+        Clearing: "Clearing";
+        Funding: "Funding";
+        Distribution: "Distribution";
+        GraceRepayment: "GraceRepayment";
+    }>;
+    signingCurve: z.ZodEnum<{
+        ed25519: EllipticalCurvesSigning.Curve25519;
+        p521: EllipticalCurvesSigning.P521;
+    }>;
+    initialCrypto: z.ZodObject<{
+        publicKey: z.ZodString;
+        shareDataHash: z.ZodString;
+        shareDataSignature: z.ZodString;
+        timestamp: z.ZodNumber;
+    }, z.core.$strip>;
+    creationConfig: z.ZodObject<{
+        metadata: z.ZodObject<{
+            shareBlockId: z.ZodString;
+            blockType: z.ZodEnum<{
+                Clearing: "Clearing";
+                Funding: "Funding";
+                Distribution: "Distribution";
+                GraceRepayment: "GraceRepayment";
+            }>;
+            relatedLoanApplicationId: z.ZodOptional<z.ZodString>;
+            description: z.ZodOptional<z.ZodString>;
+            createdAt: z.ZodNumber;
+            createdBy: z.ZodString;
+        }, z.core.$strip>;
+        creationPublicKey: z.ZodString;
+        initialState: z.ZodRecord<z.ZodString, z.ZodAny>;
+    }, z.core.$strip>;
+    structuralProofs: z.ZodRecord<z.ZodString, z.ZodObject<{
+        publicKey: z.ZodString;
+        shareDataHash: z.ZodString;
+        shareDataPreviousHash: z.ZodString;
+        shareDataSignature: z.ZodString;
+        timestamp: z.ZodNumber;
+        purpose: z.ZodString;
+    }, z.core.$strip>>;
+    authorizedSigners: z.ZodArray<z.ZodObject<{
+        publicKey: z.ZodString;
+        functionIds: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>>;
+    transactionLog: z.ZodArray<z.ZodObject<{
+        functionId: z.ZodString;
+        input: z.ZodOptional<z.ZodAny>;
+        proposedState: z.ZodRecord<z.ZodString, z.ZodAny>;
+        proof: z.ZodObject<{
+            publicKey: z.ZodString;
+            shareDataHash: z.ZodString;
+            shareDataPreviousHash: z.ZodString;
+            shareDataSignature: z.ZodString;
+            timestamp: z.ZodNumber;
+            purpose: z.ZodString;
+        }, z.core.$strip>;
+        transactionTime: z.ZodNumber;
+        ruleOutcome: z.ZodBoolean;
+    }, z.core.$strip>>;
+    expectedCurrentState: z.ZodRecord<z.ZodString, z.ZodAny>;
+    expectedCreationHash: z.ZodString;
+    expectedCreationSignature: z.ZodString;
+    expectedIsLocked: z.ZodBoolean;
+    expectedVersion: z.ZodNumber;
+}, z.core.$strip>;
+export type PersistedShareData = z.infer<typeof PersistedShareDataSchema>;
+/** The only schema version this build understands. */
+export declare const PERSISTED_SHARE_DATA_SCHEMA_VERSION: 3;
+//# sourceMappingURL=share-data-persistence-models.d.ts.map

package/dist/models/share-data/share-data-persistence-models.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"share-data-persistence-models.d.ts","sourceRoot":"","sources":["../../../src/models/share-data/share-data-persistence-models.ts"],"names":[],"mappings":"AAAA,OAAO,CAAC,MAAM,KAAK,CAAC;AACpB,OAAO,EAAE,uBAAuB,EAAE,MAAM,uCAAuC,CAAC;AAChF,OAAO,EAEH,cAAc,EAEjB,MAAM,iCAAiC,CAAC;AAmBzC;;;;GAIG;AACH,eAAO,MAAM,2BAA2B;;;EAGtC,CAAC;AAEH;;;;;;;GAOG;AACH,eAAO,MAAM,6BAA6B;;;;;;;;;;;;;;;;iBAIxC,CAAC;AAEH,MAAM,MAAM,uBAAuB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,6BAA6B,CAAC,CAAC;AAEpF;;;;;;;;GAQG;AACH,MAAM,WAAW,uBAAuB;IACpC,SAAS,EAAE,cAAc,CAAC;IAC1B,cAAc,EAAE,uBAAuB,CAAC;CAC3C;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,0BAA0B;;;;;;;;;;;;;;iBAOrC,CAAC;AAEH,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,0BAA0B,CAAC,CAAC;AAE9E;;;;;GAKG;AACH,eAAO,MAAM,wBAAwB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAuBnC,CAAC;AAEH,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,CAAC;AAE1E,sDAAsD;AACtD,eAAO,MAAM,mCAAmC,EAAG,CAAU,CAAC"}

package/dist/models/share-data/share-data-persistence-models.js

@@ -0,0 +1,101 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PERSISTED_SHARE_DATA_SCHEMA_VERSION = exports.PersistedShareDataSchema = exports.PersistedTransactionSchema = exports.PersistedCreationConfigSchema = exports.PersistedSigningCurveSchema = void 0;
+const zod_1 = __importDefault(require("zod"));
+const cryptography_settings_1 = require("../../_settings/cryptography-settings");
+const shareblock_models_1 = require("../shareblock/shareblock-models");
+const share_data_crypto_models_1 = require("./share-data-crypto-models");
+const share_data_models_1 = require("./share-data-models");
+// This file contains the wire-format models for persisting a ShareData to a
+// durable store and reconstructing it. The design is event-sourced: a
+// snapshot stores the *creation recipe* + an ordered transaction log, not a
+// field-dump of a finished object. Reload replays construction (re-verifying
+// the structural-proof chain) and the transaction log, then cross-checks the
+// result against the stored `expected*` integrity values. See
+// `plans/PERSISTENCE_PLAN.html`.
+//#region Persistence Schemas
+/**
+ * The signing curve a persisted block was created with. Mirrors the values of
+ * {@link EllipticalCurvesSigning}; stored for forward-compatibility even
+ * though every shipped factory currently uses the `Curve25519` default.
+ */
+exports.PersistedSigningCurveSchema = zod_1.default.enum([
+    cryptography_settings_1.EllipticalCurvesSigning.Curve25519,
+    cryptography_settings_1.EllipticalCurvesSigning.P521,
+]);
+/**
+ * The factory creation input needed to replay construction, minus the
+ * `proofFor` callback (which is reconstructed from the stored
+ * `structuralProofs` + `initialCrypto` at load time). `initialState` is the
+ * *partial* state the factory was given — the factory deterministically
+ * assembles the full state from it, so storing the partial form is both
+ * sufficient and forward-stable.
+ */
+exports.PersistedCreationConfigSchema = zod_1.default.object({
+    metadata: shareblock_models_1.IShareBlockMetadataSchema,
+    creationPublicKey: zod_1.default.string(),
+    initialState: zod_1.default.record(zod_1.default.string(), zod_1.default.any()),
+});
+/**
+ * One post-creation transaction, captured at apply time. The live
+ * `transactionHistory` does NOT retain a transaction's input or proposed
+ * state, so these must be recorded when the transaction is applied rather
+ * than recovered from a finished block.
+ *
+ *   - `functionId` re-resolves the live function on the rebuilt block (same
+ *     id-based lookup `createIdBasedFunctionResolver` uses).
+ *   - `proposedState` is the state written when the transaction was accepted;
+ *     it is what replay re-applies.
+ *   - `proof` is the transaction proposal proof that authorized the change. It
+ *     is re-verified against the rebuilt block + `proposedState` during replay,
+ *     so a snapshot whose proposed state or proof was edited fails the load.
+ *     Recording it also keeps the rebuilt block byte-faithful: the live history
+ *     entry carries its proof, and the canonical share-data hash folds the
+ *     history in, so replay must reproduce the proof to hash identically.
+ *   - `transactionTime` is stored so the replayed history hashes identically.
+ *   - `ruleOutcome` records whether the original proposal was accepted.
+ */
+exports.PersistedTransactionSchema = zod_1.default.object({
+    functionId: zod_1.default.string(),
+    input: zod_1.default.any().optional(),
+    proposedState: share_data_models_1.IShareDataSchema,
+    proof: share_data_crypto_models_1.IShareDataCryptoProofSchema,
+    transactionTime: zod_1.default.number(),
+    ruleOutcome: zod_1.default.boolean(),
+});
+/**
+ * A durable snapshot of a ShareData. Versioned via `schemaVersion` so a future
+ * format change can be gated cleanly. The `expected*` fields are NOT trusted
+ * on load — they are cross-checked against the independently replayed block so
+ * a snapshot whose state was edited without re-signing fails loudly.
+ */
+exports.PersistedShareDataSchema = zod_1.default.object({
+    schemaVersion: zod_1.default.literal(3),
+    id: zod_1.default.string(),
+    blockType: shareblock_models_1.ShareBlockTypeSchema,
+    signingCurve: exports.PersistedSigningCurveSchema,
+    initialCrypto: share_data_crypto_models_1.IShareDataInitialCryptoDataSchema,
+    creationConfig: exports.PersistedCreationConfigSchema,
+    structuralProofs: share_data_crypto_models_1.ShareDataProofsSchema,
+    // The delegated-signer grants registered at construction (least-privilege
+    // function scoping per grant). The registration *proofs* live in
+    // `structuralProofs` keyed by their `delegate:<key>:<ids>` purpose; this
+    // field carries the grant tuples the builder replays via
+    // `addAuthorizedSigner` so the rebuilt block re-derives the same signer set
+    // (and the same canonical hash). Empty for blocks with no delegations.
+    authorizedSigners: zod_1.default.array(share_data_crypto_models_1.IAuthorizedSignerSchema),
+    transactionLog: zod_1.default.array(exports.PersistedTransactionSchema),
+    // Integrity cross-checks — compared against the replayed result, never
+    // trusted as source of truth.
+    expectedCurrentState: share_data_models_1.IShareDataSchema,
+    expectedCreationHash: zod_1.default.string(),
+    expectedCreationSignature: zod_1.default.string(),
+    expectedIsLocked: zod_1.default.boolean(),
+    expectedVersion: zod_1.default.number(),
+});
+/** The only schema version this build understands. */
+exports.PERSISTED_SHARE_DATA_SCHEMA_VERSION = 3;
+//#endregion Persistence Schemas