@allowly/verifier

TypeScript reference verifier for Allowly Receipt Format wire version 4.

Zero runtime dependencies. Uses Node.js's built-in WebCrypto for Ed25519 verification.

Install

npm install @allowly/verifier

Requires Node.js 20+.

Usage

import { verifyReceipt, VerificationError, loadKeysFromJson } from "@allowly/verifier";

const receipt = JSON.parse(receiptJson);
const keysDoc = JSON.parse(keysJson);
const configuredWorkspaceId = process.env.ALLOWLY_WORKSPACE_ID;
const configuredKeyFingerprint = process.env.ALLOWLY_TRUSTED_KEY_FINGERPRINT;
if (!configuredWorkspaceId) throw new Error("ALLOWLY_WORKSPACE_ID is required");
if (!configuredKeyFingerprint) throw new Error("ALLOWLY_TRUSTED_KEY_FINGERPRINT is required");
if (keysDoc.workspace_id !== configuredWorkspaceId) {
  throw new Error("key document workspace does not match configuration");
}
const keys = loadKeysFromJson(keysDoc);

try {
  await verifyReceipt(receipt, keys, {
    expectedWorkspaceId: configuredWorkspaceId,
    trustedKeyFingerprints: new Set([configuredKeyFingerprint]),
  });
  console.log("valid");
} catch (e) {
  if (e instanceof VerificationError) {
    console.log(`invalid: ${e.message}`);
  } else {
    throw e;
  }
}

Fetching the public keys

const configuredWorkspaceId = process.env.ALLOWLY_WORKSPACE_ID;
if (!configuredWorkspaceId) throw new Error("ALLOWLY_WORKSPACE_ID is required");
const res = await fetch(`https://api.allowly.ai/v1/workspaces/${configuredWorkspaceId}/keys`);
const keysDoc = await res.json();
if (keysDoc.workspace_id !== configuredWorkspaceId) {
  throw new Error("key document workspace does not match configuration");
}
const keys = loadKeysFromJson(keysDoc);

Honor the issuer's Cache-Control header. Allowly currently returns no-store, so do not HTTP-cache the response; retain trusted key material separately for offline audits.

API

verifyReceipt(receipt, publicKeys, opts?)

Verifies a receipt. Resolves on success, throws VerificationError on any failure.

• receipt — the full receipt object (payload + signature).
• publicKeys — array of PublicKey objects. Get these via loadKeysFromJson.
• opts.now — optional Date override for time checks. Defaults to new Date().
• opts.expectedWorkspaceId — optional. If set, the receipt's workspace_id must equal it. Pass a caller-trusted configured workspace ID, never one copied from the receipt or key document (spec §7, "Workspace binding"); a key_id alone does not bind a receipt to a workspace.
• opts.trustedKeyFingerprints — optional ReadonlySet<string>. If set, the selected receipt key must match a caller-trusted sha256:<64 lowercase hex> fingerprint. Include every trusted rotation key that may have signed the selected receipts.

canonicalize(payload)

Produces the canonical JSON byte sequence per spec §4. Exposed for implementers building signers in TypeScript.

verifyCheckpoint(checkpoint, receipts, publicKeys, opts)

Verifies the checkpoint and member signatures, exact UTC-day period, count, Merkle root, and optional prior checkpoint linkage. opts.expectedWorkspaceId is required and must come from caller-trusted configuration. Pass caller-trusted rotation keys through opts.trustedKeyFingerprints; the pins are applied to the checkpoint, every member, and the optional prior checkpoint. Success proves the supplied set matches the signed commitment; without external anchoring it does not prove issuer-registry or real-world completeness.

loadKeysFromJson(doc)

Parses the /v1/workspaces/{id}/keys response into a PublicKey[]. It requires a non-empty workspace_id, requires every key's alg to equal Ed25519, and validates any advertised public_key_fingerprint against the decoded key. Bundled fingerprint values are not caller-trusted merely because they accompany the receipts.

publicKeyFingerprint(key)

Returns the canonical sha256:<64 lowercase hex> fingerprint over the key's decoded raw 32-byte Ed25519 public key.

matchesRef(key, fieldName, value, ref)

Implements the optional hmac-v1 keyed-pseudonym convention in specification Appendix A. Decode the show-once integration key, then match locally — no call to Allowly:

import { matchesRef } from "@allowly/verifier";

const key = Buffer.from(encodedKeyB64url, "base64url"); // per-integration pseudonym key
const ok = matchesRef(key, "record", "MRN-48291", receipt.context.record_ref);

key is a Uint8Array of at least 16 bytes; fieldName is one of project, record, actor, full_tuple. The value is used exactly as supplied — no trimming, case folding, or Unicode normalization — and comparison is constant-time. Use context.ref_key_version to select the retained key version. This helper is unrelated to signature verification and does not touch the receipt schema, canonicalization, or wire version.

verifyReceipt accepts an already-parsed object. JSON.parse cannot report duplicate member names or preserve whether an integer was written as 1, 1.0, or 1e0; reject those forms at the raw-JSON boundary when the original receipt text is untrusted (spec §4.2).

What verification proves

A valid receipt proves that the selected private key signed the exact recorded decision and timestamp for the recorded subject/action. It does not independently prove when signing happened, that the action actually happened, that the user's authorization was informed, or that the user_id corresponds to any real-world person. See spec §7.1.

License

Apache 2.0. Contributions welcome — see CONTRIBUTING.md.