@motebit/verifier

Apache-2.0 library for verifying signed Motebit artifacts. The thin file-reading + human-formatting layer on top of @motebit/crypto's pure verification primitives.

Install

npm i @motebit/verifier

import { verifyArtifact } from "@motebit/verifier";

// In-memory / browser: pass the receipt JSON string. (Node convenience:
// `verifyFile("./receipt.json")` reads the file for you.)
const result = await verifyArtifact(receiptJson);
if (result.type === "receipt" && result.valid) {
  // `valid` is integrity (signed + intact) — NOT identity. The binding rung
  // is `result.sovereign`, on this package's result type (not the bare
  // `@motebit/crypto` result). Render the rung, never `valid`, as identity:
  console.log(
    result.sovereign ? "sovereign — author proven offline" : "integrity-only — signer not bound",
  );
}

Zero relay contact. Zero network. The signer's public key is embedded in the artifact or derivable from it; verification is pure crypto against committed wire formats.

Looking for the motebit-verify command-line tool?

Install @motebit/verify instead. That package ships the motebit-verify binary with every hardware-attestation platform bundled. This package (@motebit/verifier) is the library it sits on — reach for it when you're writing TypeScript code that consumes signed artifacts programmatically.

The naming follows the verb / agent-noun lineage that survives for decades — npm / @npmcli/arborist, or git beside libgit2 (the git model reimplemented as a linkable library). Verb (verify) = the tool a human installs. Agent-noun with -er suffix (verifier) = the library code links against.

Why this exists

Motebit's moat is the self-signing body: every action the agent takes emits a signed receipt that any third party can verify without running the motebit. This package is the smallest public surface of that promise — a deterministic verification library that answers "is this signed artifact authentic, and what does it claim?" — exposed for programmatic consumption.

API

Everything below is exported from the package root. The prose sections that follow are the detail behind each line.

