@openagentid/http API

export declare const OPENAGENT_AUTH_SCHEME: "OpenAgent";

export declare const HEADER_OPENAGENT_DID: "x-openagent-did";

export declare const HEADER_OPENAGENT_SESSION: "x-openagent-session";

export declare const CONTENT_TYPE_JSON: "application/json";

export declare const extractOpenAgentToken: (authorization: string) => string | undefined;

export declare const buildOpenAgentHeader: (token: string) => string;

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

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

export declare const CHALLENGE_TYPE: "openagent-challenge-v1";

export declare const canonicalChallengeBytes: (challenge: IdentityChallenge) => Uint8Array;

export 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>; }, z.core.$strict>;

export declare const identityVerifiedSchema: z.ZodObject<{ did: z.ZodString; trust_tier: z.ZodEnum<{ anonymous: "anonymous"; identified: "identified"; sovereign: "sovereign"; }>; session_token: z.ZodString; session_expires: z.ZodString; capabilities: z.ZodOptional<z.ZodArray<z.ZodString>>; }, z.core.$strip>;

/** Server → Agent: a cryptographic challenge (Section 15.2). */
export interface IdentityChallenge {
    type: string;
    /** 64-character lowercase hex string (32 CSPRNG bytes). */
    nonce: string;
    /** ISO 8601 UTC, Z suffix, seconds precision. */
    timestamp: string;
    /** `scheme://host[:port]`. */
    origin: string;
    /** Optional protection-space identifier. */
    realm?: string;
}

/** Agent → Server: the cryptographic proof of identity (Section 15.3). */
export interface IdentityProof {
    /** Base64url (no padding) signature over the JCS-canonical challenge bytes. */
    signature: string;
    /** Base64url (no padding) raw public key. */
    public_key: string;
    key_type: KeyType;
    /** The nonce from the challenge, echoed. */
    nonce: string;
}

/** Server → Agent: identity confirmed; session issued (Section 15.4). */
export interface IdentityVerified {
    did: string;
    trust_tier: TrustTier;
    session_token: string;
    /** ISO 8601 UTC timestamp of session expiry. */
    session_expires: string;
    capabilities?: string[];
}

/** Signature scheme for a proof (Section 15.3). */
export type KeyType = 'ed25519' | 'secp256k1';

/** The resolution tier the server assigns (Section 15.4). */
export type TrustTier = 'anonymous' | 'identified' | 'sovereign';

/** Configuration for the HTTP transport. */
export interface HttpTransportConfig {
    /** Request timeout in milliseconds. Default: 30000. */
    timeoutMs?: number;
    /** Custom headers to include in all requests. */
    headers?: Record<string, string>;
}

/** Conformance level enum values. */
export type ConformanceLevel = 'L0' | 'L1' | 'L2';

/** Discovery document returned by the server. */
export interface DiscoveryDocument {
    auth_endpoint: string;
    supported_versions: number[];
    server_did: string;
    required_conformance_level: ConformanceLevel;
}

export declare const discoveryDocumentSchema: z.ZodObject<{ auth_endpoint: z.ZodString; supported_versions: z.ZodArray<z.ZodNumber>; server_did: z.ZodString; required_conformance_level: z.ZodEnum<{ L0: "L0"; L1: "L1"; L2: "L2"; }>; }, z.core.$strip>;

export declare const WELL_KNOWN_PATH: "/.well-known/openagent";

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

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

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

export declare const resolveAuthEndpoint: (baseUrl: string, doc: DiscoveryDocument) => string;

export declare const resolveProveEndpoint: (baseUrl: string, doc: DiscoveryDocument) => string;

export declare const DEFAULT_SESSION_TTL_SECS: 300;

export declare const DEFAULT_CHALLENGE_TTL_SECS: 60;

/** Server configuration for the HTTP endpoints. */
export interface ServerConfig {
    /** The server's origin per RFC 6454 (`scheme://host[:port]`). Bound into every challenge. */
    origin: string;
    /** Optional protection-space identifier. */
    realm?: string;
    /** The trust tier assigned to verified agents. Default: anonymous. */
    trustTier?: TrustTier;
    /** Session TTL in seconds. */
    sessionTtlSecs?: number;
    /** Challenge TTL in seconds. */
    challengeTtlSecs?: number;
    /** Conformance level advertised in discovery. */
    requiredConformance?: ConformanceLevel;
}

