@degenerate/endpoints 0.1.6 → 0.2.0

package/dist/routes/sharedata/v1.routes.js

@@ -0,0 +1,259 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.v1 = void 0;
+const express = __importStar(require("express"));
+const validate_jwt_share_data_1 = require("../../cors/authority/jwt/validate-jwt-share-data");
+const add_unique_tracking_1 = require("../../cors/logging/add-unique-tracking");
+const validate_request_body_1 = require("../../cors/endpoints/helpers/validate-request-body");
+const validate_incoming_request_data_1 = require("../../cors/endpoints/helpers/validate-incoming-request-data");
+const all_error_handler_1 = require("../../cors/errors/all-error-handler");
+const bad_request_handler_1 = require("../../cors/errors/bad-request-handler");
+const unauthorized_handler_1 = require("../../cors/errors/unauthorized-handler");
+const generic_1 = require("@degenerate/generic");
+const shareblock_1 = require("@degenerate/shareblock");
+// eslint-disable-next-line new-cap
+const router = express.Router({ mergeParams: true });
+// The ShareDataManager is provided by the host application via
+// `app.set('shareDataManager', manager)`. Sharing the same instance across
+// HTTP and realtime is what makes route mutations broadcast to subscribed
+// WebSocket clients. Tests must `app.set('shareDataManager', new ShareDataManager())`
+// in their setup before mounting this router.
+const getManager = (req) => {
+    const manager = req.app.get('shareDataManager');
+    if (!manager) {
+        throw new Error('shareDataManager is not registered on the app — see createApp()');
+    }
+    return manager;
+};
+// Authorization claims ride on the verified JWT as loosely-typed custom
+// claims. Treat `allowedSigningKeys` as authoritative only when it is
+// genuinely an array of strings — a malformed token that supplied a bare
+// string would otherwise fall into String.prototype.includes substring
+// semantics and could wrongly authorize a partially-matching key. Both the
+// create and delete gates parse through here so they can't drift.
+const getAllowedSigningKeys = (req) => {
+    const raw = req.auth?.customClaims?.allowedSigningKeys;
+    return Array.isArray(raw) && raw.every((k) => typeof k === 'string')
+        ? raw
+        : undefined;
+};
+router.use(add_unique_tracking_1.addUniqueTracking); // add the unique tracking id to the request
+router.use(validate_jwt_share_data_1.validateJWTShareData); // validate the JWT token
+/**
+ * This creates a new sharedata object.
+ */
+router.post(// https://{hostname}/sharedata/v1
+'/', validate_request_body_1.validateRequestBody, // make sure this is a valid request body
+(0, validate_incoming_request_data_1.validateIncomingRequestData)(generic_1.ISAFETransactionShareDataAddSchema), async (req, res) => {
+    try {
+        const { metadata, initialState, initialCrypto, proofs } = req.body.transaction.data;
+        const creationPublicKey = initialCrypto.publicKey;
+        // Cross-check: the verified JWT must authorize the caller to sign
+        // as `creationPublicKey`. Token issuers attach
+        // `customClaims.allowedSigningKeys: string[]` listing the public
+        // keys the subject is vouched for — without this check, anyone
+        // holding a valid SHAREDATA JWT could create a block attributed to
+        // any key (since they generate the proofs themselves with their
+        // own keypair). The shared validateJWTShareData middleware has
+        // already verified signature/issuer/audience/expiry; this gate
+        // closes the subject → signing-key binding.
+        const allowedSigningKeys = getAllowedSigningKeys(req);
+        if (!allowedSigningKeys || !allowedSigningKeys.includes(creationPublicKey)) {
+            return res.status(403).send({
+                successful: false,
+                error: `creation-public-key-mismatch: JWT does not authorize signing as ${creationPublicKey}`,
+            });
+        }
+        // Cross-check: every proof in the bundle must be signed by the same
+        // key the initialCrypto attributes the block to. A mismatch means
+        // the client either swapped a proof in or supplied a forged
+        // creationPublicKey — reject early with one clear error rather
+        // than letting it surface as a verifyStructuralProof failure inside
+        // the factory.
+        for (const [purpose, proof] of Object.entries(proofs)) {
+            if (proof.publicKey !== creationPublicKey) {
+                return res.status(400).send({
+                    successful: false,
+                    error: `proof-public-key-mismatch: proof for '${purpose}' signed by ${proof.publicKey}, but initialCrypto attributes block to ${creationPublicKey}`,
+                });
+            }
+        }
+        // Cross-check: bundle covers every purpose the factory will request.
+        // Surfaces a missing proof once, here, instead of as the first
+        // MissingRequiredProofError thrown mid-construction.
+        const requiredPurposes = REQUIRED_PURPOSES_BY_BLOCK_TYPE[metadata.blockType];
+        for (const purpose of requiredPurposes) {
+            if (!(purpose in proofs)) {
+                return res.status(400).send({
+                    successful: false,
+                    error: `missing-proof: bundle is missing required proof for purpose '${purpose}' on ${metadata.blockType} ShareBlock`,
+                });
+            }
+        }
+        // Schema's literal union and the enum are the same string values —
+        // narrow once and reuse so we don't repeat the cast.
+        const blockType = metadata.blockType;
+        const proofFor = (0, shareblock_1.buildLookupProofFor)({
+            proofs,
+            initialCrypto,
+            blockType,
+        });
+        const factoryArgs = { metadata, creationPublicKey, initialState, proofFor };
+        let shareData;
+        switch (blockType) {
+            case generic_1.ShareBlockType.Clearing:
+                shareData = (0, shareblock_1.createClearingShareBlock)(factoryArgs);
+                break;
+            case generic_1.ShareBlockType.Funding:
+                shareData = (0, shareblock_1.createFundingShareBlock)(factoryArgs);
+                break;
+            case generic_1.ShareBlockType.Distribution:
+                shareData = (0, shareblock_1.createDistributionShareBlock)(factoryArgs);
+                break;
+            default: {
+                // Exhaustiveness check — schema validation should prevent
+                // reaching this, but TS doesn't know that. A runtime fallback
+                // makes the intent explicit and silences the unioned-undefined
+                // warning on `shareData`.
+                const _exhaustive = blockType;
+                return res.status(400).send({
+                    successful: false,
+                    error: `unknown blockType: ${_exhaustive}`,
+                });
+            }
+        }
+        // Carry the creation recipe so a repository-backed manager can persist
+        // this block and keep writing through as transactions accrue. The
+        // factory was handed exactly `{ metadata, creationPublicKey,
+        // initialState }`; the manager re-serializes from those.
+        await getManager(req).addShareData(shareData, {
+            blockType,
+            creationConfig: { metadata, creationPublicKey, initialState },
+        });
+        return res.status(200).send({ successful: true });
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : 'Unknown error';
+        return res.status(400).send({ successful: false, error: message });
+    }
+});
+// Coverage-check table — keeps the per-variant required-proof list lookup
+// in one place rather than hard-coding switches in the route body.
+const REQUIRED_PURPOSES_BY_BLOCK_TYPE = {
+    [generic_1.ShareBlockType.Clearing]: shareblock_1.CLEARING_REQUIRED_PROOF_PURPOSES,
+    [generic_1.ShareBlockType.Funding]: shareblock_1.FUNDING_REQUIRED_PROOF_PURPOSES,
+    [generic_1.ShareBlockType.Distribution]: shareblock_1.DISTRIBUTION_REQUIRED_PROOF_PURPOSES,
+};
+/**
+ * This gets the sharedata objects and their data.
+ */
+router.get(// https://{hostname}/sharedata/v1
+'/', add_unique_tracking_1.addUniqueTracking, // add a unique tracking id to the request
+async (req, res) => {
+    res.status(200).send({ successful: true });
+    return;
+});
+/**
+ * PATCH is intentionally unsupported. The previous handler replaced the
+ * stored ShareData wholesale with the request body — bypassing the rule
+ * engine and the structural-proof trust chain entirely. That is state
+ * forgery, not merely a missing access check: a caller could overwrite a
+ * block's canonical state with arbitrary JSON. In the SAFE model, state
+ * changes are signed PROPOSALS judged by `startRuleEvaluation` (the
+ * `ShareDataManager.applyTransaction` path), never client-uploaded blobs.
+ * Until a proposal-over-HTTP endpoint exists, PATCH stays closed. Body
+ * shape is still validated first, so malformed requests get 400 before 501.
+ */
+router.patch(// https://{hostname}/sharedata/v1/{sharedataid}
+'/:sharedataid', add_unique_tracking_1.addUniqueTracking, // add a unique tracking id to the request
+validate_request_body_1.validateRequestBody, (0, validate_incoming_request_data_1.validateIncomingRequestData)(generic_1.ISAFETransactionShareDataUpdateSchema), async (_req, res) => {
+    return res.status(501).send({
+        successful: false,
+        error: 'patch-unsupported: ShareData mutations must go through the rule-engine-verified proposal path, not a wholesale state replacement.',
+    });
+});
+/**
+ * This deletes the sharedata object.
+ */
+router.delete(// https://{hostname}/sharedata/v1/{sharedataid}
+'/:sharedataid', add_unique_tracking_1.addUniqueTracking, // add a unique tracking id to the request
+validate_request_body_1.validateRequestBody, (0, validate_incoming_request_data_1.validateIncomingRequestData)(generic_1.ISAFETransactionShareDataDeleteSchema), async (req, res) => {
+    try {
+        const shareDataId = req.params.sharedataid;
+        // Body/URL agreement: the wire payload names a target block; it must
+        // match the id in the URL path. A mismatch is a malformed request.
+        const bodyId = req.body
+            .transaction.data.metadata.shareBlockId;
+        if (bodyId !== shareDataId) {
+            return res.status(400).send({
+                successful: false,
+                error: `sharedata-id-mismatch: URL id ${shareDataId} does not match body id ${bodyId}`,
+            });
+        }
+        // Per-resource authorization (BOLA gate). The router-level
+        // validateJWTShareData only proves the caller holds a valid SHAREDATA
+        // token — it does NOT prove they may act on THIS block. Look up the
+        // target and require the verified JWT to vouch for the key that
+        // created it. Authorize against the stored block's creationPublicKey,
+        // never the client-supplied body. Mirrors the POST create gate.
+        const existing = getManager(req).getShareDataById(shareDataId);
+        if (!existing) {
+            return res.status(404).send({
+                successful: false,
+                error: `not-found: no ShareData with id ${shareDataId}`,
+            });
+        }
+        const allowedSigningKeys = getAllowedSigningKeys(req);
+        if (!allowedSigningKeys || !allowedSigningKeys.includes(existing.creationPublicKey)) {
+            return res.status(403).send({
+                successful: false,
+                error: `creation-public-key-mismatch: JWT does not authorize mutating block created by ${existing.creationPublicKey}`,
+            });
+        }
+        await getManager(req).removeShareDataById(shareDataId);
+        return res.status(200).send({ successful: true });
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : 'Unknown error';
+        return res.status(400).send({ successful: false, error: message });
+    }
+});
+// Error handlers must be registered AFTER routes — express only routes
+// errors to handlers that follow the throwing middleware in the chain.
+router.use(unauthorized_handler_1.unauthorizedHandler); // the unauthorized handler should be the first error handler
+router.use(bad_request_handler_1.badRequestHandler); // the bad request handler should be the second error handler
+router.use(all_error_handler_1.allErrorHandler); // the all error handler catches all remaining errors
+exports.v1 = router; // https://{hostname}/sharedata/v1

