mememage-js

The JavaScript SDK for the Mememage protocol — the JS implementation of mememage-core, so JavaScript developers can work with Mememage (decode, verify, and — as this is built out — encode) natively, without a Python dependency. It's the counterpart to the Python mememage package: two language bindings of one protocol.

Python is the reference. This SDK never becomes a second source of truth — every operation mirrors a Python function and is validated against Python's own output by a parity gate. Maintenance means fixing the Python core; the gate tells us if the JS side needs to follow. So there's nothing here to chase down independently.

Status — complete at core parity

The SDK now covers the whole raw-core protocol, each op gated against Python:

• decodeBar — read the bar → { identifier, contentHash }.
• verifyWitnessed / isSupportedHashVersion — integrity (the open model).
• encode — stamp a bar + build the record, byte-identical to mememage.encode.
• encryptField / decryptField / encode(…, {password, private}) / unlock / isEncrypted — field encryption (AES-256-GCM / PBKDF2), envelope byte-compatible with Python: a record encrypted in either language opens in the other.

The open hash model (schema-agnostic)

The SDK is schema-agnostic: it implements the open hash model — the content hash covers every field a record holds (what the raw API and ComfyUI produce). So it verifies any adopter's record no matter what they store, without knowing any particular chain's schema.

Curated integer hash versions (the canonical chain's hash_version: 1, with its fixed field list) are a reference-implementation concern. A record on one of those reads as UNSUPPORTED here — not tampered, exactly the verdict ComfyUI's verifier and the core CLI give. Call isSupportedHashVersion(record) before verifyWitnessed to tell UNSUPPORTED apart from ALTERED.

Deliberately not here — reference-implementation features, out of raw-core scope: signing / AUTHENTICATED (the raw core's verify() is integrity-only), EMBODIED (dHash + luma grid), and the distributed watermark. These are the canonical chain's specific tamper-evidence technique — they need a record carrying a thumbnail and a luma_grid, and another adopter might use a different technique or none. They belong to the reference implementation, not the core. For now they live only in the decoder site (docs/js); if they're ever ported to JS they'll be a separate surface with its own parity anchor (the reference impl).

Use

import {
  decodeBar, isSupportedHashVersion, verifyWitnessed,
} from "mememage-js";

// 1. decode the bar from image pixels (canvas getImageData().data, flat RGBA)
const bar = decodeBar(pixels, width, height);
if (!bar) { /* NO BAR */ }
// -> { identifier: "mememage-…", contentHash: "…" }

// 2. fetch the record for bar.identifier from wherever it lives (yours to resolve),
//    then produce a verdict — by math alone, no server needed:
if (!isSupportedHashVersion(record)) {
  // UNSUPPORTED — a hash model this layer doesn't implement (e.g. a canonical-chain
  // record). NOT tampered; verify it in that app's own decoder.
} else if (await verifyWitnessed(record, bar.contentHash)) {
  // WITNESSED — intact and matched to the image (integrity)
} else {
  // ALTERED — the record does not match the image
}

Raw core exports (extractBarScaleAware, decodePayload, packPayload, extractIdentifier, normalizeIdentifier, computeContentHash, encode, contentIdentifier) are available for lower-level use.

Parity

Codec/verify bodies are verbatim from the parity-locked decoder in docs/js (the frozen decoder site), wrapped as ES modules. npm test validates the core layer against the Python core directly: decode-parity decodes bars the core produced (gen-vectors.py), verify-parity recomputes hashes the core stamped (gen-hash-vectors.py, using compute_content_hash), and checks encode output — across sequential + even-fill layouts, custom prefixes, the real V1 example soul, open- version records, and a tamper negative. Regenerate vectors from the repo root with python3 test/gen-vectors.py and python3 test/gen-hash-vectors.py.

MIT.