SchemaFingerprint

Content-hash a BitPackerSchema so two parties can agree they're using byte-identical schemas before they exchange payloads. The fingerprint is computed over a canonical serialisation (sorted keys, no whitespace, deterministic encoding), and the hash algorithm is pluggable via HashAlgorithmRegistry.

(no submodules)

Purpose

Whenever a producer and consumer of bit-packed bytes are not co-located — mesh peers, drive replicas, network plugins, or two services that pinned their schemas independently — they need a way to confirm "we're talking the same shape" before risking a parse error on a half-mismatched schema. A schema fingerprint compresses that question to a fixed-size digest that can be compared in a handshake.

The fingerprint must be order-insensitive: a producer that declared fields in declaration order (foo, bar) and a consumer that declared them in the order (bar, foo) should fingerprint identically, because the wire format itself is order-independent at the bit-packer level (object keys participate, but their declaration order does not). Achieving that requires canonical-serialisation, which this module owns.

Features

Default algorithm: sha256 (32 bytes, cryptographically strong)
Built-in alternatives: xxhash32 (4 bytes, fast non-crypto), crc32 (4 bytes, fast non-crypto)
Pluggable: register blake3 (or any custom hash) via HashAlgorithmRegistry and pass it as registry argument
assertSchemaFingerprint(schema, expected, ...) is the single-call handshake check; throws CRYPTO_SCHEMA_FINGERPRINT_MISMATCH with a context that includes hex expected and actual for diagnosability
Unknown algorithm name throws CRYPTO_HASH_ALGORITHM_UNKNOWN
Functions inside the schema (e.g. ConditionalSchema._if) are rejected; v1 fingerprintable schemas are data-shape only
Constant-time digest comparison in assertSchemaFingerprint (so timing side channels can't leak partial-match information)
OTel span bitpacker-crypto.fingerprint with algorithm + payload_bytes

Usage: Basic Example

import {
    assertSchemaFingerprint,
    schemaFingerprint,
} from "@suaveplan/bitpacker-crypto";

const schema = { foo: 255, bar: 65535 };
const fp = await schemaFingerprint(schema); // sha256 by default

// On the other side of a handshake, validate the schemas match:
await assertSchemaFingerprint(localSchema, fp);

Usage: Advanced Example — registry-backed BLAKE3

import {
    type HashAlgorithm,
    createHashRegistry,
    schemaFingerprint,
} from "@suaveplan/bitpacker-crypto";
import { blake3 as nobleBlake3 } from "@noble/hashes/blake3";

const blake3: HashAlgorithm = {
    name: "blake3",
    outputBytes: 32,
    hash: (data) => Promise.resolve(nobleBlake3(data)),
};

const registry = createHashRegistry();
registry.register(blake3);

const fp = await schemaFingerprint(schema, "blake3", registry);

API Reference