@openagentid/oas-crypto

All packages · Runnable examples · Start an agent

This reference is generated from the integrity-verified npm archive for this exact version. Signatures describe the public contract; they are not standalone programs. Complete examples are checked separately.

Import conditions

Use the public entry point above. The package resolves it to these shipped files; do not import its internal files directly.

Exports

• AgentLineageProof
• AgentLineageProofData — type
• base64urlDecode
• base64urlEncode
• blake3Hash
• blake3HashHex
• CryptoError
• CryptoErrorCode
• deriveChildKeypair
• deriveKeyMaterial
• jcsCanonicalize
• jcsCanonicalizeToString
• multibaseDecode
• multibaseEncode
• OasKeyPair
• PROOF_ALGORITHM
• PROOF_TYPE

AgentLineageProof

AgentLineageProof provides generation and verification of OAS lineage proofs.

See OAS Specification §9.4 (generation) and §9.5 (verification).

declare const AgentLineageProof: {
    readonly generate: (parentKeypair: OasKeyPair, parentDid: string, childDid: string, derivationPath: string) => Promise<AgentLineageProofData>;
    readonly verify: (proof: AgentLineageProofData) => Promise<boolean>;
    readonly verifyWithKey: (proof: AgentLineageProofData, publicKeyMultibase: string) => Promise<boolean>;
    readonly toJSON: (proof: AgentLineageProofData) => Record<string, string>;
    readonly fromJSON: (obj: Record<string, unknown>) => AgentLineageProofData;
};

Source: @openagentid/oas-crypto@1.0.2, dist/proof.d.ts:61.

AgentLineageProofData

A verifiable proof linking a child entity to its parent in the OAS lineage chain.

AgentLineageProof2025 establishes cryptographic accountability by proving that a parent entity authorized the creation of a child entity at a specific derivation path.

The proof contains:

• The parent and child DIDs
• The derivation path used for HKDF key derivation
• The parent's public key (multibase-encoded)
• An Ed25519 signature over the canonical proof payload

See OAS Specification §9.4, §9.5 for the complete proof format.

Type-only declaration; it is not a runtime value.

export interface AgentLineageProofData {
    readonly proofType: typeof PROOF_TYPE;
    readonly parentDid: string;
    readonly childDid: string;
    readonly derivationPath: string;
    readonly algorithm: typeof PROOF_ALGORITHM;
    readonly publicKeyMultibase: string;
    readonly signature: string;
}

Source: @openagentid/oas-crypto@1.0.2, dist/proof.d.ts:40.

base64urlDecode

Decodes a base64url string (RFC 4648 §5, no padding) to bytes.

export declare function base64urlDecode(encoded: string): Uint8Array;

Source: @openagentid/oas-crypto@1.0.2, dist/encoding.d.ts:68.

throws: {

link: CryptoError} with code {@link CryptoErrorCode.Base64DecodeFailed } on failure.

base64urlEncode

Encodes bytes as base64url (RFC 4648 §5, no padding).

export declare function base64urlEncode(bytes: Uint8Array): string;

Source: @openagentid/oas-crypto@1.0.2, dist/encoding.d.ts:51.

blake3Hash

Computes a BLAKE3 hash of the input bytes.

BLAKE3 is the OAS-mandated content hashing algorithm, providing fast, cryptographically secure hashes.

export declare function blake3Hash(data: Uint8Array): Uint8Array;

Source: @openagentid/oas-crypto@1.0.2, dist/hashing.d.ts:18.

blake3HashHex

Computes a BLAKE3 hash and returns it as a lowercase hex string.

export declare function blake3HashHex(data: Uint8Array): string;

Source: @openagentid/oas-crypto@1.0.2, dist/hashing.d.ts:33.

CryptoError

Structured error for OAS cryptographic operations.

Every instance carries a machine-readable {@link CryptoErrorCode} and a human-readable message with enough context to diagnose the issue without exposing sensitive key material.

export declare class CryptoError extends Error {
    readonly code: CryptoErrorCode;
    readonly details: Readonly<Record<string, unknown>>;
    constructor(code: CryptoErrorCode, message: string, details?: Record<string, unknown>);
}

Source: @openagentid/oas-crypto@1.0.2, dist/error.d.ts:43.

CryptoErrorCode

Error codes for OAS cryptographic operations.

Machine-readable codes for programmatic error matching.

declare const CryptoErrorCode: {
    readonly InvalidSignature: "INVALID_SIGNATURE";
    readonly InvalidKeyLength: "INVALID_KEY_LENGTH";
    readonly DerivationFailed: "DERIVATION_FAILED";
    readonly MultibaseDecodeFailed: "MULTIBASE_DECODE_FAILED";
    readonly Base64DecodeFailed: "BASE64_DECODE_FAILED";
    readonly CanonicalizationFailed: "CANONICALIZATION_FAILED";
    readonly InvalidProofPayload: "INVALID_PROOF_PAYLOAD";
    readonly KeyConstructionFailed: "KEY_CONSTRUCTION_FAILED";
};

Source: @openagentid/oas-crypto@1.0.2, dist/error.d.ts:6.

export type CryptoErrorCode = (typeof CryptoErrorCode)[keyof typeof CryptoErrorCode];

