swarmlite 0.2.0

package/src/publisher.js

@@ -0,0 +1,240 @@
+// The pure-JS publisher: stamps, upload, and signed feed updates over
+// a Bee node's HTTP API — so a JS developer never needs the Python
+// package. Mirrors swarmlite/publish.py + swarmfs (stamps.py, feeds.py)
+// behavior for behavior; the signing math is checked byte-for-byte
+// against swarmfs-generated fixtures (RFC 6979 is deterministic).
+//
+// Money rules match the Python side exactly: `autoStamp` selects, and
+// `planBatch`/`buyBatch` exist as capabilities — nothing here spends
+// xBZZ unless the caller explicitly asks (the CLI asks the human).
+
+// signing uses built-in WebCrypto (noble's signAsync); Node 18 has it
+// under node:crypto rather than on globalThis — browsers skip this
+if (!globalThis.crypto?.subtle) {
+  const { webcrypto } = await import('node:crypto');
+  globalThis.crypto = webcrypto;
+}
+
+import { getPublicKey, signAsync } from '../vendor/noble-secp256k1/index.js';
+import { keccak256Bytes } from '../vendor/js-sha3/index.js';
+import { chunkAddress, feedIdentifier, fromHex, socAddress, toHex } from './verify.js';
+import { topicHex } from './feeds.js';
+
+const BLOCK_SECS = 5; // Gnosis block time
+const PLUR_PER_BZZ = 10 ** 16;
+const MIN_TTL_SECS = 60;
+
+// upload size -> batch depth; see swarmfs stamps.py — an immutable
+// batch dies when any single bucket fills (measured live: one 42 MB
+// upload filled a depth-18 batch), so keep overflow risk under ~5%
+const DEPTH_TIERS = [[15 * 2 ** 20, 18], [150 * 2 ** 20, 19], [2 ** 30, 20]];
+
+export class PublishError extends Error {
+  name = 'PublishError';
+}
+
+const doFetch = (fetchFn) => fetchFn ?? ((...args) => globalThis.fetch(...args));
+
+async function checkOk(resp, what) {
+  if (resp.ok) return resp;
+  const detail = (await resp.text().catch(() => '')).slice(0, 200);
+  throw new PublishError(`Bee API ${resp.status} for ${what}: ${detail}`);
+}
+
+// ---- stamps ----------------------------------------------------------------
+
+/** Pick the usable batch with the longest TTL (swarmfs auto-selection). */
+export async function autoStamp(apiUrl, { fetchFn } = {}) {
+  const resp = await checkOk(await doFetch(fetchFn)(`${apiUrl}/stamps`), '/stamps');
+  const stamps = (await resp.json()).stamps ?? [];
+  const usable = stamps.filter((s) =>
+    s.usable && !(s.utilizationRatio >= 1.0) &&
+    !(s.batchTTL >= 0 && s.batchTTL <= MIN_TTL_SECS));
+  if (!usable.length) {
+    throw new PublishError(
+      stamps.length
+        ? `no usable postage stamp on ${apiUrl}: ` + stamps.map((s) =>
+            `${s.batchID.slice(0, 8)}…(${s.usable ? 'full or expiring' : 'not usable'})`).join('; ')
+        : `no postage stamps on ${apiUrl} — buy one first (planBatch/buyBatch, ` +
+          'or `swarmlite publish --buy` from the Python CLI)',
+    );
+  }
+  return usable.reduce((a, b) =>
+    (b.batchTTL ?? -1) > (a.batchTTL ?? -1) ? b : a).batchID;
+}
+
+export function suggestDepth(sizeBytes) {
+  for (const [limit, depth] of DEPTH_TIERS) {
+    if (sizeBytes <= limit) return depth;
+  }
+  return 20 + Math.ceil(Math.log2(sizeBytes / 2 ** 30));
+}
+
+/** Price a batch for sizeBytes lasting ttlSecs (floor padded an hour
+ * above the chain's strict 24h minimum — mirrors swarmfs). */
+export async function planBatch(apiUrl, sizeBytes, ttlSecs, { fetchFn } = {}) {
+  const resp = await checkOk(await doFetch(fetchFn)(`${apiUrl}/chainstate`), '/chainstate');
+  const chain = await resp.json();
+  const price = Number(chain.currentPrice);
+  const floor = Number(chain.minimumValidityBlocks ?? 0) + 3600 / BLOCK_SECS;
+  const blocks = Math.max(Math.ceil(ttlSecs / BLOCK_SECS), floor);
+  const depth = suggestDepth(sizeBytes);
+  const amount = blocks * price;
+  return { depth, amount, ttlSecs: blocks * BLOCK_SECS,
+           costBzz: amount * 2 ** depth / PLUR_PER_BZZ };
+}
+
+/** Buy a batch and poll until usable. Spends the node wallet's xBZZ —
+ * callers decide, this only executes. Every failure path after the
+ * purchase carries the batch id. */
+export async function buyBatch(apiUrl, amount, depth, { fetchFn, waitSecs = 300 } = {}) {
+  const f = doFetch(fetchFn);
+  const resp = await checkOk(
+    await f(`${apiUrl}/stamps/${amount}/${depth}`, { method: 'POST' }),
+    'POST /stamps');
+  const batchId = (await resp.json()).batchID;
+  const deadline = Date.now() + waitSecs * 1000;
+  while (Date.now() < deadline) {
+    const poll = await f(`${apiUrl}/stamps/${batchId}`);
+    if (poll.ok && (await poll.json()).usable) return batchId;
+    if (!poll.ok && poll.status !== 400 && poll.status !== 404) {
+      throw new PublishError(
+        `batch ${batchId} was bought (tx submitted) but polling failed ` +
+        `(HTTP ${poll.status}) — check ${apiUrl}/stamps/${batchId} and ` +
+        'use it once usable');
+    }
+    await new Promise((r) => setTimeout(r, 3000));
+  }
+  throw new PublishError(
+    `batch ${batchId} was bought but is still not usable after ${waitSecs}s ` +
+    `— check ${apiUrl}/stamps/${batchId} and use it once usable`);
+}
+
+// ---- upload ----------------------------------------------------------------
+
+/** Upload one file via POST /bzz (Bee builds the single-file manifest).
+ * Returns the manifest root reference. */
+export async function uploadFile(apiUrl, name, bytes, stamp, { fetchFn } = {}) {
+  const resp = await checkOk(await doFetch(fetchFn)(
+    `${apiUrl}/bzz?name=${encodeURIComponent(name)}`,
+    {
+      method: 'POST',
+      body: bytes,
+      headers: {
+        'Content-Type': 'application/octet-stream',
+        'Swarm-Postage-Batch-Id': stamp,
+      },
+    },
+  ), 'POST /bzz');
+  return (await resp.json()).reference;
+}
+
+// ---- signed feed updates ---------------------------------------------------
+
+/** The feed owner's 20-byte address for a private key, as hex. */
+export function ownerAddress(privateKeyHex) {
+  const pub = getPublicKey(privateKeyHex.replace(/^0x/, ''), false); // uncompressed
+  return toHex(keccak256Bytes(pub.subarray(1)).subarray(12));
+}
+
+async function personalSign(digest32, privateKeyHex) {
+  const prefixed = keccak256Bytes(concat(
+    new TextEncoder().encode('\x19Ethereum Signed Message:\n32'), digest32));
+  const sig = await signAsync(prefixed, privateKeyHex.replace(/^0x/, ''));
+  const out = new Uint8Array(65);
+  out.set(sig.toBytes(), 0); // r ‖ s (compact)
+  out[64] = sig.recovery + 27;
+  return out;
+}
+
+function concat(...parts) {
+  const out = new Uint8Array(parts.reduce((n, p) => n + p.length, 0));
+  let off = 0;
+  for (const p of parts) { out.set(p, off); off += p.length; }
+  return out;
+}
+
+const cacData = (payload) => {
+  const span = new Uint8Array(8);
+  new DataView(span.buffer).setBigUint64(0, BigInt(payload.length), true);
+  return concat(span, payload);
+};
+
+/** Build one signed feed-update chunk (bee-js format: timestamp + ref).
+ * Pure function of its inputs — testable against swarmfs fixtures. */
+export async function buildFeedUpdate(privateKeyHex, topic, index, referenceHex, timestamp) {
+  const identifier = feedIdentifier(fromHex(topicHex(topic)), index);
+  const ts = new Uint8Array(8);
+  new DataView(ts.buffer).setBigUint64(0, BigInt(timestamp), false);
+  const data = cacData(concat(ts, fromHex(referenceHex)));
+  const digest = keccak256Bytes(concat(identifier, chunkAddress(data)));
+  const signature = await personalSign(digest, privateKeyHex);
+  return { identifier, signature, data,
+           soc: concat(identifier, signature, data) };
+}
+
+/** Publish `referenceHex` as the feed's next update. */
+export async function updateFeed(apiUrl, privateKeyHex, topic, referenceHex, stamp,
+                                 { fetchFn, timestamp } = {}) {
+  const f = doFetch(fetchFn);
+  const owner = ownerAddress(privateKeyHex);
+  // next index: current head + 1, or 0 for a fresh feed
+  const head = await f(
+    `${apiUrl}/feeds/${owner}/${topicHex(topic)}?type=sequence`,
+    { headers: { 'Swarm-Only-Root-Chunk': 'true' } });
+  await head.body?.cancel?.();
+  const headIndex = head.ok ? head.headers.get('swarm-feed-index') : null;
+  const index = headIndex ? parseInt(headIndex, 16) + 1 : 0;
+
+  const { identifier, signature, data } = await buildFeedUpdate(
+    privateKeyHex, topic, index, referenceHex,
+    timestamp ?? Math.floor(Date.now() / 1000));
+  await checkOk(await f(
+    `${apiUrl}/soc/${owner}/${toHex(identifier)}?sig=${toHex(signature)}`,
+    {
+      method: 'POST',
+      body: data,
+      headers: { 'Swarm-Postage-Batch-Id': stamp },
+    },
+  ), 'POST /soc');
+  return { owner, index };
+}
+
+// ---- orchestration ---------------------------------------------------------
+
+/** The whole publish flow: prepare -> upload -> optionally advance a
+ * feed. Returns { root, warnings, feed? }. `log` receives the human
+ * lines (pin/feed/warnings); pass a no-op for quiet. */
+export async function publish(bytes, {
+  apiUrl = 'http://localhost:1633',
+  name = 'site.db',
+  stamp = 'auto',
+  feed = null,
+  signer = null,
+  fetchFn,
+  moduleOptions,
+  log = () => {},
+} = {}) {
+  const { prepare } = await import('./prepare.js');
+  const { bytes: prepared, warnings } = await prepare(bytes, { moduleOptions });
+  for (const w of warnings) log(`warning: ${w}`);
+
+  if (!stamp || stamp === 'auto') stamp = await autoStamp(apiUrl, { fetchFn });
+  const root = await uploadFile(apiUrl, name, prepared, stamp, { fetchFn });
+  log(`pin:  bzz://${root}/${name}`);
+
+  let feedInfo = null;
+  if (feed) {
+    if (!signer) {
+      throw new PublishError(
+        'feed publishing needs a signer key: pass signer (the feed ' +
+        "owner's private key hex)");
+    }
+    feedInfo = await updateFeed(apiUrl, signer, feed, root, stamp, { fetchFn });
+    log(`feed: bzzf://${feedInfo.owner}/${feed}/${name}`);
+  } else {
+    log('tip:  this URL names exactly this version. If the data will ' +
+        'change, republish with a feed so readers get one stable URL');
+  }
+  return { root, warnings, feed: feedInfo };
+}

