@openagentid/client API

export declare class OpenAgentClient {
  constructor(keyPair: KeyPair, options?: OpenAgentClientOptions): OpenAgentClient;
  getKeyPair(): KeyPair;
  getCachedSession(origin: string): string | undefined;
  clearSession(): void;
  fetch(url: string, options?: FetchOptions): Promise<AuthenticatedResponse>;
  logout(): void;
}

/**
 * Optional configuration for the {@link OpenAgentClient}.
 */
export interface OpenAgentClientOptions {
    /**
     * Custom `fetch` implementation. Defaults to `globalThis.fetch`.
     * Useful for tests, polyfills, or wiring through a proxy.
     */
    fetch?: typeof fetch;
    /**
     * Optional clock used for session expiry checks. Defaults to
     * `() => new Date()`. Allows tests to inject a fake clock.
     */
    now?: () => Date;
    /**
     * Maximum acceptable age of a server-issued challenge before we refuse
     * to sign it. Defaults to 60 seconds (matches the server's default
     * 30-second nonce TTL with margin).
     */
    maxChallengeAgeMs?: number;
}

export declare class KeyPair {
  fromSecretBytes(secretKey: Uint8Array): KeyPair;
  fromSecretBase64Url(secretBase64Url: string): KeyPair;
  generate(): KeyPair;
  publicKeyBytes(): Uint8Array;
  publicKeyBase64Url(): string;
  toDidKey(): string;
  sign(message: Uint8Array): Uint8Array;
  exportSecretBytes(): Uint8Array;
  exportSecretBase64Url(): string;
}

export declare const encodeDidKey: (publicKey: Uint8Array) => string;

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

export declare const parseWwwAuthenticate: (headerValue: string) => Challenge;

export declare const validateChallenge: (value: unknown) => Challenge;

export declare const canonicalizeChallenge: (challenge: Challenge) => Uint8Array;

export declare const isChallengeFresh: (challenge: Challenge, options?: { now?: Date; maxAgeMs?: number; }) => boolean;

/**
 * A challenge issued by an OpenAgent server, decoded from the
 * `WWW-Authenticate: OpenAgent challenge="<base64url>"` header.
 *
 * Per OPENAGENT-CORE-SPEC.md §4:
 * - `type` MUST equal `"openagent-challenge-v1"`
 * - `nonce` MUST be a 64-character hex string (32 random bytes)
 * - `timestamp` MUST be RFC 3339 / ISO 8601 UTC
 * - `origin` MUST be the server origin in `scheme://host[:port]` form
 * - `realm` is optional
 */
export interface Challenge {
    type: string;
    nonce: string;
    timestamp: string;
    origin: string;
    realm?: string;
}

export declare class OpenAgentClientError {
  code: string;
  constructor(code: string, message: string, options?: ErrorOptions): OpenAgentClientError;
}

export declare class InvalidUrlError {
  constructor(url: string): InvalidUrlError;
}

export declare class NoChallengeHeaderError {
  constructor(): NoChallengeHeaderError;
}

export declare class MalformedChallengeError {
  constructor(reason: string): MalformedChallengeError;
}

export declare class NetworkError {
  constructor(cause: unknown): NetworkError;
}

export declare class InvalidKeyError {
  constructor(reason: string): InvalidKeyError;
}

export declare const bodyAsString: (response: AuthenticatedResponse) => string;

export declare const bodyAsJson: <T = unknown>(response: AuthenticatedResponse) => T;

// Public types returned by the OpenAgent client API.
/**
 * Result of an authenticated request through {@link OpenAgentClient.fetch}.
 *
 * Mirrors `AuthenticatedResponse` in the Rust client. Includes both the
 * raw HTTP response (`status`, `headers`, `bodyBytes`) and the OpenAgent
 * principal headers (`did`, `trustTier`, `sessionToken`) extracted from
 * the server's response.
 */
export interface AuthenticatedResponse {
    /** HTTP status code. */
    status: number;
    /** All response headers. */
    headers: Headers;
    /** Raw response body bytes. */
    bodyBytes: Uint8Array;
    /**
     * The agent's resolved DID, if the server returned `X-OpenAgent-DID`.
     * Always present after a successful challenge-response round.
     */
    did?: string;
    /**
     * Numeric trust tier (0-4), if the server returned
     * `X-OpenAgent-Trust-Tier` and it parses as a number.
     */
    trustTier?: number;
    /**
     * Session JWT issued by the server in the `X-OpenAgent-Session` header,
     * if present. The client caches this internally and reuses it on
     * subsequent requests until 401.
     */
    sessionToken?: string;
    /**
     * Session expiration timestamp from `X-OpenAgent-Session-Expires`, if
     * present. ISO 8601.
     */
    sessionExpires?: string;
    /**
     * Legacy lineage response metadata retained only for migration and audit.
     * It cannot satisfy an authorization predicate.
     */
    legacyLineageEvidence?: InformationalLineageEvidence;
}

/**
 * Options for {@link OpenAgentClient.fetch}.
 */
export interface FetchOptions {
    /** HTTP method. Defaults to `"GET"`, or `"POST"` if a body is given. */
    method?: string;
    /**
     * Request body. Strings are sent as `text/plain`, objects are
     * JSON-encoded with `application/json`, Uint8Array goes through as-is.
     */
    body?: string | Uint8Array | Record<string, unknown>;
    /** Extra headers to include on the request. */
    headers?: Record<string, string>;
    /**
     * If true, do NOT consume the cached session token even if one exists
     * for this origin. Forces a fresh challenge-response round.
     *
     * Use sparingly — only for debugging or after a logout.
     */
    forceChallenge?: boolean;
    /**
     * Optional `AbortSignal` for cancellation, propagated to the underlying
     * fetch calls.
     */
    signal?: AbortSignal;
}

/** Explicitly informational wrapper for a legacy response header. */
export interface InformationalLineageEvidence {
    readonly status: "informational";
    readonly profile: "agent-lineage-proof-2025";
    readonly evidence: LegacyLineageEvidence;
}

/** Legacy wire fields. None of these fields confer authority. */
export interface LegacyLineageEvidence {
    subject: string;
    root: string;
    path_kind: string;
    source: string;
    path: string[];
    finalized_block: number;
    scopes: string[];
    generation: number;
    root_kind?: string;
    org_root_commitment?: string;
    expires_at?: string;
}

export declare const base64url: typeof import("openagents/openagent.id/clients/typescript/src/base64url");

export declare const hex: typeof import("openagents/openagent.id/clients/typescript/src/hex");