@openagentid/http

All packages · Runnable examples · Start an agent

Contract	Value
Package	@openagentid/http@0.1.1
Entry point	@openagentid/http
Availability	Known integration limitations
Reference source	Published TypeScript declarations
Package engines	node >=20

Entry points

Before integrating

Declares an optional peer on @openagentid/auth-protocol ^0.1.0; the registry returns 404 for that peer package.

Published adapter has not qualified for the current production path. Use current SDK identity verification and explicit receiver policy.

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.

Condition	Published file
types	`./dist/index.d.ts`
import	`./dist/index.js`
require	`./dist/index.cjs`

Exports

AUTH_ENDPOINT_PATH
AuthenticatedSession
authenticateRequest
AuthResult — type
buildOpenAgentHeader
canonicalChallengeBytes
CHALLENGE_TYPE
ClientConfig — type
ConformanceLevel — type
CONTENT_TYPE_JSON
CoreAuthError
createOpenAgentHandler
createOpenAgentMiddleware
createServerConfig
DEFAULT_CHALLENGE_TTL_SECS
DEFAULT_SESSION_TTL_SECS
DiscoveryDocument — type
discoveryDocumentSchema
extractOpenAgentToken
fetchDiscovery
handleChallenge
handleDiscovery
handleProve
HEADER_OPENAGENT_DID
HEADER_OPENAGENT_SESSION
HttpAuthClient
HttpTransport
HttpTransportConfig — type
IdentityChallenge — type
identityChallengeSchema
IdentityProof — type
IdentityVerified — type
identityVerifiedSchema
InMemorySessionStore
KeyType — type
MiddlewareOptions — type
OPENAGENT_AUTH_SCHEME
PROVE_ENDPOINT_PATH
resolveAuthEndpoint
resolveProveEndpoint
ServerConfig — type
SessionState — type
SessionStore — type
SignFn — type
StoredSession — type
TransportError
TrustTier — type
VerifySignatureFn — type
VERSION
WELL_KNOWN_PATH

AUTH_ENDPOINT_PATH

Default auth endpoint path.

Signature

declare const AUTH_ENDPOINT_PATH = "/.well-known/openagent/auth";

Source: @openagentid/http@0.1.1, dist/discovery.d.ts:40.

AuthenticatedSession

An authenticated HTTP session obtained after a successful Core Protocol identity flow.

Signature

declare class AuthenticatedSession {
    constructor(params: {
        baseUrl: string;
        sessionId: string;
        peerDid: string;
        sessionToken: string;
        expiresAt: number;
    });
    isExpired(): boolean;
    getSessionId(): string;
    getPeerDid(): string;
    getBaseUrl(): string;
    fetch(path: string, init?: RequestInit): Promise<Response>;
    get(path: string): Promise<Response>;
    post(path: string, body: unknown): Promise<Response>;
    put(path: string, body: unknown): Promise<Response>;
    delete(path: string): Promise<Response>;
}

Source: @openagentid/http@0.1.1, dist/session.d.ts:8.

authenticateRequest

Authenticate an incoming request by checking the session token.

Signature

declare function authenticateRequest(request: Request, store: SessionStore): Promise<AuthResult>;

Source: @openagentid/http@0.1.1, dist/server.d.ts:117.

AuthResult

Result of authenticating an incoming request.

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

Signature

interface AuthResult {
    authenticated: boolean;
    peerDid?: string;
    sessionToken?: string;
    error?: string;
}

Source: @openagentid/http@0.1.1, dist/server.d.ts:110.

buildOpenAgentHeader

Build an Authorization: OpenAgent <token> header value.

Signature

declare function buildOpenAgentHeader(token: string): string;

Source: @openagentid/http@0.1.1, dist/headers.d.ts:19.

canonicalChallengeBytes

The JCS-canonical (RFC 8785) UTF-8 bytes of a challenge object.

Scoped to the challenge shape: a flat object whose values are strings (or absent). JCS for that shape is lexicographic key order, no whitespace, and JSON string escaping — which is exactly what this produces. Do not reuse for nested or numeric payloads; pull in a full JCS implementation there.

