@napplet/conformance
v0.32.0
Published
Framework-agnostic napplet protocol conformance engine — reference mock shell, per-NAP envelope validators, manifest validator, check registry, and reporters
Maintainers
Readme
@napplet/conformance
Framework-agnostic conformance engine for the napplet protocol. It lets a napplet self-verify that it conforms to NIP-5D + the NAP wire protocol before publishing, in two scopes that share this one engine:
- Headless / CI — driven by the
napplet-conformancePlaywright CLI. - Standalone web runtime — the single-window
apps/conformanceapp.
v1 is zero-config protocol conformance: NIP-5D manifest-event validity, boots under sandbox="allow-scripts", receives runtime-injected window.napplet, every emitted postMessage envelope validates against the per-NAP validators, graceful degradation when domains are absent, and no forbidden globals.
The harness acts as a NIP-5D shell for the port-bound identity model: it binds the MessagePort from the first valid napplet.hello, answers only over that port, and revokes the napplet and removes its frame on a second hello, any other window-level message, a second load or the port closing. wire/port-only fails a napplet that posts messages at window level instead of through window.napplet; lifecycle/keeps-verified-document is an advisory for a napplet that navigates or reloads its own frame.
Local maturity policy
The reference mock can enforce a resolved host domain ceiling: createReferenceShell({ domains: selection.domains }), where selection comes from selectNapDomains in @napplet/core. The same set belongs in the injected prelude. Per-endpoint grants can narrow this ceiling but cannot widen it; excluded requests remain recorded for envelope validation and receive no response.
bootAndCollect({ ...options, domains: ['storage', 'llm'], maturity: {} }) selects supported candidates before boot and uses that set in both injection and dispatch. A named opt-in such as maturity: { optIn: ['llm'] } enables evaluation of that candidate. Normal conformance runs omit maturity filtering and retain full-domain coverage. Experimental status never waives protocol validation. See the maturity guide.
What's in the box
validateEnvelope(msg)— runtime validation of anydomain.actionenvelope a napplet emits, across all active NAP domains. Catches malformed payloads, unknown types, and napplets that put shell→napplet (inbound) traffic on the wire.validateManifestEvent(event)— checks that a resolved Nostr event is a NIP-5D napplet manifest (5129,15129, or35129) with a single artifactxhash, a non-empty description, and bareR/Odomains. Domains outside the toolchain registry produce the advisorymanifest/requires-knownwarning; they do not fail a run or imply runtime support.validateManifest(html)— compatibility wrapper for older HTML-only harnesses. HTML alone cannot prove a signed NIP-5D manifest event.parsePresentationMedia(event)— applies NIP-5D §Presentation media toscreenshotandpreviewtags: splits NIP-92key valuefields, requires onexsha256, drops entries clients must ignore (missing, malformed or repeatedx; an undecodablem; more than onepreview), and returns the usable list in manifest order with advisories for everything ignored.
Manifest validation accepts additional Nostr tags without changing the event or restricting tag names. It checks required fields and the specified shape and cardinality of recognized optional metadata. For example, source accepts one HTTP(S), SSH, Git, scp-like, or NIP-34 nostr:// repository location; source-commit must be one full lowercase-hex commit ID and source-archive one HTTPS URL, sha256 and MIME type; malformed icon, screenshot and preview metadata remains an advisory (manifest/media-usable) with fallback, as does a source-commit without a repository source. Extra tags cannot satisfy missing content or hide invalid hashes or capability declarations. This is non-normative guidance; the living NIP-5D proposal defines these requirements.
The validator surface is kept in lockstep with @napplet/nap by a drift test, so a new NAP message type cannot ship without matching conformance coverage.
@napplet/nap remains a devDependency because the drift test reads NAP source files directly and the GAMEPAD parity test imports its state helpers. This workspace dependency lets Turbo invalidate cached conformance tests after NAP-only source changes; it is not a runtime dependency of the published engine. Run pnpm test:workflow-contracts from the repository root to verify cache invalidation against the current Turbo configuration.
For intent envelopes, conformance checks the merged intent.invoke request/result carrier. Requests require URI-derived archetype, action, and stable convention identity. Acceptance results transfer delivery responsibility to the runtime, while targets receive buffered intent.deliver pushes. Payload semantics belong to the convention and target.
This non-normative description follows the living NAP-INC and NAP-INTENT documents.
import { validateEnvelope, validateManifestEvent } from '@napplet/conformance';
validateEnvelope({ type: 'relay.subscribe', id: 'a', subId: 'b', filters: [{ kinds: [1] }] }).ok; // true
validateManifestEvent(resolvedManifestEvent).ok; // true when the NIP-5D event is well-formedThis package is a development/testing tool. It is not loaded inside the napplet sandbox at runtime.
Install
pnpm add -D @napplet/conformanceJSR consumers can import the same source package:
import { runConformance, validateEnvelope, validateManifest } from 'jsr:@napplet/conformance';Most application projects should use the napplet-conformance CLI wrapper in CI. Use this package directly when you are embedding the engine in a custom harness, building a shell-side test runtime, or validating individual envelopes and resolved manifest events in unit tests.
Common Workflows
Validate one envelope
import { validateEnvelope } from '@napplet/conformance';
const verdict = validateEnvelope({
type: 'storage.get',
id: 'request-1',
key: 'settings',
});
if (!verdict.ok) {
console.error(verdict.errors);
}Validate a resolved manifest event
import { validateManifestEvent } from '@napplet/conformance';
const verdict = validateManifestEvent(resolvedManifestEvent);
if (!verdict.ok) {
throw new Error(verdict.errors.map((e) => e.message).join('\n'));
}Run the full engine
import { makeContext, runConformance } from '@napplet/conformance';
const context = makeContext({
manifestHtml: '<!doctype html><html><head></head><body></body></html>',
});
const run = runConformance(context);
for (const check of run.checks) {
console.log(check.id, check.status);
}Public Surface
- Envelope validation:
validateEnvelope,knownEnvelopeTypes,ENVELOPE_SPECS - Manifest validation:
validateManifestEvent,validateManifest - Reference shell harness:
createReferenceShell,attachReferenceShell,bindNappletPort - Browser boot collection:
bootAndCollect - Context helpers:
makeContext,buildContext - Runner and report helpers:
runConformance,toJson,toPretty,toJUnit
CLI Pairing
The package intentionally stays framework-agnostic. For a project-level command that launches real Chromium against a built napplet, use the companion napplet-conformance CLI shipped from @napplet/conformance-cli.
GAMEPAD integration
GAMEPAD validation recognizes only gamepad.subscribe, gamepad.unsubscribe, and gamepad.state; correlation ids are rejected. The injected browser API shares snapshot validation with the portable binding and accepts only parent messages. The reference mock reports unavailable controllers rather than physical input. Focus and native-access isolation require host integration tests. See the proposed NAP-GAMEPAD.
Custom browser hosts
bootAndCollect({ url, html, runtimePreludeSource, verifiedManifest }) requires the maintained shim IIFE source and accepts an optional loaded HTML snapshot and a manifest already verified by the loading host. The CLI reads @napplet/shim/prelude.global; Vite hosts can import it with ?raw. The harness appends the explicit domain allowlist call, so the napplet sees exactly the bindings the maintained runtime installs; it ships no bindings of its own. Supplying html avoids refetching an artifact after the host verifies its signature and raw bytes. The engine remains browser-safe and does not import Node APIs or bundled asset loaders. Signed CLI runs pass the actual verified manifest through verifiedManifest, so navigation eligibility uses that napplet's advertised conventions and parameter names. Unsigned local runs use the reference fixture only; they do not establish eligibility for a published artifact. verifiedManifest is trusted host input, not a replacement for signature and artifact-hash verification. installedGlobal records observed installation independently from bootError; an app failure does not imply injection failed. Signature/hash verification belongs to the loading host, while validateManifestEvent checks the event structure. This is non-normative implementation guidance; consult the living NIP-5D proposal and NAPs.
Reference navigation history
The reference shell implements the NAP-NAVIGATION draft with the NAP-INTENT delivery draft. This is non-normative testing guidance, not a production shell policy. Bind a live endpoint with registerEndpoint(endpoint) and its already verified manifest before exercising history. Each endpoint keeps independent reports, visits, and pending traversal state. A pending revisit records the highest report revision seen at dispatch, and the first accepted report above it settles the revisit by value. A host domain ceiling from createReferenceShell({ domains }) also bounds history and intent delivery, and revoking a port binding ends the endpoint and discards its history; detach() alone does not.
navigation.report / navigation.get receive correlated results, including structured rejections for recognized requests with usable IDs. Validation covers report shape, exact advertised conventions and parameter lists, JSON values, revision ordering, and rejection recovery. Runtime tests cover retained history, duplicate invocations, revisit settlement, timeout/late reports, and endpoint isolation.
Shell-side fixture methods are navigationView(endpointId), revisit(endpointId, entryId), pruneNavigation(endpointId, keepIds), and terminateEndpoint(endpointId). deliverIntent(endpointId: string, request: IntentRequest): IntentDelivery | undefined takes an already normalized request, not a URI, and replays it to that existing endpoint as an ordinary delivery whose sender is the endpoint's own catalog identifier. failNavigationDelivery(endpointId, definite?) ends a pending revisit after a failed dispatch. These are host test controls, not new NAP wire operations or APIs exposed to napplet code. The navigation options set maxEntries, maxLocationBytes, timeoutMs, canReport, and canRevisit; the fixture defaults to 100 entries, 65,536 location bytes, and a 30-second pending timeout.
A production host supplies verified endpoint metadata, consent/policy, UI controls, and actual rendering checks. The reference runtime does not prove that an accepted report matches rendered content. See the navigation guide for application integration.
LLM conformance scope
NAP-LLM validation checks the four request schemas (exact API-row parameters, strict input records without unknown fields or null, enum roles and formats, padded base64 image data, nonempty ids, positive integer maxTokens, portable unique tool names with object-rooted schemas, an explicit toolChoice only with tools and a listed forced name, thinking and toolCall parts only in assistant messages, and each tool call answered exactly once by an adjacent, name-matching toolResult) and rejects result and delta envelopes emitted by napplets, following the living NAP-LLM proposal. The reference shell is a deterministic mock: one connection that supports images, JSON, tools, and every tool-choice mode, endpoint-scoped handles, exact-model requirement matching, a start / delta / end block lifecycle before the authoritative result, echoed output (trailing tool results echoed with the specified Tool execution failed. prefix for errors), a toolUse result for required or named choices, and fixture markers in the last user text ([[decline]], [[refuse]], [[stall]], [[think]], [[tool]]) for a declined prompt, a provider refusal, a generation that stays active until cancel, a display-only thinking block, and a call to the first supplied tool. It never executes a tool call. It returns typed failures rather than fabricated success. A malformed LLM request that still carries a non-empty id gets its .result with an invalid-request error, as the Wire Protocol requires; uncorrelated envelopes and napplet-emitted results are discarded. Passing mock conformance does not prove live inference, consent prompts, provider adapters, or billing behavior; test those in an LLM-capable host.
BLOSSOM coverage
The reference shell answers the thirteen NAP-BLOSSOM wire operations with typed unavailable results (unsupported, not-signed-in or server-list-unavailable). Local URI helpers are available through the injected binding. These fixtures exercise request handling without network access or signing and do not establish live server availability, deletion, integrity verification or host network-policy conformance.
Catalog integration
Envelope validation recognizes catalog.get with a string correlation id, and rejects napplet-emitted catalog.get.result as inbound-only traffic. createReferenceShell builds catalog snapshots from supplied host-verified, loadable manifest fixtures and shares selectors with intent discovery. The host checks each complete required-domain set before supplying a manifest; the caller's own domain grants are not the target napplet's compatibility set. Use catalogFilter to omit entries for a caller and intentResolver: false to exercise discovery without a resolver. It includes role-less entries and omits incomplete descriptors. The reference fixture is not a signature or artifact verifier. Use the maintained runtime prelude for browser catalog exercises. This non-normative guidance defers to the living NAP-CATALOG draft.
Torrent conformance scope
NAP-TORRENT validation checks the transfer request schemas and rejects result or job push messages emitted by napplets, following the living proposal. The reference shell advertises a mock reference transport and session-scoped jobs; it exercises source validation, isolated job controls, and revisioned settings without a torrent engine or persistent storage. Its empty formats and createFormats lists claim no verified format support. Metadata, reads, and export return metadata-unavailable; picking, saving, and opening files are unsupported. It returns typed failures rather than fabricated verified data. Passing mock conformance does not prove live reads, exports, tracker/DHT behavior, storage isolation, file handoff, consent, or retained-job recovery in a host. Test those separately with a TORRENT-capable runtime.
Soulseek conformance scope
NAP-SOULSEEK validation checks the fourteen request schemas (exact API-row parameters, nonempty text, canonical decimal offsets, positive page and read bounds, handle kinds) and rejects result envelopes emitted by napplets, following the living NAP-SOULSEEK proposal. The reference shell is a deterministic mock: an online account with one canned peer sharing three small text files, queries that settle on the next results poll, transfers that complete on the next status or transfers poll, bounded base64 reads, canSave: false, endpoint-scoped handles, and request-id replay. It returns typed failures rather than fabricated success. Passing mock conformance does not prove live Soulseek interoperability, consent prompts, storage isolation, or export; test those in a SOULSEEK-capable host.
