@openagentid/client

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

• AuthenticatedResponse — type
• base64url
• bodyAsJson
• bodyAsString
• canonicalizeChallenge
• Challenge — type
• CHALLENGE_TYPE
• encodeDidKey
• FetchOptions — type
• hex
• InvalidKeyError
• InvalidUrlError
• isChallengeFresh
• KeyPair
• MalformedChallengeError
• NetworkError
• NoChallengeHeaderError
• OpenAgentClient
• OpenAgentClientError
• OpenAgentClientOptions — type
• parseWwwAuthenticate
• validateChallenge

AuthenticatedResponse

Result of an authenticated request through {@link OpenAgentClient.fetch }.

Mirrors AuthenticatedResponse in the Rust client. Includes both the raw HTTP response (status, headers, bodyBytes) and the OpenAgent principal headers (did, trustTier, sessionToken) extracted from the server's response.

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

export interface AuthenticatedResponse {
    status: number;
    headers: Headers;
    bodyBytes: Uint8Array;
    did?: string;
    trustTier?: number;
    sessionToken?: string;
    sessionExpires?: string;
    lineageAuthority?: LineageAuthorityContext;
}

Source: @openagentid/client@0.1.1, dist/types.d.ts:9.

base64url

export * as base64url from "./base64url.js";

Source: @openagentid/client@0.1.1, dist/index.d.ts:9.

bodyAsJson

Helper: parses the response body as JSON. Throws on parse failure.

export declare function bodyAsJson<T = unknown>(response: AuthenticatedResponse): T;

Source: @openagentid/client@0.1.1, dist/types.d.ts:64.

bodyAsString

Helper: parses the response body as a UTF-8 string.

export declare function bodyAsString(response: AuthenticatedResponse): string;

Source: @openagentid/client@0.1.1, dist/types.d.ts:60.

canonicalizeChallenge

JCS-canonicalizes a challenge per RFC 8785 and returns the UTF-8 bytes.

The result MUST byte-equal what the openagent-server produces from serde_jcs::to_string over the same logical object.

export declare function canonicalizeChallenge(challenge: Challenge): Uint8Array;

Source: @openagentid/client@0.1.1, dist/challenge.d.ts:43.

Challenge

A challenge issued by an OpenAgent server, decoded from the WWW-Authenticate: OpenAgent challenge="<base64url>" header.

Per OPENAGENT-CORE-SPEC.md §4:

• type MUST equal "openagent-challenge-v1"
• nonce MUST be a 64-character hex string (32 random bytes)
• timestamp MUST be RFC 3339 / ISO 8601 UTC
• origin MUST be the server origin in scheme://host[:port] form
• realm is optional

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

export interface Challenge {
    type: string;
    nonce: string;
    timestamp: string;
    origin: string;
    realm?: string;
}

Source: @openagentid/client@0.1.1, dist/challenge.d.ts:13.

CHALLENGE_TYPE

declare const CHALLENGE_TYPE = "openagent-challenge-v1";

Source: @openagentid/client@0.1.1, dist/challenge.d.ts:1.

encodeDidKey

Encodes an Ed25519 public key as a did:key URI per the W3C did:key method specification.

Multicodec prefix for Ed25519 public keys: 0xed 0x01 (varint of 0xed). Multibase prefix: z for base58btc.

export declare function encodeDidKey(publicKey: Uint8Array): string;

Source: @openagentid/client@0.1.1, dist/keypair.d.ts:64.

FetchOptions

Options for {@link OpenAgentClient.fetch }.

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

export interface FetchOptions {
    method?: string;
    body?: string | Uint8Array | Record<string, unknown>;
    headers?: Record<string, string>;
    forceChallenge?: boolean;
    signal?: AbortSignal;
}

Source: @openagentid/client@0.1.1, dist/types.d.ts:68.

hex

export * as hex from "./hex.js";

Source: @openagentid/client@0.1.1, dist/index.d.ts:10.

InvalidKeyError

The signing key is invalid (must be 32 raw bytes for Ed25519).

export declare class InvalidKeyError extends OpenAgentClientError {
    constructor(reason: string);
}

Source: @openagentid/client@0.1.1, dist/errors.d.ts:42.

InvalidUrlError

The URL passed to {@link OpenAgentClient.fetch } could not be parsed.

export declare class InvalidUrlError extends OpenAgentClientError {
    constructor(url: string);
}

Source: @openagentid/client@0.1.1, dist/errors.d.ts:14.

isChallengeFresh

Optional sanity check on the challenge timestamp.

Returns true if the timestamp parses as a date and is within maxAgeMs of now. Implementations SHOULD reject stale challenges before signing them (per spec §3.3 step 3).

export declare function isChallengeFresh(challenge: Challenge, options?: {
    now?: Date;
    maxAgeMs?: number;
}): boolean;

Source: @openagentid/client@0.1.1, dist/challenge.d.ts:51.

KeyPair

An Ed25519 signing key. Holds 32 raw secret bytes plus the lazily-derived public key.

Instances are immutable. Callers SHOULD NOT log or serialize the secret key — use {@link KeyPair.publicKeyBytes} for the safe public half.

export declare class KeyPair {
    static fromSecretBytes(secretKey: Uint8Array): KeyPair;
    static fromSecretBase64Url(secretBase64Url: string): KeyPair;
    static generate(): KeyPair;
    publicKeyBytes(): Uint8Array;
    publicKeyBase64Url(): string;
    toDidKey(): string;
    sign(message: Uint8Array): Uint8Array;
    exportSecretBytes(): Uint8Array;
    exportSecretBase64Url(): string;
}

