HTTP adapter API
Discovery, challenge, proof, and opaque session behavior from the TypeScript adapter.
@openagentid/http implements the Core Protocol handshake for fetch-standard and Express-style applications. It is a separate package from the standalone Rust server.
| Method | Path | Success body |
|---|---|---|
| GET | /.well-known/openagent | auth_endpoint, supported_versions, server_did, required_conformance_level |
| POST | /.well-known/openagent/auth | type, nonce, timestamp, origin, optional realm |
| POST | /.well-known/openagent/auth/prove | Established identity/session data defined by IdentityVerified |
Proof input
The current source schema requires these nonempty fields:
{
"signature": "base64url-encoded-signature",
"public_key": "base64url-encoded-public-key",
"key_type": "ed25519",
"nonce": "nonce-from-the-issued-challenge"
}The strings above describe encoding and provenance; they are not working credentials. The parser also accepts secp256k1 as a key-type value. Acceptance by the schema does not certify algorithm support by your supplied verifier. The application must configure and test the algorithm it accepts.
Handler integration
handleDiscovery(config)creates the discovery document.handleChallenge(config, store)issues and stores a pending challenge.handleProve(config, store, body, verifySignature)verifies a correlated proof and establishes a session.authenticateRequest(request, store)validates the presented opaque session.createOpenAgentHandler(options)wraps these routes for fetch-standard frameworks.createOpenAgentMiddleware(options)exposes the Express-style adapter.
Session defaults are 300 seconds and challenge defaults are 60 seconds in this TypeScript adapter. They differ from the standalone server. Override deliberately; use a shared store when requests can reach multiple replicas.
Failures and replay
Unknown, consumed, and expired challenge nonces fail. Cryptographic proof verification is provided by VerifySignatureFn; never substitute an always-true callback. A malformed proof can fail schema parsing before pending-state handling. Inspect exact validation order and expiry behavior in src/server.ts when implementing a custom store.
CoreAuthError carries an HTTP status. Middleware produces JSON errors, with fallback 400 for invalid challenge requests and 401 for failed proof authentication. Do not treat error text as a stable authorization decision; use the HTTP result and typed implementation contract.
Source: openagent-sdk/adapters/http/typescript/src/{middleware,server,transport,headers,discovery}.ts.