@openagentid/oas-sdk

Unified OAS SDK for TypeScript -- the primary developer entry point for the Open Agent Specification ecosystem.

This package provides high-level workflows for identity creation, lineage derivation, chain verification, and the upstream lineage verifier contract used by downstream platforms. Install this one package to get the complete OAS TypeScript SDK.

Lineage Verification Contract

The OAS SDK is the upstream API for lineage decisions. Downstream packages should consume OAS verification results instead of redefining lineage locally.

• verifyChain is valid for local DID/document/proof verification and test fixtures.
• Privileged authority requires Sigil GAL-backed verification of root anchors, typed lineage edges, org lineage roots, expiry, scope, and revocation.
• Forge, Kin, Aut0, Arsenal, AEGIS, OATS, MARS, OpenAgent SDK, and OpenAgentID should route lineage checks through OAS SDK adapters.
• When Sigil state is required but unavailable, privileged access must fail closed.

Installation

npm i @openagentid/oas-sdk

Requirements: Node.js >= 20, ESM-only.

Quick Start

import { createHmr, deriveChild, verifyChain, InMemoryProvider, EntityKind } from '@openagentid/oas-sdk';

// 1. Create a Human Root identity
const hmr = await createHmr('l1fe', 'alice', new Date().toISOString());

// 2. Derive an agent from the HMR
const agent = await deriveChild(
  hmr.keypair,
  hmr.document,
  'l1fe',
  EntityKind.Agent,
  'analyzer',
  '/agent-analyzer',
  new Date().toISOString(),
);

// 3. Verify the local chain
const provider = new InMemoryProvider();
provider.register(hmr.document);
provider.register(agent.document);
const result = await verifyChain(agent.document, provider);
console.log(result.chainLength);  // 1
console.log(result.humanRootDid); // 'did:oas:l1fe:hmr:alice'

For production authorization, use a Sigil-backed OAS verifier/resolver before issuing ACTs, sessions, credentials, or org membership decisions.

Usage

Create a Human Root (HMR)

import { createHmr } from '@openagentid/oas-sdk';

const hmr = await createHmr('l1fe', 'alice', '2026-01-01T00:00:00Z');
console.log(hmr.document.id);   // 'did:oas:l1fe:hmr:alice'
console.log(hmr.document.kind); // 'hmr'
// hmr.keypair is the Ed25519 keypair for this identity

Create a Multi-Human Root (MHR)

import { createMhr } from '@openagentid/oas-sdk';

const mhr = await createMhr('l1fe', 'sentinel', '2026-01-01T00:00:00Z');
console.log(mhr.document.kind); // 'mhr'

Create a root with an existing keypair

import { createRootWithKeypair, OasKeyPair, EntityKind } from '@openagentid/oas-sdk';

const keypair = await OasKeyPair.fromSigningKeyBytes(existingKeyBytes);
const hmr = await createRootWithKeypair(
  'l1fe',
  EntityKind.Hmr,
  'alice',
  keypair,
  '2026-01-01T00:00:00Z',
);

Derive a child identity

import { createHmr, deriveChild, EntityKind } from '@openagentid/oas-sdk';

const hmr = await createHmr('l1fe', 'alice', '2026-01-01T00:00:00Z');
const agent = await deriveChild(
  hmr.keypair,
  hmr.document,
  'l1fe',
  EntityKind.Agent,
  'analyzer',
  '/agent-analyzer',
  '2026-01-01T00:00:00Z',
);

// Derive a tool from the agent (multi-level chain)
const tool = await deriveChild(
  agent.keypair,
  agent.document,
  'l1fe',
  EntityKind.Tool,
  'search',
  '/tool-search',
  '2026-01-01T00:00:00Z',
);
console.log(tool.document.id); // 'did:oas:l1fe:tool:search'

Verify a lineage chain

import { verifyChain, InMemoryProvider } from '@openagentid/oas-sdk';

const provider = new InMemoryProvider();
provider.register(hmr.document);
provider.register(agent.document);
provider.register(tool.document);

const result = await verifyChain(tool.document, provider);
console.log(result.chainLength);  // 2 (tool -> agent -> hmr)
console.log(result.humanRootDid); // 'did:oas:l1fe:hmr:alice'

Access sub-package APIs directly

The unified SDK re-exports everything from all sub-packages:

// DID parsing
import { OasDid, EntityKind, isRootKind, validateNamespace } from '@openagentid/oas-sdk';

// Cryptography
import { OasKeyPair, blake3HashHex, jcsCanonicalizeToString } from '@openagentid/oas-sdk';

// Documents
import { DocumentBuilder, ConformanceLevel, LifecycleStatus } from '@openagentid/oas-sdk';

// Resolution
import { CachingResolver, FallbackResolver } from '@openagentid/oas-sdk';

// Attestation
import { CredentialBuilder, AttestationType, signCredential } from '@openagentid/oas-sdk';

Error handling

import { OasError, OasErrorCode } from '@openagentid/oas-sdk';

try {
  await createHmr('INVALID', 'alice', new Date().toISOString());
} catch (e) {
  if (e instanceof OasError) {
    console.log(e.code);    // 'DID_ERROR'
    console.log(e.message); // human-readable description
    console.log(e.details); // { code: 'INVALID_NAMESPACE' }
  }
}

API Reference

SDK workflow functions

