@degenerate/sharedata 0.2.7 → 0.4.0

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

@@ -1,76 +1,281 @@
-import { IShareData, IShareDataEvent, IShareFunction, IShareRuleApplied, IShareRuleEvalutionResult, IShareDataTransactionHistory } from '@degenerate/generic';
+import { IShareData, IShareDataEvent, IShareFunction, IShareRuleApplied, IShareRuleEvalutionResult, IShareDataTransactionHistory, IShareDataCryptoProof, EllipticalCurvesSigning, IShareDataInitialCryptoData, IAuthorizedSigner } from '@degenerate/generic';
 /**
  * This contains the interface for the share data object
  */
 export declare class ShareData {
     private _id;
     private _version;
+    private _isLocked;
     private _rules;
     private _functions;
     private _transactionHistory;
     private _events;
-    private isLocked;
-    private _data;
+    private _currentState;
+    private _cryptoProofs;
+    private _creationPublicKey;
+    private _creationHash;
+    private _creationSignature;
+    private _signingCurve;
+    private _lastUpdated;
+    private _structuralProofs;
+    private _authorizedSigners;
     /**
      * This is the constructor for the share data object
      * @param id the id of the share data
+     * @param creationPublicKey the public key of the creator of the share data
      */
-    constructor(id: string);
+    constructor(id: string, creationPublicKey: string, signingCurve?: EllipticalCurvesSigning);
     /**
-     * This adds a rule to the share block.
-     * @param rule the rule to add to the share block
+     * This initializes the cryptographic properties of the share data
+     * @param creationPublicKey the public key of the creator of the share data (in hex format)
+     * @param creationHash the hash of the share data
+     * @param creationSignature the cryptographic signature of the share data
      */
-    addRule(rule: IShareRuleApplied): void;
+    initializeCrypto(initialCryptoData: IShareDataInitialCryptoData): void;
     /**
-     * This gets the rules for the share block
+     * This validates the cryptographic properties of the share data
      */
-    get rules(): IShareRuleApplied[];
     /**
-     * This gets the transaction history for the share block
+     * This validates the cryptographic properties of the share data
+     * @param creationPublicKey the public key of the creator of the share data (in hex format)
      */
-    addFunction(func: IShareFunction<any, (...args: any[]) => any, any>): void;
     /**
-     * This gets the functions for the share block
+     * get the creation hash
      */
-    get functions(): IShareFunction<any, (...args: any[]) => any, any>[];
+    get creationHash(): string;
+    /**
+     * get the creation public key
+     */
+    get creationPublicKey(): string;
+    /**
+     * get the creation signature
+     */
+    get creationSignature(): string;
+    /**
+     * This gets all cryptographic proofs for the share data
+     */
+    get cryptoProofs(): IShareDataCryptoProof[];
+    /**
+     * This returns the current state of data for the share block
+     */
+    get currentState(): IShareData;
     /**
      * This gets the events for the sharedata
      */
     get events(): IShareDataEvent[];
+    /**
+     * This gets the functions for the share block
+     */
+    get functions(): IShareFunction<any, (...args: any[]) => any, any>[];
+    /**
+     * This gets the id for the share data
+     */
+    get id(): string;
+    /**
+     * This get whether the share data is locked
+     */
+    get isLocked(): boolean;
+    /**
+     * This gets the last timestamp (in milliseconds) that the share data was updated
+     */
+    get lastUpdated(): number;
+    /**
+     * This gets the rules for the share block
+     */
+    get rules(): IShareRuleApplied[];
+    /**
+     * This gets the elliptical curve used for signing
+     */
+    get signingCurve(): EllipticalCurvesSigning;
+    /**
+     * This gets the structure proofs for the share data
+     */
+    get structuralProofs(): IShareDataCryptoProof[];
+    /**
+     * This gets the delegated authorized-signer grants for the share data.
+     * Each grant is a `{ publicKey, functionIds }` pair: a key the owner has
+     * delegated the right to propose transactions for, scoped to those function
+     * ids. The block owner (`creationPublicKey`) is always authorized and is
+     * NOT listed here.
+     */
+    get authorizedSigners(): IAuthorizedSigner[];
+    /**
+     * This gets the transaction history for the share block
+     */
+    get transactionHistory(): IShareDataTransactionHistory[];
+    /**
+     * This gets the version of the share data
+     */
+    get version(): number;
     /**
      * This adds an event to the share data
      * @param event the event to add
      */
     addEvent(event: IShareDataEvent): void;
     /**
-     * This adds a transaction to the share block
-     * @param rulesEvaluation the evaluation of the rules (result)
-     * @param transactionFunction the function that was run
+     * This adds a function to the share block.
+     * @param func the function to add to the share block
+     */
+    addFunction(func: IShareFunction<any, (...args: any[]) => any, any>, cryptoProof: IShareDataCryptoProof): void;
+    /**
+     * This adds a rule to the share block.
+     * @param rule the rule to add to the share block
+     */
+    addRule(rule: IShareRuleApplied, cryptoProof: IShareDataCryptoProof): void;
+    /**
+     * Delegates `signerPublicKey` the right to propose runtime transactions for
+     * the given `functionIds` (and ONLY those — least privilege). Creation-time
+     * only: rejected once the block is locked. The registration is part of the
+     * signed structure, so a delegate cannot be injected into a tampered
+     * snapshot without invalidating the chain.
+     *
+     * Three gates, in order:
+     *   1. Owner-identity: `registrationProof.publicKey === creationPublicKey`.
+     *      ONLY the block owner may delegate — this is the check `addFunction` /
+     *      `addRule` deliberately omit (the HTTP layer supplies it there). It
+     *      must live here because the security of the widened transaction gate
+     *      (see {@link isAuthorizedSigner}) rests on "the allow-list was
+     *      authorized by the owner." It also blocks transitive delegation: a
+     *      delegate's key is never the creation key, so a delegate can never
+     *      register further delegates.
+     *   2. Grant binding: the proof's `purpose` must equal
+     *      `buildDelegatePurpose(signerPublicKey, functionIds)`. The proof signs
+     *      over the PRE-append state (the grant is not yet folded into
+     *      `_authorizedSigners`), so the purpose is the only thing that attests
+     *      to the exact `(key, functionIds)` grant — without this a tampered
+     *      snapshot could widen a delegate's scope without breaking the
+     *      signature.
+     *   3. Structural verification against the current (pre-append) state,
+     *      reusing the same machinery `addFunction` / `addRule` use; folds the
+     *      proof into the hash chain and verifies the owner's signature.
+     *
+     * Throws {@link ShareDataIsLockedError} if locked,
+     * {@link ShareDataDelegationNotAuthorizedError} for a non-owner registrant /
+     * empty grant / mismatched purpose, and
+     * {@link ShareDataStructuralProofFailedError} if the proof does not verify.
+     */
+    addAuthorizedSigner(signerPublicKey: string, functionIds: string[], registrationProof: IShareDataCryptoProof): void;
+    /**
+     * Whether `publicKey` is authorized to propose a transaction for
+     * `functionId` on this block. The block owner (`creationPublicKey`) is
+     * always authorized for every function; a delegated key is authorized only
+     * for the function ids its registration granted. This is the single
+     * predicate behind the proposer-identity gate, called from both the live
+     * mutation path ({@link addTransaction}) and the persistence replay path so
+     * the two cannot drift.
      */
-    addTransactionAlreadyValidated(proposedData: IShareData, rulesEvaluation: IShareRuleEvalutionResult, transactionFunction: IShareFunction<any, (...args: any[]) => any, any>): void;
+    isAuthorizedSigner(publicKey: string, functionId: string): boolean;
+    /**
+     * Append a pre-validated transaction to the history. Pass `transactionTime`
+     * when the caller needs the recorded timestamp to be deterministic — for
+     * example, when a wire-format payload is being reconstructed and the
+     * resulting share-data state must hash identically to the one the
+     * remote signer produced. Omit it for ordinary live calls; defaults to
+     * `Date.now()`.
+     *
+     * Pass `proof` when replaying a persisted transaction so the rebuilt
+     * history entry carries the same proposal proof the live entry did. The
+     * canonical share-data hash folds `transactionHistory` in, so omitting the
+     * proof here would make a replayed block hash differently from the original
+     * and break verification of any later transaction's proof.
+     */
+    addTransactionAlreadyValidated(proposedData: IShareData, rulesEvaluation: IShareRuleEvalutionResult, transactionFunction: IShareFunction<any, (...args: any[]) => any, any>, transactionTime?: number, proof?: IShareDataCryptoProof): void;
     /**
      * This adds a transaction to the share block but the transaction has not yet been validated
      *
+     * The unsigned/internal apply path: it runs the rule engine and records the
+     * outcome but carries no proposal proof, so it does NOT attest that any key
+     * holder authorized the change. New runtime mutations should go through
+     * {@link addTransaction}, which verifies a transaction proposal proof first.
+     * Retained for internal replay/seed callers that operate before the signed
+     * boundary is in play.
+     *
      * @param proposedData the proposed data
      * @param transactionFunction the function that was attempted
      */
-    addTransactionNotValidated(proposedData: IShareData, transactionFunction: IShareFunction<any, (...args: any[]) => any, any>): void;
+    addTransactionNotValidated(proposedData: IShareData, transactionFunction: IShareFunction<any, (...args: any[]) => any, any>): {
+        accepted: boolean;
+        transactionId: string;
+    };
     /**
-     * This gets the transaction history for the share block
-     */
-    get transactionHistory(): IShareDataTransactionHistory[];
-    /**
-     * This returns the current state of data for the share block
+     * Signed runtime mutation path. Verifies that `proof` cryptographically
+     * authorizes applying `transactionFunction` to move this share-data to
+     * exactly `proposedData`, then runs the rule engine and records the
+     * outcome. The recorded history entry carries `proof`, so the audit log
+     * itself holds the signature — not merely "which function ran."
+     *
+     * Four gates, in order:
+     *   1. The function must be registered on this block.
+     *   2. The function must be addressable (`id` set) and the proof must be
+     *      minted for that same id (`proof.purpose === transactionFunction.id`).
+     *      This binds the proof to *this* function so a proof minted for one
+     *      function can't be replayed to drive another even if the proposed
+     *      state would satisfy both functions' rules.
+     *   3. The proof's signer must be authorized for this block AND this
+     *      function — the creation key for any function, or a delegated key for
+     *      the function ids its registration granted (`isAuthorizedSigner`).
+     *      Signature validity alone only proves *someone* signed the transition;
+     *      this binds the *authorized* someone. Without it any valid keypair
+     *      could sign a legal transition.
+     *   4. The proof must verify against the current state AND `proposedData`
+     *      (closes the amount-replay hole — see
+     *      `verifyTransactionProposalProof`).
+     *
+     * Throws {@link ShareDataTransactionNotAuthorizedError} when the signer is
+     * not authorized (gate 3), {@link ShareDataTransactionProofFailedError} on
+     * any other auth failure — both before the rule engine runs and before any
+     * state is touched.
+     *
+     * @param proposedData the proposed next state
+     * @param transactionFunction the function producing `proposedData`
+     * @param proof the transaction proposal proof authorizing the change
      */
-    get data(): IShareData;
+    addTransaction(proposedData: IShareData, transactionFunction: IShareFunction<any, (...args: any[]) => any, any>, proof: IShareDataCryptoProof): {
+        accepted: boolean;
+        transactionId: string;
+    };
     /**
-     * This gets the version of the share data
+     * Shared rule-evaluate → apply-if-valid → record path used by both
+     * {@link addTransactionNotValidated} (no proof) and {@link addTransaction}
+     * (proof already verified by the caller). When `proof` is supplied it is
+     * recorded on the history entry so the audit log carries the signature.
      */
-    get version(): number;
+    private evaluateAndApply;
     /**
      * This copies a share data object to a new transaction number
      * @param transactionNumber the number of the transaction to run until.
+     * @param publicKey the public key of the application that will be the new owner of the share data
+     */
+    copyTo(transactionNumber: number, publicKey: string): ShareData;
+    /**
+     * This adds a cryptographic proof to the share data
+     * @param proof the cryptographic proof to add
+     */
+    addCryptoProof(proof: IShareDataCryptoProof): void;
+    /**
+     * Verifies that `proof` is a faithful attestation of this share-data's
+     * current structural state under `proof.purpose`. Returns `true` on
+     * success; throws `ShareDataStructuralProofFailedError` on any mismatch
+     * (hash, previousHash, signature, or purpose).
+     */
+    verifyStructuralProof(proof: IShareDataCryptoProof, curve?: EllipticalCurvesSigning): true;
+    /**
+     * Verifies that `proof` authorizes applying a transaction that moves this
+     * share-data to exactly `proposedData`. Unlike {@link verifyStructuralProof}
+     * (which binds only the current state under a purpose), this additionally
+     * binds the proposed state — a proof minted for one proposed state will not
+     * verify against any other. Returns `true`; throws
+     * `ShareDataTransactionProofFailedError` on any mismatch.
+     */
+    verifyTransactionProof(proof: IShareDataCryptoProof, proposedData: IShareData, curve?: EllipticalCurvesSigning): true;
+    /**
+     * This adds a structure proof to the share data
+     * @param proof the structure proof to add
+     */
+    addStructuralProof(proof: IShareDataCryptoProof): void;
+    /**
+     * This initializes the share data object and locks it
      */
-    copyTo(transactionNumber: number): ShareData;
+    initialize(): void;
 }
 //# sourceMappingURL=share-data.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"share-data.d.ts","sourceRoot":"","sources":["../../src/share-data/share-data.ts"],"names":[],"mappings":"AACA,OAAO,EACH,UAAU,EACV,eAAe,EACf,cAAc,EACd,iBAAiB,EACjB,yBAAyB,EACzB,4BAA4B,EAG/B,MAAM,qBAAqB,CAAC;AAE7B;;GAEG;AACH,qBAAa,SAAS;IAClB,OAAO,CAAC,GAAG,CAAS;IACpB,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,MAAM,CAAsB;IACpC,OAAO,CAAC,UAAU,CAAsD;IACxE,OAAO,CAAC,mBAAmB,CAAiC;IAC5D,OAAO,CAAC,OAAO,CAAoB;IACnC,OAAO,CAAC,QAAQ,CAAU;IAC1B,OAAO,CAAC,KAAK,CAAa;IAE1B;;;OAGG;gBACS,EAAE,EAAE,MAAM;IAatB;;;OAGG;IACH,OAAO,CAAC,IAAI,EAAE,iBAAiB,GAAG,IAAI;IAOtC;;OAEG;IACH,IAAI,KAAK,IAAI,iBAAiB,EAAE,CAE/B;IAED;;OAEG;IACH,WAAW,CAAC,IAAI,EAAE,cAAc,CAAC,GAAG,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG,EAAE,GAAG,CAAC,GAAG,IAAI;IAO1E;;OAEG;IACH,IAAI,SAAS,IAAI,cAAc,CAAC,GAAG,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG,EAAE,GAAG,CAAC,EAAE,CAEnE;IAED;;OAEG;IACH,IAAI,MAAM,IAAI,eAAe,EAAE,CAE9B;IAED;;;OAGG;IACH,QAAQ,CAAC,KAAK,EAAE,eAAe,GAAG,IAAI;IAItC;;;;OAIG;IACH,8BAA8B,CAC1B,YAAY,EAAE,UAAU,EACxB,eAAe,EAAE,yBAAyB,EAC1C,mBAAmB,EAAE,cAAc,CAAC,GAAG,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG,EAAE,GAAG,CAAC,GACvE,IAAI;IAwBP;;;;;OAKG;IACH,0BAA0B,CACtB,YAAY,EAAE,UAAU,EACxB,mBAAmB,EAAE,cAAc,CAAC,GAAG,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG,EAAE,GAAG,CAAC,GACvE,IAAI;IA0BP;;OAEG;IACH,IAAI,kBAAkB,IAAI,4BAA4B,EAAE,CAEvD;IAED;;OAEG;IACH,IAAI,IAAI,IAAI,UAAU,CAErB;IAED;;OAEG;IACH,IAAI,OAAO,IAAI,MAAM,CAEpB;IAED;;;OAGG;IACH,MAAM,CAAC,iBAAiB,EAAE,MAAM,GAAG,SAAS;CAa/C"}
+{"version":3,"file":"share-data.d.ts","sourceRoot":"","sources":["../../src/share-data/share-data.ts"],"names":[],"mappings":"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"}