@maatara/aegis-pure

Pure, dependency-free utilities for the Aegis Provenance Fabric.

"Pure" is the contract. No WASM, no network, no platform APIs beyond what a browser and a Cloudflare Worker both provide. Every export is a function of its arguments. That is what makes this package publishable, independently testable, and — the reason it exists — safe to run on the user's own device.

npm install @maatara/aegis-pure

ESM only. No runtime dependencies.

Why 0.2.0 exists

Text fingerprinting used to run on the server. To register a note, a client had to POST the note's plaintext body so the server could normalise, shingle and hash it.

That contradicted the rule the whole architecture rests on — no unencrypted user information leaves the device — and it contradicted the published claim that original text is never persisted. The fingerprint is one-way and 256 bits per chunk. There was never a reason it could not be computed locally.

So it is computed locally now. POST /api/query/text and the text registration path accept vectors only; a request carrying text, title, body or content is rejected with an explanation rather than quietly ignored, so an un-upgraded client fails loudly instead of continuing to send prose.

The 0.1.0 surface (ksr.ts) is unchanged, byte for byte. This release adds a module; it does not edit the one that was already published.

Layer T — text fingerprinting

A one-way locality-sensitive fingerprint over normalised text. Similar text produces similar vectors; the original words are not recoverable from them.

import { fingerprintText, fingerprintQuery } from '@maatara/aegis-pure';

// You supply the hash. The package stays pure by not choosing one for you —
// any function (string) => lowercase-hex SHA3-384 will do.
const sha3String = (s: string) => myWasm.hash.sha3String(s);

const fp = fingerprintText(sha3String, noteBody);
// fp.assetId    -> 'text-<32 hex chars>', derived from the full normalised text
// fp.wordCount  -> number of tokens after normalisation
// fp.chunks     -> [{ index, values: Float32Array(256), wordCount }, ...]

Send fp — never the text.

For search, fingerprintQuery caps the work at maxChunks (default 8) so a long query does not fan out into an unbounded number of vectors:

const q = fingerprintQuery(sha3String, searchText, 8);

The pipeline, exactly

normaliseText → tokenise → chunkWords → shingles → simhash256.

| Constant | Value | Meaning | | ---------------- | ----- | --------------------------------------- | | SIMHASH_BITS | 256 | Vector width; entries are +1 or -1 | | SHINGLE_K | 5 | Words per shingle | | CHUNK_WORDS | 200 | Words per chunk | | CHUNK_OVERLAP | 40 | Overlap between consecutive chunks |

Normalisation is lowercase → NFKC → strip everything that is not a letter, number, apostrophe or whitespace → collapse runs of whitespace → trim.

Every intermediate step is exported. You do not have to trust the composite.

Bit-exactness is a compatibility requirement, not a nicety

Vectors already in the index were produced by the previous server-side implementation. One flipped vote and previously registered work silently stops matching — no error is raised anywhere, because a near-miss and a non-match look identical to a nearest-neighbour index.

So the test suite carries a verbatim transcription of the original server implementation and asserts the two agree across a corpus built specifically to break a port: Unicode folding, apostrophes, punctuation runs, exact chunk boundaries, sign ties at zero, and mixed scripts. 100 assertions, against real SHA3-384.

If you reimplement this in another language, port the corpus first.

Key-status records

Unchanged from 0.1.0.

import {
  computeValidityWindow,
  determineProvenanceValidity,
  computeKeyFingerprintV2,
} from '@maatara/aegis-pure';

const result = determineProvenanceValidity(new Date(claimedAt), keyStatusRecord);
// result.valid, result.reason, result.confidence ('full' | 'reduced'), result.window

The question these answer is "was this key valid at the moment the content claims to have been signed?" — not "is this key valid now?". A key compromised in 2027 does not retroactively invalidate a signature made in 2026; a key that was already compromised does not get to sign anything afterwards. computeValidityWindow turns a KeyStatusRecord into that window, and determineProvenanceValidity tests a timestamp against it.

A suspected key returns valid: true with confidence: 'reduced' and a warning, rather than a verdict — an investigation is not a finding.

computeKeyFingerprintV2 creates an algorithm-scoped SHA3-384 identifier and is the only fingerprint function intended for new records. The deprecated computeKeyFingerprint export remains solely to read or reproduce published v1 SHA-256 fingerprints; changing its output would silently orphan existing key-status records. Callers provide the SHA3-384 byte function from the same audited WASM/runtime used by the rest of their Ma'atara stack.

What is not here

No capsule construction, no image or video fingerprinting, no scoring or thresholds. This package is the pure, device-side subset. The Ma'atara Provenance capsule format is proprietary and patent-pending, and is not published here or anywhere else.

Licence

Apache-2.0. Note that this differs from the wider Ma'atara repository, which is BSL 1.1 — this package is deliberately permissive because it is the piece third parties must be able to run on their own devices and audit for themselves.

PATENT PENDING — Ma'atara Protocol.