/** Session states. */
export type SessionState = 'awaiting_proof' | 'established' | 'closed';

/** A stored session. */
export interface StoredSession {
    id: string;
    state: SessionState;
    initiatorDid: string;
    responderDid: string;
    nonce: string;
    /** The exact challenge timestamp (spec format); needed to reconstruct the signed payload. */
    challengeTimestamp: string;
    createdAt: number;
    expiresAt: number;
    capabilities: string[];
}

/** Session store interface. */
export interface SessionStore {
    put(session: StoredSession): Promise<void>;
    get(sessionId: string): Promise<StoredSession | undefined>;
    remove(sessionId: string): Promise<void>;
}

/**
 * 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.
 */
export type VerifySignatureFn = (params: {
    publicKeyBase64Url: string;
    payload: Uint8Array;
    signatureBase64Url: string;
}) => Promise<boolean>;

/** Result of authenticating an incoming request. */
export interface AuthResult {
    authenticated: boolean;
    peerDid?: string;
    sessionToken?: string;
    error?: string;
}

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

export declare class CoreAuthError {
  statusCode: number;
  constructor(message: string, statusCode: number): CoreAuthError;
}

export declare const createServerConfig: (origin: string, overrides?: Partial<ServerConfig>) => Required<Pick<ServerConfig, "origin" | "trustTier" | "sessionTtlSecs" | "challengeTtlSecs" | "requiredConformance">> & ServerConfig;

export declare const handleDiscovery: (config: ServerConfig & { requiredConformance?: ConformanceLevel; }) => DiscoveryDocument;

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

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

export declare const authenticateRequest: (request: Request, store: SessionStore) => Promise<AuthResult>;

/** Options for creating OAAP middleware. */
export interface MiddlewareOptions {
    /** Server DID. */
    serverDid: string;
    /** Session store (default: in-memory). */
    store?: SessionStore;
    /** Required conformance level (default: L2). */
    requiredConformance?: 'L0' | 'L1' | 'L2';
    /** Session TTL in seconds (default: 300). */
    sessionTtlSecs?: number;
    /** Challenge TTL in seconds (default: 60). */
    challengeTtlSecs?: number;
    /** Signature verification function. */
    verifySignature: VerifySignatureFn;
    /** Paths to exclude from authentication (well-known paths are always excluded). */
    excludePaths?: string[];
}

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

app.use(createOpenAgentMiddleware({
  serverDid: 'did:oas:l1fe:service:api',
  verifySignature: async (did, payload, sig) => { ... },
}));

export declare const 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>;

/** Client configuration. */
export interface ClientConfig {
    /**
     * The agent's DID. Reported to the server for audit and, where the
     * deployment resolves DIDs, for trust-tier assignment. The agent proves
     * possession of the key - lineage evaluation is the server's job.
     */
    did: string;
    /** The signature scheme the `sign` function implements. */
    keyType?: KeyType;
    /** Request timeout in milliseconds. Default: 30000. */
    timeoutMs?: number;
}

/**
 * Function that signs a payload and returns a base64url (no padding)
 * encoded signature.
 *
 * The caller provides this — it may use @openagentid/crypto-wasm, Web Crypto,
 * or any Ed25519 implementation.
 */
export type SignFn = (payload: Uint8Array) => Promise<string>;

const client = new HttpAuthClient({
  config: { did: 'did:oas:l1fe:agent:my-bot' },
  sign: async (payload) => base64url(ed25519Sign(privateKey, payload)),
  publicKey: async () => base64url(ed25519PublicKey(privateKey)),
});
const session = await client.authenticate('https://api.example.com');
const resp = await session.get('/api/tools');

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

export declare class AuthenticatedSession {
  constructor(params: { baseUrl: string; sessionId: string; peerDid: string; sessionToken: string; expiresAt: number; }): AuthenticatedSession;
  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>;
}

export declare const VERSION: "0.1.1";