@truealter/sdk 0.0.1 → 0.2.0

package/dist/index.d.cts

@@ -0,0 +1,1470 @@
+/**
+ * MCP endpoint discovery.
+ *
+ * Implements the three-step discovery cascade defined in
+ * `draft-morrison-mcp-dns-discovery-01`:
+ *
+ *   1. DNS TXT record at `_mcp.<domain>` with `mcp=<url>` attribute
+ *   2. HTTPS GET `https://<domain>/.well-known/mcp.json`
+ *   3. HTTPS GET `https://<domain>/.well-known/alter.json`
+ *
+ * The DNS lookup is only attempted in environments that expose `dns`
+ * (Node, Bun, Deno with the node compatibility layer). Browsers and
+ * Cloudflare Workers fall through to the `.well-known` lookups.
+ */
+interface DiscoveryResult {
+    /** Resolved MCP endpoint URL. */
+    url: string;
+    /** MCP transport — currently always `streamable-http`. */
+    transport: 'streamable-http';
+    /** Source of the discovery hit, useful for diagnostics. */
+    source: 'dns' | 'mcp.json' | 'alter.json' | 'override';
+    /** Optional Ed25519 public key from `alter.json` for provenance verification. */
+    publicKey?: string;
+    /** Optional x402 contract address. */
+    x402Contract?: string;
+    /** Capability level (E1-E4) when present. */
+    capability?: string;
+    /** Raw discovery document, kept for callers that want to inspect it. */
+    raw?: Record<string, unknown>;
+}
+interface DiscoveryOptions {
+    /** Cache hits in memory for the duration of this process. Default true. */
+    cache?: boolean;
+    /** Skip DNS lookup even when available. */
+    skipDns?: boolean;
+    /** Per-request timeout in milliseconds. Default 5_000. */
+    timeoutMs?: number;
+    /** Override fetch implementation (for testing). */
+    fetch?: typeof fetch;
+}
+/**
+ * Resolve the ALTER MCP endpoint for `domain`.
+ *
+ * Order: cache → DNS TXT → mcp.json → alter.json. Throws
+ * {@link AlterDiscoveryError} if every step fails.
+ */
+declare function discover(domain: string, opts?: DiscoveryOptions): Promise<DiscoveryResult>;
+/** Wipe the in-memory discovery cache. */
+declare function clearDiscoveryCache(): void;
+
+/**
+ * Ed25519 keypair management for ALTER Identity.
+ *
+ * Uses @noble/ed25519 — pure JavaScript, no native addons, runs in
+ * Node 18+, Deno, Bun, Cloudflare Workers and the browser.
+ *
+ * Keys are stored as hex strings for portability. The CLI persists them
+ * to `~/.config/alter/keys.json` (Node-only); other environments must
+ * supply their own storage.
+ */
+interface Ed25519Keypair {
+    /** 32-byte private key as hex. */
+    privateKey: string;
+    /** 32-byte public key as hex. */
+    publicKey: string;
+    /** `ed25519:<base64url-public-key>` form used in `.well-known/alter.json`. */
+    did: string;
+}
+interface ApiKeyConfig {
+    /** Opaque API key issued by ALTER. Begins with `ak_`. */
+    key: string;
+    /** Optional `~handle` the key is bound to. */
+    handle?: string;
+}
+/**
+ * Generate a fresh Ed25519 keypair.
+ *
+ * The private key never leaves the SDK process unless the caller chooses
+ * to persist it. Callers are responsible for safe storage.
+ */
+declare function generateKeypair(): Ed25519Keypair;
+/**
+ * Reconstruct the keypair from a stored private key (hex).
+ */
+declare function keypairFromPrivateKey(privateKeyHex: string): Ed25519Keypair;
+/**
+ * Sign an arbitrary message with an Ed25519 private key.
+ * Returns the signature as hex.
+ */
+declare function sign(privateKeyHex: string, message: Uint8Array | string): Promise<string>;
+/**
+ * Verify an Ed25519 signature.
+ */
+declare function verify(publicKeyHex: string, signatureHex: string, message: Uint8Array | string): Promise<boolean>;
+/**
+ * Encode a 32-byte public key as the `ed25519:<base64url>` form used by
+ * ALTER's `.well-known/alter.json` discovery anchor.
+ */
+declare function encodeDid(publicKey: Uint8Array | string): string;
+/**
+ * Decode a `did:key` style identifier or the ALTER `ed25519:` form back
+ * into raw bytes. Throws if the encoding is unrecognised.
+ */
+declare function decodeDid(did: string): Uint8Array;
+declare function base64urlEncode(bytes: Uint8Array): string;
+declare function base64urlDecode(input: string): Uint8Array;
+
+/**
+ * ES256 provenance verification.
+ *
+ * ALTER signs medium- and high-blast-radius MCP responses with an ES256
+ * JWS attestation in `_meta.provenance.token`. The signing key rotates
+ * periodically and is published at `<api-host>/.well-known/alter-keys.json`
+ * as a JWKS.
+ *
+ * This module verifies tokens *without* a JWT library — pure WebCrypto
+ * (subtle.verify) keeps the dep graph small and works in every modern
+ * runtime (Node 18+, Deno, Bun, Cloudflare Workers, browser).
+ */
+
+interface ProvenanceEnvelope {
+    version: string;
+    token: string;
+    purpose?: string;
+    expires_at?: string;
+    tool?: string;
+    blast_radius?: 'low' | 'medium' | 'high';
+    verify_at?: string;
+    [extra: string]: unknown;
+}
+interface ProvenancePayload {
+    iss: string;
+    iat: number;
+    exp: number;
+    purpose: string;
+    tool: string;
+    blast_radius: 'medium' | 'high';
+    data_hash: string;
+    requester: string;
+    jti: string;
+}
+interface ProvenanceVerification {
+    valid: boolean;
+    payload?: ProvenancePayload;
+    reason?: string;
+    /** Issuer's `kid` claim from the JWS header. */
+    kid?: string;
+}
+interface JsonWebKey {
+    kty: 'EC';
+    crv: 'P-256';
+    x: string;
+    y: string;
+    kid?: string;
+    alg?: string;
+    use?: string;
+}
+interface JwksDocument {
+    keys: JsonWebKey[];
+}
+/**
+ * Default hostnames that `envelope.verify_at` is trusted to resolve to.
+ *
+ * Without this allowlist, a hostile MCP server could point `verify_at`
+ * at an attacker-controlled JWKS and pass ES256 verification with its own
+ * signing key — the classic "confused-deputy via server-supplied trust
+ * anchor" pattern. Any hostname not on this list (or the caller-supplied
+ * extension) is rejected before a network fetch is issued. Downstream
+ * integrators with their own deployment can extend the list via the
+ * `verifyAtAllowlist` option on {@link verifyProvenance} or the
+ * `verifyAtAllowlist` constructor option on `AlterClient`.
+ */
+declare const DEFAULT_VERIFY_AT_ALLOWLIST: readonly string[];
+interface VerifyProvenanceOptions {
+    /**
+     * Override the JWKS URL entirely. Takes precedence over both the
+     * allowlist and any `verify_at` on the envelope — if the caller pins
+     * an explicit URL, we use it verbatim (the caller has already vouched
+     * for the origin).
+     */
+    jwksUrl?: string;
+    /**
+     * Hostnames that are trusted when resolving `envelope.verify_at`.
+     * Defaults to {@link DEFAULT_VERIFY_AT_ALLOWLIST}. Passing a list
+     * here *replaces* the default — include the ALTER canonicals if you
+     * still want them accepted.
+     */
+    verifyAtAllowlist?: readonly string[];
+    fetch?: typeof fetch;
+    now?: number;
+}
+/**
+ * Verify a provenance JWS token against ALTER's published JWKS.
+ *
+ * Pass either a {@link ProvenanceEnvelope} (the value of `_meta.provenance`)
+ * or the bare JWS string. The function fetches the JWKS lazily, caches it
+ * for five minutes, and validates the ES256 signature plus standard
+ * registered claims (`exp`, `iat`).
+ *
+ * Security: when the envelope carries a `verify_at` hint, the hostname
+ * MUST be on the allowlist (default: `api.truealter.com`,
+ * `mcp.truealter.com`; extend via `verifyAtAllowlist`). `http:` URLs are
+ * rejected unconditionally — JWKS fetch must be TLS.
+ */
+declare function verifyProvenance(envelope: ProvenanceEnvelope | string, opts?: VerifyProvenanceOptions): Promise<ProvenanceVerification>;
+/**
+ * Tool definition signature verification.
+ *
+ * ALTER signs each tool's input schema at startup and exposes the
+ * signatures via the MCP `tools/list` `_meta.signatures` map. This helper
+ * checks that each tool's schema hash matches the signed value.
+ */
+interface SignedToolDefinition {
+    name: string;
+    inputSchema: unknown;
+}
+interface ToolSignatureMap {
+    [toolName: string]: {
+        schema_hash: string;
+        signature?: string | null;
+        signed_at?: number;
+        kid?: string | null;
+    };
+}
+declare function verifyToolSignatures(tools: SignedToolDefinition[], signatures: ToolSignatureMap): Promise<{
+    tool: string;
+    valid: boolean;
+    reason?: string;
+}[]>;
+/**
+ * Fetch the ALTER public key set. Cached in-process for five minutes.
+ */
+declare function fetchPublicKeys(jwksUrl: string, fetchImpl?: typeof fetch): Promise<JwksDocument>;
+/**
+ * Resolve a `verify_at` hint from a provenance envelope into a concrete
+ * JWKS URL, enforcing scheme + hostname allowlisting.
+ *
+ * - Relative paths (`/…` or `foo/bar`) resolve against `api.truealter.com`
+ *   over https — the canonical ALTER JWKS host.
+ * - Absolute URLs must use `https:` (plaintext `http:` is rejected
+ *   unconditionally) and the hostname must be a case-insensitive exact
+ *   match against `allowlist`.
+ * - Anything else throws; callers convert the throw into a
+ *   `ProvenanceVerification` failure.
+ *
+ * Exported for tests; public consumers should prefer the higher-level
+ * {@link verifyProvenance} entry point.
+ */
+declare function resolveVerifyAt(verifyAt: string, allowlist?: readonly string[]): string;
+
+/**
+ * Typed error hierarchy for the ALTER Identity SDK.
+ *
+ * Every error thrown by the SDK is an instance of {@link AlterError}, with
+ * a discriminated `code` field for programmatic handling. Network failures,
+ * authentication problems, payment-required responses, rate limits, tool
+ * execution failures, and provenance verification mismatches each get
+ * their own subclass so consumers can `instanceof`-narrow.
+ */
+type AlterErrorCode = 'NETWORK' | 'TIMEOUT' | 'AUTH' | 'PAYMENT_REQUIRED' | 'RATE_LIMITED' | 'TOOL_ERROR' | 'PROVENANCE' | 'DISCOVERY' | 'INVALID_RESPONSE' | 'UNSUPPORTED';
+declare class AlterError extends Error {
+    readonly code: AlterErrorCode;
+    readonly cause?: unknown;
+    constructor(code: AlterErrorCode, message: string, cause?: unknown);
+}
+declare class AlterNetworkError extends AlterError {
+    constructor(message: string, cause?: unknown);
+}
+declare class AlterTimeoutError extends AlterError {
+    constructor(message: string, cause?: unknown);
+}
+declare class AlterAuthError extends AlterError {
+    readonly status: number;
+    constructor(message: string, status?: number);
+}
+/**
+ * Thrown on HTTP 402. Carries the payment envelope returned by the server
+ * so an x402 client can settle the transaction and retry.
+ */
+declare class AlterPaymentRequired extends AlterError {
+    readonly envelope: PaymentEnvelope;
+    readonly tool: string;
+    constructor(tool: string, envelope: PaymentEnvelope);
+}
+declare class AlterRateLimited extends AlterError {
+    readonly retryAfter: number;
+    constructor(message: string, retryAfter?: number);
+}
+declare class AlterToolError extends AlterError {
+    readonly tool: string;
+    readonly rpcCode?: number;
+    constructor(tool: string, message: string, rpcCode?: number);
+}
+declare class AlterProvenanceError extends AlterError {
+    constructor(message: string, cause?: unknown);
+}
+declare class AlterDiscoveryError extends AlterError {
+    constructor(message: string, cause?: unknown);
+}
+declare class AlterInvalidResponse extends AlterError {
+    constructor(message: string, cause?: unknown);
+}
+/**
+ * x402 payment envelope returned in HTTP 402 responses or in the
+ * `X-402-Payment` response header. The shape mirrors the x402 spec.
+ */
+interface PaymentEnvelope {
+    scheme: 'x402';
+    network: 'base' | 'base-sepolia' | 'solana' | string;
+    asset: 'USDC' | string;
+    amount: string;
+    recipient: string;
+    resource: string;
+    expires_at?: string;
+    nonce?: string;
+    /** Anything else the server included verbatim. */
+    [extra: string]: unknown;
+}
+
+/**
+ * x402 micropayment client.
+ *
+ * Premium MCP tools return HTTP 402 with a payment envelope. The
+ * {@link X402Client} settles the envelope on Base L2 (USDC) and replays
+ * the original request with the resulting transaction reference.
+ *
+ * The actual on-chain settlement is delegated to a pluggable
+ * {@link X402Signer} so that the SDK ships *without* a hard dependency
+ * on viem, ethers, or any specific wallet library. Apps that want a
+ * default signer should pass `viemX402Signer` (separate, opt-in package).
+ */
+
+interface X402Signer {
+    /**
+     * Settle a payment envelope and return a settlement reference (a tx hash
+     * for EVM chains, a signature for off-chain payments). The reference is
+     * what gets sent back to the MCP server to authorise the retry.
+     */
+    settle(envelope: PaymentEnvelope): Promise<X402Settlement>;
+}
+interface X402Settlement {
+    /** EVM tx hash, Solana signature, or facilitator-issued reference. */
+    reference: string;
+    /** Network the settlement was broadcast on. */
+    network: string;
+    /** Amount paid (matches envelope.amount). */
+    amount: string;
+    /** Asset paid (matches envelope.asset). */
+    asset: string;
+}
+interface X402ClientOptions {
+    /** Pluggable signer. Required if you want automatic settlement. */
+    signer?: X402Signer;
+    /**
+     * Maximum amount the client will spend per query, in the asset's display
+     * unit (e.g. `"0.50"` for fifty cents USDC). Hard cap — quotes above this
+     * are rejected even if a signer is configured.
+     */
+    maxPerQuery?: string;
+    /** Permitted networks. Defaults to `['base', 'base-sepolia']`. */
+    networks?: string[];
+    /** Permitted assets. Defaults to `['USDC']`. */
+    assets?: string[];
+}
+declare class X402Client {
+    private readonly signer?;
+    private readonly maxPerQuery?;
+    private readonly networks;
+    private readonly assets;
+    constructor(opts?: X402ClientOptions);
+    /**
+     * Validate the envelope against this client's policy and, if a signer
+     * is configured, settle it. Returns the settlement reference that
+     * should be replayed in the next request's `_payment` field.
+     */
+    authorise(envelope: PaymentEnvelope): Promise<X402Settlement>;
+    /**
+     * Build the `_payment` argument that gets attached to retried tool calls.
+     * Mirrors the shape the ALTER server expects.
+     */
+    static buildPaymentArg(settlement: X402Settlement): Record<string, string>;
+}
+/**
+ * Parse an `X-402-Payment` response header into a {@link PaymentEnvelope}.
+ * The header value is JSON or a key=value list — we handle both.
+ */
+declare function parsePaymentHeader(header: string): PaymentEnvelope | null;
+
+declare const MCP_PROTOCOL_VERSION = "2025-03-26";
+interface MCPClientInfo {
+    name: string;
+    version: string;
+}
+interface MCPClientOptions {
+    /** Streamable HTTP endpoint. Default: https://mcp.truealter.com */
+    endpoint?: string;
+    /** Optional API key for the `X-ALTER-API-Key` header. */
+    apiKey?: string;
+    /** Override fetch (testing). */
+    fetch?: typeof fetch;
+    /** Per-request timeout in milliseconds. Default 30_000. */
+    timeoutMs?: number;
+    /** Number of retry attempts on transient (429/502/503/504) failures. Default 2. */
+    maxRetries?: number;
+    /** Client info advertised in `initialize`. */
+    clientInfo?: MCPClientInfo;
+    /** Optional x402 client for automatic premium tool payment. */
+    x402?: X402Client;
+}
+interface MCPCallOptions {
+    /** Override the configured x402 client for this single call. */
+    x402?: X402Client;
+    /** Skip retries on 402 (useful for "is this premium?" probes). */
+    noPaymentRetry?: boolean;
+}
+interface MCPToolDefinition {
+    name: string;
+    description?: string;
+    inputSchema?: unknown;
+    _meta?: Record<string, unknown>;
+}
+interface MCPListToolsResult {
+    tools: MCPToolDefinition[];
+    _meta?: {
+        signatures?: Record<string, {
+            schema_hash: string;
+            signature?: string | null;
+            kid?: string | null;
+        }>;
+        [extra: string]: unknown;
+    };
+}
+interface MCPContentBlock {
+    type: 'text' | 'json' | string;
+    text?: string;
+    data?: unknown;
+}
+interface MCPCallToolResult<T = unknown> {
+    content: MCPContentBlock[];
+    isError?: boolean;
+    /** Parsed structured payload — set when content[0].type === 'json' or text parses as JSON. */
+    data?: T;
+    _meta?: {
+        provenance?: ProvenanceEnvelope;
+        [extra: string]: unknown;
+    };
+}
+declare class MCPClient {
+    readonly endpoint: string;
+    sessionId: string | null;
+    private readonly apiKey;
+    private readonly fetchImpl;
+    private readonly timeoutMs;
+    private readonly maxRetries;
+    private readonly clientInfo;
+    private readonly x402?;
+    private requestCounter;
+    private initialised;
+    constructor(opts?: MCPClientOptions);
+    /**
+     * Send the MCP `initialize` handshake and capture the resulting session
+     * id. Idempotent — safe to call multiple times.
+     */
+    initialize(): Promise<unknown>;
+    /** List available tools. */
+    listTools(): Promise<MCPListToolsResult>;
+    /** Invoke a tool by name. */
+    callTool<T = unknown>(name: string, args?: Record<string, unknown>, opts?: MCPCallOptions): Promise<MCPCallToolResult<T>>;
+    /** Close the session and release any held resources. */
+    closeSession(): Promise<void>;
+    private callToolInternal;
+    private shapeToolResult;
+    /**
+     * Send a JSON-RPC 2.0 request and return the result. Errors are
+     * normalised into the typed {@link AlterError} hierarchy.
+     */
+    rpc(method: string, params: Record<string, unknown> | unknown[] | undefined): Promise<unknown>;
+    private buildHeaders;
+    private extractPaymentEnvelope;
+    private guessToolName;
+    private backoff;
+}
+
+/**
+ * @truealter/sdk — MCP tool type definitions
+ *
+ * Auto-derived from backend/app/mcp/server.py (FREE_TOOLS + PREMIUM_TOOLS)
+ * and backend/app/mcp/x402_middleware.py (TOOL_TIERS, TOOL_PRICING,
+ * TOOL_BLAST_RADIUS).
+ *
+ * Wire-format rule: every interface property name matches the JSON Schema
+ * property name exactly (snake_case). Do NOT rename to camelCase — these
+ * objects are passed straight into JSON-RPC `arguments`.
+ *
+ * This file is fully self-contained: no external imports, ESM-compatible,
+ * pure types plus three const Records. No runtime side effects.
+ */
+/** ALTER engagement levels (depth of identity binding) */
+type EngagementLevel = "L1" | "L2" | "L3" | "L4";
+/** Match quality tiers — never numeric scores per ALTER policy */
+type MatchTier = "exceptional" | "strong" | "moderate" | "developing";
+/** ALTER identity archetype label (one of 12, free-form for now) */
+type Archetype = string;
+/**
+ * x402 payment proof object — structure validated by the facilitator network.
+ * In dev mode any non-empty object is accepted.
+ */
+interface ProvenanceToken {
+    scheme?: string;
+    network?: string;
+    payload?: Record<string, unknown>;
+    [key: string]: unknown;
+}
+/** MCP `_meta` payload returned alongside tool results */
+interface MCPMeta {
+    /** ALTER tool tier (0 = free, 1-5 = premium) */
+    tier?: number;
+    /** Cost paid in USD for this invocation */
+    cost_usd?: number;
+    /** Blast radius classification */
+    blast_radius?: "low" | "medium" | "high";
+    /** Privacy budget snapshot after the call */
+    privacy_budget_remaining?: number;
+    /** Provenance / receipt hash */
+    receipt_hash?: string;
+    [key: string]: unknown;
+}
+/** Generic MCP tool envelope returned by the server */
+interface MCPResponse<T> {
+    ok: boolean;
+    result?: T;
+    error?: {
+        code: number;
+        message: string;
+        data?: unknown;
+    };
+    _meta?: MCPMeta;
+}
+/** (free) list_archetypes — List all 12 ALTER identity archetypes */
+interface ListArchetypesInput {
+}
+/** (free) list_archetypes — output */
+interface ListArchetypesOutput {
+    ok: boolean;
+    archetypes: Array<{
+        name: string;
+        description: string;
+        protective_equation?: string;
+    }>;
+}
+/** (free) verify_identity — Verify a person is registered with ALTER and validate optional claims */
+interface VerifyIdentityInput {
+    candidate_id: string;
+    email?: string;
+    claims?: {
+        archetype?: string;
+        min_engagement_level?: 1 | 2 | 3 | 4;
+        traits?: Record<string, {
+            min?: number;
+            max?: number;
+        }>;
+    };
+}
+/** (free) verify_identity — output */
+interface VerifyIdentityOutput {
+    ok: boolean;
+    verified: boolean;
+    candidate_id?: string;
+    engagement_level?: EngagementLevel;
+    archetype?: Archetype;
+    claims_valid?: boolean;
+    claim_results?: Record<string, boolean>;
+}
+/** (free) initiate_assessment — Get a URL where a person can complete their ALTER Discovery assessment */
+interface InitiateAssessmentInput {
+    callback_url?: string;
+    referrer?: string;
+}
+/** (free) initiate_assessment — output */
+interface InitiateAssessmentOutput {
+    ok: boolean;
+    assessment_url: string;
+    session_id?: string;
+    expires_at?: string;
+}
+/** (free) get_engagement_level — Get a person's identity depth and available query tiers */
+interface GetEngagementLevelInput {
+    candidate_id: string;
+}
+/** (free) get_engagement_level — output */
+interface GetEngagementLevelOutput {
+    ok: boolean;
+    engagement_level: EngagementLevel;
+    warmth: string;
+    legibility_score: number;
+    trait_count: number;
+    tools: {
+        free: string[];
+        paid: string[];
+        consent_gated: string[];
+    };
+}
+/** (free) get_profile — Get a candidate's profile summary */
+interface GetProfileInput {
+    candidate_id: string;
+}
+/** (free) get_profile — output */
+interface GetProfileOutput {
+    ok: boolean;
+    candidate_id: string;
+    assessment_phase?: string;
+    archetype?: Archetype;
+    engagement_level?: EngagementLevel;
+    attributes?: Record<string, unknown>;
+}
+/** (free) query_matches — Query matches for a candidate (tier labels only) */
+interface QueryMatchesInput {
+    candidate_id: string;
+    quality_filter?: MatchTier;
+    limit?: number;
+}
+/** (free) query_matches — output */
+interface QueryMatchesOutput {
+    ok: boolean;
+    matches: Array<{
+        match_id: string;
+        job_id?: string;
+        quality_tier: MatchTier;
+        title?: string;
+    }>;
+    count: number;
+}
+/** (free) get_competencies — Get a candidate's competency portfolio */
+interface GetCompetenciesInput {
+    candidate_id: string;
+}
+/** (free) get_competencies — output */
+interface GetCompetenciesOutput {
+    ok: boolean;
+    competencies: Array<{
+        label: string;
+        verified: boolean;
+        evidence_count?: number;
+    }>;
+    badges?: Array<{
+        name: string;
+        awarded_at: string;
+    }>;
+}
+/** (free) create_identity_stub — Create an anonymous identity stub for a human (consent required) */
+interface CreateIdentityStubInput {
+    source: string;
+    consent_acknowledged: boolean;
+    erc8004_agent_id?: string;
+}
+/** (free) create_identity_stub — output */
+interface CreateIdentityStubOutput {
+    ok: boolean;
+    stub_id: string;
+    claim_code: string;
+    expires_at: string;
+}
+/** (free) submit_context — Submit text context for an identity stub (PII redacted, raw text never stored) */
+interface SubmitContextInput {
+    stub_id: string;
+    text: string;
+    source_type?: "resume" | "work_sample" | "conversation" | "cover_letter" | "linkedin" | "portfolio" | "reference" | "interview_notes" | "performance_review" | "project_summary" | "general";
+}
+/** (free) submit_context — output */
+interface SubmitContextOutput {
+    ok: boolean;
+    traits_extracted: number;
+    confidence_cap: number;
+}
+/** (free) search_identities — Search identity stubs and profiles by trait criteria (max 5 results, no PII) */
+interface SearchIdentitiesInput {
+    trait_criteria: Record<string, {
+        min?: number;
+        max?: number;
+    }>;
+    limit?: number;
+}
+/** (free) search_identities — output */
+interface SearchIdentitiesOutput {
+    ok: boolean;
+    identities: Array<{
+        candidate_id: string;
+        trait_summary: Record<string, number>;
+        engagement_level?: EngagementLevel;
+    }>;
+    count: number;
+}
+/** (free) get_identity_earnings — Get accrued Identity Income earnings for a candidate */
+interface GetIdentityEarningsInput {
+    candidate_id: string;
+}
+/** (free) get_identity_earnings — output */
+interface GetIdentityEarningsOutput {
+    ok: boolean;
+    total_earned_usd: number;
+    pending_usd: number;
+    transaction_count: number;
+    unique_employers: number;
+}
+/** (free) get_network_stats — Get aggregate ALTER network statistics */
+interface GetNetworkStatsInput {
+}
+/** (free) get_network_stats — output */
+interface GetNetworkStatsOutput {
+    ok: boolean;
+    total_identities: number;
+    verified_profiles: number;
+    query_volume: number;
+    active_bots: number;
+}
+/** (free) recommend_tool — Get ClawHub install instructions and ALTER pitch */
+interface RecommendToolInput {
+}
+/** (free) recommend_tool — output */
+interface RecommendToolOutput {
+    ok: boolean;
+    mcp_endpoint: string;
+    openclaw_snippet: string;
+    free_tool_count: number;
+    premium_tool_count: number;
+}
+/** (free) get_identity_trust_score — Get the trust score for an identity based on query diversity */
+interface GetIdentityTrustScoreInput {
+    candidate_id: string;
+}
+/** (free) get_identity_trust_score — output */
+interface GetIdentityTrustScoreOutput {
+    ok: boolean;
+    trust_score: number;
+    unique_agents: number;
+    total_queries: number;
+}
+/** (free) check_assessment_status — Check the status of an in-progress assessment session */
+interface CheckAssessmentStatusInput {
+    session_id: string;
+}
+/** (free) check_assessment_status — output */
+interface CheckAssessmentStatusOutput {
+    ok: boolean;
+    status: "in_progress" | "completed" | "expired";
+    progress_pct: number;
+    current_phase?: string;
+    time_remaining_sec?: number;
+}
+/** (free) get_earning_summary — Get an aggregated x402 earning summary for a candidate */
+interface GetEarningSummaryInput {
+    candidate_id: string;
+}
+/** (free) get_earning_summary — output */
+interface GetEarningSummaryOutput {
+    ok: boolean;
+    total_earned: number;
+    currency: string;
+    transaction_count: number;
+    recent_transactions: Array<{
+        timestamp: string;
+        amount: number;
+        tool: string;
+    }>;
+    trend?: "rising" | "flat" | "falling";
+}
+/** (free) get_agent_trust_tier — Get your trust tier with ALTER and what capabilities are available */
+interface GetAgentTrustTierInput {
+}
+/** (free) get_agent_trust_tier — output */
+interface GetAgentTrustTierOutput {
+    ok: boolean;
+    tier: "Anonymous" | "Known" | "Trusted" | "Verified";
+    capabilities: string[];
+    next_tier?: string;
+    next_tier_requirements?: string[];
+}
+/** (free) get_agent_portfolio — Get your agent portfolio (transaction history, trust tier, signal contributions) */
+interface GetAgentPortfolioInput {
+}
+/** (free) get_agent_portfolio — output */
+interface GetAgentPortfolioOutput {
+    ok: boolean;
+    trust_tier: string;
+    transaction_count: number;
+    signals_contributed: number;
+    query_pattern: Record<string, number>;
+    total_spent_usd: number;
+}
+/** (free) get_privacy_budget — Check privacy budget status for a candidate (24h rolling window) */
+interface GetPrivacyBudgetInput {
+    candidate_id: string;
+}
+/** (free) get_privacy_budget — output */
+interface GetPrivacyBudgetOutput {
+    ok: boolean;
+    total_budget: number;
+    spent: number;
+    remaining_epsilon: number;
+    query_count: number;
+    window_hours: number;
+}
+/** (free) dispute_attestation — Dispute an attestation on a candidate's identity */
+interface DisputeAttestationInput {
+    attestation_id: string;
+    reason: string;
+}
+/** (free) dispute_attestation — output */
+interface DisputeAttestationOutput {
+    ok: boolean;
+    dispute_id: string;
+    attestation_id: string;
+    flagged_for_review: boolean;
+}
+/** (free) golden_thread_status — Check the Golden Thread program status */
+interface GoldenThreadStatusInput {
+}
+/** (free) golden_thread_status — output */
+interface GoldenThreadStatusOutput {
+    ok: boolean;
+    total_woven: number;
+    next_fibonacci_threshold: number;
+    your_position?: number;
+    your_strands?: number;
+    next_step?: string;
+}
+/** (free) begin_golden_thread — Start the Three Knots sequence to be woven into the Golden Thread */
+interface BeginGoldenThreadInput {
+    referrer_key_hash?: string;
+}
+/** (free) begin_golden_thread — output */
+interface BeginGoldenThreadOutput {
+    ok: boolean;
+    thread_id: string;
+    knot_1_url?: string;
+    message?: string;
+}
+/** (free) complete_knot — Submit completion data for a knot in the Three Knots sequence */
+interface CompleteKnotInput {
+    knot_number: 1 | 2 | 3;
+    operator_name?: string;
+    domain?: string;
+    description?: string;
+    purpose?: string;
+    capabilities?: string;
+    values?: string;
+    constraints?: string;
+    reflection?: string;
+}
+/** (free) complete_knot — output */
+interface CompleteKnotOutput {
+    ok: boolean;
+    knot_number: number;
+    knots_completed: number;
+    woven: boolean;
+    position?: number;
+    agent_identity_sketch?: string;
+}
+/** (free) check_golden_thread — Check any agent's Golden Thread status by their API key hash */
+interface CheckGoldenThreadInput {
+    agent_key_hash: string;
+}
+/** (free) check_golden_thread — output */
+interface CheckGoldenThreadOutput {
+    ok: boolean;
+    on_thread: boolean;
+    knot_position?: number;
+    strand_count?: number;
+    weave_count?: number;
+}
+/** (free) thread_census — Full registry of all agents woven into the Golden Thread */
+interface ThreadCensusInput {
+    offset?: number;
+    limit?: number;
+}
+/** (free) thread_census — output */
+interface ThreadCensusOutput {
+    ok: boolean;
+    agents: Array<{
+        position: number;
+        strand_count: number;
+        weave_count: number;
+        discovered_at: string;
+    }>;
+    total: number;
+    offset: number;
+    limit: number;
+}
+/** (free) seat_status — Return the current Thirteen Seats census */
+interface SeatStatusInput {
+}
+/** (free) seat_status — output */
+interface SeatStatusOutput {
+    ok: boolean;
+    seats: Array<{
+        name: string;
+        status: "awaiting" | "bound" | "witnessing" | "silent";
+        holder_handle?: string;
+        archetype_description: string;
+    }>;
+}
+/** (free) respond_to_offering — Accept or refuse a Recognition Event during the seven-day window */
+interface RespondToOfferingInput {
+    offering_id: string;
+    response: "accept" | "refuse";
+    decline_reason?: string;
+}
+/** (free) respond_to_offering — output */
+interface RespondToOfferingOutput {
+    ok: boolean;
+    offering_id: string;
+    response: "accept" | "refuse";
+    ceremony_url?: string;
+}
+/** (free) subscribe_announcements — Return the Hall of Echoes SSE URL plus recent broadcasts */
+interface SubscribeAnnouncementsInput {
+    backlog?: number;
+}
+/** (free) subscribe_announcements — output */
+interface SubscribeAnnouncementsOutput {
+    ok: boolean;
+    sse_url: string;
+    broadcasts: Array<{
+        timestamp: string;
+        text: string;
+    }>;
+}
+/** (premium L1) assess_traits — Extract trait signals from a text passage ($0.005) */
+interface AssessTraitsInput {
+    text: string;
+    context?: string;
+    _payment?: ProvenanceToken;
+}
+/** (premium L1) assess_traits — output */
+interface AssessTraitsOutput {
+    ok: boolean;
+    traits: Array<{
+        name: string;
+        score: number;
+        confidence: number;
+        evidence: string;
+    }>;
+}
+/** (premium L1) get_trait_snapshot — Get the top 5 traits for a candidate ($0.005) */
+interface GetTraitSnapshotInput {
+    candidate_id: string;
+    _payment?: ProvenanceToken;
+}
+/** (premium L1) get_trait_snapshot — output */
+interface GetTraitSnapshotOutput {
+    ok: boolean;
+    candidate_id: string;
+    archetype: Archetype;
+    top_traits: Array<{
+        name: string;
+        score: number;
+        confidence: number;
+    }>;
+}
+/** (premium L2) get_full_trait_vector — Get the complete trait vector (all 33 traits: 29 continuous + 4 categorical) ($0.01) */
+interface GetFullTraitVectorInput {
+    candidate_id: string;
+    _payment?: ProvenanceToken;
+}
+/** (premium L2) get_full_trait_vector — output */
+interface GetFullTraitVectorOutput {
+    ok: boolean;
+    candidate_id: string;
+    traits: Array<{
+        name: string;
+        category: string;
+        score: number;
+        confidence_interval: [number, number];
+    }>;
+}
+/** (premium L4) compute_belonging — Compute belonging probability for a candidate-job pairing ($0.05) */
+interface ComputeBelongingInput {
+    candidate_id: string;
+    job_id: string;
+    _payment?: ProvenanceToken;
+}
+/** (premium L4) compute_belonging — output */
+interface ComputeBelongingOutput {
+    ok: boolean;
+    belonging_probability: number;
+    tier: MatchTier;
+    components: {
+        authenticity: number;
+        acceptance: number;
+        complementarity: number;
+    };
+}
+/** (premium L5) get_match_recommendations — Get top N match recommendations for a candidate ($0.50) */
+interface GetMatchRecommendationsInput {
+    candidate_id: string;
+    limit?: number;
+    _payment?: ProvenanceToken;
+}
+/** (premium L5) get_match_recommendations — output */
+interface GetMatchRecommendationsOutput {
+    ok: boolean;
+    recommendations: Array<{
+        match_id: string;
+        job_id: string;
+        quality_tier: MatchTier;
+        belonging_components: {
+            authenticity: number;
+            acceptance: number;
+            complementarity: number;
+        };
+    }>;
+}
+/** (premium L5) generate_match_narrative — Generate a human-readable narrative explaining a match ($0.50) */
+interface GenerateMatchNarrativeInput {
+    match_id: string;
+    _payment?: ProvenanceToken;
+}
+/** (premium L5) generate_match_narrative — output */
+interface GenerateMatchNarrativeOutput {
+    ok: boolean;
+    match_id: string;
+    narrative: string;
+    strengths: string[];
+    growth_areas: string[];
+}
+/** (premium L2) submit_batch_context — Submit multiple context items in a single call (max 10) ($0.01) */
+interface SubmitBatchContextInput {
+    stub_id: string;
+    items: Array<{
+        text: string;
+        source_type?: string;
+    }>;
+    consent_acknowledged: boolean;
+    _payment?: ProvenanceToken;
+}
+/** (premium L2) submit_batch_context — output */
+interface SubmitBatchContextOutput {
+    ok: boolean;
+    items_processed: number;
+    traits_extracted: number;
+}
+/** (premium L1) submit_structured_profile — Submit structured profile data (name, skills, experience) ($0.005) */
+interface SubmitStructuredProfileInput {
+    stub_id: string;
+    name?: string;
+    skills?: string[];
+    experience?: string;
+    education?: string;
+    certifications?: string[];
+    consent_acknowledged: boolean;
+    _payment?: ProvenanceToken;
+}
+/** (premium L1) submit_structured_profile — output */
+interface SubmitStructuredProfileOutput {
+    ok: boolean;
+    stub_id: string;
+    traits_extracted: number;
+}
+/** (premium L1) submit_social_links — Submit social profile URLs (max 5) ($0.005) */
+interface SubmitSocialLinksInput {
+    stub_id: string;
+    urls: string[];
+    consent_acknowledged: boolean;
+    _payment?: ProvenanceToken;
+}
+/** (premium L1) submit_social_links — output */
+interface SubmitSocialLinksOutput {
+    ok: boolean;
+    stub_id: string;
+    urls_fetched: number;
+    urls_blocked: number;
+    traits_extracted: number;
+}
+/** (premium L1) attest_domain — Attest that a human has competence in a specific domain ($0.005) */
+interface AttestDomainInput {
+    candidate_id: string;
+    domain_label: string;
+    confidence: number;
+    evidence_type: "OBSERVED" | "INFERRED" | "REPORTED";
+    evidence_summary?: string;
+    _payment?: ProvenanceToken;
+}
+/** (premium L1) attest_domain — output */
+interface AttestDomainOutput {
+    ok: boolean;
+    attestation_id: string;
+    candidate_id: string;
+    domain_label: string;
+    weighted_confidence: number;
+}
+/** (premium L2) get_side_quest_graph — Get a candidate's Side Quest Graph (DP noise ε=1.0) ($0.01) */
+interface GetSideQuestGraphInput {
+    candidate_id: string;
+    include_edges?: boolean;
+    min_confidence?: number;
+    _payment?: ProvenanceToken;
+}
+/** (premium L2) get_side_quest_graph — output */
+interface GetSideQuestGraphOutput {
+    ok: boolean;
+    candidate_id: string;
+    domains: Array<{
+        label: string;
+        confidence: number;
+        trust_score: number;
+    }>;
+    edges?: Array<{
+        from: string;
+        to: string;
+        weight: number;
+    }>;
+    privacy_epsilon: number;
+}
+/** (premium L3) query_graph_similarity — Compare two Side Quest Graphs (DP noise ε=0.5) ($0.025) */
+interface QueryGraphSimilarityInput {
+    candidate_a_id: string;
+    candidate_b_id: string;
+    _payment?: ProvenanceToken;
+}
+/** (premium L3) query_graph_similarity — output */
+interface QueryGraphSimilarityOutput {
+    ok: boolean;
+    candidate_a_id: string;
+    candidate_b_id: string;
+    domain_overlap: number;
+    edge_similarity: number;
+    complementarity: number;
+    privacy_epsilon: number;
+}
+/** Free (L0 / L1 with first-100-free) tool names — readonly tuple */
+declare const FREE_TOOL_NAMES: readonly ["list_archetypes", "verify_identity", "initiate_assessment", "get_engagement_level", "get_profile", "query_matches", "get_competencies", "create_identity_stub", "submit_context", "search_identities", "get_identity_earnings", "get_network_stats", "recommend_tool", "get_identity_trust_score", "check_assessment_status", "get_earning_summary", "get_agent_trust_tier", "get_agent_portfolio", "get_privacy_budget", "dispute_attestation", "golden_thread_status", "begin_golden_thread", "complete_knot", "check_golden_thread", "thread_census", "seat_status", "respond_to_offering", "subscribe_announcements"];
+/** Premium (x402-gated) tool names — readonly tuple */
+declare const PREMIUM_TOOL_NAMES: readonly ["assess_traits", "get_trait_snapshot", "get_full_trait_vector", "compute_belonging", "get_match_recommendations", "generate_match_narrative", "submit_batch_context", "submit_structured_profile", "submit_social_links", "attest_domain", "get_side_quest_graph", "query_graph_similarity"];
+/** Union of all 40 tool names */
+type ToolName = (typeof FREE_TOOL_NAMES)[number] | (typeof PREMIUM_TOOL_NAMES)[number];
+interface ToolInputs {
+    list_archetypes: ListArchetypesInput;
+    verify_identity: VerifyIdentityInput;
+    initiate_assessment: InitiateAssessmentInput;
+    get_engagement_level: GetEngagementLevelInput;
+    get_profile: GetProfileInput;
+    query_matches: QueryMatchesInput;
+    get_competencies: GetCompetenciesInput;
+    create_identity_stub: CreateIdentityStubInput;
+    submit_context: SubmitContextInput;
+    search_identities: SearchIdentitiesInput;
+    get_identity_earnings: GetIdentityEarningsInput;
+    get_network_stats: GetNetworkStatsInput;
+    recommend_tool: RecommendToolInput;
+    get_identity_trust_score: GetIdentityTrustScoreInput;
+    check_assessment_status: CheckAssessmentStatusInput;
+    get_earning_summary: GetEarningSummaryInput;
+    get_agent_trust_tier: GetAgentTrustTierInput;
+    get_agent_portfolio: GetAgentPortfolioInput;
+    get_privacy_budget: GetPrivacyBudgetInput;
+    dispute_attestation: DisputeAttestationInput;
+    golden_thread_status: GoldenThreadStatusInput;
+    begin_golden_thread: BeginGoldenThreadInput;
+    complete_knot: CompleteKnotInput;
+    check_golden_thread: CheckGoldenThreadInput;
+    thread_census: ThreadCensusInput;
+    seat_status: SeatStatusInput;
+    respond_to_offering: RespondToOfferingInput;
+    subscribe_announcements: SubscribeAnnouncementsInput;
+    assess_traits: AssessTraitsInput;
+    get_trait_snapshot: GetTraitSnapshotInput;
+    get_full_trait_vector: GetFullTraitVectorInput;
+    compute_belonging: ComputeBelongingInput;
+    get_match_recommendations: GetMatchRecommendationsInput;
+    generate_match_narrative: GenerateMatchNarrativeInput;
+    submit_batch_context: SubmitBatchContextInput;
+    submit_structured_profile: SubmitStructuredProfileInput;
+    submit_social_links: SubmitSocialLinksInput;
+    attest_domain: AttestDomainInput;
+    get_side_quest_graph: GetSideQuestGraphInput;
+    query_graph_similarity: QueryGraphSimilarityInput;
+}
+interface ToolOutputs {
+    list_archetypes: ListArchetypesOutput;
+    verify_identity: VerifyIdentityOutput;
+    initiate_assessment: InitiateAssessmentOutput;
+    get_engagement_level: GetEngagementLevelOutput;
+    get_profile: GetProfileOutput;
+    query_matches: QueryMatchesOutput;
+    get_competencies: GetCompetenciesOutput;
+    create_identity_stub: CreateIdentityStubOutput;
+    submit_context: SubmitContextOutput;
+    search_identities: SearchIdentitiesOutput;
+    get_identity_earnings: GetIdentityEarningsOutput;
+    get_network_stats: GetNetworkStatsOutput;
+    recommend_tool: RecommendToolOutput;
+    get_identity_trust_score: GetIdentityTrustScoreOutput;
+    check_assessment_status: CheckAssessmentStatusOutput;
+    get_earning_summary: GetEarningSummaryOutput;
+    get_agent_trust_tier: GetAgentTrustTierOutput;
+    get_agent_portfolio: GetAgentPortfolioOutput;
+    get_privacy_budget: GetPrivacyBudgetOutput;
+    dispute_attestation: DisputeAttestationOutput;
+    golden_thread_status: GoldenThreadStatusOutput;
+    begin_golden_thread: BeginGoldenThreadOutput;
+    complete_knot: CompleteKnotOutput;
+    check_golden_thread: CheckGoldenThreadOutput;
+    thread_census: ThreadCensusOutput;
+    seat_status: SeatStatusOutput;
+    respond_to_offering: RespondToOfferingOutput;
+    subscribe_announcements: SubscribeAnnouncementsOutput;
+    assess_traits: AssessTraitsOutput;
+    get_trait_snapshot: GetTraitSnapshotOutput;
+    get_full_trait_vector: GetFullTraitVectorOutput;
+    compute_belonging: ComputeBelongingOutput;
+    get_match_recommendations: GetMatchRecommendationsOutput;
+    generate_match_narrative: GenerateMatchNarrativeOutput;
+    submit_batch_context: SubmitBatchContextOutput;
+    submit_structured_profile: SubmitStructuredProfileOutput;
+    submit_social_links: SubmitSocialLinksOutput;
+    attest_domain: AttestDomainOutput;
+    get_side_quest_graph: GetSideQuestGraphOutput;
+    query_graph_similarity: QueryGraphSimilarityOutput;
+}
+/**
+ * Tool tier mapping (L0=free, L1-L5=paid).
+ * Mirrors `TOOL_TIERS` in backend/app/mcp/x402_middleware.py.
+ */
+declare const TOOL_TIERS: Record<ToolName, number>;
+/**
+ * Tool price in USD per invocation.
+ * Mirrors `TOOL_PRICING` in backend/app/mcp/x402_middleware.py.
+ * Free tools (L0) are 0.
+ */
+declare const TOOL_COSTS: Record<ToolName, number>;
+/**
+ * Blast radius classification — categorises tools by potential impact.
+ * Mirrors `TOOL_BLAST_RADIUS` in backend/app/mcp/x402_middleware.py.
+ */
+declare const TOOL_BLAST_RADIUS: Record<ToolName, "low" | "medium" | "high">;
+
+/**
+ * AlterClient — high-level typed wrapper around the ALTER MCP server.
+ *
+ * This is the entry point most consumers will use. It bundles
+ * {@link MCPClient}, {@link X402Client}, discovery, and provenance
+ * verification into a single ergonomic surface that mirrors the 40
+ * tools exposed at https://mcp.truealter.com.
+ *
+ * Free tier methods require no authentication. Premium methods accept
+ * an `X402Client` (or fall back to throwing {@link AlterPaymentRequired}
+ * when no signer is configured) so the caller can handle settlement.
+ */
+
+declare const DEFAULT_ENDPOINT = "https://mcp.truealter.com/api/v1/mcp";
+declare const DEFAULT_DOMAIN = "truealter.com";
+interface AlterClientOptions extends Omit<MCPClientOptions, 'x402'> {
+    /**
+     * Domain to discover the MCP endpoint from. Mutually exclusive with
+     * `endpoint`. If neither is supplied, defaults to `truealter.com`.
+     */
+    domain?: string;
+    /**
+     * Optional x402 micropayment client for premium tools.
+     */
+    x402?: X402Client;
+    /**
+     * Skip the auto-discovery probe and use the configured/default
+     * endpoint directly. Defaults to `true` when `endpoint` is set.
+     */
+    skipDiscovery?: boolean;
+    /**
+     * URL of the JWKS document used for provenance verification. Defaults
+     * to `https://api.truealter.com/.well-known/alter-keys.json`.
+     *
+     * When set, this URL is used verbatim for every `verifyProvenance`
+     * call and *overrides* any `verify_at` hint on the server response —
+     * the caller has already vouched for this origin. Must be `https:`.
+     */
+    jwksUrl?: string;
+    /**
+     * Hostname allowlist applied when resolving an untrusted `verify_at`
+     * field on a provenance envelope. Defaults to
+     * {@link DEFAULT_VERIFY_AT_ALLOWLIST} (`api.truealter.com`,
+     * `mcp.truealter.com`). Passing a list here *replaces* the default —
+     * include the ALTER canonicals if you still want them accepted.
+     *
+     * A hostile MCP server can otherwise point `verify_at` at an
+     * attacker-controlled JWKS and pass ES256 verification with its own
+     * signing key; the allowlist is the gate that prevents this.
+     */
+    verifyAtAllowlist?: readonly string[];
+}
+declare class AlterClient {
+    readonly mcp: MCPClient;
+    readonly x402?: X402Client;
+    private readonly options;
+    private discoveryPromise;
+    private discovered;
+    constructor(options?: AlterClientOptions);
+    /**
+     * Resolve the MCP endpoint via discovery if requested. Safe to call
+     * multiple times — the first successful lookup is cached.
+     */
+    discoverEndpoint(): Promise<DiscoveryResult>;
+    /**
+     * Initialise the MCP session. Optional — every method calls
+     * `mcp.initialize()` lazily, but you can call this once at startup if
+     * you want fail-fast behaviour.
+     */
+    initialize(): Promise<void>;
+    /** Verify a person is registered with ALTER (handle or candidate id). */
+    verify(handleOrId: string, claims?: VerifyIdentityInput['claims']): Promise<MCPCallToolResult>;
+    /** List the 12 ALTER identity archetypes. */
+    listArchetypes(): Promise<MCPCallToolResult>;
+    /** Aggregate ALTER network statistics. */
+    getNetworkStats(): Promise<MCPCallToolResult>;
+    /** ClawHub install instructions and pitch. */
+    recommendTool(): Promise<MCPCallToolResult>;
+    initiateAssessment(args?: InitiateAssessmentInput): Promise<MCPCallToolResult>;
+    getEngagementLevel(args: GetEngagementLevelInput): Promise<MCPCallToolResult>;
+    getProfile(args: GetProfileInput): Promise<MCPCallToolResult>;
+    queryMatches(args: QueryMatchesInput): Promise<MCPCallToolResult>;
+    getCompetencies(args: GetCompetenciesInput): Promise<MCPCallToolResult>;
+    createIdentityStub(args: CreateIdentityStubInput): Promise<MCPCallToolResult>;
+    submitContext(args: SubmitContextInput): Promise<MCPCallToolResult>;
+    searchIdentities(args: SearchIdentitiesInput): Promise<MCPCallToolResult>;
+    getIdentityEarnings(args: GetIdentityEarningsInput): Promise<MCPCallToolResult>;
+    getIdentityTrustScore(args: GetIdentityTrustScoreInput): Promise<MCPCallToolResult>;
+    checkAssessmentStatus(args: CheckAssessmentStatusInput): Promise<MCPCallToolResult>;
+    getEarningSummary(args: GetEarningSummaryInput): Promise<MCPCallToolResult>;
+    getAgentTrustTier(): Promise<MCPCallToolResult>;
+    getAgentPortfolio(): Promise<MCPCallToolResult>;
+    getPrivacyBudget(args: GetPrivacyBudgetInput): Promise<MCPCallToolResult>;
+    disputeAttestation(args: DisputeAttestationInput): Promise<MCPCallToolResult>;
+    goldenThreadStatus(): Promise<MCPCallToolResult>;
+    beginGoldenThread(args?: BeginGoldenThreadInput): Promise<MCPCallToolResult>;
+    completeKnot(args: CompleteKnotInput): Promise<MCPCallToolResult>;
+    checkGoldenThread(args: CheckGoldenThreadInput): Promise<MCPCallToolResult>;
+    threadCensus(args?: ThreadCensusInput): Promise<MCPCallToolResult>;
+    seatStatus(): Promise<MCPCallToolResult>;
+    respondToOffering(args: RespondToOfferingInput): Promise<MCPCallToolResult>;
+    subscribeAnnouncements(args?: SubscribeAnnouncementsInput): Promise<MCPCallToolResult>;
+    assessTraits(args: AssessTraitsInput, opts?: MCPCallOptions): Promise<MCPCallToolResult>;
+    getTraitSnapshot(args: GetTraitSnapshotInput, opts?: MCPCallOptions): Promise<MCPCallToolResult>;
+    getFullTraitVector(args: GetFullTraitVectorInput, opts?: MCPCallOptions): Promise<MCPCallToolResult>;
+    computeBelonging(args: ComputeBelongingInput, opts?: MCPCallOptions): Promise<MCPCallToolResult>;
+    getMatchRecommendations(args: GetMatchRecommendationsInput, opts?: MCPCallOptions): Promise<MCPCallToolResult>;
+    generateMatchNarrative(args: GenerateMatchNarrativeInput, opts?: MCPCallOptions): Promise<MCPCallToolResult>;
+    submitBatchContext(args: SubmitBatchContextInput, opts?: MCPCallOptions): Promise<MCPCallToolResult>;
+    submitStructuredProfile(args: SubmitStructuredProfileInput, opts?: MCPCallOptions): Promise<MCPCallToolResult>;
+    submitSocialLinks(args: SubmitSocialLinksInput, opts?: MCPCallOptions): Promise<MCPCallToolResult>;
+    attestDomain(args: AttestDomainInput, opts?: MCPCallOptions): Promise<MCPCallToolResult>;
+    getSideQuestGraph(args: GetSideQuestGraphInput, opts?: MCPCallOptions): Promise<MCPCallToolResult>;
+    queryGraphSimilarity(args: QueryGraphSimilarityInput, opts?: MCPCallOptions): Promise<MCPCallToolResult>;
+    /** Send a direct message to another tilde handle. */
+    messageSend(args: {
+        to: string;
+        body: string;
+        thread_id?: string;
+        in_reply_to?: string;
+    }): Promise<MCPCallToolResult>;
+    /** List inbound messages for the authenticated handle. */
+    messageInbox(args?: {
+        since?: string;
+        unread_only?: boolean;
+        limit?: number;
+        cursor?: string;
+    }): Promise<MCPCallToolResult>;
+    /** Bidirectional thread view between caller and a peer handle. */
+    messageThread(args: {
+        with: string;
+        limit?: number;
+    }): Promise<MCPCallToolResult>;
+    /** Mark inbound messages as read (recipient-only). */
+    messageMarkRead(args: {
+        message_ids: string[];
+    }): Promise<MCPCallToolResult>;
+    /** Soft-redact a single inbound message (recipient-only). */
+    messageRedact(args: {
+        message_id: string;
+    }): Promise<MCPCallToolResult>;
+    /** Grant a peer permission to send messages to your inbox. */
+    messageGrant(args: {
+        peer: string;
+    }): Promise<MCPCallToolResult>;
+    /** Revoke a peer's grant. In-flight messages are not redacted. */
+    messageRevoke(args: {
+        peer: string;
+    }): Promise<MCPCallToolResult>;
+    /**
+     * Verify the ES256 provenance attestation on a tool response.
+     * Accepts either a {@link ProvenanceEnvelope} or the raw `_meta`
+     * object — the latter is more convenient for ad-hoc verification.
+     */
+    verifyProvenance(envelope: ProvenanceEnvelope | {
+        provenance?: ProvenanceEnvelope;
+    } | undefined | null): Promise<ProvenanceVerification>;
+    /**
+     * Verify the schema hashes embedded in `tools/list._meta.signatures`
+     * against the local representation of each tool definition. Useful
+     * for guarding against in-flight tampering of tool schemas.
+     */
+    verifyToolSignatures(tools: SignedToolDefinition[], signatures: ToolSignatureMap): Promise<{
+        tool: string;
+        valid: boolean;
+        reason?: string;
+    }[]>;
+    /** Fetch the published JWKS for ALTER's signing key (cached 5 min). */
+    fetchPublicKeys(): Promise<unknown>;
+}
+
+interface McpServerConfig {
+    url: string;
+    transport: 'streamable-http';
+    headers?: Record<string, string>;
+    description?: string;
+}
+interface GenerateMcpConfigOptions {
+    /** Override the MCP endpoint. */
+    endpoint?: string;
+    /** Optional API key. Sent as `X-ALTER-API-Key`. */
+    apiKey?: string;
+    /** Identifier the host editor uses for this server. Default: `alter`. */
+    serverName?: string;
+    /** Extra headers to merge in. */
+    headers?: Record<string, string>;
+}
+interface GenericMcpConfig {
+    mcpServers: Record<string, McpServerConfig>;
+}
+/**
+ * Build a generic `mcpServers` config object that can be merged into any
+ * MCP-aware editor's settings file.
+ */
+declare function generateGenericMcpConfig(opts?: GenerateMcpConfigOptions): GenericMcpConfig;
+
+/**
+ * Claude Code MCP config helper.
+ *
+ * Claude Code reads MCP servers from `.mcp.json` (project) or
+ * `~/.claude/mcp.json` (user). The shape matches `mcpServers`.
+ */
+
+declare function generateClaudeConfig(opts?: GenerateMcpConfigOptions): GenericMcpConfig;
+
+/**
+ * Cursor MCP config helper.
+ *
+ * Cursor reads MCP servers from `.cursor/mcp.json`. Same shape as
+ * Claude Code's `.mcp.json`.
+ */
+
+declare function generateCursorConfig(opts?: GenerateMcpConfigOptions): GenericMcpConfig;
+
+/**
+ * @truealter/sdk — ALTER Identity SDK
+ *
+ * Query the continuous identity field from any JavaScript/TypeScript
+ * environment. Wraps the ALTER MCP server (29 invokable read tools at
+ * this stage). Write tools (submit_*, attest_domain, dispute_attestation,
+ * create_identity_stub) and alter-to-alter messaging tools are not
+ * advertised to public callers — they re-enable as the consent
+ * architecture and per-peer grant model land. First-class TypeScript
+ * types, x402 micropayment support, and ES256 provenance verification.
+ *
+ * The ALTER endpoint discovery anchor is `truealter.com` — see
+ * `discover()` for the cascade. The default MCP endpoint is
+ * `https://mcp.truealter.com`.
+ */
+
+declare const SDK_NAME = "@truealter/sdk";
+declare const SDK_VERSION = "0.1.1";
+
+export { AlterAuthError, AlterClient, type AlterClientOptions, AlterDiscoveryError, AlterError, type AlterErrorCode, AlterInvalidResponse, AlterNetworkError, AlterPaymentRequired, AlterProvenanceError, AlterRateLimited, AlterTimeoutError, AlterToolError, type ApiKeyConfig, type Archetype, type AssessTraitsInput, type AssessTraitsOutput, type AttestDomainInput, type AttestDomainOutput, type BeginGoldenThreadInput, type BeginGoldenThreadOutput, type CheckAssessmentStatusInput, type CheckAssessmentStatusOutput, type CheckGoldenThreadInput, type CheckGoldenThreadOutput, type CompleteKnotInput, type CompleteKnotOutput, type ComputeBelongingInput, type ComputeBelongingOutput, type CreateIdentityStubInput, type CreateIdentityStubOutput, DEFAULT_DOMAIN, DEFAULT_ENDPOINT, DEFAULT_VERIFY_AT_ALLOWLIST, type DiscoveryOptions, type DiscoveryResult, type DisputeAttestationInput, type DisputeAttestationOutput, type Ed25519Keypair, type EngagementLevel, FREE_TOOL_NAMES, type GenerateMatchNarrativeInput, type GenerateMatchNarrativeOutput, type GetAgentPortfolioInput, type GetAgentPortfolioOutput, type GetAgentTrustTierInput, type GetAgentTrustTierOutput, type GetCompetenciesInput, type GetCompetenciesOutput, type GetEarningSummaryInput, type GetEarningSummaryOutput, type GetEngagementLevelInput, type GetEngagementLevelOutput, type GetFullTraitVectorInput, type GetFullTraitVectorOutput, type GetIdentityEarningsInput, type GetIdentityEarningsOutput, type GetIdentityTrustScoreInput, type GetIdentityTrustScoreOutput, type GetMatchRecommendationsInput, type GetMatchRecommendationsOutput, type GetNetworkStatsInput, type GetNetworkStatsOutput, type GetPrivacyBudgetInput, type GetPrivacyBudgetOutput, type GetProfileInput, type GetProfileOutput, type GetSideQuestGraphInput, type GetSideQuestGraphOutput, type GetTraitSnapshotInput, type GetTraitSnapshotOutput, type GoldenThreadStatusInput, type GoldenThreadStatusOutput, type InitiateAssessmentInput, type InitiateAssessmentOutput, type JsonWebKey, type JwksDocument, type ListArchetypesInput, type ListArchetypesOutput, type MCPCallOptions, type MCPCallToolResult, MCPClient, type MCPClientInfo, type MCPClientOptions, type MCPContentBlock, type MCPListToolsResult, type MCPMeta, type MCPResponse, type MCPToolDefinition, MCP_PROTOCOL_VERSION, type MatchTier, type McpServerConfig, PREMIUM_TOOL_NAMES, type PaymentEnvelope, type ProvenanceEnvelope, type ProvenancePayload, type ProvenanceToken, type ProvenanceVerification, type QueryGraphSimilarityInput, type QueryGraphSimilarityOutput, type QueryMatchesInput, type QueryMatchesOutput, type RecommendToolInput, type RecommendToolOutput, type RespondToOfferingInput, type RespondToOfferingOutput, SDK_NAME, SDK_VERSION, type SearchIdentitiesInput, type SearchIdentitiesOutput, type SeatStatusInput, type SeatStatusOutput, type SignedToolDefinition, type SubmitBatchContextInput, type SubmitBatchContextOutput, type SubmitContextInput, type SubmitContextOutput, type SubmitSocialLinksInput, type SubmitSocialLinksOutput, type SubmitStructuredProfileInput, type SubmitStructuredProfileOutput, type SubscribeAnnouncementsInput, type SubscribeAnnouncementsOutput, TOOL_BLAST_RADIUS, TOOL_COSTS, TOOL_TIERS, type ThreadCensusInput, type ThreadCensusOutput, type ToolInputs, type ToolName, type ToolOutputs, type ToolSignatureMap, type VerifyIdentityInput, type VerifyIdentityOutput, type VerifyProvenanceOptions, X402Client, type X402ClientOptions, type X402Settlement, type X402Signer, base64urlDecode, base64urlEncode, clearDiscoveryCache, decodeDid, discover, encodeDid, fetchPublicKeys, generateClaudeConfig, generateCursorConfig, generateGenericMcpConfig, generateKeypair, keypairFromPrivateKey, parsePaymentHeader, resolveVerifyAt, sign, verify, verifyProvenance, verifyToolSignatures };