@surrealdb/seal-core

Browser-safe verifier and domain library for Surreal Seal — SurrealDB's software-signing and trust infrastructure.

Surreal Seal publishes a tamper-evident, append-only cryptographic chain of release and licence attestations. This library is the client-side verifier: it reconstructs trust state from raw chain entries and verifies everything locally, so you never have to trust a server's answer — you check the chain yourself. It powers the public trust portal at seal.surrealdb.com and is safe to run in the browser.

Install

npm install @surrealdb/seal-core
# or: bun add @surrealdb/seal-core

Browser-safe by design

The package depends only on Web-standard crypto (crypto.subtle) and portable primitives. It never imports Node-only, AWS, or KMS APIs, so it runs unchanged in browsers, workers, Bun, Deno, and Node. It ships as ESM only.

Usage

Fetch the chain and rebuild verified trust state with TrustEngine:

import { ChainApiClient, TrustEngine } from "@surrealdb/seal-core";

// 1. Pull the public chain from a Seal API.
const client = new ChainApiClient("https://api.seal.surrealdb.com", fetch.bind(globalThis));
const { entries } = await client.fetchFullChain();

// 2. Replay it through the engine. `pushEntries` throws on a structurally
//    broken chain (bad hash link, non-contiguous index); content-level
//    problems are recorded as issues instead.
const engine = new TrustEngine();
await engine.pushEntries(entries);

// 3. Inspect the resulting trust state.
if (engine.openIssues().size > 0) {
  console.warn("chain has unacknowledged issues");
}

for (const subject of engine.subjects()) {
  const verdict = engine.verdict(subject);
  console.log(subject.id.toString(), verdict.tag); // e.g. "valid" | "revoked"
}

For entity-level checks (a specific licence, release, or module) the library also provides stepped verification flows that expose each cryptographic step as an inspectable result:

import { SteppedLicenseVerification } from "@surrealdb/seal-core";

API surface

Everything is exported from the package root as named exports. Notable groups:

• Trust engine — TrustEngine, trust queries, entry-signature verification.
• Stepped verification — SteppedLicenseVerification, SteppedReleaseVerification, SteppedModuleVerification, and the entry-proof stepper, each surfacing per-step results for UIs.
• Chain — ChainApiClient, chain-entry envelopes, hashing, dispatch.
• Identifiers & catalog — LicenseId, CustomerId, product/OID catalog.
• Schemas — Effect-Schema definitions for the Seal HTTP API responses.
• Utilities — Crockford base32, ULID, JCS canonicalisation, PEM, digests, ECDSA helpers.

Versioning

This package is at 0.1.0 and the API may change before 1.0.0. The authoritative cross-language implementation of the verification rules is the Rust crate surreal-seal-core (embedded in SurrealDB Enterprise); this library tracks the same conformance vectors.

License

Licensed under the Apache License, Version 2.0.