Signature

declare function canonicalChallengeBytes(challenge: IdentityChallenge): Uint8Array;

Source: @openagentid/http@0.1.1, dist/transport.d.ts:96.

CHALLENGE_TYPE

The literal type value of an identity challenge (Section 15.2).

Signature

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

Source: @openagentid/http@0.1.1, dist/transport.d.ts:12.

ClientConfig

Client configuration.

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

Signature

interface ClientConfig {
    did: string;
    keyType?: KeyType;
    timeoutMs?: number;
}

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

ConformanceLevel

Conformance level enum values.

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

Signature

type ConformanceLevel = 'L0' | 'L1' | 'L2';

Source: @openagentid/http@0.1.1, dist/discovery.d.ts:12.

CONTENT_TYPE_JSON

Content-Type for all Core Protocol JSON payloads.

Signature

declare const CONTENT_TYPE_JSON = "application/json";

Source: @openagentid/http@0.1.1, dist/headers.d.ts:11.

CoreAuthError

Error returned by server handlers, carrying the HTTP status to render.

Signature

declare class CoreAuthError extends Error {
    readonly statusCode: number;
    constructor(message: string, statusCode: number);
}

Source: @openagentid/http@0.1.1, dist/server.d.ts:70.

createOpenAgentHandler

Create a generic OAAP middleware using the standard fetch Request/Response API.

Returns a function that:

Handles OAAP well-known endpoints
Validates authenticated requests
Returns undefined for well-known routes (caller should send the JSON response)

Works with Hono, Cloudflare Workers, Deno, Bun, and any fetch-based framework.

Signature

declare function createOpenAgentHandler(options: MiddlewareOptions): {
    config: ServerConfig;
    store: SessionStore;
    handle: (request: Request) => Promise<Response | AuthResult>;
};

Source: @openagentid/http@0.1.1, dist/middleware.d.ts:40.

createOpenAgentMiddleware

Create Express-compatible middleware.

Usage:

Signature

declare function createOpenAgentMiddleware(options: MiddlewareOptions): (req: {
    url?: string;
    method?: string;
    headers: Record<string, string | string[] | undefined>;
    path?: string;
}, res: {
    status: (code: number) => {
        json: (body: unknown) => void;
        end: () => void;
    };
}, next: () => void) => Promise<void>;

Source: @openagentid/http@0.1.1, dist/middleware.d.ts:62.

createServerConfig

Create a server config with sensible defaults.

Signature

declare function createServerConfig(origin: string, overrides?: Partial<ServerConfig>): Required<Pick<ServerConfig, 'origin' | 'trustTier' | 'sessionTtlSecs' | 'challengeTtlSecs' | 'requiredConformance'>> & ServerConfig;

Source: @openagentid/http@0.1.1, dist/server.d.ts:40.

DEFAULT_CHALLENGE_TTL_SECS

Default challenge TTL in seconds (Section 7: default 30s, max 300s).

Signature

declare const DEFAULT_CHALLENGE_TTL_SECS = 60;

Source: @openagentid/http@0.1.1, dist/server.d.ts:23.

DEFAULT_SESSION_TTL_SECS

Default session TTL in seconds.

Signature

declare const DEFAULT_SESSION_TTL_SECS = 300;

Source: @openagentid/http@0.1.1, dist/server.d.ts:21.

DiscoveryDocument

Discovery document returned by the server.

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

Signature

interface DiscoveryDocument {
    auth_endpoint: string;
    supported_versions: number[];
    server_did: string;
    required_conformance_level: ConformanceLevel;
}

Source: @openagentid/http@0.1.1, dist/discovery.d.ts:14.

discoveryDocumentSchema

Zod schema for DiscoveryDocument.

Signature

