@entpoind/verify 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Avonao, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,86 @@
-# Temporary Holding Version
+# @entpoind/verify
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Offline verification of **Entpoind Tools** receipts and **VerifiableArtifact**
+bundles. Zero dependencies; it uses only the runtime's own WebCrypto.
+
+```bash
+npm install @entpoind/verify
+```
+
+```ts
+import { verifyReceiptOnline } from "@entpoind/verify";
+
+const result = await verifyReceiptOnline(receiptJson);
+if (result.ok) {
+  console.log("signed at", result.signedAt, "by key", result.signatureKeyId);
+} else {
+  console.log("not verified:", result.reason);
+}
+```
+
+`receiptJson` can be the receipt object, its JSON text, or the `{ "receipt": … }`
+wrapper the API returns.
+
+## Where it runs
+
+Any runtime whose WebCrypto verifies Ed25519: Node 20 or later (tested on
+Node 22), Deno, Bun, Cloudflare Workers, and current browsers (Chrome and Edge
+137+, Firefox 129+, Safari 17+). Browsers expose WebCrypto only on secure
+(`https:` or `localhost`) pages. Where Ed25519 is missing, verification returns
+`unsupported_runtime` instead of judging the receipt; `ed25519Supported()` tells
+you in advance.
+
+## What it verifies
+
+- **Tools receipts**: the signed envelope every Tools call returns, of every
+  receipt `type` (`agent.call`, `content.attest`, `monitor.http`,
+  `heartbeat.attest`, …). Scheduled-watch digest receipts verify the same way.
+- **VerifiableArtifact envelopes and bundles**: the signature, and, when a bundle
+  carries an `anchor`, that the artifact is included under the anchored Merkle
+  root.
+
+The signature is Ed25519 over the **RFC 8785 (JCS)** canonical form of the
+envelope minus `signature`. Public keys come from the published JWK Set at
+`https://entpoind.com/.well-known/tools-keys.json`, which any origin may fetch
+(`access-control-allow-origin: *`). For air-gapped checks, save that file and pass
+its `keys` to `verifyReceipt`.
+
+## API
+
+| Function | Purpose |
+|---|---|
+| `verifyReceipt(input, keys)` | Verify a receipt against keys you supply. No network. |
+| `verifyReceiptOnline(input, url?)` | Fetch the published keys, then verify. |
+| `fetchToolsKeys(url)` | Fetch the published JWK Set and keep its Ed25519 keys. |
+| `verifyArtifact(input, keys)` | Verify a standalone artifact envelope. |
+| `verifyBundle(input, keys)` | Signature, plus Merkle inclusion when anchored. |
+| `verifyMerkleInclusion(leaf, proof, root)` | Fold an inclusion proof locally. |
+| `canonicalJcs(value)` | The RFC 8785 canonical string. |
+| `ed25519Supported()` | Whether this runtime can verify Ed25519. |
+| `verifySignature(key, message, signature)` | The raw Ed25519 check, as a boolean. |
+
+The `verify*` functions never throw on hostile input. `fetchToolsKeys` and
+`verifyReceiptOnline` throw when the keys cannot be fetched, so "could not
+check" is never reported as a verdict.
+
+## Failure reasons
+
+| `reason` | Meaning |
+|---|---|
+| `malformed_envelope` | Not a complete receipt or artifact. |
+| `unknown_key` | `signatureKeyId` matches no Ed25519 key in the set. Refresh the keys; if it is still missing, the document was not signed by Entpoind. |
+| `bad_signature` | The signature does not match the canonical bytes: the document was altered, or is not Entpoind's. |
+| `unsupported_runtime` | This runtime cannot verify Ed25519. Nothing was judged. |
+| `not_in_anchored_root` | Bundles only: the signature is valid but the Merkle proof does not reach the anchored root. |
+
+A bundle without an anchor verifies with `anchored: false`; that is a valid
+result, not a failure.
+
+## Documentation
+
+Receipt format, verification procedure and key rotation:
+<https://entpoind.com/docs/verification>.
+
+## License
+
+MIT © Avonao, Inc.

package/dist/canonical-json.d.ts

