@allowly/verifier

TypeScript reference verifier for Allowly Receipt Format wire version 4.

Uses Node.js's built-in WebCrypto for Ed25519 verification, plus focused RFC 8785 canonicalization and strict JSON parsing dependencies for SEAL records.

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.

verifyPolicyEvaluation(receipt, authorizationReceipts, publicKeys, opts)

Authenticates the action receipt and every supplied authorization receipt, then repeats the conditional policy calculation for supported engines 2026-09-16.1, 2026-09-24.1, and 2026-09-27.1. Both opts.expectedWorkspaceId and a non-empty opts.trustedKeyFingerprints set are required and must come from caller-trusted configuration.

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

const result = await verifyPolicyEvaluation(
  actionReceipt,
  authorizationReceipts,
  loadKeysFromJson(keysDoc),
  {
    expectedWorkspaceId: configuredWorkspaceId,
    trustedKeyFingerprints: new Set(configuredKeyFingerprints),
  },
);

if (result.status === "mismatch") {
  console.error(result.diagnostic, result.recorded_evaluation, result.calculated_evaluation);
}

The result uses the same snake-case contract as the Python verifier:

interface PolicyEvaluationResult {
  profile: "allowly-conditional-evaluation-v1";
  engine_version: string;
  receipt_id: string;
  authorization_receipt_id: string | null;
  status: "matched" | "mismatch" | "not_checked";
  diagnostic: string;
  recorded_evaluation: Record<string, unknown> | null;
  calculated_evaluation: Record<string, unknown> | null;
}

matched means the signed rules and reconstructed signed context produce the recorded complete policy_eval object. It does not reproduce the final allow, deny, confirm, or escalate decision. Runtime state such as revocation, expiry, rate limits, budgets, confirmations, and escalations can change that decision. not_checked keeps missing evidence and unsupported historical profiles visible instead of treating them as successful checks.

See the allowly-conditional-evaluation-v1 profile for the exact pairing, context reconstruction, operator, precedence, and diagnostic rules.

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.

SEAL hashing and verification

hashSealJson(rawJson) accepts a string or Uint8Array, strictly parses the raw JSON, applies the allowly.seal.jcs-sha256.v1 RFC 8785 profile, and returns the 64-character lowercase SHA-256 digest. Prefer it at untrusted input boundaries because it can reject duplicate decoded object keys and precision-losing number tokens. hashSealValue(record) is the explicit already-parsed boundary; parsing has already erased those details.

verifySealJson and verifySealValue first verify the full wire-4 receipt, including a caller-supplied expectedWorkspaceId and optional trusted key fingerprints. They then require the fixed SEAL action and identities, the signed profile and digest, and a matching local record. The result keeps signatureVerified separate from recordMatches and includes a stable failureReason.

The package publishes the exact shared JSON vectors at these stable subpaths:

import profileVectors from "@allowly/verifier/vectors/seal/profile-v1.json" with { type: "json" };
import verificationVectors from "@allowly/verifier/vectors/seal/verification-v1.json" with { type: "json" };
import policyVectors from "@allowly/verifier/vectors/policy/profile-v1.json" with { type: "json" };

They are copied from the repository's canonical vectors/seal/ and vectors/policy/ files during the package build; integrations should consume these fixtures instead of maintaining a second source.

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.

Browser builds for the dashboard and website

browser/sealJson.ts owns their shared strict JSON parsing and hashing. npm test checks it against the same SEAL vectors as the Node verifier. After building this directory, run python3 scripts/refresh-verifier.py in each consumer repo. Those wrappers use scripts/build-browser.py here to generate the self-hosted receipt verifier and JSON helper. The generated receipt verifier includes verifyPolicyEvaluation and its conditional evaluator without a runtime package dependency. Edit these sources instead of the generated consumer files.

License

Apache 2.0. Contributions welcome — see CONTRIBUTING.md.