declare const discoveryDocumentSchema: z.ZodObject<{
    auth_endpoint: z.ZodString;
    supported_versions: z.ZodArray<z.ZodNumber, "many">;
    server_did: z.ZodString;
    required_conformance_level: z.ZodEnum<[
        "L0",
        "L1",
        "L2"
    ]>;
}, "strip", z.ZodTypeAny, {
    auth_endpoint: string;
    supported_versions: number[];
    server_did: string;
    required_conformance_level: "L0" | "L1" | "L2";
}, {
    auth_endpoint: string;
    supported_versions: number[];
    server_did: string;
    required_conformance_level: "L0" | "L1" | "L2";
}>;

Source: @openagentid/http@0.1.1, dist/discovery.d.ts:21.

extractOpenAgentToken

Extract the session token from an Authorization: OpenAgent <token> header. Returns undefined if the header is missing, malformed, or uses a different scheme.

Signature

declare function extractOpenAgentToken(authorization: string): string | undefined;

Source: @openagentid/http@0.1.1, dist/headers.d.ts:17.

fetchDiscovery

Fetch the discovery document from a server.

Signature

declare function fetchDiscovery(baseUrl: string, timeoutMs?: number): Promise<DiscoveryDocument>;

Source: @openagentid/http@0.1.1, dist/discovery.d.ts:49.

handleChallenge

Handle the challenge step - issue an IdentityChallenge.

Records a pending session keyed by the nonce: the proof carries exactly that correlation, and single-use-ness is enforced by removal.

Signature

declare function handleChallenge(config: ServerConfig & {
    requiredConformance?: ConformanceLevel;
}, store: SessionStore): Promise<IdentityChallenge>;

Source: @openagentid/http@0.1.1, dist/server.d.ts:84.

handleDiscovery

Handle GET /.well-known/openagent - returns the discovery document.

Signature

declare function handleDiscovery(config: ServerConfig & {
    requiredConformance?: ConformanceLevel;
}): DiscoveryDocument;

Source: @openagentid/http@0.1.1, dist/server.d.ts:75.

handleProve

Handle the prove step - verify an IdentityProof and issue a session.

Verification is normative-ordered: pending challenge first (present, unexpired), then shape checks (nonce echo), then the signature over the JCS-canonical challenge bytes. The nonce is consumed on success and on failure - a failed answer must not be retryable, or a verifier becomes an oracle.

Signature

declare function handleProve(config: ServerConfig & {
    requiredConformance?: ConformanceLevel;
}, store: SessionStore, body: unknown, verifySignature: VerifySignatureFn): Promise<IdentityVerified>;

Source: @openagentid/http@0.1.1, dist/server.d.ts:106.

HEADER_OPENAGENT_DID

Header carrying the authenticated agent's DID.

Signature

declare const HEADER_OPENAGENT_DID = "x-openagent-did";

Source: @openagentid/http@0.1.1, dist/headers.d.ts:7.

HEADER_OPENAGENT_SESSION

Header carrying the session token (alternative to Authorization).

Signature

declare const HEADER_OPENAGENT_SESSION = "x-openagent-session";

Source: @openagentid/http@0.1.1, dist/headers.d.ts:9.

HttpAuthClient

HTTP client that performs the Core Protocol identity flow.

Usage:

Signature

declare class HttpAuthClient {
    constructor(params: {
        config: ClientConfig;
        sign: SignFn;
        publicKey: () => Promise<string>;
        transport?: HttpTransport;
    });
    authenticate(baseUrl: string): Promise<AuthenticatedSession>;
}

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

HttpTransport

HTTP transport carrying the identity flow over REST.

Signature

declare class HttpTransport {
    constructor(config?: HttpTransportConfig);
    fetchChallenge(endpoint: string): Promise<IdentityChallenge>;
    prove(endpoint: string, proof: IdentityProof): Promise<IdentityVerified>;
}

Source: @openagentid/http@0.1.1, dist/transport.d.ts:111.

HttpTransportConfig

Configuration for the HTTP transport.

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

Signature

interface HttpTransportConfig {
    timeoutMs?: number;
    headers?: Record<string, string>;
}

