@ai-dossier/core weekly downloads statistics

@ai-dossier/core

Use one portable AI-agent skill across Claude Code, Codex, OpenCode, and MCP-compatible workflows.

@ai-dossier/core is the TypeScript library for developers building secure AI-agent workflows. It parses, verifies, signs, and lints dossiers: portable, versioned skills whose integrity and publisher can be checked before an LLM uses them.

Part of the ai-dossier ecosystem: use @ai-dossier/cli to author and install skills, @ai-dossier/mcp-server to expose them through MCP, and the ai-dossier project for the complete platform.

Installation

npm install @ai-dossier/core

Requires Node.js >= 20.0.0.

Quick Start

import {
  parseDossierContent,
  verifyIntegrity,
  lintDossier,
} from '@ai-dossier/core';

// 1. Parse a dossier
const dossier = parseDossierContent(rawContent);
console.log(dossier.frontmatter.title); // => "My Dossier"

// 2. Verify integrity
const integrity = verifyIntegrity(
  dossier.body,
  dossier.frontmatter.checksum?.hash
);
console.log(integrity.status); // => "valid" | "invalid" | "missing"

// 3. Lint for issues
const result = lintDossier(rawContent);
console.log(result.errorCount, result.warningCount);

API

Parsing

import {
  parseDossierContent,
  parseDossierFile,
  validateFrontmatter,
} from '@ai-dossier/core';

parseDossierContent(content: string): ParsedDossier

Parse a dossier content string into frontmatter and body. Accepts both ---dossier (JSON/YAML) and standard --- (YAML) delimiters, in either frontmatter shape: legacy (every Dossier field flat at the top level) or spec (Agent Skills fields name, description, license, compatibility, allowed-tools at the top level, every other field under metadata as dossier.<field> strings). frontmatter is always the same flat logical object; rawFrontmatter is the frontmatter as it sits on disk and shape says which layout it uses. Throws a SpecShapeError (message prefixed Invalid spec-shaped frontmatter:) when a spec-shaped frontmatter is ambiguous — see fromSpecFrontmatter.

const { frontmatter, body, raw, rawFrontmatter, shape } = parseDossierContent(content);

toSpecFrontmatter(logical) / fromSpecFrontmatter(spec)

Convert flat logical frontmatter to the spec shape and back. Values under metadata are strings: a string is stored as-is unless it would itself parse as JSON (then it is JSON-quoted), and any other value is stored as canonical JSON (encodeSpecValue / decodeSpecValue), so fromSpecFrontmatter(toSpecFrontmatter(x)) equals x. fromSpecFrontmatter throws SpecShapeError on anything ambiguous: a Dossier field at the top level, dossier.<agent-skills-field>, or a non-string metadata value.

parseDossierFile(filePath: string): ParsedDossier

Read and parse a dossier file from disk.

const parsed = parseDossierFile('./path/to/dossier.ds.md');

validateFrontmatter(frontmatter: DossierFrontmatter): string[]

Validate required fields and enum values. Returns an array of error messages (empty if valid).

const errors = validateFrontmatter(parsed.frontmatter);
if (errors.length > 0) {
  console.error('Validation errors:', errors);
}

Checksum Verification

import { calculateChecksum, verifyIntegrity } from '@ai-dossier/core';

calculateChecksum(body: string): string

Calculate the SHA-256 hash of dossier body content (excluding frontmatter).

verifyIntegrity(body: string, expectedHash: string | undefined): IntegrityResult

Compare the computed hash against the expected hash from frontmatter.

const result = verifyIntegrity(body, frontmatter.checksum?.hash);
// result.status: "valid" | "invalid" | "missing"

Signature Verification

import {
  buildVerificationPayload,
  verifySignature,
  verifyWithEd25519,
  verifyWithKms,
  loadTrustedKeys,
  findTrustedIdentifier,
  normalizePublicKey,
  isSupportedPublicKey,
} from '@ai-dossier/core';

verifySignature(content: string, signature: SignatureResult): Promise<VerifyResult>

Verify a signature using the verifier registry. Automatically selects the correct verifier based on signature.algorithm.

const parsed = parseDossierContent(content);
const result = await verifySignature(buildVerificationPayload(parsed), parsed.frontmatter.signature);
console.log(result.valid); // true | false

buildVerificationPayload(parsed: ParsedDossier): string

The bytes a parsed dossier's signature must verify against. Selects the scheme from signature.covers — absent: v1 (body only); frontmatter+body: v2 (flat frontmatter + body); spec-frontmatter+body: v3 (on-disk spec-shaped frontmatter minus metadata["dossier.signature"], + body) — and binds it to the file's shape: spec-shaped files verify only under v3, legacy files only under v1/v2. Throws on an unsigned dossier, an unknown covers, or a scheme/shape mismatch; treat a throw as a failed verification.

verifyWithEd25519(content: string, signature: string, publicKey: string): VerifyResult

Verify an Ed25519 signature directly. publicKey may be SPKI PEM, raw 32-byte base64, or base64 SPKI DER.

verifyWithKms(content: string, signature: string, keyId: string, region?: string): Promise<VerifyResult>

Verify an ECDSA-SHA-256 signature using AWS KMS.

loadTrustedKeys(filePath?: string): Map<string, string>…