@@ -0,0 +1,19 @@
+/**
+ * @entpoind/verify — RFC 8785 (JCS) canonicalization.
+ *
+ * Byte-identical port of the signer's canonicalizer
+ * (runtime/shared/canonical-json.ts). A receipt verifies only when the verifier
+ * re-derives the EXACT bytes the signature covers, so this file must never
+ * drift from that source: recursive key sort by UTF-16 code unit, ECMAScript
+ * Number→String formatting, JSON.stringify escaping, loud rejection of values
+ * two implementations couldn't serialize identically.
+ */
+export type JsonValue = null | boolean | number | string | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+export declare class NonCanonicalizableError extends Error {
+    readonly path: string;
+    constructor(message: string, path: string);
+}
+/** The RFC 8785 canonical string for `value` — the bytes a signature covers. */
+export declare function canonicalJcs(value: unknown): string;

package/dist/canonical-json.js

@@ -0,0 +1,57 @@
+/**
+ * @entpoind/verify — RFC 8785 (JCS) canonicalization.
+ *
+ * Byte-identical port of the signer's canonicalizer
+ * (runtime/shared/canonical-json.ts). A receipt verifies only when the verifier
+ * re-derives the EXACT bytes the signature covers, so this file must never
+ * drift from that source: recursive key sort by UTF-16 code unit, ECMAScript
+ * Number→String formatting, JSON.stringify escaping, loud rejection of values
+ * two implementations couldn't serialize identically.
+ */
+export class NonCanonicalizableError extends Error {
+    path;
+    constructor(message, path) {
+        super(`canonical-json: ${message} (at ${path || "<root>"})`);
+        this.path = path;
+        this.name = "NonCanonicalizableError";
+    }
+}
+function canonicalizeValue(value, path) {
+    if (value === null)
+        return null;
+    const t = typeof value;
+    if (t === "boolean" || t === "string")
+        return value;
+    if (t === "number") {
+        if (!Number.isFinite(value)) {
+            throw new NonCanonicalizableError(`non-finite number (${String(value)}) is not valid JSON`, path);
+        }
+        return value;
+    }
+    if (t === "bigint") {
+        throw new NonCanonicalizableError("bigint cannot be canonicalized (no JSON representation)", path);
+    }
+    if (t === "undefined" || t === "function" || t === "symbol") {
+        throw new NonCanonicalizableError(`${t} cannot be canonicalized`, path);
+    }
+    if (Array.isArray(value)) {
+        return value.map((v, i) => canonicalizeValue(v, `${path}[${i}]`));
+    }
+    const proto = Object.getPrototypeOf(value);
+    if (proto !== Object.prototype && proto !== null) {
+        throw new NonCanonicalizableError(`non-plain object (${value.constructor?.name ?? "unknown"}) cannot be canonicalized; pass plain JSON`, path);
+    }
+    const obj = value;
+    const out = {};
+    for (const key of Object.keys(obj).sort()) {
+        const child = obj[key];
+        if (child === undefined)
+            continue;
+        out[key] = canonicalizeValue(child, path ? `${path}.${key}` : key);
+    }
+    return out;
+}
+/** The RFC 8785 canonical string for `value` — the bytes a signature covers. */
+export function canonicalJcs(value) {
+    return JSON.stringify(canonicalizeValue(value, ""));
+}

package/dist/index.d.ts

