mememage-resolver

Resolve a Mememage identifier to a record over configured mirrors, then check its integrity — framework-agnostic, dependency-free.

A Mememage bar carries an identifier and a content hash. The identifier is a lookup key, not an authority. This module walks an ordered list of record sources (mirrors), takes the first that has the record, and checks it against the hash in the bar. The source is never trusted: the content hash is the authority, so a mirror can only fail to verify, never forge.

It owns the mirror walk, the per-source timeout, and the fallback. It is I/O-injected — you provide fetch and the verify math from the mememage SDK.

Install

npm install mememage-resolver mememage

Use

import { createResolver } from "mememage-resolver";
import { computeContentHash, isSupportedHashVersion } from "mememage";

const resolver = createResolver({
  fetch,                                              // your HTTP fetch
  verifyMath: { computeContentHash, isSupportedHashVersion },
  sources: [                                          // ordered mirrors; first hit wins
    "https://souls.mememage.art",
    "https://archive.org/download/{id}",             // {id} substitutes the identifier
  ],
  timeout: 5000,                                       // per-source ms
});

// bar comes from the detector / a decode: { identifier, contentHash }
const verdict = await resolver.verify(bar);
// -> { state: "verified" | "altered" | "norecord" | "error" | "nosource" | "unsupported", ... }

const found = await resolver.fetchRecord(bar.identifier);
// -> { ok, url, source } | { noSource } | { notFound, detail }

sources and timeout also accept a function (sync or async), so you can back them with live config that changes at runtime:

createResolver({ fetch, verifyMath, sources: () => readMyMirrors(), timeout: () => readMyTimeout() });

Per call, opts overrides them: resolver.verify(bar, { sources, timeout }).

Mirror format

A source is a URL base. {id} is substituted with the identifier; the resolver then tries <base>/<id>.json and <base>/<id>.soul.

• https://souls.mememage.art → https://souls.mememage.art/<id>.json
• https://archive.org/download/{id} → https://archive.org/download/<id>/<id>.json

Verdicts

| state | Meaning | |---|---| | verified | The record's content hash matches the bar. Integrity confirmed. | | altered | A record was found, but it recomputes to a different hash. | | norecord | Every source answered, none had the record. | | error | One or more sources timed out or were unreachable. | | nosource | No sources configured. | | unsupported | The record uses a hash model this check does not cover. Not tampering. |

verify returns the source and recordUrl that answered, plus a human detail/reason for the non-verified states.

License

MIT © Catmemes