@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

Requires Node.js >= 20.0.0.

Quick Start

API

Parsing

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. 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.

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., or a non-string metadata value.

parseDossierFile(filePath: string): ParsedDossier

Read and parse a dossier file from disk.

validateFrontmatter(frontmatter: DossierFrontmatter): string[]

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

Checksum Verification

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.

Signature Verification

verifySignature(content: string, signature: SignatureResult): Promise

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

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

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

loadTrustedKeys(filePath?: string): Map

Load trusted public keys from a file (default: ~/.dossier/trusted-keys.txt), format one per line. Returns a map of public key to identifier, indexed under both the written and the normalized form. Unreadable lines are reported to stderr, not dropped silently.

findTrustedIdentifier(trustedKeys, signature): string | undefined

Resolve the identifier a signature is trusted under. Use this rather than probing the map by hand — it consults key_id only when there is no public_key, which is what stops a dossier from claiming a trusted signer's identity while verifying under a different key.

normalizePublicKey(key) / isSupportedPublicKey(key)

Reduce an Ed25519 key to its canonical raw 32-byte base64 form, and test whether a key is one this project can verify against. Validate with isSupportedPublicKey before storing a key: normalizePublicKey deliberately passes uninterpretable input through.

See core API reference for the full trust-file helper set.

Linting

lintDossier(content: string, config?: LintConfig): LintResult

Lint dossier content against built-in rules (checksum validity, schema validation, required sections, semver version, etc.).

lintDossierFile(filePath: string, config?: LintConfig): LintResult

Lint a dossier file from disk.

Formatting

formatDossierContent(content: string, options?: Partial): FormatResult

Format dossier content (sort keys, update checksum). Returns { formatted, changed }.

formatDossierFile(filePath: string, options?: Partial): FormatResult

Format a dossier file in place. Only writes if changes were made.

Signer/Verifier Interfaces

The package exports extensible interfaces for signing and verification:

Built-in implementations: • Ed25519Signer / Ed25519Verifier — Ed25519 key pair signing • KmsSigner / KmsVerifier — AWS KMS ECDSA-SHA-256 signing

Registry for algorithm dispatch:

Agent Usage & Run Log

Shared with packages/sched so both the ai-dossier run headless path and the scheduler's detached dispatch path agree on which block of an agent's result is the source of record.…