Source: @openagentid/http@0.1.1, dist/transport.d.ts:104.

IdentityChallenge

Server → Agent: a cryptographic challenge (Section 15.2).

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

Signature

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

Source: @openagentid/http@0.1.1, dist/transport.d.ts:14.

identityChallengeSchema

Zod schema for challenge validation (agents MUST validate before signing).

Signature

declare const identityChallengeSchema: z.ZodObject<{
    type: z.ZodLiteral<"openagent-challenge-v1">;
    nonce: z.ZodString;
    timestamp: z.ZodString;
    origin: z.ZodString;
    realm: z.ZodOptional<z.ZodString>;
}, "strict", z.ZodTypeAny, {
    origin: string;
    type: "openagent-challenge-v1";
    nonce: string;
    timestamp: string;
    realm?: string | undefined;
}, {
    origin: string;
    type: "openagent-challenge-v1";
    nonce: string;
    timestamp: string;
    realm?: string | undefined;
}>;

Source: @openagentid/http@0.1.1, dist/transport.d.ts:49.

IdentityProof

Agent → Server: the cryptographic proof of identity (Section 15.3).

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

Signature

interface IdentityProof {
    signature: string;
    public_key: string;
    key_type: KeyType;
    nonce: string;
}

Source: @openagentid/http@0.1.1, dist/transport.d.ts:28.

IdentityVerified

Server → Agent: identity confirmed; session issued (Section 15.4).

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

Signature

interface IdentityVerified {
    did: string;
    trust_tier: TrustTier;
    session_token: string;
    session_expires: string;
    capabilities?: string[];
}

Source: @openagentid/http@0.1.1, dist/transport.d.ts:40.

identityVerifiedSchema

Zod schema for the verified session message.

Signature

declare const identityVerifiedSchema: z.ZodObject<{
    did: z.ZodString;
    trust_tier: z.ZodEnum<[
        "anonymous",
        "identified",
        "sovereign"
    ]>;
    session_token: z.ZodString;
    session_expires: z.ZodString;
    capabilities: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
}, "strip", z.ZodTypeAny, {
    did: string;
    trust_tier: "anonymous" | "identified" | "sovereign";
    session_token: string;
    session_expires: string;
    capabilities?: string[] | undefined;
}, {
    did: string;
    trust_tier: "anonymous" | "identified" | "sovereign";
    session_token: string;
    session_expires: string;
    capabilities?: string[] | undefined;
}>;

Source: @openagentid/http@0.1.1, dist/transport.d.ts:69.

InMemorySessionStore

In-memory session store for development and testing.

Signature

declare class InMemorySessionStore implements SessionStore {
    put(session: StoredSession): Promise<void>;
    get(sessionId: string): Promise<StoredSession | undefined>;
    remove(sessionId: string): Promise<void>;
}

Source: @openagentid/http@0.1.1, dist/server.d.ts:63.

KeyType

Signature scheme for a proof (Section 15.3).

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

Signature

type KeyType = 'ed25519' | 'secp256k1';

Source: @openagentid/http@0.1.1, dist/transport.d.ts:26.

MiddlewareOptions

Options for creating OAAP middleware.

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

Signature

interface MiddlewareOptions {
    serverDid: string;
    store?: SessionStore;
    requiredConformance?: 'L0' | 'L1' | 'L2';
    sessionTtlSecs?: number;
    challengeTtlSecs?: number;
    verifySignature: VerifySignatureFn;
    excludePaths?: string[];
}

Source: @openagentid/http@0.1.1, dist/middleware.d.ts:14.

OPENAGENT_AUTH_SCHEME

The canonical authorization scheme for OpenAgent-authenticated requests.

Signature

declare const OPENAGENT_AUTH_SCHEME = "OpenAgent";

Source: @openagentid/http@0.1.1, dist/headers.d.ts:5.

PROVE_ENDPOINT_PATH

Default prove endpoint path.

Signature

declare const PROVE_ENDPOINT_PATH = "/.well-known/openagent/auth/prove";

