@degenerate/sharedata 0.2.7 → 0.4.0

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

@@ -3,6 +3,8 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.ShareData = void 0;
 const rules_1 = require("@degenerate/rules");
 const generic_1 = require("@degenerate/generic");
+const verify_share_data_proposal_proof_1 = require("./proofs/verification/verify-share-data-proposal-proof");
+const verify_transaction_proposal_proof_1 = require("./proofs/verification/verify-transaction-proposal-proof");
 /**
  * This contains the interface for the share data object
  */
@@ -10,48 +12,85 @@ class ShareData {
     /**
      * 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) {
-        this.isLocked = false;
-        this._version = 1,
-            this._id = id;
+    constructor(id, creationPublicKey, signingCurve = generic_1.EllipticalCurvesSigning.Curve25519) {
+        this._id = id;
+        this._creationHash = '';
+        this._creationSignature = '';
+        this._creationPublicKey = creationPublicKey,
+            this._version = 1,
+            this._isLocked = false;
+        this._lastUpdated = 0;
         this._rules = [];
         this._functions = [];
         this._transactionHistory = [];
         this._events = [];
-        this._data = {};
+        this._currentState = {};
+        this._cryptoProofs = [];
+        this._signingCurve = signingCurve;
+        this._structuralProofs = [];
+        this._authorizedSigners = [];
     }
-    //#region Getters and Setters
     /**
-     * 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) {
-        if (this.isLocked) {
-            throw new generic_1.ShareDataIsLockedError(this._id, generic_1.ShareDataTypes.RULE);
+    initializeCrypto(initialCryptoData) {
+        // Implement the logic to initialize the cryptographic properties
+        if (this._creationSignature || this._creationHash || this._lastUpdated != 0) {
+            throw new generic_1.ShareDataCryptoAlreadyExistsError(this._id);
         }
-        this._rules.push(rule);
+        if (initialCryptoData.publicKey !== this._creationPublicKey) {
+            throw new generic_1.CryptoInitializationPublicKeyIsDifferentError(this._id);
+        }
+        // check that the share data proof is valid.
+        this._lastUpdated = initialCryptoData.timestamp;
+        this._creationHash = initialCryptoData.shareDataHash;
+        this._creationSignature = initialCryptoData.shareDataSignature;
     }
+    //#region Validation
     /**
-     * This gets the rules for the share block
+     * This validates the cryptographic properties of the share data
      */
-    get rules() {
-        return this._rules;
+    // validateRuleUpdate = (ruleToAdd )
+    //#endregion Validation
+    /**
+     * This validates the cryptographic properties of the share data
+     * @param creationPublicKey the public key of the creator of the share data (in hex format)
+     */
+    //#region Getters and Setters
+    /**
+     * get the creation hash
+     */
+    get creationHash() {
+        return this._creationHash;
     }
     /**
-     * This gets the transaction history for the share block
+     * get the creation public key
      */
-    addFunction(func) {
-        if (this.isLocked) {
-            throw new generic_1.ShareDataIsLockedError(this._id, generic_1.ShareDataTypes.FUNCTION);
-        }
-        this._functions.push(func);
+    get creationPublicKey() {
+        return this._creationPublicKey;
     }
     /**
-     * This gets the functions for the share block
+     * get the creation signature
      */
-    get functions() {
-        return this._functions;
+    get creationSignature() {
+        return this._creationSignature;
+    }
+    /**
+     * This gets all cryptographic proofs for the share data
+     */
+    get cryptoProofs() {
+        return this._cryptoProofs;
+    }
+    /**
+     * This returns the current state of data for the share block
+     */
+    get currentState() {
+        return this._currentState;
     }
     /**
      * This gets the events for the sharedata
@@ -59,6 +98,72 @@ class ShareData {
     get events() {
         return this._events;
     }
+    /**
+     * This gets the functions for the share block
+     */
+    get functions() {
+        return this._functions;
+    }
+    /**
+     * This gets the id for the share data
+     */
+    get id() {
+        return this._id;
+    }
+    /**
+     * This get whether the share data is locked
+     */
+    get isLocked() {
+        return this._isLocked;
+    }
+    /**
+     * This gets the last timestamp (in milliseconds) that the share data was updated
+     */
+    get lastUpdated() {
+        return this._lastUpdated;
+    }
+    /**
+     * This gets the rules for the share block
+     */
+    get rules() {
+        return this._rules;
+    }
+    /**
+     * This gets the elliptical curve used for signing
+     */
+    get signingCurve() {
+        return this._signingCurve;
+    }
+    /**
+     * This gets the structure proofs for the share data
+     */
+    get structuralProofs() {
+        return this._structuralProofs;
+    }
+    /**
+     * 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() {
+        return this._authorizedSigners;
+    }
+    /**
+     * This gets the transaction history for the share block
+     */
+    get transactionHistory() {
+        return this._transactionHistory;
+    }
+    /**
+     * This gets the version of the share data
+     */
+    get version() {
+        return this._version;
+    }
+    //#endregion Getters and Setters
+    //#region Adders
     /**
      * This adds an event to the share data
      * @param event the event to add
@@ -67,16 +172,125 @@ class ShareData {
         this._events.push(event);
     }
     /**
-     * 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, cryptoProof) {
+        if (this._isLocked) {
+            throw new generic_1.ShareDataIsLockedError(this._id, generic_1.ShareDataTypes.FUNCTION);
+        }
+        // Verify against the share-data state as it stands BEFORE this
+        // function is appended. The signer signed over that pre-append
+        // snapshot, so verifying after the push would always fail.
+        this.verifyStructuralProof(cryptoProof);
+        this._structuralProofs.push(cryptoProof);
+        this._functions.push(func);
+    }
+    /**
+     * This adds a rule to the share block.
+     * @param rule the rule to add to the share block
+     */
+    addRule(rule, cryptoProof) {
+        if (this._isLocked) {
+            throw new generic_1.ShareDataIsLockedError(this._id, generic_1.ShareDataTypes.RULE);
+        }
+        // Same pre-append verification as addFunction — the signer signed
+        // over the state before this rule was added.
+        this.verifyStructuralProof(cryptoProof);
+        this._structuralProofs.push(cryptoProof);
+        this._rules.push(rule);
+    }
+    /**
+     * 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, functionIds, registrationProof) {
+        if (this._isLocked) {
+            throw new generic_1.ShareDataIsLockedError(this._id, generic_1.ShareDataTypes.AUTHORIZATION);
+        }
+        // Gate 1: owner-identity. Only the creation key may delegate.
+        if (registrationProof.publicKey !== this._creationPublicKey) {
+            throw new generic_1.ShareDataDelegationNotAuthorizedError(this._id, registrationProof.publicKey);
+        }
+        // Normalize so the purpose, the stored grant, and the canonical hash all
+        // agree byte-for-byte on live-create and on replay.
+        const normalizedFunctionIds = Array.from(new Set(functionIds.map((id) => id.trim()).filter((id) => id.length > 0))).sort();
+        if (normalizedFunctionIds.length === 0) {
+            throw new generic_1.ShareDataDelegationNotAuthorizedError(this._id, registrationProof.publicKey);
+        }
+        // Gate 2: the proof must bind this exact (key, functionIds) grant.
+        const expectedPurpose = (0, generic_1.buildDelegatePurpose)(signerPublicKey, normalizedFunctionIds);
+        if (registrationProof.purpose !== expectedPurpose) {
+            throw new generic_1.ShareDataDelegationNotAuthorizedError(this._id, registrationProof.publicKey);
+        }
+        // Gate 3: structural verification (pre-append, mirroring addFunction).
+        this.verifyStructuralProof(registrationProof);
+        this._structuralProofs.push(registrationProof);
+        this._authorizedSigners.push({ publicKey: signerPublicKey, functionIds: normalizedFunctionIds });
+    }
+    /**
+     * 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, rulesEvaluation, transactionFunction) {
+    isAuthorizedSigner(publicKey, functionId) {
+        if (publicKey === this._creationPublicKey) {
+            return true;
+        }
+        const grant = this._authorizedSigners.find((s) => s.publicKey === publicKey);
+        return grant !== undefined && grant.functionIds.includes(functionId);
+    }
+    /**
+     * 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, rulesEvaluation, transactionFunction, transactionTime = Date.now(), proof) {
         // make sure the function is known.
         if (!this._functions.includes(transactionFunction)) {
             throw new Error('The function is not known');
         }
-        const transactionTime = Date.now(); // get the current time
         const transactionId = this._transactionHistory.length + 1; // get the transaction id
         const ruleOutcome = (rulesEvaluation.proposedResult && rulesEvaluation.currentResult);
         const transaction = {
@@ -85,76 +299,192 @@ class ShareData {
             transactionFunction,
             transactionId: transactionId.toString(),
             transactionTime,
+            ...(proof ? { proof } : {}),
         };
         // the outcome of the rules is valid write the data to be the new current data.
         if (ruleOutcome) {
-            this._data = proposedData;
+            this._currentState = proposedData;
         }
         this._transactionHistory.push(transaction);
     }
     /**
      * 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, transactionFunction) {
+        return this.evaluateAndApply(proposedData, transactionFunction);
+    }
+    /**
+     * 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
+     */
+    addTransaction(proposedData, transactionFunction, proof) {
+        // Gate 1: function registered on this block.
+        if (!this._functions.includes(transactionFunction)) {
+            throw new Error('The function is not known');
+        }
+        // Gate 2: bind the proof to this specific function. The signed runtime
+        // path requires addressable functions — an id-less function cannot be
+        // the subject of a proof, so reject rather than silently skip the
+        // binding.
+        const functionId = transactionFunction.id;
+        if (typeof functionId !== 'string' || functionId.length < 1) {
+            throw new generic_1.ShareDataTransactionProofFailedError(this._id);
+        }
+        if (proof.purpose !== functionId) {
+            throw new generic_1.ShareDataTransactionProofFailedError(this._id);
+        }
+        // Gate 3: bind the proposer identity. The block's creation key may
+        // authorize any function; a delegated key may authorize only the
+        // function ids it was granted (see addAuthorizedSigner / isAuthorizedSigner).
+        // `functionId` equals `proof.purpose` here (enforced by Gate 2), so the
+        // scope check is against the function the proof is bound to. Checked
+        // before the (more expensive) signature verification so an unauthorized
+        // signer fails fast.
+        if (!this.isAuthorizedSigner(proof.publicKey, functionId)) {
+            throw new generic_1.ShareDataTransactionNotAuthorizedError(this._id, proof.publicKey);
+        }
+        // Gate 4: proof binds current state + proposed state + chain position.
+        this.verifyTransactionProof(proof, proposedData);
+        return this.evaluateAndApply(proposedData, transactionFunction, proof);
+    }
+    /**
+     * 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.
+     */
+    evaluateAndApply(proposedData, transactionFunction, proof) {
         // make sure the function is known.
         if (!this._functions.includes(transactionFunction)) {
             // throw ShareDataFunctionBeingAppliedDoesNotExistOnShareDataError
             throw new Error('The function is not known');
         }
-        // // evaluate the rules.
-        // const rulesEvalOutcome = evaluateRules('transaction', this._data, proposedData, this._rules);
-        const rulesOutcome = (0, rules_1.startRuleEvaluation)(this._id, transactionFunction, this.functions, this._rules, this._data, proposedData);
-        const transactionTime = Date.now(); // get the current time
-        const transactionId = this._transactionHistory.length + 1; // get the transaction id
+        const rulesOutcome = (0, rules_1.startRuleEvaluation)(this._id, transactionFunction, this.functions, this._rules, this._currentState, proposedData);
+        const transactionTime = Date.now();
+        const transactionId = (this._transactionHistory.length + 1).toString();
         const transaction = {
             ruleOutcome: rulesOutcome.isValidProposal,
             ruleFailures: [],
             transactionFunction,
-            transactionId: transactionId.toString(),
+            transactionId,
             transactionTime,
+            ...(proof ? { proof } : {}),
         };
-        // update the data if the rules are valid
         if (rulesOutcome.isValidProposal) {
-            this._data = proposedData;
+            this._currentState = proposedData;
         }
-        // add the transaction to the history
         this._transactionHistory.push(transaction);
+        return { accepted: rulesOutcome.isValidProposal, transactionId };
     }
-    /**
-     * This gets the transaction history for the share block
-     */
-    get transactionHistory() {
-        return this._transactionHistory;
-    }
-    /**
-     * This returns the current state of data for the share block
-     */
-    get data() {
-        return this._data;
-    }
-    /**
-     * This gets the version of the share data
-     */
-    get version() {
-        return this._version;
-    }
+    //#region Adders
+    //#region Copy
     /**
      * 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) {
+    copyTo(transactionNumber, publicKey) {
         // return share data with a new ID
-        const newShareData = new ShareData(`${this._id}-${transactionNumber}`);
+        const newShareData = new ShareData(`${this._id}-${transactionNumber}`, publicKey);
         newShareData._rules = [...this._rules];
         newShareData._functions = [...this._functions];
         newShareData._transactionHistory = [...this._transactionHistory];
         newShareData._events = [...this._events];
-        newShareData._data = { ...this._data };
+        newShareData._currentState = { ...this._currentState };
         newShareData._version = this._version;
         return newShareData;
     }
+    //#endregion Copy
+    //#region Crypto Proofs
+    /**
+     * This adds a cryptographic proof to the share data
+     * @param proof the cryptographic proof to add
+     */
+    addCryptoProof(proof) {
+        this._cryptoProofs.push(proof);
+    }
+    /**
+     * 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, curve = this._signingCurve) {
+        return (0, verify_share_data_proposal_proof_1.verifyShareDataProposalProof)(proof, this, curve);
+    }
+    /**
+     * 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, proposedData, curve = this._signingCurve) {
+        return (0, verify_transaction_proposal_proof_1.verifyTransactionProposalProof)(proof, this, proposedData, curve);
+    }
+    //#endregion Crypto Proofs
+    //#region Structure Proofs
+    /**
+     * This adds a structure proof to the share data
+     * @param proof the structure proof to add
+     */
+    addStructuralProof(proof) {
+        if (this._structuralProofs.includes(proof)) {
+            throw new generic_1.ShareDataStructuralProofFailedError(this._id);
+        }
+        this._structuralProofs.push(proof);
+    }
+    //#region Initialization
+    /**
+     * This initializes the share data object and locks it
+     */
+    initialize() {
+        // Perform any necessary initialization steps here
+        // Lock the share data object
+        this._isLocked = true;
+    }
 }
 exports.ShareData = ShareData;
+const itiem2 = new ShareData('1', '1234');
+const item = new ShareData('1', '1234');
+item.initialize();

package/package.json

@@ -1,22 +1,40 @@
 {
   "name": "@degenerate/sharedata",
-  "version": "0.2.7",
+  "version": "0.4.0",
   "description": "This contains the ShareData Adaptive Framework Ecosystem (SAFE) network core code",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
   "scripts": {
     "build": "rm -rf dist/* && tsc -p tsconfig.pkg.json",
     "compile": "rm -rf dist/* && tsc -p tsconfig.pkg.json",
-    "test": "jest --forceExit --detectOpenHandles --verbose --silent=false --env node --config tsconfig.pkg.json",
-    "test:coverage": "jest --forceExit --coverage --detectOpenHandles --verbose --silent=false --env node  --config tsconfig.pkg.json",
+    "test": "jest --forceExit --detectOpenHandles --verbose --silent=false --env node",
+    "test:coverage": "jest --forceExit --coverage --detectOpenHandles --verbose --silent=false --env node ",
     "test:clearCache": "jest --clearCache"
   },
   "devDependencies": {
-    "@types/jest": "^29.5.14",
-    "@types/node": "^22.8.0",
-    "jest": "^29.7.0",
-    "ts-jest": "^29.2.5",
-    "typescript": "^5.6.3"
+    "@types/jest": "^30.0.0",
+    "@types/node": "^22.19.18",
+    "firebase-admin": "^13.10.0",
+    "jest": "^30.4.2",
+    "ts-jest": "^29.4.9",
+    "typescript": "^6.0.3"
+  },
+  "peerDependencies": {
+    "firebase-admin": "^13.10.0"
+  },
+  "peerDependenciesMeta": {
+    "firebase-admin": {
+      "optional": true
+    }
   },
   "keywords": [
     "ShareData Adaptive Framework Ecosystem",
@@ -31,13 +49,13 @@
     "url": "https://github.com/syncrude/safe/issues"
   },
   "homepage": "https://github.com/syncrude/safe#readme",
-  "gitHead": "29034ad37b42e7ec71a842e679b6c8a257d7cb6a",
+  "gitHead": "9453d9ab785e03fd01eb5b408ed0e3ca22baefd5",
   "dependencies": {
-    "@degenerate/generic": "^0.2.7",
-    "@degenerate/rules": "^0.2.7",
-    "zod": "^3.24.1"
+    "@degenerate/generic": "^0.4.0",
+    "@degenerate/rules": "^0.4.0",
+    "zod": "^4.4.3"
   },
   "engines": {
-    "node": "22.x"
+    "node": ">=22"
   }
 }