@bsv/overlay 2.3.1 → 2.6.1

package/README.md

@@ -79,6 +79,52 @@ The root entry point exports:
 imports remain available through the documented package export map, but new
 applications should prefer the root entry point wherever possible.
 
+## Optional persistence capability
+
+`AdmissionStorage` defines an additive v1 atomic admission contract for future
+adapters. `storageHasAdmission(storage)` reports whether the optional
+`admission` field is present. `getAdmissionStorage(storage)` detects an explicit provider with both
+commit and reconciliation methods. Existing Knex and injected legacy adapters
+remain supported; their individual methods do not imply atomic submission.
+When `getAdmissionStorage(storage)` observes a complete `overlay-admission-v1`
+provider, `Engine.submit` builds an admission plan and returns the saved STEAK
+only after majority commit. The SQL/Knex path and its early STEAK callback are
+unchanged; that callback is not a durable commit receipt.
+
+The contract separates local commit, index visibility and propagation. It binds
+operation identity to verified transaction, topic/policy and off-chain context;
+uses ready payload references and outbox intents; and fences recovery by both
+chain epoch and topic history generation. Helper functions and shared fixtures
+pin exact integers, deterministic identity, leases and cursor eligibility.
+See the [persistence specification](https://github.com/bsv-blockchain/ts-stack/blob/main/specs/overlay/persistence-v1.md).
+No consumer migration, storage-default change or database migration is included
+in this release candidate.
+
+## Optional Mongo foundation
+
+The package also contains an opt-in MongoDB foundation for schema bootstrap,
+content-addressed payload publication, reference guards, payload collection,
+and an explicit `AdmissionStorage` adapter. Mongo is not the default Engine
+storage selection; importing `@bsv/overlay` alone does not load MongoDB.
+
+Applications using a Mongo deep entry point install the optional peer first:
+
+```sh
+npm install @bsv/overlay mongodb@^7.5.0
+```
+
+The initial entry points are
+`@bsv/overlay/storage/mongo/MongoSchema`,
+`@bsv/overlay/storage/mongo/MongoPayloadStore`,
+`@bsv/overlay/storage/mongo/MongoAdmissionStorage`, and
+`@bsv/overlay/storage/mongo/MongoOverlayStorage`. They require an explicitly
+operated unsharded replica set; the supported deployment profile is three
+members. Payload publication makes GridFS bytes physically `published` before
+the guarded payload row becomes `ready`; caller-session reference and GC
+operations share that row guard. See the [Mongo v1
+foundation](https://github.com/bsv-blockchain/ts-stack/blob/main/specs/overlay/mongo-v1.md)
+for operational bounds, recovery rules, and the opt-in admission path.
+
 ## Runtime and package formats
 
 The package supports both module systems:
@@ -117,9 +163,129 @@ For production deployments:
 - avoid logging raw secrets, authorization headers, or unbounded payloads;
 - monitor readiness, proof acquisition, synchronization, and unproven state.
 
+Run every `KnexStorageMigrations` migration before serving traffic. The topical
+uniqueness migration deliberately stops when duplicate `(txid, outputIndex,
+topic)` output rows or `(txid, topic)` applied-transaction rows already exist;
+operators must inspect and reconcile those records rather than letting a
+migration discard security-relevant state. The engine serializes submissions
+inside one process, while database uniqueness and conditional unspent updates
+enforce the same spend/admission boundary across processes.
+
+Prefer roll-forward after these migrations. Older package versions do not know
+their migration names, so a bare image rollback can fail migration-list
+validation. To restore an older version, stop writes and either use the new
+migration source to reverse `spentBy` and topical uniqueness in reverse order
+after exporting and reconciling every `spent`/`spentBy` association, or restore
+coordinated pre-migration SQL and lookup-store backups. Never drop `spentBy` or
+restore only one store without preserving that spend evidence.
+
+Submission is intentionally not a single all-or-nothing transaction across
+primary storage and external lookup indexes. The Engine validates before
+mutation, propagates failures, and never invokes the success callback until all
+attempted writes complete, but a late failure does not roll back an earlier
+committed write or third-party index update. A rejected submission therefore
+does not assert rollback. Operators and custom adapters must detect and
+reconcile partially applied work before replaying or exposing affected state.
+
+GASP v1 bidirectional `submitNode` omits the `spentBy` parent outpoint. A
+receiver must already have the relevant parent, request it in a subsequent
+sync round, or reject the graph; it must never infer the edge from the child
+alone. Pull-only operation avoids that assumption. The Overlay pull adapter
+binds topic, graph, raw transaction, output, parent edge, proof, resource
+limits, and historical spend state before finalization.
+
+Remote GASP/BASM peers and propagation/header providers are separate network
+authorities. Production adapters accept credential-free public HTTPS, pin DNS
+addresses to the requested origin, reject redirects, bound streamed bodies and
+deadlines, and correlate every transaction, topic, height, index, and proof to
+its request. Private or HTTP targets belong only in explicit isolated local
+development configurations.
+
+Reorg event streams are hints rather than independent chain-state authority.
+Before demoting a proven admission for a reported orphaned block, the Engine
+requires the configured canonical header resolver to return a different hash
+for that exact height. An unavailable resolver or a hash that is still
+canonical rejects the event before any durable mutation.
+
+SHIP tracker answers are discovery hints, not trusted routing authority. Before
+using a discovered endpoint for GASP, the Engine now requires a canonical
+identity-linked advertisement signature, a one-satoshi token, exact BEEF/TXID
+correlation, and the requested topic. The endpoint still passes through the
+same public-HTTPS and DNS-pinning controls as an explicitly configured peer.
+
+Custom `Storage`, `LookupService`, `TopicManager`, advertiser, chain-tracker,
+and header-resolver implementations are trusted local components, but their
+runtime results are still checked before the Engine mutates or returns state.
+Storage queries must return only records bound to the requested outpoint,
+topic, height, block hash, and score window. Lookup formulas use a default
+1,000-result limit and an unconditional 100,000-result safety ceiling; history
+depth, context bytes, stored BEEF, graph fan-out, and aggregate traversal work
+are also bounded. `maxLookupResults: -1` disables the operator-selected lower
+limit, not the hard safety ceiling. BASM anchor stores must return strictly
+ordered, request-bound, canonical hash records.
+
+Public component metadata is copied through a bounded own-data-property schema;
+names, descriptions, versions, and HTTP(S) links that are malformed, accessor
+backed, or oversized fall back to a minimal local registry description.
+Component Markdown documentation is limited to 1 MiB before it crosses the
+Engine/HTTP boundary.
+
 `@bsv/overlay-express` supplies these standard HTTP controls while preserving
 public protocol access by default.
 
+### BASM peer validation and current recovery limits
+
+BASM uses the current BRC-136 ordered admitted subset and block-anchored TAC.
+The five existing JSON POST routes remain compatible; empty tips remain
+`{ topic, blockHeight: -1, tac: <zero hash> }`. Unsupported storage capabilities
+are errors, not empty histories. The remote client validates response shape,
+topic/height/hash binding, ordered unique admitted positions, contiguous
+returned ranges, and complete proof/raw response ID sets before use.
+
+`BASMRemote` retains its injectable third `fetch` argument and accepts optional
+limits as a fourth argument. Defaults are 64 MiB per decoded response, 8 MiB
+per proof, 32 MiB per raw transaction, 100,000 admitted entries, 1,000 requested
+txids, 1,024 requested anchor heights, and 30 seconds per request including its
+body. Aggregate response limits also apply to hex-encoded transactions. These
+are configurable local acceptance limits, not consensus rules. Standard fetch
+bodies are bounded while streaming; legacy injected `text()` implementations
+are checked after buffering. Classified errors expose `code`, including
+`BASM_UNSUPPORTED`, `BASM_RESOURCE_LIMIT`, and `BASM_TIMEOUT`.
+
+Reconciliation requires a canonical header resolver as well as a ChainTracker.
+An optional `TopicAnchorHeader.blockTransactionCount` must come independently
+from the trusted canonical provider and refer to that exact `blockHash`.
+It enables full-block count/index bounds and odd-duplication checks. The sync
+report's `positionValidation` is `canonical-count` only when that evidence was
+available for every checked proof; legacy providers yield `encoded-offset-only`.
+A Merkle root plus an encoded offset alone cannot disambiguate Bitcoin's
+duplicate-last-leaf position ambiguity. No provider is required to add the
+field, and the engine does not download full blocks to infer it.
+
+Forward sync pages now contain at most 1,000 anchors to fit the standard HTTP
+server. Proof height, requested original index, canonical hash/root, raw byte
+identity, TAC continuity, and repeated peer anchors are checked before historical
+submission. Claimed admitted-list indices are bound to the compound path whenever
+a remote list is used as evidence, including when every remote txid is already
+local. Inclusion uses the chain tracker root/height check rather than
+`MerklePath.verify`, which also enforces coinbase 100-block spendability.
+Because inclusion is proven independently, admission submits in the
+`historical-tx-no-spv` mode so `Transaction.verify` does not re-apply that
+coinbase rule; the public `historical-tx` mode keeps full SPV verification.
+Admission still applies the local TopicManager, and because every admitted
+transaction carries its extracted Merkle path, neither network broadcast nor
+overlay propagation occurs. Automatic BASM sync remains disabled by default.
+
+This is bounded protocol hardening, not durable recovery. An empty local node
+whose topic genesis precedes the recent bootstrap window now refuses the
+untrusted TAC prefix; this intentionally replaces the old unchecked tail
+behavior. A block above 1,000 admitted entries reaches a request-limit error
+until proof/raw chunking is implemented. Equal-height/local-ahead divergence,
+whole-target bootstrap, durable cursors/leases, atomic revision fencing, and
+truthful per-topic agreement status remain required follow-up work. A successful
+legacy report does not establish global completeness, current unspentness, or
+durable recovery completion. See [BASM details](./docs/BRC-136-BASM.md).
+
 ## Development
 
 From the repository root:

package/dist/cjs/mod.d.ts

@@ -3,6 +3,9 @@ export { serializeErrorForLog, serializeLogValue } from './src/SafeLog.js';
 export type * from './src/LookupService.js';
 export type { TopicAdmittanceContext, TopicManager } from './src/TopicManager.js';
 export type { Storage, AppliedTransaction } from './src/storage/Storage.js';
+export { storageHasAdmission } from './src/storage/Storage.js';
+export * from './src/storage/AdmissionStorage.js';
+export * from './src/storage/RecoveryContract.js';
 export type { Output } from './src/Output.js';
 export type { TaggedBEEF, STEAK, LookupQuestion, LookupAnswer, AdmittanceInstructions } from '@bsv/sdk';
 export type { LookupFormula } from './src/LookupFormula.js';

package/dist/cjs/mod.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mod.d.ts","sourceRoot":"","sources":["../../mod.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAA;AACxC,OAAO,EAAE,oBAAoB,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAA;AAC1E,mBAAmB,wBAAwB,CAAA;AAC3C,YAAY,EAAE,sBAAsB,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAA;AAGjF,YAAY,EAAE,OAAO,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAA;AAC3E,YAAY,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAA;AAC7C,YAAY,EACV,UAAU,EACV,KAAK,EACL,cAAc,EACd,YAAY,EACZ,sBAAsB,EACvB,MAAM,UAAU,CAAA;AACjB,YAAY,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAA;AAC3D,YAAY,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAA;AAC3D,YAAY,EAAE,iBAAiB,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAA;AACxE,OAAO,EACL,cAAc,EACd,eAAe,EACf,UAAU,EACV,0BAA0B,EAC3B,MAAM,eAAe,CAAA;AACtB,YAAY,EACV,mBAAmB,EACnB,oBAAoB,EACpB,aAAa,EACb,kBAAkB,EAClB,yBAAyB,EACzB,0BAA0B,EAC1B,mBAAmB,EACnB,oBAAoB,EACpB,qBAAqB,EACrB,sBAAsB,EACtB,iBAAiB,EACjB,yBAAyB,EACzB,uBAAuB,EACvB,wBAAwB,EACxB,cAAc,EACd,gBAAgB,EACjB,MAAM,eAAe,CAAA;AAGtB,OAAO,EAAE,WAAW,EAAE,MAAM,mCAAmC,CAAA;AAC/D,OAAO,KAAK,qBAAqB,MAAM,sCAAsC,CAAA"}
+{"version":3,"file":"mod.d.ts","sourceRoot":"","sources":["../../mod.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAA;AACxC,OAAO,EAAE,oBAAoB,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAA;AAC1E,mBAAmB,wBAAwB,CAAA;AAC3C,YAAY,EAAE,sBAAsB,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAA;AAGjF,YAAY,EAAE,OAAO,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAA;AAC3E,OAAO,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAA;AAC9D,cAAc,mCAAmC,CAAA;AACjD,cAAc,mCAAmC,CAAA;AACjD,YAAY,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAA;AAC7C,YAAY,EACV,UAAU,EACV,KAAK,EACL,cAAc,EACd,YAAY,EACZ,sBAAsB,EACvB,MAAM,UAAU,CAAA;AACjB,YAAY,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAA;AAC3D,YAAY,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAA;AAC3D,YAAY,EAAE,iBAAiB,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAA;AACxE,OAAO,EACL,cAAc,EACd,eAAe,EACf,UAAU,EACV,0BAA0B,EAC3B,MAAM,eAAe,CAAA;AACtB,YAAY,EACV,mBAAmB,EACnB,oBAAoB,EACpB,aAAa,EACb,kBAAkB,EAClB,yBAAyB,EACzB,0BAA0B,EAC1B,mBAAmB,EACnB,oBAAoB,EACpB,qBAAqB,EACrB,sBAAsB,EACtB,iBAAiB,EACjB,yBAAyB,EACzB,uBAAuB,EACvB,wBAAwB,EACxB,cAAc,EACd,gBAAgB,EACjB,MAAM,eAAe,CAAA;AAGtB,OAAO,EAAE,WAAW,EAAE,MAAM,mCAAmC,CAAA;AAC/D,OAAO,KAAK,qBAAqB,MAAM,sCAAsC,CAAA"}

package/dist/cjs/mod.js

@@ -15,6 +15,9 @@ var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (
 }) : function(o, v) {
     o["default"] = v;
 });
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
 var __importStar = (this && this.__importStar) || (function () {
     var ownKeys = function(o) {
         ownKeys = Object.getOwnPropertyNames || function (o) {
@@ -33,13 +36,17 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.KnexStorageMigrations = exports.KnexStorage = exports.extractMerkleProofMetadata = exports.computeTac = exports.computeBasmRoot = exports.BASM_ZERO_HASH = exports.serializeLogValue = exports.serializeErrorForLog = exports.Engine = void 0;
+exports.KnexStorageMigrations = exports.KnexStorage = exports.extractMerkleProofMetadata = exports.computeTac = exports.computeBasmRoot = exports.BASM_ZERO_HASH = exports.storageHasAdmission = exports.serializeLogValue = exports.serializeErrorForLog = exports.Engine = void 0;
 // Fundamentals
 var Engine_js_1 = require("./src/Engine.js");
 Object.defineProperty(exports, "Engine", { enumerable: true, get: function () { return Engine_js_1.Engine; } });
 var SafeLog_js_1 = require("./src/SafeLog.js");
 Object.defineProperty(exports, "serializeErrorForLog", { enumerable: true, get: function () { return SafeLog_js_1.serializeErrorForLog; } });
 Object.defineProperty(exports, "serializeLogValue", { enumerable: true, get: function () { return SafeLog_js_1.serializeLogValue; } });
+var Storage_js_1 = require("./src/storage/Storage.js");
+Object.defineProperty(exports, "storageHasAdmission", { enumerable: true, get: function () { return Storage_js_1.storageHasAdmission; } });
+__exportStar(require("./src/storage/AdmissionStorage.js"), exports);
+__exportStar(require("./src/storage/RecoveryContract.js"), exports);
 var BASM_js_1 = require("./src/BASM.js");
 Object.defineProperty(exports, "BASM_ZERO_HASH", { enumerable: true, get: function () { return BASM_js_1.BASM_ZERO_HASH; } });
 Object.defineProperty(exports, "computeBasmRoot", { enumerable: true, get: function () { return BASM_js_1.computeBasmRoot; } });

package/dist/cjs/mod.js.map

@@ -1 +1 @@
-{"version":3,"file":"mod.js","sourceRoot":"","sources":["../../mod.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA,eAAe;AACf,6CAAwC;AAA/B,mGAAA,MAAM,OAAA;AACf,+CAA0E;AAAjE,kHAAA,oBAAoB,OAAA;AAAE,+GAAA,iBAAiB,OAAA;AAiBhD,yCAKsB;AAJpB,yGAAA,cAAc,OAAA;AACd,0GAAA,eAAe,OAAA;AACf,qGAAA,UAAU,OAAA;AACV,qHAAA,0BAA0B,OAAA;AAqB5B,0BAA0B;AAC1B,oEAA+D;AAAtD,6GAAA,WAAW,OAAA;AACpB,QAAY,qBAAqB,iEAA4C"}
+{"version":3,"file":"mod.js","sourceRoot":"","sources":["../../mod.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA,eAAe;AACf,6CAAwC;AAA/B,mGAAA,MAAM,OAAA;AACf,+CAA0E;AAAjE,kHAAA,oBAAoB,OAAA;AAAE,+GAAA,iBAAiB,OAAA;AAMhD,uDAA8D;AAArD,iHAAA,mBAAmB,OAAA;AAC5B,oEAAiD;AACjD,oEAAiD;AAYjD,yCAKsB;AAJpB,yGAAA,cAAc,OAAA;AACd,0GAAA,eAAe,OAAA;AACf,qGAAA,UAAU,OAAA;AACV,qHAAA,0BAA0B,OAAA;AAqB5B,0BAA0B;AAC1B,oEAA+D;AAAtD,6GAAA,WAAW,OAAA;AACpB,QAAY,qBAAqB,iEAA4C"}

package/dist/cjs/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bsv/overlay",
-  "version": "2.3.1",
+  "version": "2.6.1",
   "sideEffects": false,
   "engines": {
     "node": ">=22"
@@ -26,7 +26,7 @@
     "format:check": "pnpm --workspace-root exec prettier --check \"packages/overlays/overlay/{README.md,jest.config.js,mod.ts,package.json,tsconfig*.json}\"",
     "lint": "oxlint mod.ts src jest.config.js --deny-warnings",
     "lint:ci": "pnpm lint",
-    "pack:check": "pnpm build && node ../../../scripts/check-package-artifact.mjs . --exports BASM_ZERO_HASH,Engine,KnexStorage,KnexStorageMigrations,computeBasmRoot,computeTac,extractMerkleProofMetadata,serializeErrorForLog,serializeLogValue --entry-exports \"./storage=;./storage/knex/KnexStorage=KnexStorage\"",
+    "pack:check": "pnpm build && node ../../../scripts/check-package-artifact.mjs . --exports admissionSemanticDigest,canAdvanceGaspCursor,getAdmissionStorage,isRecoveryLeaseCurrent,isReplaySafeProjection,parseStorageUint64,parseStorageOutputIndex,storageHasAdmission,BASM_ZERO_HASH,Engine,KnexStorage,KnexStorageMigrations,computeBasmRoot,computeTac,extractMerkleProofMetadata,serializeErrorForLog,serializeLogValue --entry-exports \"./storage=storageHasAdmission;./storage/knex/KnexStorage=KnexStorage\"",
     "typecheck": "tsc --project tsconfig.base.json --noEmit --incremental false",
     "build": "tsc -b && tsconfig-to-dual-package tsconfig.cjs.json",
     "dev": "tsc -b -w",
@@ -62,18 +62,24 @@
     "ts-jest": "^29.4.12",
     "ts2md": "^0.2.8",
     "tsconfig-to-dual-package": "^1.2.0",
-    "typescript": "npm:@typescript/typescript6@6.0.2"
+    "typescript": "npm:@typescript/typescript6@6.0.2",
+    "mongodb": "7.5.0",
+    "mongodb-memory-server": "^11.2.0"
   },
   "dependencies": {
     "@bsv/gasp": "workspace:^",
     "knex": "^3.3.0"
   },
   "peerDependencies": {
-    "@bsv/sdk": "^2.1.6"
+    "@bsv/sdk": "^2.1.6",
+    "mongodb": "^7.5.0"
   },
   "peerDependenciesMeta": {
     "@bsv/sdk": {
       "optional": false
+    },
+    "mongodb": {
+      "optional": true
     }
   },
   "typesVersions": {

package/dist/cjs/src/BASM.d.ts

@@ -35,6 +35,8 @@ export interface TopicAnchorHeader {
     blockHeight: number;
     blockHash: string;
     merkleRoot?: string;
+    /** Independently obtained full block transaction count, bound to this blockHash. */
+    blockTransactionCount?: number;
 }
 export type TopicAnchorHeaderResolver = (blockHeight: number) => Promise<TopicAnchorHeader | undefined>;
 export interface TopicAnchorRangeRequest {
@@ -87,6 +89,10 @@ export interface BASMPeerSyncReport {
     checkedHeights: number[];
     missingTxids: string[];
     fetchedTxCount: number;
+    /** Weakest position evidence used by this attempt; absent when no proof was checked. */
+    positionValidation?: 'canonical-count' | 'encoded-offset-only';
+    /** Present for classified peer protocol or transport failures. */
+    errorCode?: string;
     message?: string;
 }
 type AdmittedTxLike = string | AdmittedTxRef;

package/dist/cjs/src/BASM.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"BASM.d.ts","sourceRoot":"","sources":["../../../src/BASM.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"BASM.d.ts","sourceRoot":"","sources":["../../../src/BASM.ts"],"names":[],"mappings":"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"}

package/dist/cjs/src/BASM.js

@@ -6,6 +6,7 @@ exports.computeTac = computeTac;
 exports.extractMerkleProofMetadata = extractMerkleProofMetadata;
 const node_crypto_1 = require("node:crypto");
 exports.BASM_ZERO_HASH = '0000000000000000000000000000000000000000000000000000000000000000';
+const MAX_BASM_ROOT_LEAVES = 100000;
 function sha256d(buffer) {
     const first = (0, node_crypto_1.createHash)('sha256').update(buffer).digest();
     return (0, node_crypto_1.createHash)('sha256').update(first).digest();
@@ -23,15 +24,27 @@ function internalToDisplayHex(hash) {
     return Buffer.from(hash).reverse().toString('hex');
 }
 function normalizeAdmittedTxids(admitted) {
-    return admitted
-        .map((item, originalIndex) => {
-        if (typeof item === 'string') {
-            return { txid: item, blockIndex: originalIndex };
+    if (!Array.isArray(admitted) || admitted.length > MAX_BASM_ROOT_LEAVES) {
+        throw new TypeError(`BASM admission sets are capped at ${MAX_BASM_ROOT_LEAVES} entries`);
+    }
+    const normalized = admitted.map((item, originalIndex) => {
+        const candidate = typeof item === 'string' ? { txid: item, blockIndex: originalIndex } : item;
+        if (typeof candidate !== 'object' ||
+            candidate === null ||
+            typeof candidate.txid !== 'string' ||
+            !Number.isSafeInteger(candidate.blockIndex) ||
+            candidate.blockIndex < 0) {
+            throw new TypeError(`BASM admission at index ${originalIndex} is invalid`);
         }
-        return item;
-    })
-        .sort((a, b) => a.blockIndex - b.blockIndex)
-        .map(item => item.txid.toLowerCase());
+        assertHashHex(candidate.txid, `BASM admission at index ${originalIndex}`);
+        return { txid: candidate.txid.toLowerCase(), blockIndex: candidate.blockIndex };
+    });
+    const txids = new Set(normalized.map(item => item.txid));
+    const blockIndexes = new Set(normalized.map(item => item.blockIndex));
+    if (txids.size !== normalized.length || blockIndexes.size !== normalized.length) {
+        throw new TypeError('BASM admission sets must contain unique txids and block indexes');
+    }
+    return normalized.sort((a, b) => a.blockIndex - b.blockIndex).map(item => item.txid);
 }
 /**
  * Computes a BRC-136 BASM root from admitted topic txids.

package/dist/cjs/src/BASM.js.map

@@ -1 +1 @@
-{"version":3,"file":"BASM.js","sourceRoot":"","sources":["../../../src/BASM.ts"],"names":[],"mappings":";;;;;;AAAA,6CAAwC;AAG3B,QAAA,cAAc,GAAG,kEAAkE,CAAA;AA8GhG,SAAS,OAAO,CAAC,MAAc;IAC7B,MAAM,KAAK,GAAG,IAAA,wBAAU,EAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,MAAM,EAAE,CAAA;IAC1D,OAAO,IAAA,wBAAU,EAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,MAAM,EAAE,CAAA;AACpD,CAAC;AAED,SAAS,aAAa,CAAC,IAAY,EAAE,KAAa;IAChD,IAAI,CAAC,mBAAmB,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;QACpC,MAAM,IAAI,KAAK,CAAC,GAAG,KAAK,0BAA0B,CAAC,CAAA;IACrD,CAAC;AACH,CAAC;AAED,SAAS,oBAAoB,CAAC,IAAY;IACxC,aAAa,CAAC,IAAI,EAAE,MAAM,CAAC,CAAA;IAC3B,OAAO,MAAM,CAAC,IAAI,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC,OAAO,EAAE,CAAA;AAC3C,CAAC;AAED,SAAS,oBAAoB,CAAC,IAAY;IACxC,OAAO,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAA;AACpD,CAAC;AAED,SAAS,sBAAsB,CAAC,QAA0B;IACxD,OAAO,QAAQ;SACZ,GAAG,CAAC,CAAC,IAAI,EAAE,aAAa,EAAE,EAAE;QAC3B,IAAI,OAAO,IAAI,KAAK,QAAQ,EAAE,CAAC;YAC7B,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,UAAU,EAAE,aAAa,EAAE,CAAA;QAClD,CAAC;QACD,OAAO,IAAI,CAAA;IACb,CAAC,CAAC;SACD,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,UAAU,GAAG,CAAC,CAAC,UAAU,CAAC;SAC3C,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC,CAAA;AACzC,CAAC;AAED;;;;;;;GAOG;AACH,yBAAgC,QAA0B;IACxD,MAAM,KAAK,GAAG,sBAAsB,CAAC,QAAQ,CAAC,CAAA;IAE9C,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACvB,OAAO,QAAA,cAAc,CAAA;IACvB,CAAC;IAED,IAAI,KAAK,GAAG,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,oBAAoB,CAAC,IAAI,CAAC,CAAC,CAAA;IACzD,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACvB,OAAO,oBAAoB,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAA;IACvC,CAAC;IAED,OAAO,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACxB,MAAM,IAAI,GAAa,EAAE,CAAA;QACzB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC;YACzC,MAAM,IAAI,GAAG,KAAK,CAAC,CAAC,CAAC,CAAA;YACrB,MAAM,KAAK,GAAG,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAA;YACxD,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC,CAAA;QAClD,CAAC;QACD,KAAK,GAAG,IAAI,CAAA;IACd,CAAC;IAED,OAAO,oBAAoB,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAA;AACvC,CAAC;AAED;;;;GAIG;AACH,oBAA2B,OAAe,EAAE,SAAiB,EAAE,QAAgB;IAC7E,MAAM,KAAK,GAAG,MAAM,CAAC,MAAM,CAAC;QAC1B,oBAAoB,CAAC,OAAO,CAAC,WAAW,EAAE,CAAC;QAC3C,oBAAoB,CAAC,SAAS,CAAC,WAAW,EAAE,CAAC;QAC7C,oBAAoB,CAAC,QAAQ,CAAC,WAAW,EAAE,CAAC;KAC7C,CAAC,CAAA;IACF,OAAO,oBAAoB,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAA;AAC7C,CAAC;AAED,oCAA2C,IAAY,EAAE,KAAkB;;IACzE,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;QACxB,OAAO,SAAS,CAAA;IAClB,CAAC;IAED,MAAM,IAAI,GAAG,MAAA,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,0CAAE,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC,SAAS,CAAC,IAAI,KAAK,IAAI,CAAC,CAAA;IACtE,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;QACvB,OAAO,SAAS,CAAA;IAClB,CAAC;IAED,OAAO;QACL,WAAW,EAAE,KAAK,CAAC,WAAW;QAC9B,UAAU,EAAE,IAAI,CAAC,MAAM;QACvB,UAAU,EAAE,KAAK,CAAC,WAAW,CAAC,IAAI,CAAC;KACpC,CAAA;AACH,CAAC"}
+{"version":3,"file":"BASM.js","sourceRoot":"","sources":["../../../src/BASM.ts"],"names":[],"mappings":"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"}

package/dist/cjs/src/BASMRemote.d.ts

@@ -1,14 +1,21 @@
 import type { AdmittedListResponse, CompoundMerklePathResponse, RawTransactionResponse, TopicAnchorRangeResponse, TopicAnchorTip } from './BASM.js';
+import type { BASMRemoteLimits } from './BASMValidation.js';
+export { BASMProtocolError } from './BASMValidation.js';
+export type { BASMRemoteLimits } from './BASMValidation.js';
 export declare class BASMRemote {
+    private readonly limits;
     private readonly endpoint;
     private readonly topic;
     private readonly fetchImpl;
-    constructor(endpoint: string, topic: string, fetchImpl?: typeof fetch);
+    constructor(endpoint: string, topic: string, fetchImpl?: typeof fetch, limits?: Partial<BASMRemoteLimits>);
     requestTopicAnchorTip(): Promise<TopicAnchorTip>;
     requestTopicAnchorRange(fromHeight: number, toHeight: number): Promise<TopicAnchorRangeResponse>;
     requestAdmittedList(blockHeight: number, blockHash?: string): Promise<AdmittedListResponse>;
     requestCompoundMerklePath(blockHeight: number, txids: string[]): Promise<CompoundMerklePathResponse>;
     requestRawTransactions(txids: string[]): Promise<RawTransactionResponse>;
+    private requireCoordinate;
+    private readResponse;
     private post;
+    private postResponse;
 }
 //# sourceMappingURL=BASMRemote.d.ts.map

package/dist/cjs/src/BASMRemote.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"BASMRemote.d.ts","sourceRoot":"","sources":["../../../src/BASMRemote.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,oBAAoB,EACpB,0BAA0B,EAC1B,sBAAsB,EACtB,wBAAwB,EACxB,cAAc,EACf,MAAM,WAAW,CAAA;AAElB,qBAAa,UAAU;IAEnB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,SAAS;IAH5B,YACmB,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,EACb,SAAS,GAAE,OAAO,KAA8B,EAC9D;IAEC,qBAAqB,IAAI,OAAO,CAAC,cAAc,CAAC,CAErD;IAEK,uBAAuB,CAAC,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,wBAAwB,CAAC,CAErG;IAEK,mBAAmB,CAAC,WAAW,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAEhG;IAEK,yBAAyB,CAAC,WAAW,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,0BAA0B,CAAC,CAEzG;IAEK,sBAAsB,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,sBAAsB,CAAC,CAE7E;YAEa,IAAI;CAkBnB"}
+{"version":3,"file":"BASMRemote.d.ts","sourceRoot":"","sources":["../../../src/BASMRemote.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,oBAAoB,EACpB,0BAA0B,EAC1B,sBAAsB,EACtB,wBAAwB,EACxB,cAAc,EACf,MAAM,WAAW,CAAA;AAelB,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAA;AAG3D,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAA;AACvD,YAAY,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAA;AAE3D,qBAAa,UAAU;IACrB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA4B;IACnD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAQ;IACjC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAQ;IAC9B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAc;IAExC,YACE,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,EACb,SAAS,CAAC,EAAE,OAAO,KAAK,EACxB,MAAM,GAAE,OAAO,CAAC,gBAAgB,CAAM,EAavC;IAEK,qBAAqB,IAAI,OAAO,CAAC,cAAc,CAAC,CAErD;IAEK,uBAAuB,CAC3B,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,wBAAwB,CAAC,CA2BnC;IAEK,mBAAmB,CACvB,WAAW,EAAE,MAAM,EACnB,SAAS,CAAC,EAAE,MAAM,GACjB,OAAO,CAAC,oBAAoB,CAAC,CAiB/B;IAEK,yBAAyB,CAC7B,WAAW,EAAE,MAAM,EACnB,KAAK,EAAE,MAAM,EAAE,GACd,OAAO,CAAC,0BAA0B,CAAC,CAoBrC;IAEK,sBAAsB,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,sBAAsB,CAAC,CAkC7E;IAED,OAAO,CAAC,iBAAiB;YAOX,YAAY;YA6CZ,IAAI;YAkBJ,YAAY;CA8C3B"}

package/dist/cjs/src/BASMRemote.js

@@ -1,28 +1,169 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.BASMRemote = void 0;
+exports.BASMRemote = exports.BASMProtocolError = void 0;
+const BASMValidation_js_1 = require("./BASMValidation.js");
+const RemoteSecurity_js_1 = require("./RemoteSecurity.js");
+var BASMValidation_js_2 = require("./BASMValidation.js");
+Object.defineProperty(exports, "BASMProtocolError", { enumerable: true, get: function () { return BASMValidation_js_2.BASMProtocolError; } });
 class BASMRemote {
-    constructor(endpoint, topic, fetchImpl = fetch.bind(globalThis)) {
-        this.endpoint = endpoint;
+    constructor(endpoint, topic, fetchImpl, limits = {}) {
+        (0, RemoteSecurity_js_1.assertTopic)(topic);
+        const secured = (0, RemoteSecurity_js_1.securePeerFetch)(endpoint, fetchImpl);
+        this.endpoint = secured.endpoint;
         this.topic = topic;
-        this.fetchImpl = fetchImpl;
+        this.fetchImpl = secured.fetchImpl;
+        this.limits = Object.freeze({ ...BASMValidation_js_1.DEFAULT_BASM_REMOTE_LIMITS, ...limits });
+        for (const [key, value] of Object.entries(this.limits)) {
+            if (!Number.isSafeInteger(value) || value <= 0)
+                throw new TypeError(`Invalid BASM limit: ${key}`);
+        }
+        if (this.limits.timeoutMs > 2147483647)
+            throw new TypeError('BASM timeout exceeds timer range');
     }
     async requestTopicAnchorTip() {
-        return await this.post('/requestTopicAnchorTip', {});
+        return (0, BASMValidation_js_1.basmTip)(await this.post('/requestTopicAnchorTip', {}), this.topic);
     }
     async requestTopicAnchorRange(fromHeight, toHeight) {
-        return await this.post('/requestTopicAnchorRange', { fromHeight, toHeight });
+        (0, BASMValidation_js_1.basmInteger)(fromHeight, 'range start');
+        (0, BASMValidation_js_1.basmInteger)(toHeight, 'range end', fromHeight);
+        (0, BASMValidation_js_1.requireBASMLimit)(toHeight - fromHeight < this.limits.maxAnchorRange, 'BASM anchor range exceeds limit');
+        const obj = (0, BASMValidation_js_1.basmObject)(await this.post('/requestTopicAnchorRange', { fromHeight, toHeight }));
+        (0, BASMValidation_js_1.requireBASM)(obj.topic === this.topic && Array.isArray(obj.anchors), 'Invalid BASM anchor range');
+        (0, BASMValidation_js_1.requireBASMLimit)(obj.anchors.length <= toHeight - fromHeight + 1, 'BASM anchor count exceeds requested range');
+        const anchors = obj.anchors.map(value => (0, BASMValidation_js_1.basmAnchor)(value, this.topic));
+        let previousHeight;
+        for (const anchor of anchors) {
+            (0, BASMValidation_js_1.requireBASM)(anchor.blockHeight >= fromHeight && anchor.blockHeight <= toHeight, 'BASM anchor outside requested range');
+            (0, BASMValidation_js_1.requireBASM)(previousHeight === undefined || anchor.blockHeight === previousHeight + 1, 'BASM anchor range has a gap or is unordered');
+            previousHeight = anchor.blockHeight;
+        }
+        return { topic: this.topic, anchors };
     }
     async requestAdmittedList(blockHeight, blockHash) {
-        return await this.post('/requestAdmittedList', { blockHeight, blockHash });
+        (0, BASMValidation_js_1.basmInteger)(blockHeight, 'height');
+        if (blockHash !== undefined)
+            (0, BASMValidation_js_1.basmHash)(blockHash, 'block hash');
+        const obj = (0, BASMValidation_js_1.basmObject)(await this.post('/requestAdmittedList', { blockHeight, blockHash }));
+        this.requireCoordinate(obj, blockHeight);
+        const responseHash = obj.blockHash === undefined ? undefined : (0, BASMValidation_js_1.basmHash)(obj.blockHash, 'block hash');
+        (0, BASMValidation_js_1.requireBASM)(blockHash === undefined || responseHash === undefined || responseHash === blockHash, 'BASM admitted block hash mismatch');
+        return {
+            topic: this.topic,
+            blockHeight,
+            ...(responseHash === undefined ? {} : { blockHash: responseHash }),
+            admitted: (0, BASMValidation_js_1.basmAdmitted)(obj.admitted, this.limits.maxAdmittedTxids)
+        };
     }
     async requestCompoundMerklePath(blockHeight, txids) {
-        return await this.post('/requestCompoundMerklePath', { blockHeight, txids });
+        (0, BASMValidation_js_1.basmInteger)(blockHeight, 'height');
+        const requested = (0, BASMValidation_js_1.basmTxids)(txids, this.limits.maxRequestedTxids);
+        (0, BASMValidation_js_1.requireBASM)(requested.length > 0, 'At least one BASM proof txid is required');
+        const obj = (0, BASMValidation_js_1.basmObject)(await this.post('/requestCompoundMerklePath', { blockHeight, txids: requested }));
+        this.requireCoordinate(obj, blockHeight);
+        const returned = (0, BASMValidation_js_1.basmTxids)(obj.txids, requested.length);
+        const requestedSet = new Set(requested);
+        (0, BASMValidation_js_1.requireBASM)(returned.length === requested.length && returned.every(txid => requestedSet.has(txid)), 'BASM proof txids do not match request');
+        return {
+            topic: this.topic,
+            blockHeight,
+            txids: returned,
+            merklePath: (0, BASMValidation_js_1.basmHex)(obj.merklePath, 'Merkle path', this.limits.maxProofBytes)
+        };
     }
     async requestRawTransactions(txids) {
-        return await this.post('/requestRawTransactions', { txids });
+        const requested = new Set((0, BASMValidation_js_1.basmTxids)(txids, this.limits.maxRequestedTxids));
+        const obj = (0, BASMValidation_js_1.basmObject)(await this.post('/requestRawTransactions', { txids: [...requested] }));
+        (0, BASMValidation_js_1.requireBASM)(Array.isArray(obj.transactions), 'Invalid BASM raw transactions');
+        (0, BASMValidation_js_1.requireBASMLimit)(obj.transactions.length <= requested.size, 'BASM raw transaction count exceeds request');
+        const seen = new Set();
+        const transactions = obj.transactions.map(value => {
+            const record = (0, BASMValidation_js_1.basmObject)(value);
+            const txid = (0, BASMValidation_js_1.basmHash)(record.txid, 'txid');
+            (0, BASMValidation_js_1.requireBASM)(requested.has(txid) && !seen.has(txid), 'Unexpected or duplicate BASM raw transaction');
+            seen.add(txid);
+            const rawTx = (0, BASMValidation_js_1.basmHex)(record.rawTx, 'raw transaction', this.limits.maxRawTransactionBytes);
+            (0, RemoteSecurity_js_1.assertRawTransactionMatches)(txid, rawTx);
+            return {
+                txid,
+                rawTx
+            };
+        });
+        const missing = (0, BASMValidation_js_1.basmTxids)(obj.missing, requested.size);
+        for (const txid of missing) {
+            (0, BASMValidation_js_1.requireBASM)(requested.has(txid) && !seen.has(txid), 'Unexpected or conflicting BASM missing txid');
+            seen.add(txid);
+        }
+        (0, BASMValidation_js_1.requireBASM)(seen.size === requested.size, 'BASM raw response omits requested txids');
+        return { transactions, missing };
+    }
+    requireCoordinate(obj, blockHeight) {
+        (0, BASMValidation_js_1.requireBASM)(obj.topic === this.topic && obj.blockHeight === blockHeight, 'BASM response topic or height mismatch');
+    }
+    async readResponse(response, signal) {
+        var _a, _b;
+        const advertisedLength = (_a = response.headers) === null || _a === void 0 ? void 0 : _a.get('content-length');
+        if (advertisedLength !== null && advertisedLength !== undefined) {
+            if (Number(advertisedLength) > this.limits.maxResponseBytes) {
+                void ((_b = response.body) === null || _b === void 0 ? void 0 : _b.cancel().catch(() => { }));
+                (0, BASMValidation_js_1.requireBASMLimit)(false, 'BASM response exceeds byte limit');
+            }
+        }
+        // Preserve injected fetch implementations that expose only text(). Real HTTP
+        // responses are bounded while streaming, including decoded chunked bodies.
+        if (response.body === undefined || response.body === null) {
+            const text = await response.text();
+            (0, BASMValidation_js_1.requireBASMLimit)(Buffer.byteLength(text) <= this.limits.maxResponseBytes, 'BASM response exceeds byte limit');
+            return text;
+        }
+        const reader = response.body.getReader();
+        const chunks = [];
+        let size = 0;
+        const cancel = () => {
+            void reader.cancel().catch(() => { });
+        };
+        signal.addEventListener('abort', cancel, { once: true });
+        try {
+            while (true) {
+                signal.throwIfAborted();
+                const { done, value } = await reader.read();
+                if (done)
+                    break;
+                size += value.byteLength;
+                (0, BASMValidation_js_1.requireBASMLimit)(size <= this.limits.maxResponseBytes, 'BASM response exceeds byte limit');
+                chunks.push(value);
+            }
+            signal.throwIfAborted();
+            return Buffer.concat(chunks, size).toString('utf8');
+        }
+        catch (error) {
+            cancel();
+            throw error;
+        }
+        finally {
+            signal.removeEventListener('abort', cancel);
+            reader.releaseLock();
+        }
     }
     async post(path, body) {
+        const controller = new AbortController();
+        let timer;
+        const deadline = new Promise((_resolve, reject) => {
+            timer = setTimeout(() => {
+                const error = new BASMValidation_js_1.BASMProtocolError('BASM_TIMEOUT', 'BASM request timed out');
+                controller.abort(error);
+                reject(error);
+            }, this.limits.timeoutMs);
+        });
+        try {
+            return await Promise.race([this.postResponse(path, body, controller.signal), deadline]);
+        }
+        finally {
+            clearTimeout(timer);
+            controller.abort();
+        }
+    }
+    async postResponse(path, body, signal) {
+        var _a, _b, _c, _d;
         const response = await this.fetchImpl(new URL(path, this.endpoint).toString(), {
             method: 'POST',
             headers: {
@@ -30,13 +171,38 @@ class BASMRemote {
                 'Content-Type': 'application/json',
                 'x-bsv-topic': this.topic
             },
-            body: JSON.stringify(body)
+            body: JSON.stringify(body),
+            signal
         });
-        const text = await response.text();
+        if (signal.aborted) {
+            void ((_a = response.body) === null || _a === void 0 ? void 0 : _a.cancel().catch(() => { }));
+            signal.throwIfAborted();
+        }
+        const contentType = (_c = (_b = response.headers) === null || _b === void 0 ? void 0 : _b.get) === null || _c === void 0 ? void 0 : _c.call(_b, 'content-type');
+        if (contentType !== null &&
+            contentType !== undefined &&
+            contentType.includes('/') &&
+            !/^application\/(?:[\w.-]+\+)?json(?:\s*;|$)/i.test(contentType)) {
+            void ((_d = response.body) === null || _d === void 0 ? void 0 : _d.cancel().catch(() => { }));
+            throw new TypeError('Overlay peer response is not JSON');
+        }
+        const text = await this.readResponse(response, signal);
+        let value;
+        try {
+            value = JSON.parse(text);
+        }
+        catch {
+            if (response.ok)
+                throw new BASMValidation_js_1.BASMProtocolError('BASM_INVALID_RESPONSE', 'Invalid BASM JSON response');
+        }
         if (!response.ok) {
-            throw new Error(`BASM peer ${this.endpoint} returned ${response.status}: ${text}`);
+            const code = typeof value === 'object' && value !== null && 'code' in value ? value.code : undefined;
+            if (response.status === 501 || code === 'BASM_UNSUPPORTED') {
+                throw new BASMValidation_js_1.BASMProtocolError('BASM_UNSUPPORTED', `BASM peer returned HTTP ${response.status}: unsupported BASM capability`);
+            }
+            throw new BASMValidation_js_1.BASMProtocolError('BASM_HTTP_ERROR', `BASM peer returned HTTP ${response.status}`);
         }
-        return (text.length === 0 ? {} : JSON.parse(text));
+        return value;
     }
 }
 exports.BASMRemote = BASMRemote;