@chitmark/sdk 0.6.2 → 0.6.4

package/dist/trusted-ip-Ngrp6dUP.d.ts

@@ -0,0 +1,608 @@
+/**
+ * Shared API types for Chitmark by Open Agent Ledger.
+ * Aligns with openapi/openapi.yaml and SDK.md.
+ */
+/** Routing decision from verify. When degraded, this is always "challenge". */
+type Decision = "allow" | "challenge" | "deny";
+/** Classified actor behind the inbound action. */
+type ActorType = "human" | "agent_principal" | "agent_abusive" | "unknown";
+/** Whether a returned verdict is meant to gate traffic or only be observed. */
+type EnforcementMode = "enforce" | "log_only";
+/** Known action surfaces; custom strings are also accepted. */
+type Action = "signup" | "trial_activation" | "api_key" | "demo_request" | "quote" | "ticket" | "custom" | (string & {});
+/**
+ * Outcomes reported via feedback. Prefer fast labels first
+ * (`credit_burn`, `multi_account_cluster`, `abuse_confirmed`).
+ *
+ * `false_positive`: a previously attributed **abuse signal** on this
+ * `eventId` was reviewed and determined **not** to represent abuse
+ * (T&S clear / overturn). Conflicts with abuse-positive labels.
+ * Not "Chitmark challenged/denied a legitimate user" — that is
+ * `context.decisionCosts.falseChallenge` / `falseDeny` on verify.
+ */
+type Outcome = "credit_burn" | "multi_account_cluster" | "abuse_confirmed" | "converted" | "chargeback" | "churned" | "false_positive";
+/** Asymmetric-cost challenge methods (best → worst for anti-abuse).
+ * `payment_preauth` validates a payment-provider setup result; it does not
+ * transfer funds or authorize a purchase. */
+type ChallengeMethod = "payment_preauth" | "proof_of_work" | "device_attestation" | "web_bot_auth_stepup" | "email_otp";
+/** Client-side PII minimization mode. Default is hashed. Raw is opt-in only. */
+type PiiMode = "raw" | "hashed" | "none";
+/** Environment target; selects default base URL. */
+type ChitmarkEnv = "production" | "staging" | "development";
+/** On timeout/error, client decision fallback. NEVER "allow". */
+type OnDegraded = "challenge";
+/**
+ * Principal attribution on a Verdict: who is acting and on whose behalf.
+ *
+ * Not an authorization credential. `resolved === true` is **not** "this is
+ * a human", not an IdP login, and not permission to unlock an action. Gate
+ * on `decision` (plus `degraded` / `enforcementMode`).
+ *
+ * - `resolved`: usable principal signal present (today: verified Web Bot
+ *   Auth operator signature and/or enrichment known-good). Sparse/false for
+ *   farms and unsigned traffic.
+ * - `operator`: bot maker from Web Bot Auth Signature-Agent (e.g. "openai")
+ *   when the operator channel verified; does not by itself prove `onBehalfOf`.
+ * - `onBehalfOf`: principal the agent is acting for when known: organization
+ *   **or** end-user identifier, depending on what the signing/context path
+ *   supplies. Often absent at the wedge. Not sole authz.
+ * - `identityBasis`: signal sources that contributed (e.g. `web_bot_auth`,
+ *   `email_domain`, `enrichment`); mixed cryptographic and inferred strength.
+ */
+interface Principal {
+    resolved: boolean;
+    /** Bot maker from Web Bot Auth Signature-Agent (e.g. "openai"). */
+    operator?: string;
+    /**
+     * Principal the agent is acting for when known (org or end-user id).
+     * Often absent at the wedge; not sole authorization.
+     */
+    onBehalfOf?: string;
+    identityBasis: string[];
+}
+/** Verdict object: single source of truth for a verify call. */
+interface Verdict {
+    /** When degraded === true, this is ALWAYS "challenge", never "allow". */
+    decision: Decision;
+    actorType: ActorType;
+    /**
+     * Model confidence for the returned decision (0..1). Not a calibrated
+     * probability of abuse, and not the threshold `decisionCosts` moves. Gate
+     * on `decision` (plus degraded / enforcementMode); use for ops triage and
+     * dashboards, not as a substitute allow/deny cutoff.
+     */
+    confidence: number;
+    /**
+     * Human-readable signal strings for ops (always populated). Display copy
+     * today (`string[]`); do not scrape text as a stable machine API. A future
+     * additive revision may expose `{code, message, category}` while keeping
+     * a human-readable message for analytics without string scraping.
+     */
+    reasons: string[];
+    principal: Principal;
+    /** ES256 JWT decision receipt, bound to session.
+     * Under `enforcementMode: "log_only"` this is an observation receipt only:
+     * signature still verifies, but it does not authorize the action. */
+    verdictToken: string;
+    /** Store on the account row: feedback join key. */
+    eventId: string;
+    /** true → served under timeout/error → decision forced to challenge. */
+    degraded: boolean;
+    /** Server-computed mode. `log_only` → observe (token/decision non-authoritative for gating);
+     * `enforce` → partner may challenge / deny / allow. Not a JWT claim today. */
+    enforcementMode: EnforcementMode;
+    /**
+     * true → this verify honored `context.challengeId` for the session.
+     * Guaranteed only with `decision: "allow"` and `degraded: false` (clear
+     * short-circuits scoring). Under `log_only`, observation only.
+     */
+    challengeCleared?: boolean;
+}
+/** Subject signals for verify. Prefer hashed fields over raw PII. */
+interface Subject {
+    email?: string;
+    emailSha256?: string;
+    ip?: string;
+    ipTrunc?: string;
+    userAgent?: string;
+    /** Includes Web Bot Auth headers when present. */
+    headers?: Record<string, string | string[] | undefined>;
+    formData?: Record<string, unknown>;
+    formDataHashed?: Record<string, unknown>;
+}
+/**
+ * Relative, dimensionless weights for three error classes (not dollars and
+ * not score thresholds; only ratios matter). Repositions allow/challenge/deny
+ * boundaries for a single verify.
+ *
+ * - `falseAllow`: cost of allowing abusive traffic
+ * - `falseChallenge`: cost of challenging legitimate traffic when allow
+ *   would have been fine (a challenge can still be appropriate for
+ *   legitimate users; this names the over-friction case)
+ * - `falseDeny`: cost of denying legitimate traffic
+ *
+ * Higher `falseAllow` challenges earlier (abuse-averse); higher
+ * `falseChallenge` lets more of the gray zone through; higher `falseDeny`
+ * reserves deny for confirmed abuse. Defaults 1:1:3 keep fail-to-challenge
+ * semantics. Missing/non-positive fields fall back to their default.
+ */
+interface DecisionCosts {
+    falseAllow?: number;
+    falseChallenge?: number;
+    falseDeny?: number;
+}
+/** Per-request policy flags for POST /v1/verify. */
+interface VerifyContext {
+    /** Reference a challenge completed for this session; honored once. */
+    challengeId?: string;
+    /** "default" challenges the gray zone; "confirmed_tail_only" allows it in enforce mode. */
+    challengePolicy?: "default" | "confirmed_tail_only";
+    /** True → observation-only `log_only` verdict: nothing is blocked or challenged.
+     * Integration-side control only: set in your server code (or via env/key policy).
+     * Never derive from client-provided request data. */
+    logOnly?: boolean;
+    /** Relative dimensionless weights (falseAllow / falseChallenge / falseDeny); defaults 1:1:3. */
+    decisionCosts?: DecisionCosts;
+    /** Partner-specific flags (e.g. plan, referrer), carried, not scored. */
+    [key: string]: unknown;
+}
+/** Request body for POST /v1/verify. */
+interface VerifyRequest {
+    idempotencyKey?: string;
+    action: Action;
+    /** Binding id you supply for this action attempt. Prefer high-entropy,
+     * server-generated ids; binds challenge and verdictToken (`sub`). */
+    session?: string;
+    surface?: string;
+    subject: Subject;
+    context?: VerifyContext;
+}
+/**
+ * Scale for feedback `value`. Allowlist only (not free-form currency codes).
+ * Values in different units are not converted or comparable. Ledger dollar
+ * totals sum `credit_burn` only when `unit` is `"usd"`.
+ */
+type FeedbackUnit = "usd" | "credits" | "count";
+/**
+ * Provenance of a feedback label: why you trusted this outcome.
+ * `eventId` + `outcome` say what was learned; `source` says where it came from.
+ */
+type FeedbackSource = "billing" | "usage_metering" | "trust_queue" | "manual_review" | "customer_system" | "automated_detector";
+/** Request body for POST /v1/feedback. */
+interface FeedbackRequest {
+    /**
+     * Join key from a prior verify. Feedback cannot create attribution:
+     * unknown/cross-tenant ids return 404. Never invent a join from email/IP.
+     */
+    eventId: string;
+    outcome: Outcome;
+    /**
+     * Measured economic magnitude for this outcome, expressed in `unit`.
+     * Optional. Not intrinsically dollars: pair with `unit` (`usd` |
+     * `credits` | `count`). Different units are not comparable.
+     * For `converted`, when set: realized first-year ARR at conversion
+     * (not expected ARR, multi-year TCV, or LTV).
+     */
+    value?: number;
+    /** Scale for `value`. Default `usd` when `value` is set. Requires `value`. */
+    unit?: FeedbackUnit;
+    /**
+     * Provenance of the label. Optional. Included in warehouse identity when
+     * set (two sources with otherwise identical bodies are separate observations).
+     */
+    source?: FeedbackSource;
+    observedAt?: string;
+    /** Body form of Idempotency-Key; header takes precedence. */
+    idempotencyKey?: string;
+}
+/** Response from POST /v1/feedback. */
+interface FeedbackResponse {
+    ok: true;
+    eventId: string;
+}
+/**
+ * Scales the proof-of-work difficulty issued with a challenge so the
+ * challenge's economic tax rises with risk. Absent → "default".
+ * Monotonicity: riskTier ↑ ⇒ challenge cost never ↓
+ * (default → D, elevated → ≥ D, severe → ≥ elevated). Issued difficulty is
+ * sealed at issue and never re-derived from a later tier on complete.
+ */
+type ChallengeRiskTier = "default" | "elevated" | "severe";
+/** Request body for POST /v1/challenge: issue or complete. */
+interface ChallengeRequest {
+    /** eventId from the verify verdict that routed to challenge. */
+    eventId: string;
+    /** Binding id you supply for one action attempt. Prefer high-entropy,
+     * server-generated ids. Required for issue and completion (max 128 chars). */
+    session: string;
+    /**
+     * Ordered method hints, not guarantees. First issuable method wins;
+     * unsupported entries are skipped. Floor is proof_of_work; never email_otp.
+     */
+    prefer?: ChallengeMethod[];
+    /** Completion mode: the challenge being solved. */
+    challengeId?: string;
+    /** Completion mode: server-verified proof bound to challengeId + session. */
+    proof?: ChallengeProof;
+    /**
+     * Issue-mode context. `riskTier` scales issued PoW difficulty monotonically
+     * (higher tier ⇒ cost never lower). Difficulty is sealed at issue;
+     * completion validates that value only.
+     */
+    context?: {
+        riskTier?: ChallengeRiskTier;
+    };
+}
+/** Server-verified completion proof. */
+type ChallengeProof = {
+    type: "proof_of_work";
+    /** First nonce where sha256(`${challengeId}:${seed}:${nonce}`) hex starts with `difficulty` zero nibbles. */
+    nonce: string;
+} | {
+    type: "stripe_setup_intent";
+    /** SetupIntent id from issued instructions; provider status must be succeeded. Validates result only: no charge, no purchase auth. */
+    setupIntentId: string;
+};
+/** Response from POST /v1/challenge (issue mode). */
+interface ChallengeResponse {
+    challengeId: string;
+    method: ChallengeMethod;
+    instructions: {
+        type: "pow";
+        /** Leading zero nibbles required. Sealed at issue; completion validates this value. */
+        difficulty: number;
+        /** Combine as `${challengeId}:${seed}:${nonce}`. */
+        seed: string;
+        /** Only supported PoW algorithm today. */
+        algorithm: "sha256-prefix";
+    } | {
+        type: "stripe_setup_intent";
+        /** test = real Stripe test-mode; stub = deterministic local/CI id. */
+        mode: "test" | "stub";
+        clientSecret: string;
+        publishableKey?: string;
+    };
+    /** Solving only clears THIS session (anti-replay). Never a global identity/account/IP/device clear. */
+    boundTo: string;
+    expiresAt: string;
+}
+/** Response from POST /v1/challenge (completion mode).
+ * Session-state change only: does not authorize the action. Re-verify with
+ * `context.challengeId` and proceed only on non-degraded allow. */
+interface ChallengeCompletionResponse {
+    /** Friction satisfied for boundTo; not permission to continue without re-verify. */
+    ok: true;
+    challengeId: string;
+    /** Session that was cleared (single use). Never a global identity/account/IP/device clear. */
+    boundTo: string;
+    clearedAt: string;
+}
+/** Client constructor options. */
+interface ChitmarkOptions {
+    /** API key (Bearer). Use process.env.CHITMARK_API_KEY. */
+    apiKey: string;
+    /**
+     * Timeout/error behavior. Fixed to "challenge": never allow silent bypass.
+     * @default "challenge"
+     */
+    onDegraded?: OnDegraded;
+    /**
+     * Client-side request budget in ms. Edge path is far faster.
+     * @default 800
+     */
+    timeoutMs?: number;
+    /**
+     * Client-side PII minimization before send.
+     * @default "hashed"
+     */
+    piiMode?: PiiMode;
+    /**
+     * Selects default base URL unless baseUrl or CHITMARK_BASE_URL is set.
+     * @default "production"
+     */
+    env?: ChitmarkEnv;
+    /**
+     * Override API host (e.g. local edge). Precedence:
+     * baseUrl > CHITMARK_BASE_URL env > env default.
+     */
+    baseUrl?: string;
+    /** Custom fetch implementation (Workers, tests). */
+    fetch?: typeof fetch;
+    /** User-Agent / client identification sent as X-Chitmark-Client. */
+    clientName?: string;
+}
+interface ChitmarkErrorBody {
+    error: string;
+    message?: string;
+    code?: string;
+}
+
+/**
+ * Base error for all Chitmark client failures.
+ */
+declare class ChitmarkError extends Error {
+    name: string;
+    readonly status?: number;
+    readonly code?: string;
+    readonly body?: ChitmarkErrorBody | string;
+    constructor(message: string, options?: {
+        status?: number;
+        code?: string;
+        body?: ChitmarkErrorBody | string;
+    });
+}
+/**
+ * Raised when the API returns a non-2xx response.
+ */
+declare class ChitmarkApiError extends ChitmarkError {
+    name: string;
+    constructor(status: number, body: ChitmarkErrorBody | string, message?: string);
+}
+/**
+ * Build the degraded challenge verdict used on timeout / transport failure.
+ * Golden rule: fail to challenge, never to allow.
+ */
+declare function degradedChallengeVerdict(reason: string, session?: string): Verdict;
+/**
+ * Ensure degraded responses never surface as allow (defense in depth client-side).
+ */
+declare function enforceDegradedNeverAllow(verdict: Verdict): Verdict;
+
+/**
+ * Client-side verdictToken verification.
+ *
+ * A verdictToken is an ES256 JWT decision receipt minted by the edge and bound
+ * to session (`sub`), origin hint (`aud`), issuing tenant (`tid`), and a unique
+ * `jti` (correlation id) with a short `exp` (5 minutes). Every signed token
+ * requires a `kid` in the JWT header. Signature verification proves
+ * authenticity and integrity; it does not make the JWT single-use. This module
+ * always enforces `session` and `tenantId` (security boundary), validates
+ * `iss` against the Chitmark issuer, and optionally `aud`. `aud` reflects
+ * request headers and is attacker influenced: never enforce `aud` alone.
+ * Rejection reasons are surfaced as `VerdictTokenError.code`.
+ *
+ * JWKS: respect `Cache-Control` and, when present, `ETag` /
+ * `Last-Modified` via conditional requests (instead of a hard-coded
+ * refresh interval). Refresh immediately on unknown `kid`. Do not fetch on
+ * every verification; never permanently pin a single signing key. Each JWKS
+ * key is EC P-256 for ES256: require JWT `alg === "ES256"` before verifying
+ * (`wrong_algorithm` otherwise); never trust the token-requested algorithm.
+ * Rotation overlaps old and new keys; keep the retiring key until tokens under it
+ * expire (≥ 5 minutes + 60 seconds). Pass a cached `jwks` option to skip
+ * the network call. An empty JWKS (`keys: []`) means no token can be
+ * cryptographically verified: fail closed; never treat an empty set as
+ * evidence that a token is valid (local/CI may emit `unsigned.<eventId>`).
+ */
+
+/** Canonical issuer claim on every signed verdictToken. */
+declare const VERDICT_TOKEN_ISSUER = "https://api.chitmark.com";
+interface VerdictTokenClaims {
+    /** Issuer: https://api.chitmark.com. */
+    iss: string;
+    eventId: string;
+    decision: Decision;
+    actorType: ActorType;
+    confidence: number;
+    aud: string;
+    sub: string;
+    /** Issuing tenant, server-derived from the API key used at verify time. */
+    tid: string;
+    /** Unique token identifier (correlation). Not single-use unless you track it. */
+    jti: string;
+    iat: number;
+    exp: number;
+    degraded: boolean;
+}
+type VerdictTokenErrorCode = "malformed_token" | "wrong_algorithm" | "wrong_type" | "jwks_unavailable" | "unknown_kid" | "invalid_signature" | "expired" | "not_yet_valid" | "wrong_issuer" | "wrong_session" | "wrong_aud" | "wrong_tenant";
+declare class VerdictTokenError extends ChitmarkError {
+    name: string;
+    constructor(code: VerdictTokenErrorCode, message: string);
+}
+interface VerifyVerdictTokenOptions {
+    /** Expected session: token `sub` must equal this or verification fails. */
+    session: string;
+    /** Expected issuing tenant: token `tid` must equal this or verification fails. */
+    tenantId: string;
+    /** Expected origin hint: token `aud` must equal this or verification fails. */
+    aud?: string;
+    /**
+     * Expected issuer (`iss`). Defaults to {@link VERDICT_TOKEN_ISSUER}.
+     * Override only in tests.
+     */
+    issuer?: string;
+    /** JWKS URL; defaults to https://api.chitmark.com/.well-known/jwks.json. */
+    jwksUrl?: string;
+    /**
+     * Pre-fetched / cached JWKS; skips the network fetch when provided.
+     * Prefer caching via HTTP headers (`Cache-Control`, `ETag`, and
+     * `Last-Modified` when present) with conditional refresh and immediate
+     * refresh on unknown `kid`, rather than fetching on every verification.
+     */
+    jwks?: {
+        keys: Array<Record<string, unknown>>;
+    };
+    /** Injectable fetch (Node 24+/browsers have a global). */
+    fetch?: typeof fetch;
+    /** Clock override for tests. */
+    nowMs?: number;
+    /** Clock skew tolerance in seconds; defaults to 30. */
+    leewaySeconds?: number;
+}
+/**
+ * Verify a verdictToken signature and binding.
+ *
+ * `session` and `tenantId` are required: they are the security boundary for
+ * cross-service authorization, not optional hints.
+ */
+declare function verifyVerdictToken(token: string, options: VerifyVerdictTokenOptions): Promise<VerdictTokenClaims>;
+
+/**
+ * Official Chitmark client (Open Agent Ledger): three verbs:
+ * verify, feedback, challenge. Trust decisions on agent-mediated actions,
+ * tuned by business outcomes.
+ *
+ * @example
+ * ```ts
+ * const chitmark = new Chitmark({ apiKey: process.env.CHITMARK_API_KEY! });
+ * const verdict = await chitmark.verify({
+ *   action: "signup",
+ *   subject: { email, ip, userAgent },
+ * });
+ * ```
+ */
+declare class Chitmark {
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly timeoutMs;
+    private readonly piiMode;
+    private readonly onDegraded;
+    private readonly fetchImpl;
+    private readonly clientName;
+    constructor(options: ChitmarkOptions);
+    /**
+     * Score + route an inbound action (signup / trial / …).
+     * Client budget defaults to 800ms (2000ms for local base URLs).
+     *
+     * Store-outage degradation arrives as **HTTP 200** with a Verdict body
+     * (`degraded: true`, `decision: "challenge"`). The SDK deserializes that
+     * like any other Verdict. Verify never returns HTTP 503.
+     *
+     * HTTP 4xx / 429 Error responses throw `ChitmarkApiError`. Transport
+     * timeout / network failure (or a malformed 200 body) synthesizes a local
+     * degraded challenge Verdict (never allow, never crashes).
+     *
+     * Persist `v.eventId` on the account row: feedback joins only on that id.
+     */
+    verify(request: VerifyRequest): Promise<Verdict>;
+    /**
+     * Report a downstream outcome joined on the stored eventId from verify.
+     *
+     * Security invariant: feedback cannot create attribution. It only attaches
+     * an outcome to an existing verify event for this tenant. Unknown or
+     * cross-tenant eventIds return 404. Never invent a join from email/IP.
+     *
+     * Append-only (not latest-wins): multiple outcomes may attach to one
+     * eventId. Exact duplicates share one feedbackId. Compatible labels
+     * coexist; conflicting pairs quarantine the new observation without
+     * deleting prior evidence. HTTP `{ ok: true }` still acknowledges
+     * quarantined ingest.
+     *
+     * `idempotencyKey` is sent as both the Idempotency-Key header and body field
+     * (header takes precedence server-side) so exact retries replay the original
+     * acknowledgement.
+     */
+    feedback(request: FeedbackRequest): Promise<FeedbackResponse>;
+    /**
+     * Issue an asymmetric-cost challenge after decision === challenge | degraded.
+     */
+    challenge(request: ChallengeRequest): Promise<ChallengeResponse>;
+    /**
+     * Complete a challenge by submitting its solved proof. Clears only the bound
+     * session, once. Does not authorize the action: re-verify with
+     * `context.challengeId` and proceed only on non-degraded allow.
+     */
+    completeChallenge(request: {
+        eventId: string;
+        challengeId: string;
+        session: string;
+        proof: ChallengeProof;
+    }): Promise<ChallengeCompletionResponse>;
+    /**
+     * Verify a verdictToken's signature against the API's JWKS and its session /
+     * tenant binding. Prefers a cached `jwks` (refresh periodically and on
+     * unknown `kid`); do not fetch on every call. Rejects expired tokens,
+     * unknown kids, and invalid signatures with `VerdictTokenError`. Always
+     * pass `session` and `tenantId` (required security boundary); `aud`
+     * optionally enforces the origin hint only.
+     */
+    verifyVerdictToken(token: string, options: Omit<VerifyVerdictTokenOptions, "jwksUrl" | "fetch">): Promise<VerdictTokenClaims>;
+    /**
+     * Low-level HTTP helper. Prefer verify / feedback / challenge.
+     */
+    request<T>(path: string, init: {
+        method: string;
+        body?: unknown;
+        idempotencyKey?: string;
+    }): Promise<T>;
+    /** Public accessors for inspection / tests. */
+    get config(): {
+        baseUrl: string;
+        timeoutMs: number;
+        piiMode: PiiMode;
+        onDegraded: OnDegraded;
+    };
+}
+
+/**
+ * Client-side PII minimization helpers.
+ * Default SDK mode hashes email and truncates IP before leaving the customer process.
+ */
+/**
+ * SHA-256 hex digest of lowercased, trimmed email.
+ * Uses Web Crypto (Node 18+, browsers, Workers).
+ */
+declare function hashEmailSha256(email: string): Promise<string>;
+/**
+ * Truncate IPv4 to /24 or IPv6 to /48 for coarse geo without host identity.
+ */
+declare function truncateIp(ip: string): string;
+/**
+ * Reduce form payload to non-PII keys (domain-style fields only for hashed mode).
+ * Free-text is dropped; companyDomain-style keys are kept as-is when domain-like.
+ */
+declare function minimizeFormData(formData: Record<string, unknown> | undefined): Record<string, unknown> | undefined;
+
+declare const CHITMARK_HTTP_STATUS: {
+    readonly ok: 200;
+    readonly created: 201;
+    readonly badRequest: 400;
+    readonly unauthorized: 401;
+    readonly forbidden: 403;
+    readonly notFound: 404;
+    readonly conflict: 409;
+    readonly preconditionRequired: 428;
+    readonly tooManyRequests: 429;
+};
+type ChitmarkHttpStatus = (typeof CHITMARK_HTTP_STATUS)[keyof typeof CHITMARK_HTTP_STATUS];
+declare const CHITMARK_HTTP_STATUS_MEANING: {
+    readonly ok: "Request succeeded. For verify gates, continue only after an explicit non-degraded allow.";
+    readonly created: "Resource was created after an explicit non-degraded allow.";
+    readonly badRequest: "Required request fields are missing or malformed.";
+    readonly unauthorized: "API key is missing or invalid.";
+    readonly forbidden: "Verify returned deny; block the action.";
+    readonly notFound: "Referenced Chitmark resource was not found.";
+    readonly conflict: "Idempotency key is already associated with a different payload fingerprint.";
+    readonly preconditionRequired: "428 means the request is not rejected permanently; a required verification precondition must be satisfied before the action can proceed.";
+    readonly tooManyRequests: "Request was rate limited.";
+};
+/**
+ * Explicit non-degraded allow. Use this (or `isEligibleAllow`) before any
+ * protected action so unknown / malformed decisions cannot fall through.
+ */
+type EligibleAllowVerdict = Verdict & {
+    decision: "allow";
+    degraded: false;
+};
+/**
+ * Type guard for the only verdict that may continue a gated action.
+ * Fail closed: anything that is not an explicit non-degraded allow is ineligible.
+ */
+declare function isEligibleAllow(verdict: Verdict): verdict is EligibleAllowVerdict;
+/**
+ * Map a verify verdict to an HTTP status for framework drop-ins.
+ * Unknown or malformed decisions fail to challenge (428), never to allow (200).
+ */
+declare function verdictToHttpStatus(verdict: Verdict): ChitmarkHttpStatus;
+
+/**
+ * Resolve a client IP for verify subject signals from a Fetch Request.
+ *
+ * Prefer platform-set headers (`cf-connecting-ip`, `x-real-ip`,
+ * `x-vercel-forwarded-for`). `X-Forwarded-For` is only safe when a trusted
+ * proxy boundary strips or rewrites client-supplied values. Do not read XFF
+ * on a directly reachable origin. On Cloudflare Workers, prefer
+ * `verifyRequest` from `@chitmark/sdk/edge`, which owns this lookup.
+ */
+declare function getTrustedClientIp(req: Request): string;
+
+export { type Action as A, VerdictTokenError as B, Chitmark as C, type Decision as D, type EligibleAllowVerdict as E, type FeedbackRequest as F, type VerdictTokenErrorCode as G, type VerifyVerdictTokenOptions as H, degradedChallengeVerdict as I, enforceDegradedNeverAllow as J, getTrustedClientIp as K, hashEmailSha256 as L, isEligibleAllow as M, minimizeFormData as N, type OnDegraded as O, type PiiMode as P, truncateIp as Q, verdictToHttpStatus as R, type Subject as S, verifyVerdictToken as T, type VerifyContext as V, type VerifyRequest as a, type Verdict as b, type ActorType as c, CHITMARK_HTTP_STATUS as d, CHITMARK_HTTP_STATUS_MEANING as e, type ChallengeCompletionResponse as f, type ChallengeMethod as g, type ChallengeProof as h, type ChallengeRequest as i, type ChallengeResponse as j, type ChallengeRiskTier as k, ChitmarkApiError as l, type ChitmarkEnv as m, ChitmarkError as n, type ChitmarkErrorBody as o, type ChitmarkHttpStatus as p, type ChitmarkOptions as q, type DecisionCosts as r, type EnforcementMode as s, type FeedbackResponse as t, type FeedbackSource as u, type FeedbackUnit as v, type Outcome as w, type Principal as x, VERDICT_TOKEN_ISSUER as y, type VerdictTokenClaims as z };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chitmark/sdk",
-  "version": "0.6.2",
+  "version": "0.6.4",
   "description": "Official TypeScript SDK for Chitmark by Open Agent Ledger: trust decisions on agent-mediated actions (verify, feedback, challenge)",
   "license": "SEE LICENSE IN LICENSE",
   "author": "Open Agent Ledger",