package/package.json

@@ -1,21 +1,31 @@
 {
   "name": "@degenerate/endpoints",
-  "version": "0.1.6",
+  "version": "0.2.0",
   "description": "This contains the ShareData Adaptive Framework Ecosystem (SAFE) network endpoint code",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
   "devDependencies": {
-    "@types/jest": "^29.5.14",
-    "@types/node": "^22.9.0",
-    "jest": "^29.7.0",
-    "ts-jest": "^29.2.5",
-    "typescript": "^5.6.3"
+    "@types/express": "^5.0.6",
+    "@types/jest": "^30.0.0",
+    "@types/node": "^22.19.18",
+    "jest": "^30.4.2",
+    "ts-jest": "^29.4.9",
+    "typescript": "^6.0.3"
   },
   "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"
   },
   "repository": {
@@ -40,11 +50,17 @@
   "author": "Degenerate Inc.",
   "license": "ISC",
   "dependencies": {
-    "@degenerate/generic": "^0.2.6",
-    "@types/supertest": "^6.0.2",
-    "express": "^4.21.1",
-    "supertest": "^7.0.0",
-    "zod": "^3.24.1"
+    "@degenerate/generic": "^0.3.0",
+    "@degenerate/realtime": "^0.1.0",
+    "@degenerate/shareblock": "^0.3.0",
+    "@degenerate/sharedata": "^0.3.0",
+    "@types/supertest": "^6.0.3",
+    "express": "^5.2.1",
+    "supertest": "^7.2.2",
+    "zod": "^4.4.3"
   },
-  "gitHead": "a1ef457f3b707fb642b2e3296239c74bd75614b8"
+  "gitHead": "c33ed2f06679f5bd76c2eccf7054212c1820a014",
+  "engines": {
+    "node": ">=22"
+  }
 }