@@ -0,0 +1,131 @@
+/**
+ * @entpoind/verify — offline verification of Entpoind Tools receipts and
+ * VerifiableArtifact bundles.
+ *
+ * What a customer pastes into this library was signed by the Tools worker's
+ * per-jurisdiction Ed25519 key; the matching public keys are published as a
+ * JWK Set at `/.well-known/tools-keys.json` (CORS-open on purpose — this
+ * library is meant to run from the customer's own page or backend).
+ *
+ * No trust in us is required beyond the published key set: the signature is
+ * verified locally over the RFC 8785 canonical form of the envelope, and an
+ * artifact bundle's Merkle inclusion proof is folded locally too.
+ *
+ * Zero dependencies. WebCrypto only — runs in every modern browser, Node ≥ 20,
+ * Deno, Bun, and Cloudflare Workers.
+ */
+import { type MerkleProofStep } from "./merkle.js";
+export { canonicalJcs, NonCanonicalizableError, type JsonValue } from "./canonical-json.js";
+export { merkleLeafHash, verifyMerkleInclusion, type MerkleProofStep } from "./merkle.js";
+/** A public verification key as published in the Tools JWK Set. */
+export type PublishedKey = {
+    kid: string;
+    kty: string;
+    crv: string;
+    x: string;
+    alg?: string;
+    use?: string;
+};
+/** The `/.well-known/tools-keys.json` document shape. */
+export type ToolsKeySet = {
+    keys: PublishedKey[];
+};
+/**
+ * Where the production key set is published. The same document is mirrored on
+ * the Tools marketing domain; either origin serves it CORS-open.
+ */
+export declare const DEFAULT_KEYS_URL = "https://entpoind.com/.well-known/tools-keys.json";
+/**
+ * Fetch the published key set. `keysUrl` is absolute — e.g.
+ * `https://entpoind.com/.well-known/tools-keys.json` or the `keysUrl` field a
+ * runtime embeds in its receipts.
+ *
+ * Throws on transport failure — callers that distinguish "couldn't fetch keys"
+ * from "bad signature" should catch and report that separately.
+ */
+export declare function fetchToolsKeys(keysUrl: string): Promise<PublishedKey[]>;
+/** Whether this runtime's WebCrypto can verify Ed25519 signatures. Cached after the first call. */
+export declare function ed25519Supported(): Promise<boolean>;
+/**
+ * Verify a base64url Ed25519 signature. Never throws on hostile input. Returns
+ * false both for a wrong signature and for a runtime without Ed25519; use
+ * `ed25519Supported()` to tell those apart, or the `verify*` functions, which
+ * report `unsupported_runtime`.
+ */
+export declare function verifySignature(publicKey: {
+    kty: string;
+    crv: string;
+    x: string;
+}, message: string, signatureB64Url: string): Promise<boolean>;
+/** Why a verification failed. `unsupported_runtime` means the check could not run, not that the document is bad. */
+export type FailureReason = "bad_signature" | "unknown_key" | "malformed_envelope" | "unsupported_runtime";
+export type ReceiptVerification = {
+    ok: true;
+    signedAt: string;
+    signatureKeyId: string;
+} | {
+    ok: false;
+    reason: FailureReason;
+};
+/** The canonical bytes a receipt's signature covers: JCS(envelope − signature). */
+export declare function canonicalReceiptString(envelope: Record<string, unknown>): string;
+/** Runtime shape guard for an untrusted receipt envelope. */
+export declare function isReceiptEnvelope(x: unknown): x is Record<string, unknown>;
+/**
+ * Verify a Tools receipt against the published public keys. Accepts the parsed
+ * envelope, its JSON text, or the `{ receipt }` wrapper the API returns. Pure
+ * public-key crypto — no account, no network.
+ */
+export declare function verifyReceipt(input: unknown, publicKeys: ReadonlyArray<PublishedKey>): Promise<ReceiptVerification>;
+export type ArtifactVerification = {
+    ok: true;
+    signedAt: string;
+    signatureKeyId: string;
+    kind: string;
+} | {
+    ok: false;
+    reason: FailureReason;
+};
+/** The canonical bytes an artifact's signature covers: JCS(envelope − signature). */
+export declare function canonicalArtifactString(envelope: Record<string, unknown>): string;
+/** Runtime shape guard for an untrusted artifact envelope. */
+export declare function isArtifactEnvelope(x: unknown): x is Record<string, unknown>;
+/** Verify a standalone VerifiableArtifact against the published public keys. */
+export declare function verifyArtifact(input: unknown, publicKeys: ReadonlyArray<PublishedKey>): Promise<ArtifactVerification>;
+/** A self-contained artifact bundle: the signed artifact, its index id, and —
+ *  once the batch is anchored — the Merkle proof + anchored root. `leafHash` is
+ *  the plain SHA-256 of the leaf string, an index id; verification does not use it. */
+export type ArtifactBundle = {
+    artifact: Record<string, unknown>;
+    leafHash: string;
+    anchor?: {
+        merkleRoot: string;
+        proof: MerkleProofStep[];
+        topsRef?: string;
+    };
+};
+export type BundleVerification = {
+    ok: true;
+    anchored: boolean;
+    signedAt: string;
+    kind: string;
+} | {
+    ok: false;
+    anchored: boolean;
+    reason: FailureReason | "not_in_anchored_root";
+};
+/**
+ * Verify a bundle offline: the artifact's Ed25519 signature, then — when an
+ * anchor is present — that JCS(signed artifact) is included under the anchored
+ * Merkle root. `anchored:false` on a pre-anchor bundle is a valid result, not a
+ * failure.
+ */
+export declare function verifyBundle(input: unknown, publicKeys: ReadonlyArray<PublishedKey>): Promise<BundleVerification>;
+/**
+ * One-shot receipt verification against the published key set — fetch keys,
+ * resolve `signatureKeyId`, verify. `keysUrl` defaults to the production
+ * well-known document; pass an override for staging / self-hosted runtimes.
+ * Throws (like `fetchToolsKeys`) when the keys cannot be fetched, so "could not
+ * check" never reads as a verdict on the receipt.
+ */
+export declare function verifyReceiptOnline(input: unknown, keysUrl?: string): Promise<ReceiptVerification>;