Source: @openagentid/oas-crypto@1.0.2, dist/error.d.ts:24.

deriveChildKeypair

Derives a child Ed25519 keypair from a parent keypair using HKDF-SHA256.

The derivation uses:

• IKM (Input Keying Material): parent's signing (private) key bytes
• Salt: parent's verifying (public) key bytes
• Info: the derivation path string (UTF-8 encoded)

The output is 32 bytes of derived key material, used as the child's Ed25519 signing key. The child's verifying key is derived from the signing key.

export declare function deriveChildKeypair(parent: OasKeyPair, derivationPath: string): Promise<OasKeyPair>;

Source: @openagentid/oas-crypto@1.0.2, dist/derivation.d.ts:27.

throws: {

link: CryptoError} with code {@link CryptoErrorCode.DerivationFailed } on failure.

deriveKeyMaterial

Low-level HKDF-SHA256 key material derivation.

Derives 32 bytes of key material using HKDF-SHA256 (RFC 5869).

export declare function deriveKeyMaterial(ikm: Uint8Array, salt: Uint8Array, info: Uint8Array): Uint8Array;

Source: @openagentid/oas-crypto@1.0.2, dist/derivation.d.ts:39.

throws: {

link: CryptoError} on derivation failure.

jcsCanonicalize

Canonicalizes a JSON value to UTF-8 bytes according to RFC 8785.

export declare function jcsCanonicalize(value: unknown): Uint8Array;

Source: @openagentid/oas-crypto@1.0.2, dist/jcs.d.ts:41.

throws: {

link: CryptoError} with code {@link CryptoErrorCode.CanonicalizationFailed } on failure.

jcsCanonicalizeToString

Canonicalizes a JSON value according to RFC 8785 (JSON Canonicalization Scheme).

JCS produces a deterministic, byte-for-byte identical serialization of any JSON value by applying these rules:

• Object keys sorted lexicographically (by UTF-16 code units)
• No whitespace between tokens
• Numbers serialized per ES2015 Number.toString()
• Strings escaped according to JSON spec (minimal escaping)
• null, true, false as literals

export declare function jcsCanonicalizeToString(value: unknown): string;

Source: @openagentid/oas-crypto@1.0.2, dist/jcs.d.ts:25.

throws: {

link: CryptoError} with code {@link CryptoErrorCode.CanonicalizationFailed } if the value cannot be serialized (e.g., contains undefined, functions, or circular references).

multibaseDecode

Decodes a multibase base58btc string (strips z prefix).

export declare function multibaseDecode(encoded: string): Uint8Array;

Source: @openagentid/oas-crypto@1.0.2, dist/encoding.d.ts:36.

throws: {

link: CryptoError} with code {@link CryptoErrorCode.MultibaseDecodeFailed } on failure.

multibaseEncode

Encodes bytes as multibase base58btc (with z prefix).

This is the canonical format for publicKeyMultibase in OAS Identity Documents. The z prefix indicates base58btc encoding per the Multibase specification.

export declare function multibaseEncode(bytes: Uint8Array): string;

Source: @openagentid/oas-crypto@1.0.2, dist/encoding.d.ts:18.

OasKeyPair

An Ed25519 keypair for an OAS entity.

Holds both the signing (private) and verifying (public) keys. The signing key is stored as a Uint8Array and should be zeroed when no longer needed.

Security

• Private key bytes are never exposed via toString() or toJSON()
• All signature operations use constant-time comparison internally via @noble/ed25519
• Callers should zero the signing key bytes when the keypair is no longer needed: keypair.signingKeyBytes.fill(0)

export declare class OasKeyPair {
    static generate(): Promise<OasKeyPair>;
    static fromSigningKeyBytes(bytes: Uint8Array): Promise<OasKeyPair>;
    static verifyingKeyFromBytes(bytes: Uint8Array): Uint8Array;
    sign(message: Uint8Array): Promise<Uint8Array>;
    static verifyWithKey(publicKeyBytes: Uint8Array, message: Uint8Array, signatureBytes: Uint8Array): Promise<boolean>;
    get signingKeyBytes(): Uint8Array;
    get verifyingKeyBytes(): Uint8Array;
    publicKeyMultibase(): string;
    toString(): string;
    toJSON(): {
        verifyingKey: string;
    };
}

Source: @openagentid/oas-crypto@1.0.2, dist/keypair.d.ts:25.

PROOF_ALGORITHM

The algorithm used for key derivation in lineage proofs.

declare const PROOF_ALGORITHM: "HKDF-SHA256-Ed25519";

Source: @openagentid/oas-crypto@1.0.2, dist/proof.d.ts:9.

PROOF_TYPE

The proof type identifier for OAS lineage proofs.

declare const PROOF_TYPE: "AgentLineageProof2025";

Source: @openagentid/oas-crypto@1.0.2, dist/proof.d.ts:5.

Package requirements

Dependencies

Archive verification

Pinned integrity:

sha512-wonLqeCyTwARFvroLOe8NoFfLOzmxXLABbTM4fxAZrVbb3cVkCunOx4N+IbhZjFYh6N1YPUbPa0QE8IJUkX5SA==

Machine-readable API manifest · Coverage