sm-attest-viewer

The audited display surface for substrate-attested agent action streams.

When an autonomous agent proposes a high-stakes action — a financial transaction, a clinical recommendation, an infrastructure command — a human supervisor often needs to verify before it commits. The display surface where that supervisor reads the evidence is itself a security boundary: hostile content carried inside otherwise-trusted events (injected markup, prototype-pollution payloads, malformed identifiers) can break out of the rendered scope and undermine the verification.

sm-attest-viewer is the React / TypeScript renderer for the Attested Action Envelope (AAE) — the per-action evidence primitive aligned with Project NANDA's Attestation pillar. It displays signed agent action streams as forensic, filterable, reverse-chronological timelines, audited so what reaches the operator's eyes is exactly what the substrate emitted — without transformation, without escape, with no opportunity for hostile content to execute.

It is one layer of a human-in-the-loop verification stack — the trustworthy display step. Operator authentication, hardware-attested endpoints, signed approve/deny actions, and audit logging are responsibilities of the surrounding stack, not this package.

The first TypeScript package in an otherwise Python-first portfolio of Stellarminds.ai primitives aligned with Project NANDA standards.

What this package secures (v0.2)

• No content escape. Every user-supplied field in the envelope reaches the DOM through React's default text-escaping path — no dangerouslySetInnerHTML, no string interpolation into HTML.
• Hardened object lookups. Internal maps are accessed via Object.hasOwn guards so a hostile classification or status string cannot resolve to a prototype method.
• Defensive parsing. Malformed timestamps, missing payload fields, non-string runtime values render gracefully rather than crash.
• Adversarially tested. XSS payloads, prototype-pollution attempts, malformed inputs, and unknown trust states are explicitly covered in the 69-test suite.

What this package does not (yet) do

• Independent cryptographic verification of the proof block. Trust state at v0.1 is derived from substrate-stamped lifecycle markers (anchored, signed, etc.); the renderer trusts the substrate's attestation rather than re-checking the signature itself. Renderer-side verification is a v1.x property — see SPEC.md §3.6 and §12.
• Operator authentication, approval actions, audit logging, endpoint attestation. These belong to the surrounding HITL stack. Adopters wire their own.

Features

• Substrate-neutral — accepts AAE events as a props array; connect to AG-UI, MCP, A2A, websockets, or JSONL replay.
• Domain-neutral — no hardcoded taxonomy for classifications, regimes, or action verbs.
• Tested behavior — pure derivation and filter functions exported and exhaustively unit-tested against the trust-state and rendering rules documented in SPEC.md §11.
• Four golden VC fixtures covering every cryptosuite the AAE spec enumerates: Ed25519Signature2020, EcdsaSecp256r1Signature2019, DataIntegrityProof + eddsa-rdfc-2022, and DataIntegrityProof + ml-dsa-2025 (FIPS 204 post-quantum).
• Accessible 4-state trust gem mapping AAE lifecycle to verified / warning / failed / pending visual primitives.
• Envelope-kind discriminator (v0.2) — the top-level type field is now a tagged union over "action" \| "decision" \| "belief" \| "checkpoint" per SPEC.md §13. Decision, belief, and checkpoint rows surface with distinct badges; legacy free-text values (e.g. "EVIDENCE") normalize to "action" for full backward compatibility.

Installation

From source (current)

The package is not yet published to npm. To use the v0.2 working draft today, install directly from the repository:

git clone https://github.com/Sharathvc23/sm-attest-viewer.git
cd sm-attest-viewer
pnpm install
pnpm test

From npm (planned)

Once v0.2 stabilizes, the package will be published as @sharathvc/sm-attest-viewer:

npm install @sharathvc/sm-attest-viewer
# or
pnpm add @sharathvc/sm-attest-viewer

Peer dependencies: react >= 19.0.0, react-dom >= 19.0.0.

Quick Start

import { InboxPresentation, type AttestationEvent } from "@sharathvc/sm-attest-viewer";

export function MyInbox() {
  const [events, setEvents] = useState<AttestationEvent[]>([]);
  return <InboxPresentation events={events} status="open" />;
}

Wire events to wherever your AAEs come from — an AG-UI stream, an MCP tool output, a JSONL file, a websocket, or directly from sm-locp's VCGenerator output.

Golden Fixtures

import { goldenFixtures, envelopeKindFixtures } from "@sharathvc/sm-attest-viewer/fixtures";

// Cryptosuite coverage (v0.1)
goldenFixtures.ed25519Signature2020;        // VC 1.1
goldenFixtures.ecdsaSecp256r1Signature2019; // VC 1.1, NIST P-256
goldenFixtures.dataIntegrityEddsaRdfc2022;  // VC 2.0
goldenFixtures.dataIntegrityMlDsa2025;      // VC 2.0, post-quantum ML-DSA

// Envelope-kind discriminator (v0.2, SPEC §13)
envelopeKindFixtures.decision;   // operator authorize/deny/annotate
envelopeKindFixtures.belief;     // agent internal-state assertion
envelopeKindFixtures.checkpoint; // merkle commitment over predecessor envelopes

Fixture signatures use placeholder bytes — they do not verify against real keys. Treat them as shape examples.

Consumer Responsibilities

The renderer uses Tailwind CSS utility classes and a small set of CSS custom properties for trust-state and classification tones. Consumers must:

1. Have Tailwind CSS configured (any v3 or v4 release).
2. Define --gem-verified, --gem-warning, --gem-failed, --gem-pending CSS variables in their root scope. See fixtures/css-tokens.example.css for an accessible default.
3. Wire <TooltipProvider> once at the app root for hover tooltips.

Specification

The wire format used by the reference implementation is documented in SPEC.md as a working draft. The design rationale and the role of AAE rendering as a separable primitive live in WHITEPAPER.md.

Related Packages

Operator surfaces (peers)

Package	Role
sm-decision-inspector	HITL workbench for the "decision" envelope variant — approve / deny gestures, M-of-N countersignature quorum, signer roster.
sm-attest-auditor	Bidirectional audit drill — forward chain-walk via predecessor_hash and reverse RFC 6962 merkle inclusion verification from checkpoint envelopes.

Behavioral Trust (produces / stages AAEs)

Package	Role
sm-locp	Open Compliance Protocol — defeasible-logic engine + W3C VC issuance. Produces AAEs.
sm-airlock	Allowlist-gated plugin sandbox — denies plugin attribute access by default, per-method rate limits, Ed25519-signed plugin manifests.
sm-enclave	Speculative execution sandbox; stages side effects before AAE commit.

Federation

Package	Role
sm-bridge	NANDA-compatible registry endpoints + Quilt-style delta sync.

Model Trust

Package	Role
sm-model-provenance	Zero-dependency model identity dataclass.
sm-model-card	Unified model card schema.
sm-model-integrity-layer	Offline integrity verification.
sm-model-governance	Three-plane ML governance — training → approval → serving.

License

MIT

---

First published: 2026-05-17 | Last modified: 2026-05-20

Personal research contributions aligned with Project NANDA standards. Stellarminds.ai