• verifyFile(path, opts?) / verifyArtifact(content, opts?) / verifySkillDirectory(path, opts?) / formatHuman(result) — the core surface: read or accept an artifact, auto-detect its kind, return the typed result; render it as a printable banner.
• verifyReceiptVerdict / verifyDelegationTokenVerdict / isFullyVerified — structured VerificationVerdict producers (independent axes, no silent true) and the fail-closed collapse to a boolean. The verdict types (VerificationVerdict, EvidenceRef, RepairInstruction, …) are exported alongside.
• verifyEvidenceProvenance — re-check a verdict's cited evidence down to the primary record: presence, never truth.
• verifyApprovalDecision — the "approve" governance band's signed human-consent artifact, verified against a pinned approver key.
• verifyDelegation / verifyStandingDelegation / verifyTokenAgainstGrant / verifyDelegationRevocation / findGrantRevocation / subjectBindingDigest / verifySubjectBinding — the delegation family: standing grants, per-tick tokens, revocations, subject bindings.
• verifySovereignBinding / verifyKeySuccession / verifySuccessionChain / verifyBondCommitment / verifyMerkleInclusion — the public-verification-surface laws an auditor composes.
• signEvalAttestation / verifyEvalAttestation / EVAL_ATTESTATION_SUITE — the EvalAttestation family (signed third-party measurement; subject ≠ signer).
• signRoutingTranscript / verifyRoutingTranscript / ROUTING_TRANSCRIPT_SUITE — the RoutingDecisionTranscript family (the routing arc's proof artifact; subject = signer).
• verifyCostAttestation / verifyInvoice / executionReceiptDigest / costAttestationDigest — settlement-invoice verifiers plus the two mandated digest helpers.
• verifyWithdrawalReceipt — the relay-signed completed-withdrawal receipt, re-checked offline.
• signRequestEnvelope / verifyRequestEnvelope — stateless per-request identity authentication against a registered key.

What it verifies

The unified verify() dispatcher in @motebit/crypto auto-detects and verifies:

• identity — motebit.md (YAML frontmatter + content + Ed25519 signature)
• receipt — ExecutionReceipt (task ID, tools used, prompt/result hashes, signature)
• credential — W3C-style Verifiable Credentials
• presentation — W3C-style Verifiable Presentations

This package wraps the dispatcher with verifyFile (path → result), verifyArtifact (string → result), verifySkillDirectory (path-to-a-skill-directory → result, for skill bundles shipped as a tree rather than a single file), and formatHuman (result → printable banner).

It also re-exports the structured-verdict surface from @motebit/crypto: verifyReceiptVerdict (a signed receipt → a VerificationVerdict whose independent axes — integrity, identityBinding, authority, revocation, temporalBasis, evidenceBasis, plus a first-class repair — cannot silently collapse to true; there is no top-level valid boolean to over-read), verifyDelegationTokenVerdict (a per-tick token against its standing grant — authority and revocation stay orthogonal, and temporalMode selects whether a clock-rollback is load-bearing), and isFullyVerified (the fail-closed collapse to a boolean: true only when every load-bearing axis passes — stricter than the legacy per-function booleans by design). See verify-family-fail-closed.md.

It also re-exports verifyEvidenceProvenance — the law that re-checks a verdict's evidenceBasis down to the primary record (verifiable-locality extended from signatures to evidence). A verdict's EvidenceRef may carry optional provenance; this law confirms the named span is an exact substring of projection(bytes) where the bytes content-address to digest — re-verifiable presence, never truth, with no oracle (a fabricated figure cannot be placed into a content-addressed record). The projection recipe is an injected, app-owned seam: absent ⇒ the span is located over the raw bytes directly (re-verifiable by construction); present with no resolver ⇒ it fails closed (projection_unresolved), so motebit never owns a document-format catalog. Re-exported here so a consumer pinning @motebit/verifier re-checks evidence from the same surface it already consumes. See evidence-provenance.md.

It also re-exports verifyApprovalDecision from @motebit/crypto — the "approve" governance band's signed human-consent artifact (ApprovalDecision). Unlike the auto-detected artifact types above, an ApprovalDecision is verified explicitly against a pinned approver key (it carries no motebit_id → key binding, so verifying against its own embedded key is circular). See the governance-triad guide for where a verified decision sits on the binding ladder.

It re-exports the public-verification-surface laws an auditor composes (widened 2026-07-08 for the Auditor archetype; services consume only this aggregator, never @motebit/crypto directly): verifySovereignBinding (the identity rung — a motebit_id commits to its genesis key, offline), verifyKeySuccession / verifySuccessionChain (key-lineage over the self-signed succession chain a relay serves publicly), verifyBondCommitment (the anti-sybil address-binding + self-signature law), and verifyMerkleInclusion (RFC 6962-shaped inclusion proofs for settlement anchors and identity-transparency bundles).

It also re-exports the EvalAttestation family — the signed third-party-measurement artifact (subject ≠ signer; spec/eval-attestation-v1.md): verifyEvalAttestation (envelope law — pinned suite, closed eval_kind intake, non-empty results, signature over canonical bytes; establishes "this issuer said this about this subject", deliberately never measurement truth / issuer authority / key→id binding / freshness), signEvalAttestation for issuer services (the signRequestEnvelope precedent), and the pinned EVAL_ATTESTATION_SUITE. Each result embeds a whole per-axis VerificationVerdict, so the no-silent-true discipline survives transport; consumers re-check cited evidence with verifyEvidenceProvenance and the verdict producers above.

It also re-exports the RoutingDecisionTranscript family — the routing arc's proof artifact (subject = signer, receipt-family; spec/routing-transcript-v1.md): verifyRoutingTranscript (the INTEGRITY rung — pinned suite/spec, non-empty frozen candidate set, winner-membership, signature over canonical bytes; establishes "this delegator committed to this decision record"), signRoutingTranscript for producer runtimes, and the pinned ROUTING_TRANSCRIPT_SUITE. The FAITHFULNESS rung — recomputing the decision from the frozen inputs under the pinned algorithm_version — is recomputeRoutingDecision in source-available @motebit/semiring, deliberately outside the permissive floor.

For the same reason — authority is the scope/chain, not a motebit_id → key ladder resolvable from the artifact alone — the delegation family is also re-exported as explicit verifiers (not auto-detected): verifyDelegation (a standalone or per-tick DelegationToken), verifyStandingDelegation (a standing grant: signature, activation, expiry, and an injected revocation seam), verifyTokenAgainstGrant (a per-tick token IS a valid tick of its grant — scope narrows, TTL bounded, grant not revoked), and verifyDelegationRevocation (a revocation's signature; the caller binds it to the grant). A standing grant's revocation check is the consumer's responsibility — the verifiers are I/O-free and cannot fetch a feed — so findGrantRevocation does that check correctly: it returns the revocation that authoritatively revokes a grant from a candidate set, binding on grant_id and the grant's delegator_public_key and a valid signature, so matching grant_id alone (the foot-gun) cannot spoof a revocation. Build the verifyStandingDelegation isRevoked seam from it. This lets a consumer validate a standing monitor's authorization root, every tick token, and revocation through this package alone. See [email protected].

[email protected] extends the receipt chain to the money — a verifiable bill a customer re-derives offline (motebit owns the format; the issuer runs the rails). Two issuer-signed artifacts are re-exported as explicit verifiers, both checked against the issuer's REGISTERED key (a carried key, if present, must match it): verifyCostAttestation (an issuer's cost-of-one-execution declaration in nano-USD against a named rate table, bound to its ExecutionReceipt by digest, with an attested_at >= completed_at temporal axis) and verifyInvoice (a flat fee plus passthrough bounded by passthrough_minor <= floor(Σ cost_nanos / 1e7), with per-line cost binding, issuer-consistency, and a detectable stale_cost_overstatement axis for a downward supersession). Both return a per-axis structured verdict, never a naked boolean. The two mandated digest helpers — executionReceiptDigest and costAttestationDigest — are re-exported too so a producer and verifier reproduce a binding by construction. See [email protected].

[email protected] adds an optional, generic subject_binding on the grant (SubjectBindingV1): the delegator's signature reaches the EXACT resolved subjects the authority covers, by digest-binding a detached, vertically-typed scope artifact — closing the gap where an interpreter (not the delegator) chose the identities the agent acts on. subjectBindingDigest computes the canonical digest of that detached artifact (hex(SHA-256(canonicalJson))), and verifySubjectBinding checks, fail-closed, that a presented artifact matches the grant's signed binding (digest method, declared artifact_schema, digest). Authority only — subject completeness ("every signed subject was attempted") is a monitor receipt-profile rule on top, never a property of the generic binding.

The withdrawal receipt closes the money-out side of the self-attesting contract: a completed withdrawal is a truth the relay asserts, so it must be verifiable without relay contact. verifyWithdrawalReceipt re-checks the relay's Ed25519 signature over a WithdrawalReceiptPayload — the money-relevant subset of the market-v1 §2.9 wire record (withdrawal_id, motebit_id, amount, currency, destination, payout_reference, completed_at, relay_id). A consumer reconstructs the payload from the record's fields (all present on the response, including relay_id) and verifies against the carried relay_public_key, fail-closed on any decode or mismatch.

On the same principle, the signed-request-envelope family is re-exported as explicit signer/verifier — signRequestEnvelope and verifyRequestEnvelope ([email protected]): stateless per-request identity authentication where the signature is verified against the identity's registered public key (resolved by the caller from motebit_id, never carried by the request), the payload travels detached behind a payload_digest, and aud binding kills cross-service replay. Not auto-detected — the key comes from the registry, not the envelope.

Guarantees

• No network. Verification runs entirely offline. No relay calls, no DID resolution over the wire.
• One runtime dependency: @motebit/crypto. The only other declared dependency, @motebit/protocol, is type-only — every import that crosses it is import type / export type, so no runtime code crosses that boundary; it exists so the published type declarations resolve. Every dependency is a trust attack surface we'd have to re-audit on every upgrade.
• Suite-agile. New signature suites (post-quantum, future) are registry additions, not library changes — @motebit/crypto's verifyBySuite dispatches for us.

Related

• @motebit/verify — the motebit-verify CLI that ships with every hardware-attestation platform bundled. Install this if you want the command-line tool.
• @motebit/crypto — the verification primitives this package wraps (Apache-2.0, zero deps)
• @motebit/protocol — protocol types for the artifacts being verified (Apache-2.0, zero deps)
• @motebit/sdk — developer contract for building Motebit-powered agents
• create-motebit — scaffold a signed agent identity
• motebit — reference runtime and operator console

License

Apache-2.0 — see LICENSE.

"Motebit" is a trademark. The Apache License grants rights to this software, not to any Motebit trademarks, logos, or branding. You may not use Motebit branding in a way that suggests endorsement or affiliation without written permission.