@edssa/sdk — TypeScript SDK for EdSSA

EdSSA — Ephemeral · Decentralised · Stateless · Structural Authentication. Auth fabric without a vault.

Status: v0.2.3 — heartbeat minting LIVE; Trigger + PayloadFrame variants deferred to v0.3.x. Cross-language byte-for-byte parity asserted against a Rust-generated fixture in test/fixtures/heartbeat-v1.json. Live-wire heartbeat demo in examples/. The variant surfaces (F-26 Trigger / F-27 PayloadFrame / F-28 Pedersen commitment) return after the §5.19 patent- continuation files (hard deadline 2027-04-15) per the design doc.

npm publish is operator-gated — see roadmap/specs/npm-publish-runbook.md.

What ships in v0.2.2

Algorithm (full Phase-2 heartbeat path)

• deriveCells(seed, N) — Phase-2 ratchet cell derivation via Web Crypto SHA-256. Mirrors RatchetState::derive byte- for-byte
• advanceRatchet(cells, cursor, steps) — F-09 cell advance loop; mirrors RatchetState::step per tick
• composeState(cells, N, chaffC, thresholdT) — assembles the verifier-facing ActiveEdssaState (expectedBytes + chaffMask + thresholdRequired); mirrors RatchetState::compose
• derivePhase2State(seed, opts) — convenience that does derive → advance → compose in one call. Mirrors edssa_client::derive_phase2_state
• mintHeartbeat(state, options) — constructs an N-byte authenticated credential with chaff fill + non-chaff overlay
  • sub-ID tail. Mirrors construct_token + the Client::mint_heartbeat overlay
• verifyToken(token, state) — server-side verification. Mirrors edssa_core::engine::verify_token. Mostly for cross-language test parity; production verification stays in the Rust proxy
• Client — high-level wrapper with one-time fleet config
  • cached state + invalidateState() for ratchet-advance handling

Pure-function helpers

• encodeSubId / decodeSubId + SUB_ID_SLOTS / SUB_ID_MAX
• wireByte / wireBytes / buildHeader — ASCII-safe HTTP-header filter
• packVersion / unpackVersion + WireVersion / VersionDecodeError — Pre-flight 1.2 wire-format-era selector

What's deferred to v0.3.x

The Phase-7 variant surfaces — mintTrigger, mintPayloadFrame, the FragmentHeader shape, Pedersen commitment chain (F-28) — are intentionally NOT in v0.2.2's public package. The §5.19 continuation patent filing has a hard deadline of 2027-04-15; shipping the algorithmic specifics of these variants on a public npm registry before the continuation locks claims would create §54 / §102 novelty bars in the EPO and PCT jurisdictions (US has a 1-year grace period; international filings don't).

The Rust reference impl in code/edssa-client/src/lib.rs carries the variant logic for internal testing + cross-language fixture generation. v0.3.x of this package re-introduces the variant surfaces after the continuation files. Operators who need Trigger / PayloadFrame today configure the Rust SDK directly until then.

Installation

npm install @edssa/sdk
# or
pnpm add @edssa/sdk
# or
yarn add @edssa/sdk

Requires Node ≥18 (Web Crypto API), or any Deno / Bun / browser / Cloudflare Workers runtime with Web Crypto.

The package is scoped under @edssa so future packages (@edssa/cli, @edssa/llm-agent, etc.) share one brand namespace.

Usage

import { Client } from '@edssa/sdk';
import { readFileSync } from 'node:fs';

// One-time fleet configuration. `seed` is the operator-provided
// fleet seed file (32+ bytes, treat as sensitive).
const seed = new Uint8Array(readFileSync('/etc/edssa/fleet.seed'));
const client = new Client({
  fleetId: 'acme-prod',
  seed,
  widthN: 64,        // matches the proxy's `<fleet>.toml` width_N
  chaffC: 16,        // matches the proxy's chaff count
  thresholdT: 33,    // matches the proxy's threshold T
});

// Per-request: mint a heartbeat credential
const token = await client.mintHeartbeat({ subId: 42 });
const headerValue = client.buildHeader(token);

// POST to the EdSSA proxy
const resp = await fetch('https://demo.edssa.io/echo', {
  method: 'POST',
  headers: { 'X-EdSSA-Token': headerValue, 'Content-Type': 'text/plain' },
  body: 'hello',
});
console.log(resp.status, await resp.text());

See examples/heartbeat-demo.ts for a runnable Node / Deno / Bun script.

Why pure JS + Web Crypto API (not WASM)

• Bundle size — ~10 KB pure-TS vs ~100 KB+ WASM
• Runtime portability — Web Crypto is universal across modern Node, Deno, Bun, browsers, Cloudflare Workers, React Native
• Maintenance — small algorithm port; cross-language fixtures keep drift in check
• Auditability — TS source is readable + reviewable by every downstream consumer

Trade-off: the SDK is ESM-only + async-only (Web Crypto is Promise-based). Modern Node ≥18 / Deno / Bun all support ESM natively.

License

Dual-licensed under MIT OR Apache-2.0, matching the Rust workspace. See LICENSE-MIT + LICENSE-APACHE.

Cross-references

• roadmap/specs/edssa-js-sdk.md — design doc + per-batch breakdown + v0.3.x re-introduction plan
• roadmap/specs/wire-format.md — on-wire credential layout (v0)
• roadmap/specs/npm-publish-runbook.md — operator publish flow
• CHANGELOG.md — version-by-version history