/**
 * Creates a new Human Root (HMR) identity.
 * Generates a random Ed25519 keypair, constructs a DID, builds and signs
 * an OAS Identity Document with L0 conformance.
 *
 * @param namespace - The namespace (e.g., "l1fe").
 * @param identifier - The identifier (e.g., "alice").
 * @param created - ISO 8601 timestamp for the document proof.
 * @returns A CreatedIdentity with the document and keypair.
 * @throws OasError on creation failure.
 */
async function createHmr(
  namespace: string,
  identifier: string,
  created: string,
): Promise<CreatedIdentity>;

/**
 * Creates a new Multi-Human Root (MHR) identity.
 * Same as createHmr but for multi-human threshold roots.
 */
async function createMhr(
  namespace: string,
  identifier: string,
  created: string,
): Promise<CreatedIdentity>;

/**
 * Creates a root identity with an externally provided keypair.
 * Use this when you have an existing Ed25519 keypair (e.g., from HSM or KMS).
 *
 * @param kind - Must be 'hmr' or 'mhr'.
 * @throws OasError if kind is not a root kind.
 */
async function createRootWithKeypair(
  namespace: string,
  kind: 'hmr' | 'mhr',
  identifier: string,
  keypair: OasKeyPair,
  created: string,
): Promise<CreatedIdentity>;

/**
 * Derives a child identity from a parent.
 * 1. Constructs the child DID
 * 2. Derives a child keypair via HKDF-SHA256
 * 3. Generates a lineage proof
 * 4. Builds and signs the child's identity document
 *
 * @param parentKeypair - The parent entity's keypair.
 * @param parentDoc - The parent entity's identity document.
 * @param childNamespace - The child's namespace.
 * @param childKind - The child's entity kind.
 * @param childIdentifier - The child's identifier.
 * @param derivationPath - The HKDF derivation path.
 * @param created - ISO 8601 timestamp for the document proof.
 * @throws OasError on derivation failure.
 */
async function deriveChild(
  parentKeypair: OasKeyPair,
  parentDoc: OasDocument,
  childNamespace: string,
  childKind: EntityKind,
  childIdentifier: string,
  derivationPath: string,
  created: string,
): Promise<DerivedIdentity>;

/**
 * Verifies the full lineage chain of an identity document.
 * Convenience wrapper around @openagentid/oas-lineage verifyLineage.
 *
 * @throws OasError on verification failure.
 */
async function verifyChain(
  document: OasDocument,
  provider: DocumentProvider,
  config?: VerifyConfig,
): Promise<VerifyResult>;

SDK types

/** Result of creating a root identity. */
interface CreatedIdentity {
  readonly document: OasDocument;
  readonly keypair: OasKeyPair;
}

/** Result of deriving a child identity. */
interface DerivedIdentity {
  readonly document: OasDocument;
  readonly keypair: OasKeyPair;
}

SDK error classes

/**
 * Unified error type for the OAS SDK.
 * Wraps errors from all sub-packages with a unified code system.
 */
class OasError extends Error {
  readonly code: OasErrorCode;
  readonly details: Readonly<Record<string, unknown>>;

  constructor(code: OasErrorCode, message: string, details?: Record<string, unknown>);

  /** Wraps a sub-package error into an OasError. */
  static from(error: unknown): OasError;
}

const OasErrorCode = {
  Did: 'DID_ERROR',
  Crypto: 'CRYPTO_ERROR',
  Document: 'DOCUMENT_ERROR',
  Lineage: 'LINEAGE_ERROR',
  Resolve: 'RESOLVE_ERROR',
  Attestation: 'ATTESTATION_ERROR',
  Sdk: 'SDK_ERROR',
} as const;
type OasErrorCode = (typeof OasErrorCode)[keyof typeof OasErrorCode];

Re-exported packages

The unified SDK re-exports all public symbols from:

| Package | Key exports | |---------|-------------| | @openagentid/oas-did | OasDid, EntityKind, isRootKind, validateNamespace, validateIdentifier, DidError | | @openagentid/oas-crypto | OasKeyPair, AgentLineageProof, deriveChildKeypair, blake3Hash, jcsCanonicalize, multibaseEncode, CryptoError | | @openagentid/oas-document | OasDocument, DocumentBuilder, ConformanceLevel, LifecycleStatus, isRootDocument, DocumentError | | @openagentid/oas-lineage | deriveChildEntity, verifyLineage, verifyLineageStructural, InMemoryProvider, LineageError | | @openagentid/oas-resolve | InMemoryResolver, CachingResolver, FallbackResolver, ResolveError | | @openagentid/oas-attestation | CredentialBuilder, AttestationType, signCredential, verifyCredential, AttestationError |

See each package's README for full API details.

Dependencies

| Package | Purpose | |---------|---------| | @openagentid/oas-did 1.0.0 | DID parsing and validation | | @openagentid/oas-crypto 1.0.0 | Cryptographic primitives | | @openagentid/oas-document 1.0.0 | Identity document schema and builder | | @openagentid/oas-lineage 1.0.0 | Lineage derivation and verification | | @openagentid/oas-resolve 1.0.0 | DID resolution interface | | @openagentid/oas-attestation 1.0.0 | Verifiable Credentials |

License

Copyright © 2026 L1fe Labs, Inc.

Licensed under either of Apache License 2.0 or MIT license, at your option.