package/src/verify.js

@@ -0,0 +1,267 @@
+// Client-side verification: BMT chunk addressing, a verifying chunk
+// store over GET /chunks, a verified tree reader, and single-owner
+// chunk (feed update) verification. Line-for-line ports of swarmfs's
+// bmt.py / join.py / feeds.py — the two implementations are held
+// together by shared fixtures (js/test/fixtures/, generated BY swarmfs).
+//
+// This is what makes reads through an UNTRUSTED endpoint (a public
+// gateway) actually trustless: a Swarm reference is the hash of the
+// content, so a tampering gateway is caught on the first bad chunk.
+// Against a local light node the node verifies natively and the plain
+// Range-read path is faster — see open()'s `verify` option.
+
+import { keccak256Bytes } from '../vendor/js-sha3/index.js';
+import { Signature } from '../vendor/noble-secp256k1/index.js';
+
+export const CHUNK_SIZE = 4096;
+const SEGMENT = 32;
+const REF_SIZE = 32;
+const SOC_IDENTIFIER_SIZE = 32;
+const SOC_SIGNATURE_SIZE = 65;
+const SOC_SPAN_OFFSET = SOC_IDENTIFIER_SIZE + SOC_SIGNATURE_SIZE; // 97
+const FETCH_TIMEOUT_MS = 30_000;
+
+export class VerificationError extends Error {
+  name = 'VerificationError';
+}
+
+export const toHex = (bytes) =>
+  Array.from(bytes, (b) => b.toString(16).padStart(2, '0')).join('');
+
+export function fromHex(hex) {
+  const out = new Uint8Array(hex.length / 2);
+  for (let i = 0; i < out.length; i++) {
+    out[i] = parseInt(hex.slice(2 * i, 2 * i + 2), 16);
+  }
+  return out;
+}
+
+function concat(...parts) {
+  const out = new Uint8Array(parts.reduce((n, p) => n + p.length, 0));
+  let off = 0;
+  for (const p of parts) { out.set(p, off); off += p.length; }
+  return out;
+}
+
+// ---- BMT addressing -------------------------------------------------------
+
+/** Root of the binary Merkle tree over 32-byte segments of the payload,
+ * zero-padded to 4096 bytes. */
+export function bmtRoot(payload) {
+  if (payload.length > CHUNK_SIZE) {
+    throw new VerificationError(`payload size ${payload.length} exceeds ${CHUNK_SIZE}`);
+  }
+  const padded = new Uint8Array(CHUNK_SIZE);
+  padded.set(payload);
+  let level = [];
+  for (let i = 0; i < CHUNK_SIZE; i += SEGMENT) {
+    level.push(padded.subarray(i, i + SEGMENT));
+  }
+  while (level.length > 1) {
+    const next = [];
+    for (let i = 0; i < level.length; i += 2) {
+      next.push(keccak256Bytes(concat(level[i], level[i + 1])));
+    }
+    level = next;
+  }
+  return level[0];
+}
+
+/** BMT address of a content-addressed chunk (data = span + payload). */
+export function chunkAddress(data) {
+  return keccak256Bytes(concat(data.subarray(0, 8), bmtRoot(data.subarray(8))));
+}
+
+/** Little-endian span -> content length. Bee stores the erasure-coding
+ * redundancy level in the top byte (span[7] > 128). */
+export function decodeSpan(span) {
+  let size = 0;
+  for (let i = 6; i >= 0; i--) size = size * 256 + span[i];
+  if (span[7] <= 128) size += span[7] * 256 ** 7;
+  return size;
+}
+
+// ---- verifying chunk store ------------------------------------------------
+
+/** Fetches raw chunks via GET /chunks/{ref} and verifies each against
+ * the reference it was requested by. Content-addressed, so the cache
+ * never goes stale. */
+export class VerifiedChunkStore {
+  #cache = new Map(); // ref hex -> Uint8Array (Map keeps LRU order)
+  #cacheChunks;
+  #fetch;
+  apiUrl;
+  stats = { chunksFetched: 0, bytesFetched: 0 };
+
+  constructor(apiUrl, { cacheChunks = 4096, fetchFn } = {}) {
+    this.apiUrl = apiUrl.replace(/\/+$/, '');
+    this.#cacheChunks = Math.max(1, cacheChunks);
+    this.#fetch = fetchFn ?? ((...args) => globalThis.fetch(...args));
+  }
+
+  /** One verified chunk (span + payload) by 64-hex reference. */
+  async chunk(refHex) {
+    const hit = this.#cache.get(refHex);
+    if (hit !== undefined) {
+      this.#cache.delete(refHex); // refresh LRU position
+      this.#cache.set(refHex, hit);
+      return hit;
+    }
+    const resp = await this.#fetch(`${this.apiUrl}/chunks/${refHex}`, {
+      signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),
+    });
+    if (!resp.ok) {
+      throw new Error(`HTTP ${resp.status} fetching chunk ${refHex.slice(0, 16)}…`);
+    }
+    const data = new Uint8Array(await resp.arrayBuffer());
+    if (toHex(chunkAddress(data)) !== refHex) {
+      throw new VerificationError(
+        `chunk ${refHex.slice(0, 16)}… failed verification: content does ` +
+        'not hash to its address (tampering, corruption, or a bad endpoint)',
+      );
+    }
+    this.stats.chunksFetched += 1;
+    this.stats.bytesFetched += data.length;
+    this.#cache.set(refHex, data);
+    while (this.#cache.size > this.#cacheChunks) {
+      this.#cache.delete(this.#cache.keys().next().value);
+    }
+    return data;
+  }
+}
+
+// ---- verified tree reader -------------------------------------------------
+
+function rootRef(refHex) {
+  if (refHex.length !== 64) {
+    throw new VerificationError(
+      `cannot verify reference ${refHex.slice(0, 16)}…: encrypted ` +
+      '(128-hex) references are not supported by the verifying reader yet',
+    );
+  }
+  return refHex;
+}
+
+/** Verified content length of a reference. */
+export async function verifiedSize(store, refHex) {
+  return decodeSpan((await store.chunk(rootRef(refHex))).subarray(0, 8));
+}
+
+/** Verified read of [start, end) of a reference's content, descending
+ * only the subtrees the range needs. */
+export async function verifiedRead(store, refHex, start, end) {
+  const chunk = await store.chunk(rootRef(refHex));
+  const size = decodeSpan(chunk.subarray(0, 8));
+  const s = Math.min(start ?? 0, size);
+  const e = end === undefined ? size : Math.min(end, size);
+  if (e <= s) return new Uint8Array(0);
+  const out = new Uint8Array(e - s);
+  await readTree(store, chunk, s, e, out, 0);
+  return out;
+}
+
+/** Append [start, end) of this subtree (both subtree-relative) into
+ * out at outPos; returns bytes written. An intermediate chunk's payload
+ * holds the data child references first (exactly ceil(span/unit)), then
+ * parity references when erasure coding is on — those are ignored.
+ *
+ * The per-child span `unit` is read from the FIRST child's own span
+ * rather than computed as a power of 128: with erasure coding the
+ * effective fanout is smaller (seen live: 107 data + 21 parity refs per
+ * intermediate on a redundancy-uploaded file), and every child but the
+ * last spans the same unit — a Bee tree invariant this walk verifies. */
+async function readTree(store, chunk, start, end, out, outPos) {
+  const size = decodeSpan(chunk.subarray(0, 8));
+  const payload = chunk.subarray(8);
+  if (size <= CHUNK_SIZE) {
+    const piece = payload.subarray(start, end);
+    out.set(piece, outPos);
+    return piece.length;
+  }
+  if (payload.length < REF_SIZE) {
+    throw new VerificationError('intermediate chunk has no child references');
+  }
+  const first = await store.chunk(toHex(payload.subarray(0, REF_SIZE)));
+  const unit = decodeSpan(first.subarray(0, 8));
+  if (unit <= 0 || unit >= size) {
+    throw new VerificationError(
+      `first child spans ${unit} of a ${size}-byte subtree — not a valid tree`,
+    );
+  }
+  const nData = Math.ceil(size / unit);
+  if (payload.length < nData * REF_SIZE) {
+    throw new VerificationError(
+      `intermediate chunk carries ${Math.floor(payload.length / REF_SIZE)} ` +
+      `references but its span requires ${nData}`,
+    );
+  }
+  let written = 0;
+  for (let i = Math.floor(start / unit); i < nData; i++) {
+    const lo = i * unit;
+    if (lo >= end) break;
+    const hi = Math.min(lo + unit, size);
+    const child = i === 0
+      ? first
+      : await store.chunk(toHex(payload.subarray(i * REF_SIZE, (i + 1) * REF_SIZE)));
+    const childSpan = decodeSpan(child.subarray(0, 8));
+    if (childSpan !== hi - lo) {
+      throw new VerificationError(
+        `child chunk span ${childSpan} does not match its position in ` +
+        `the tree (expected ${hi - lo})`,
+      );
+    }
+    written += await readTree(
+      store, child, Math.max(start, lo) - lo, Math.min(end, hi) - lo,
+      out, outPos + written,
+    );
+  }
+  return written;
+}
+
+// ---- single-owner chunks (feed updates) -----------------------------------
+
+/** 32-byte feed identifier: keccak256(topic ‖ index as 8-byte BE). */
+export function feedIdentifier(topicBytes, index) {
+  const idx = new Uint8Array(8);
+  new DataView(idx.buffer).setBigUint64(0, BigInt(index), false);
+  return keccak256Bytes(concat(topicBytes, idx));
+}
+
+/** Address a single-owner chunk lives at: keccak256(identifier ‖ owner). */
+export function socAddress(identifier, ownerBytes) {
+  return keccak256Bytes(concat(identifier, ownerBytes));
+}
+
+/** Full client-side check of a single-owner chunk: address derivation,
+ * and recovery of the owner from the signature over the wrapped chunk's
+ * BMT address — exactly what a Bee node checks on upload. Returns the
+ * wrapped chunk's payload (the feed update). */
+export function verifySoc(data, ownerBytes, addressBytes) {
+  if (data.length < SOC_SPAN_OFFSET + 8) {
+    throw new VerificationError(`single-owner chunk too short: ${data.length} bytes`);
+  }
+  const identifier = data.subarray(0, SOC_IDENTIFIER_SIZE);
+  const sig = data.subarray(SOC_IDENTIFIER_SIZE, SOC_SPAN_OFFSET);
+  const cac = data.subarray(SOC_SPAN_OFFSET);
+  if (toHex(socAddress(identifier, ownerBytes)) !== toHex(addressBytes)) {
+    throw new VerificationError('single-owner chunk does not match its address');
+  }
+  const digest = keccak256Bytes(concat(identifier, chunkAddress(cac)));
+  const prefixed = keccak256Bytes(concat(
+    new TextEncoder().encode('\x19Ethereum Signed Message:\n32'), digest,
+  ));
+  let recovered;
+  try {
+    recovered = Signature.fromCompact(sig.subarray(0, 64))
+      .addRecoveryBit(sig[64] - 27)
+      .recoverPublicKey(prefixed)
+      .toBytes(false); // uncompressed: 0x04 ‖ x ‖ y
+  } catch (e) {
+    throw new VerificationError(`feed update signature is malformed: ${e}`);
+  }
+  const recoveredOwner = keccak256Bytes(recovered.subarray(1)).subarray(12);
+  if (toHex(recoveredOwner) !== toHex(ownerBytes)) {
+    throw new VerificationError('feed update signature was not made by the feed owner');
+  }
+  return cac.subarray(8); // the update payload (timestamp + reference)
+}

