@openagentid/http/server

All packages · Runnable examples · Start an agent

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

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/server.d.ts`
import	`./dist/server.js`
require	`./dist/server.cjs`

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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