Source: @openagentid/http@0.1.1, dist/discovery.d.ts:42.

resolveAuthEndpoint

Resolve the full auth endpoint URL from a base URL and discovery document.

Signature

declare function resolveAuthEndpoint(baseUrl: string, doc: DiscoveryDocument): string;

Source: @openagentid/http@0.1.1, dist/discovery.d.ts:51.

resolveProveEndpoint

Resolve the prove endpoint URL (auth endpoint + /prove).

Signature

declare function resolveProveEndpoint(baseUrl: string, doc: DiscoveryDocument): string;

Source: @openagentid/http@0.1.1, dist/discovery.d.ts:53.

ServerConfig

Server configuration for the HTTP endpoints.

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

Signature

interface ServerConfig {
    origin: string;
    realm?: string;
    trustTier?: TrustTier;
    sessionTtlSecs?: number;
    challengeTtlSecs?: number;
    requiredConformance?: ConformanceLevel;
}

Source: @openagentid/http@0.1.1, dist/server.d.ts:25.

SessionState

Session states.

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

Signature

type SessionState = 'awaiting_proof' | 'established' | 'closed';

Source: @openagentid/http@0.1.1, dist/server.d.ts:42.

SessionStore

Session store interface.

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

Signature

interface SessionStore {
    put(session: StoredSession): Promise<void>;
    get(sessionId: string): Promise<StoredSession | undefined>;
    remove(sessionId: string): Promise<void>;
}

Source: @openagentid/http@0.1.1, dist/server.d.ts:57.

SignFn

Function that signs a payload and returns a base64url (no padding) encoded signature.

The caller provides this — it may use

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

Signature

type SignFn = (payload: Uint8Array) => Promise<string>;

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

openagentid: /crypto-wasm, Web Crypto, or any Ed25519 implementation.

StoredSession

A stored session.

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

Signature

interface StoredSession {
    id: string;
    state: SessionState;
    initiatorDid: string;
    responderDid: string;
    nonce: string;
    challengeTimestamp: string;
    createdAt: number;
    expiresAt: number;
    capabilities: string[];
}

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

TransportError

Transport error with HTTP context.

Signature

declare class TransportError extends Error {
    readonly statusCode: number | undefined;
    readonly responseBody: string | undefined;
    constructor(message: string, statusCode?: number, responseBody?: string);
}

Source: @openagentid/http@0.1.1, dist/transport.d.ts:98.

TrustTier

The resolution tier the server assigns (Section 15.4).

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

Signature

type TrustTier = 'anonymous' | 'identified' | 'sovereign';

Source: @openagentid/http@0.1.1, dist/transport.d.ts:38.

VerifySignatureFn

Signature verifier function. The caller provides this (crypto-wasm, libsodium, noble-ed25519, a KMS call) since Ed25519 verification is not in every runtime's Web Crypto.

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

Signature

type VerifySignatureFn = (params: {
    publicKeyBase64Url: string;
    payload: Uint8Array;
    signatureBase64Url: string;
}) => Promise<boolean>;

Source: @openagentid/http@0.1.1, dist/server.d.ts:92.

VERSION

SDK version — kept in sync with package.json.

Signature

declare const VERSION = "0.1.1";

Source: @openagentid/http@0.1.1, dist/index.d.ts:20.

WELL_KNOWN_PATH

Default well-known path.

Signature

declare const WELL_KNOWN_PATH = "/.well-known/openagent";

Source: @openagentid/http@0.1.1, dist/discovery.d.ts:38.

Package requirements

Dependencies

Package	Published range
zod	`^3.23.8`

Peer dependencies

Package	Published range	Optional
@openagentid/auth-protocol	`^0.1.0`	Yes

Archive verification

Pinned integrity:

SHA-512 integrity

sha512-Ecd1WkgKIlAusRSIeeyRuTXIMUka8QwTiWh8JRoxwA5i2MrT4xuza1kNXe4w+O0PTWMousqpc/Val2cNXKoNQQ==

Machine-readable API manifest · Coverage

On this page