@openagentid/client

TypeScript client for the OpenAgent Core challenge-response authentication protocol — one Ed25519 key, transparent 401 → sign → retry handling, and per-origin session caching. Runs in the browser, Node 18+, Bun, and Deno (anything with the WHATWG fetch API).

It mirrors the Rust openagent-client crate and speaks the wire protocol described in OPENAGENT-CORE-SPEC.md.

Install

npm install @openagentid/client

Usage

import {
  KeyPair,
  OpenAgentClient,
  bodyAsJson,
} from "@openagentid/client";

// 1. Identity — generate a fresh Ed25519 key pair, or load a persisted
//    32-byte secret with KeyPair.fromSecretBytes / fromSecretBase64Url.
const keyPair = KeyPair.generate();
console.log(keyPair.toDidKey()); // did:key:z6Mk...

// 2. Create the client. It owns the key pair and a per-origin session cache.
const client = new OpenAgentClient(keyPair);

// 3. Fetch. On a 401 with `WWW-Authenticate: OpenAgent`, the client
//    freshness-checks and JCS-canonicalizes (RFC 8785) the challenge,
//    signs it with Ed25519, retries with the proof, and caches the
//    session token from `X-OpenAgent-Session` for subsequent calls.
const res = await client.fetch("https://api.example.com/v1/profile", {
  method: "GET",
});

if (res.status === 200) {
  const profile = bodyAsJson(res);
  console.log(profile, res.did, res.trustTier);
}

// Drop the cached session; the next fetch starts a fresh challenge round.
client.logout();

Lower-level helpers are also exported for custom flows: parseWwwAuthenticate, validateChallenge, canonicalizeChallenge, isChallengeFresh, and encodeDidKey, plus typed errors (OpenAgentClientError, NoChallengeHeaderError, MalformedChallengeError, NetworkError, InvalidUrlError, InvalidKeyError).

Links

• Protocol and platform: openagent.id
• Source: github.com/l1feai/openagents (openagent.id/clients/typescript)

License

Copyright © 2026 L1fe Labs, Inc.

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