package/vendor/js-sha3/LICENSE

@@ -0,0 +1,20 @@
+Copyright 2015-2023 Chen, Yi-Cyuan
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/vendor/js-sha3/PROVENANCE.md

@@ -0,0 +1,19 @@
+# Vendored: js-sha3 0.9.3
+
+Source: the `js-sha3` npm package, version 0.9.3
+(https://github.com/emn178/js-sha3), MIT license (see LICENSE).
+
+Vendored subset: `src/sha3.js` only (unmodified), plus our `index.js`
+ESM facade. Used for keccak256: hashing human-readable feed topics
+(`src/feeds.js`), and later chunk/BMT verification.
+
+Vendored (rather than npm-installed) for the same reason as wa-sqlite:
+demo pages must be fully self-contained to be published on Swarm —
+no CDN, no registry, only relative URLs under one immutable root.
+
+Sanity check: `keccak256('hello')` =
+`1c8aff950685c2ed4bc3174f3472287b56d9517b9c948127319a09a7a36deac8`
+(the well-known Ethereum keccak vector; asserted in `test/feed.mjs`).
+
+To upgrade: `npm pack js-sha3`, extract, copy `src/sha3.js` and
+LICENSE, update the version here, re-run `node js/test/feed.mjs`.

package/vendor/js-sha3/index.js

@@ -0,0 +1,12 @@
+// ESM facade over the unmodified UMD build: in ES-module scope neither
+// `module` nor `define` exists, so sha3.js falls through to attaching
+// its methods to the global object (window / self / global); re-export
+// the one method swarmlite uses.
+import './sha3.js';
+
+/** keccak256 over a string or byte array -> lowercase hex (no 0x). */
+export const keccak256 = globalThis.keccak_256;
+
+/** keccak256 over a byte array -> Uint8Array (for BMT/SOC hashing). */
+export const keccak256Bytes = (data) =>
+  Uint8Array.from(globalThis.keccak_256.array(data));