@desenlabs/core

The DESEN Protocol engine. Schemas, validators, risk classifier, token integrity, audit primitives. Pure TypeScript, zero UI.

When to use this package directly

Most developers should install desen instead — it re-exports everything here and also ships the CLI. Reach for @desenlabs/core when you are:

• Writing a custom Runtime (alternative to our React renderer).
• Building a DSL Producer that does not want to depend on the CLI.
• Embedding DESEN validation in a larger tool or pipeline.
• Shipping to a non-Node target where desen's bin entry is irrelevant.

See ADR-0001 for the full audience split.

Install

pnpm add @desenlabs/core

Quick tour

import {
  surfaceSpec,
  elementSpec,
  compositionSpec,
  classifyRisk,
  sanitizePayload,
  AuditLog,
} from "@desenlabs/core";

// 1. Validate against the protocol
const result = surfaceSpec.safeParse(incomingDocument);
if (!result.success) {
  // §3.2 fail-closed: reject, emit BINDING_ERROR downstream
}

// 2. Classify a proposed revision (§5.2.1)
const risk = classifyRisk(prevSurface, nextSurface);
// "R1" | "R2" | "R3" | null

// 3. Enforce the telemetry payload allowlist (§4.3)
const clean = sanitizePayload("INTERACT", rawPayload);

// 4. Append to a cryptographically chained audit log (§5.4)
const audit = new AuditLog();
audit.append({
  actor: "governance-bot",
  action: "approve",
  surface_id: "promo.surface",
  revision_id: "rev_a1b2c3",
  risk_level: "R1",
  description: "R1 cosmetic change auto-approved",
});

What lives here

• Schemas (Zod): elementSpec, compositionSpec, repeaterSpec, surfaceSpec, bindingSpec, bindReference, modifiersSpec, goalSpec, telemetryEnvelopeSpec, plus the Implementation Profile schema.
• Validators: every schema exposes .safeParse and .parse (standard Zod API).
• Risk classifier (classifyRisk): §5.2.1 algorithm — returns R1/R2/R3 by canonical diff.
• Sanitizer (sanitizePayload): per-event-type allowlist enforcement.
• Audit log (AuditLog): SHA-256 chained, append-only, verify() detects tampering.
• Token integrity: computeTokenChecksum, verifyTokenSource — §6.2 mitigations.

Conformance

Every rule here is backed by a fixture in packages/conformance (published on npm as @desenlabs/conformance). 176 unit tests live in this package; additional cross-package behavior is exercised in the conformance suite.

Zero UI

This package does not import React, the DOM, or any runtime target. It runs in Node, Deno, Bun, browsers, and edge runtimes.

Links

• Protocol: SPEC.md
• Implementer cookbook: IMPLEMENTATION-COOKBOOK.md
• Umbrella package: desen
• Schemas at canonical URLs: schemas.desen.run

License

Apache 2.0