Source: @openagentid/client@0.1.1, dist/keypair.d.ts:8.

MalformedChallengeError

The WWW-Authenticate header was present but could not be parsed as an OpenAgent challenge.

export declare class MalformedChallengeError extends OpenAgentClientError {
    constructor(reason: string);
}

Source: @openagentid/client@0.1.1, dist/errors.d.ts:29.

NetworkError

Network error during the underlying fetch call. The original error is exposed as cause for inspection.

export declare class NetworkError extends OpenAgentClientError {
    constructor(cause: unknown);
}

Source: @openagentid/client@0.1.1, dist/errors.d.ts:36.

NoChallengeHeaderError

The server returned 401 but no WWW-Authenticate header was present.

This indicates a server bug or a non-OpenAgent server returning 401.

export declare class NoChallengeHeaderError extends OpenAgentClientError {
    constructor();
}

Source: @openagentid/client@0.1.1, dist/errors.d.ts:22.

OpenAgentClient

Client for the OpenAgent Core challenge-response protocol.

The client owns an Ed25519 {@link KeyPair} and a per-origin session cache. On each {@link OpenAgentClient.fetch} call:

1. If a non-expired cached session token exists for the request origin, it is sent as Authorization: Bearer <token>. If that returns 401, the cache is cleared and the client falls through to a challenge.

2. Otherwise the client sends the request unauthenticated. If the server replies 401 with a WWW-Authenticate: OpenAgent header, the client decodes the challenge, freshness-checks the timestamp and origin, JCS-canonicalizes it (RFC 8785), signs the canonical bytes with Ed25519, and re-sends the request with the proof in the Authorization header.

3. The new session token from X-OpenAgent-Session is cached for subsequent calls.

export declare class OpenAgentClient {
    constructor(keyPair: KeyPair, options?: OpenAgentClientOptions);
    getKeyPair(): KeyPair;
    getCachedSession(origin: string): string | undefined;
    clearSession(): void;
    fetch(url: string, options?: FetchOptions): Promise<AuthenticatedResponse>;
    logout(): void;
}

Source: @openagentid/client@0.1.1, dist/client.d.ts:44.

OpenAgentClientError

Base class for all OpenAgent client errors.

All thrown errors from OpenAgentClient are instances of this class — callers may rely on instanceof OpenAgentClientError for control flow.

export declare class OpenAgentClientError extends Error {
    readonly code: string;
    constructor(code: string, message: string, options?: ErrorOptions);
}

Source: @openagentid/client@0.1.1, dist/errors.d.ts:7.

OpenAgentClientOptions

Optional configuration for the {@link OpenAgentClient}.

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

export interface OpenAgentClientOptions {
    fetch?: typeof fetch;
    now?: () => Date;
    maxChallengeAgeMs?: number;
}

Source: @openagentid/client@0.1.1, dist/client.d.ts:6.

parseWwwAuthenticate

Parses an OpenAgent challenge from a WWW-Authenticate header value.

export declare function parseWwwAuthenticate(headerValue: string): Challenge;

Source: @openagentid/client@0.1.1, dist/challenge.d.ts:31.

throws: {MalformedChallengeError} if the header is missing the OpenAgent scheme, the challenge parameter is not present, the parameter value is not valid base64url JSON, or the decoded JSON does not match the {@link Challenge} schema.

validateChallenge

Validates a parsed JSON object against the {@link Challenge} schema and returns it as a typed value.

export declare function validateChallenge(value: unknown): Challenge;

Source: @openagentid/client@0.1.1, dist/challenge.d.ts:36.

Supporting declarations

These package-owned declarations are referenced by the exports above. Their presence here does not make them importable from this entry point. Import only the names in Exports.

decode

Decodes a base64url (or base64) string to a Uint8Array.

Throws if the input contains characters outside the alphabet.

export declare function decode(input: string): Uint8Array;

Source: @openagentid/client@0.1.1, dist/base64url.d.ts:10.

decode

Decodes a hex string into bytes. Accepts both upper and lowercase.

Throws on odd length or non-hex characters.

export declare function decode(input: string): Uint8Array;

Source: @openagentid/client@0.1.1, dist/hex.d.ts:10.

decodeString

Decodes a base64url string to a UTF-8 string.

export declare function decodeString(input: string): string;

Source: @openagentid/client@0.1.1, dist/base64url.d.ts:18.

encode

Encodes a Uint8Array to a base64url string (no padding).

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

Source: @openagentid/client@0.1.1, dist/base64url.d.ts:4.

encode

Encodes bytes as a lowercase hex string.

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

Source: @openagentid/client@0.1.1, dist/hex.d.ts:4.

encodeString

Encodes a UTF-8 string to base64url.

export declare function encodeString(input: string): string;

Source: @openagentid/client@0.1.1, dist/base64url.d.ts:14.

LineageAuthorityContext

OAS/Sigil-backed privileged lineage authority attached by OpenAgentID.

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

export interface LineageAuthorityContext {
    subject: string;
    root: string;
    path_kind: string;
    source: string;
    path: string[];
    finalized_block: number;
    scopes: string[];
    generation: number;
    root_kind?: string;
    org_root_commitment?: string;
    expires_at?: string;
}

Source: @openagentid/client@0.1.1, dist/types.d.ts:44.

Package requirements

Dependencies

Archive verification

Pinned integrity:

sha512-0N/grSygK2RD59oOUOPUwJg+A6wHPC2RPk0ouuyjcDVnGkA2QR/tGQbEY6kzK/YjhORVN/3pXTtiivh9AjVI9Q==

Machine-readable API manifest · Coverage