package/dist/index.js

@@ -0,0 +1,221 @@
+/**
+ * @entpoind/verify — offline verification of Entpoind Tools receipts and
+ * VerifiableArtifact bundles.
+ *
+ * What a customer pastes into this library was signed by the Tools worker's
+ * per-jurisdiction Ed25519 key; the matching public keys are published as a
+ * JWK Set at `/.well-known/tools-keys.json` (CORS-open on purpose — this
+ * library is meant to run from the customer's own page or backend).
+ *
+ * No trust in us is required beyond the published key set: the signature is
+ * verified locally over the RFC 8785 canonical form of the envelope, and an
+ * artifact bundle's Merkle inclusion proof is folded locally too.
+ *
+ * Zero dependencies. WebCrypto only — runs in every modern browser, Node ≥ 20,
+ * Deno, Bun, and Cloudflare Workers.
+ */
+import { canonicalJcs } from "./canonical-json.js";
+import { verifyMerkleInclusion } from "./merkle.js";
+export { canonicalJcs, NonCanonicalizableError } from "./canonical-json.js";
+export { merkleLeafHash, verifyMerkleInclusion } from "./merkle.js";
+/**
+ * Where the production key set is published. The same document is mirrored on
+ * the Tools marketing domain; either origin serves it CORS-open.
+ */
+export const DEFAULT_KEYS_URL = "https://entpoind.com/.well-known/tools-keys.json";
+/**
+ * Fetch the published key set. `keysUrl` is absolute — e.g.
+ * `https://entpoind.com/.well-known/tools-keys.json` or the `keysUrl` field a
+ * runtime embeds in its receipts.
+ *
+ * Throws on transport failure — callers that distinguish "couldn't fetch keys"
+ * from "bad signature" should catch and report that separately.
+ */
+export async function fetchToolsKeys(keysUrl) {
+    const res = await fetch(keysUrl, { headers: { accept: "application/jwk-set+json, application/json" } });
+    if (!res.ok)
+        throw new Error(`tools keys: HTTP ${res.status} from ${keysUrl}`);
+    const doc = (await res.json());
+    if (!doc || !Array.isArray(doc.keys))
+        throw new Error("tools keys: response is not a JWK Set");
+    return doc.keys.filter((k) => k && typeof k.kid === "string" && k.kty === "OKP" && k.crv === "Ed25519" && typeof k.x === "string");
+}
+// ─── Ed25519 ──────────────────────────────────────────────────────────
+function bytesFromBase64Url(s) {
+    const pad = (4 - (s.length % 4)) % 4;
+    const b64 = s.replace(/-/g, "+").replace(/_/g, "/") + "=".repeat(pad);
+    const bin = atob(b64);
+    const out = new Uint8Array(bin.length);
+    for (let i = 0; i < bin.length; i++)
+        out[i] = bin.charCodeAt(i);
+    return out;
+}
+// RFC 8032 §7.1 test 1 public key: importing it fails only where WebCrypto has no Ed25519.
+const PROBE_KEY = { kty: "OKP", crv: "Ed25519", x: "11qYAYKxCrfVS_7TyWQHOg7hcvPapiMlrwIaaPcHURo", ext: true };
+let ed25519Probe;
+/** Whether this runtime's WebCrypto can verify Ed25519 signatures. Cached after the first call. */
+export function ed25519Supported() {
+    ed25519Probe ??= (async () => {
+        try {
+            await crypto.subtle.importKey("jwk", PROBE_KEY, { name: "Ed25519" }, false, ["verify"]);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    })();
+    return ed25519Probe;
+}
+async function checkSignature(publicKey, message, signatureB64Url) {
+    let key;
+    try {
+        key = await crypto.subtle.importKey("jwk", { kty: publicKey.kty, crv: publicKey.crv, x: publicKey.x, ext: true }, { name: "Ed25519" }, false, ["verify"]);
+    }
+    catch {
+        // A key that will not import is a bad key, unless the runtime cannot do Ed25519 at all.
+        return (await ed25519Supported()) ? "invalid" : "unsupported";
+    }
+    try {
+        const ok = await crypto.subtle.verify({ name: "Ed25519" }, key, bytesFromBase64Url(signatureB64Url), new TextEncoder().encode(message));
+        return ok ? "valid" : "invalid";
+    }
+    catch {
+        return "invalid";
+    }
+}
+/**
+ * Verify a base64url Ed25519 signature. Never throws on hostile input. Returns
+ * false both for a wrong signature and for a runtime without Ed25519; use
+ * `ed25519Supported()` to tell those apart, or the `verify*` functions, which
+ * report `unsupported_runtime`.
+ */
+export async function verifySignature(publicKey, message, signatureB64Url) {
+    return (await checkSignature(publicKey, message, signatureB64Url)) === "valid";
+}
+/** The canonical bytes a receipt's signature covers: JCS(envelope − signature). */
+export function canonicalReceiptString(envelope) {
+    const rest = { ...envelope };
+    delete rest.signature;
+    return canonicalJcs(rest);
+}
+/** Runtime shape guard for an untrusted receipt envelope. */
+export function isReceiptEnvelope(x) {
+    if (!x || typeof x !== "object")
+        return false;
+    const e = x;
+    return (e.version === "1" &&
+        typeof e.receiptId === "string" &&
+        typeof e.issuedAt === "string" &&
+        typeof e.type === "string" &&
+        typeof e.signatureKeyId === "string" &&
+        typeof e.signature === "string" &&
+        !!e.body &&
+        typeof e.body === "object" &&
+        e.body.type === e.type);
+}
+/**
+ * Verify a Tools receipt against the published public keys. Accepts the parsed
+ * envelope, its JSON text, or the `{ receipt }` wrapper the API returns. Pure
+ * public-key crypto — no account, no network.
+ */
+export async function verifyReceipt(input, publicKeys) {
+    let envelope = typeof input === "string" ? safeParse(input) : input;
+    if (!isReceiptEnvelope(envelope) && envelope && typeof envelope === "object") {
+        envelope = envelope.receipt;
+    }
+    if (!isReceiptEnvelope(envelope))
+        return { ok: false, reason: "malformed_envelope" };
+    const key = findKey(publicKeys, envelope.signatureKeyId);
+    if (!key)
+        return { ok: false, reason: "unknown_key" };
+    const check = await checkSignature(key, canonicalReceiptString(envelope), envelope.signature);
+    if (check === "unsupported")
+        return { ok: false, reason: "unsupported_runtime" };
+    if (check === "invalid")
+        return { ok: false, reason: "bad_signature" };
+    return { ok: true, signedAt: envelope.issuedAt, signatureKeyId: envelope.signatureKeyId };
+}
+/** The canonical bytes an artifact's signature covers: JCS(envelope − signature). */
+export function canonicalArtifactString(envelope) {
+    const rest = { ...envelope };
+    delete rest.signature;
+    return canonicalJcs(rest);
+}
+/** Runtime shape guard for an untrusted artifact envelope. */
+export function isArtifactEnvelope(x) {
+    if (!x || typeof x !== "object")
+        return false;
+    const e = x;
+    return (e.version === "1" &&
+        typeof e.artifactId === "string" &&
+        typeof e.issuedAt === "string" &&
+        typeof e.kind === "string" &&
+        typeof e.signatureKeyId === "string" &&
+        typeof e.signature === "string" &&
+        "subject" in e &&
+        "claims" in e);
+}
+/** Verify a standalone VerifiableArtifact against the published public keys. */
+export async function verifyArtifact(input, publicKeys) {
+    const envelope = typeof input === "string" ? safeParse(input) : input;
+    if (!isArtifactEnvelope(envelope))
+        return { ok: false, reason: "malformed_envelope" };
+    const key = findKey(publicKeys, envelope.signatureKeyId);
+    if (!key)
+        return { ok: false, reason: "unknown_key" };
+    const check = await checkSignature(key, canonicalArtifactString(envelope), envelope.signature);
+    if (check === "unsupported")
+        return { ok: false, reason: "unsupported_runtime" };
+    if (check === "invalid")
+        return { ok: false, reason: "bad_signature" };
+    return {
+        ok: true,
+        signedAt: envelope.issuedAt,
+        signatureKeyId: envelope.signatureKeyId,
+        kind: envelope.kind,
+    };
+}
+/**
+ * Verify a bundle offline: the artifact's Ed25519 signature, then — when an
+ * anchor is present — that JCS(signed artifact) is included under the anchored
+ * Merkle root. `anchored:false` on a pre-anchor bundle is a valid result, not a
+ * failure.
+ */
+export async function verifyBundle(input, publicKeys) {
+    const bundle = (typeof input === "string" ? safeParse(input) : input);
+    if (!bundle || typeof bundle !== "object" || !isArtifactEnvelope(bundle.artifact)) {
+        return { ok: false, anchored: false, reason: "malformed_envelope" };
+    }
+    const sig = await verifyArtifact(bundle.artifact, publicKeys);
+    if (!sig.ok)
+        return { ok: false, anchored: false, reason: sig.reason };
+    if (!bundle.anchor)
+        return { ok: true, anchored: false, signedAt: sig.signedAt, kind: sig.kind };
+    const leaf = canonicalJcs(bundle.artifact);
+    const included = await verifyMerkleInclusion(leaf, bundle.anchor.proof ?? [], bundle.anchor.merkleRoot);
+    if (!included)
+        return { ok: false, anchored: true, reason: "not_in_anchored_root" };
+    return { ok: true, anchored: true, signedAt: sig.signedAt, kind: sig.kind };
+}
+/**
+ * One-shot receipt verification against the published key set — fetch keys,
+ * resolve `signatureKeyId`, verify. `keysUrl` defaults to the production
+ * well-known document; pass an override for staging / self-hosted runtimes.
+ * Throws (like `fetchToolsKeys`) when the keys cannot be fetched, so "could not
+ * check" never reads as a verdict on the receipt.
+ */
+export async function verifyReceiptOnline(input, keysUrl = DEFAULT_KEYS_URL) {
+    return verifyReceipt(input, await fetchToolsKeys(keysUrl));
+}
+// Only a well-formed Ed25519 public key is ever used, whatever the caller's key list holds.
+function findKey(keys, kid) {
+    return keys.find((k) => !!k && k.kid === kid && k.kty === "OKP" && k.crv === "Ed25519" && typeof k.x === "string");
+}
+function safeParse(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
+}

package/dist/merkle.d.ts

@@ -0,0 +1,18 @@
+/**
+ * @entpoind/verify — domain-separated Merkle inclusion proofs.
+ *
+ * Byte-identical port of runtime/shared/merkle.ts's verify path:
+ *   leaf hash  = SHA-256( 0x00 ‖ utf8(leaf) )
+ *   node hash  = SHA-256( 0x01 ‖ leftBytes ‖ rightBytes )
+ *   odd nodes are carried up unchanged (never duplicated).
+ */
+export declare function merkleLeafHash(leaf: string): Promise<string>;
+export type MerkleProofStep = {
+    sibling: string;
+    position: "left" | "right";
+};
+/**
+ * Verify that `leaf` (the original leaf STRING — the canonical signed envelope)
+ * folds along `proof` into `root`. Never throws on a malformed proof.
+ */
+export declare function verifyMerkleInclusion(leaf: string, proof: ReadonlyArray<MerkleProofStep>, root: string): Promise<boolean>;

package/dist/merkle.js

@@ -0,0 +1,62 @@
+/**
+ * @entpoind/verify — domain-separated Merkle inclusion proofs.
+ *
+ * Byte-identical port of runtime/shared/merkle.ts's verify path:
+ *   leaf hash  = SHA-256( 0x00 ‖ utf8(leaf) )
+ *   node hash  = SHA-256( 0x01 ‖ leftBytes ‖ rightBytes )
+ *   odd nodes are carried up unchanged (never duplicated).
+ */
+const ENC = new TextEncoder();
+async function sha256Hex(input) {
+    const bytes = typeof input === "string" ? ENC.encode(input) : input;
+    const digest = await crypto.subtle.digest("SHA-256", bytes);
+    return [...new Uint8Array(digest)].map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+const SHA256_HEX = /^[0-9a-f]{64}$/;
+function hexBytes(hex) {
+    const out = new Uint8Array(hex.length / 2);
+    for (let i = 0; i < out.length; i++)
+        out[i] = parseInt(hex.slice(i * 2, i * 2 + 2), 16);
+    return out;
+}
+function concat(...parts) {
+    const out = new Uint8Array(parts.reduce((n, p) => n + p.length, 0));
+    let off = 0;
+    for (const p of parts) {
+        out.set(p, off);
+        off += p.length;
+    }
+    return out;
+}
+export async function merkleLeafHash(leaf) {
+    return sha256Hex(concat(Uint8Array.of(0x00), ENC.encode(leaf)));
+}
+async function merkleNodeHash(leftHex, rightHex) {
+    return sha256Hex(concat(Uint8Array.of(0x01), hexBytes(leftHex), hexBytes(rightHex)));
+}
+/**
+ * Verify that `leaf` (the original leaf STRING — the canonical signed envelope)
+ * folds along `proof` into `root`. Never throws on a malformed proof.
+ */
+export async function verifyMerkleInclusion(leaf, proof, root) {
+    try {
+        if (typeof leaf !== "string" || typeof root !== "string" || !Array.isArray(proof))
+            return false;
+        const want = root.toLowerCase();
+        if (!SHA256_HEX.test(want))
+            return false;
+        let h = await merkleLeafHash(leaf);
+        for (const step of proof) {
+            if (!step || (step.position !== "left" && step.position !== "right"))
+                return false;
+            if (typeof step.sibling !== "string" || !SHA256_HEX.test(step.sibling.toLowerCase()))
+                return false;
+            const sibling = step.sibling.toLowerCase();
+            h = step.position === "left" ? await merkleNodeHash(sibling, h) : await merkleNodeHash(h, sibling);
+        }
+        return h === want;
+    }
+    catch {
+        return false;
+    }
+}

package/package.json

@@ -1,6 +1,32 @@
 {
   "name": "@entpoind/verify",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Offline verification of Entpoind Tools receipts and VerifiableArtifact bundles — Ed25519 over RFC 8785 canonical JSON, plus Merkle inclusion proofs. Zero dependencies.",
+  "license": "MIT",
+  "author": "Avonao, Inc.",
+  "homepage": "https://entpoind.com/docs/sdks",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": ["dist", "README.md", "LICENSE"],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\" && tsc -p tsconfig.build.json",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": ["entpoind", "tools", "receipt", "ed25519", "verification", "jcs", "rfc8785", "merkle", "webcrypto"],
+  "devDependencies": {
+    "typescript": "^5.6.3",
+    "vitest": "^4.1.11"
+  }
+}