@openagentid/oas-did

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

• deriveChildDidHkdf
• DidError
• DidErrorCode
• ED25519_PUBLIC_KEY_LENGTH
• EntityKind
• entityKindComponentCount
• entityKindFromString
• entityKindToString
• generateDidOas
• GenerateDidOasOptions — type
• generateFrostDid
• isReservedNamespace
• isRootKind
• multibaseEncodeBase58btc
• Namespace — type
• OasDid
• RESERVED_NAMESPACES
• validateIdentifier
• validateNamespace

deriveChildDidHkdf

Placeholder for HKDF-lineage child DID derivation.

The Rust SDK (oas-sdk::lineage::derive_child) performs HKDF-SHA256 derivation to produce a child Ed25519 keypair from a parent. The TypeScript port lives inside @forge-sdk/identity as deriveAgentIdentity (via a pluggable CryptoBridge) — this shim exists so callers importing from @openagentid/oas-did get an explicit, non-silent failure instead of a placeholder DID.

export declare function deriveChildDidHkdf(): never;

Source: @openagentid/oas-did@1.0.2, dist/generate.d.ts:122.

throws: Always — use @forge-sdk/identity or the Rust SDK instead.

internal:

DidError

Structured error for DID parsing and validation failures.

Every instance carries a machine-readable {@link DidErrorCode} and a human-readable message with enough context to diagnose the issue.

export declare class DidError extends Error {
    readonly code: DidErrorCode;
    constructor(code: DidErrorCode, message: string);
}

Source: @openagentid/oas-did@1.0.2, dist/error.d.ts:39.

DidErrorCode

Error codes for DID parsing and validation failures.

These string enum codes enable programmatic matching without relying on error message string content.

declare const DidErrorCode: {
    readonly Empty: "EMPTY";
    readonly InvalidPrefix: "INVALID_PREFIX";
    readonly TooFewComponents: "TOO_FEW_COMPONENTS";
    readonly InvalidNamespace: "INVALID_NAMESPACE";
    readonly UnknownEntityKind: "UNKNOWN_ENTITY_KIND";
    readonly InvalidIdentifier: "INVALID_IDENTIFIER";
};

Source: @openagentid/oas-did@1.0.2, dist/error.d.ts:7.

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

Source: @openagentid/oas-did@1.0.2, dist/error.d.ts:21.

ED25519_PUBLIC_KEY_LENGTH

Ed25519 public key length, in bytes (OAS Spec §11.1, RFC 8032 §5.1.5).

declare const ED25519_PUBLIC_KEY_LENGTH = 32;

Source: @openagentid/oas-did@1.0.2, dist/generate.d.ts:14.

EntityKind

The set of recognized OAS entity kinds.

Each entity kind represents a category of autonomous entity in the OAS identity system. Root kinds ({@link EntityKind.Hmr}, {@link EntityKind.Mhr}, {@link EntityKind.Enr}) are the trust anchors from which all other entities derive their lineage.

declare const EntityKind: {
    readonly Hmr: "hmr";
    readonly Mhr: "mhr";
    readonly Enr: "enr";
    readonly Ao: "ao";
    readonly Agent: "agent";
    readonly AgentInstance: "agent:instance";
    readonly Tool: "tool";
    readonly Skill: "skill";
    readonly Workflow: "workflow";
    readonly Model: "model";
    readonly Dataset: "dataset";
    readonly Service: "service";
};

Source: @openagentid/oas-did@1.0.2, dist/kind.d.ts:18.

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

Source: @openagentid/oas-did@1.0.2, dist/kind.d.ts:44.

entityKindComponentCount

Returns the number of colon-separated components in the kind string.

Simple kinds (e.g., "agent") have 1 component. Compound kinds (e.g., "agent:instance") have 2 components.

export declare function entityKindComponentCount(kind: EntityKind): number;

Source: @openagentid/oas-did@1.0.2, dist/kind.d.ts:101.

entityKindFromString

Parses a string into an {@link EntityKind}.

Handles the compound agent:instance kind by accepting both the full string and the two-part colon-separated form.

export declare function entityKindFromString(s: string): EntityKind | undefined;

Source: @openagentid/oas-did@1.0.2, dist/kind.d.ts:65.

entityKindToString

Returns the string representation of an entity kind.

export declare function entityKindToString(kind: EntityKind): string;

Source: @openagentid/oas-did@1.0.2, dist/kind.d.ts:72.

generateDidOas

Constructs a did:oas:<namespace>:<kind>:<identifier> string.

The identifier is either taken verbatim from options.identifier, or derived from options.publicKey as multibase base58btc (prefix z).

This is a pure function — it does not touch I/O, crypto, or random state. Output is byte-identical to the Rust SDK for the same inputs.

export declare function generateDidOas(options: GenerateDidOasOptions): string;

Source: @openagentid/oas-did@1.0.2, dist/generate.d.ts:94.

throws: {DidError} If the namespace, identifier, or key length is invalid.

GenerateDidOasOptions

Arguments accepted by {@link generateDidOas}.

Either provide an explicit human-readable identifier (e.g., "alice", "my-bot"), or let the identifier be derived from the publicKey via multibase base58btc encoding (OAS Spec §11.1).

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

export interface GenerateDidOasOptions {
    namespace: Namespace;
    kind: EntityKind;
    publicKey?: Uint8Array;
    identifier?: string;
}

Source: @openagentid/oas-did@1.0.2, dist/generate.d.ts:41.

generateFrostDid

Placeholder for FROST threshold-signing DID derivation.

FROST (frost-ed25519) is not yet ported to the TypeScript SDK. Callers that require FROST-backed MHR or threshold-signed entities must use the Rust SDK (oas-crypto) and hand the resulting DID back to the TypeScript surface.

export declare function generateFrostDid(): never;

Source: @openagentid/oas-did@1.0.2, dist/generate.d.ts:107.

throws: Always — FROST is not yet supported in the TS SDK.

internal:

isReservedNamespace

Returns true if the namespace is in the reserved list.

Reserved namespaces (oas, test, example) are defined by the OAS specification and cannot be used for production entities.

export declare function isReservedNamespace(namespace: string): boolean;

Source: @openagentid/oas-did@1.0.2, dist/namespace.d.ts:47.

isRootKind

Returns true if the entity kind is a root kind (HMR, MHR, or ENR).

Root kinds are trust anchors — they do not derive from a parent entity. Their lineage chain terminates at themselves.

export declare function isRootKind(kind: EntityKind): boolean;

Source: @openagentid/oas-did@1.0.2, dist/kind.d.ts:91.

multibaseEncodeBase58btc

Encodes bytes as multibase base58btc with the z prefix.

Matches the Rust SDK's oas_crypto::encoding::multibase_encode exactly on the same input bytes. Used here to derive the identifier portion of a did:oas from a raw Ed25519 public key.

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

Source: @openagentid/oas-did@1.0.2, dist/generate.d.ts:33.

Namespace

The supported OAS namespaces.

The reserved namespace set is enforced by {@link validateNamespace }; this type narrows the common deployment-environment namespaces used by L1fe product surfaces. Application code that needs a custom namespace should continue using the string-accepting {@link OasDid.create } API directly.

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

export type Namespace = 'prod' | 'staging' | 'test' | 'l1fe' | string;

Source: @openagentid/oas-did@1.0.2, dist/generate.d.ts:10.

OasDid

A parsed and validated OAS Decentralized Identifier.

OasDid is an immutable value object representing a fully validated did:oas:<namespace>:<kind>:<identifier> string. Once constructed, all components are guaranteed to be valid per the OAS specification.

Construction is via the static {@link OasDid.parse} method or the {@link OasDid.create} factory. Both perform full validation.

export declare class OasDid {
    readonly namespace: string;
    readonly kind: EntityKind;
    readonly identifier: string;
    static create(namespace: string, kind: EntityKind, identifier: string): OasDid;
    static parse(input: string): OasDid;
    get isRoot(): boolean;
    get kindComponentCount(): number;
    toString(): string;
    toJSON(): string;
    equals(other: OasDid): boolean;
}

Source: @openagentid/oas-did@1.0.2, dist/did.d.ts:28.

RESERVED_NAMESPACES

Reserved namespaces that cannot be used for production entities.

These namespaces are reserved by the OAS specification for testing, examples, and internal specification use.

declare const RESERVED_NAMESPACES: ReadonlyArray<string>;

Source: @openagentid/oas-did@1.0.2, dist/namespace.d.ts:7.

validateIdentifier

Validates an identifier string against OAS Spec rules.

A valid identifier:

• Is 1-128 characters long
• Contains only [a-zA-Z0-9._-] characters

export declare function validateIdentifier(identifier: string): void;

Source: @openagentid/oas-did@1.0.2, dist/validation.d.ts:21.

throws: {

link: DidError} with code {@link DidErrorCode.InvalidIdentifier } if validation fails.

validateNamespace

Validates a namespace string against OAS Spec rules.

A valid namespace:

• Is 1-63 characters long
• Contains only lowercase alphanumeric characters and hyphens
• Does not start or end with a hyphen

export declare function validateNamespace(namespace: string): void;

Source: @openagentid/oas-did@1.0.2, dist/namespace.d.ts:29.

throws: {

link: DidError} with code {@link DidErrorCode.InvalidNamespace } if validation fails.

Package requirements

This version declares no dependencies or peer dependencies.

Archive verification

Pinned integrity:

sha512-r2zBGPUb1/svcPNeCp54FABRz4J03XruDmzfeTwxQqHks9c2B7B5LJaLkn1E2P/1ub6uWVaIg6MnJkkTw8FRSA==

Machine-readable API manifest · Coverage