@chitmark/sdk 0.6.2 → 0.6.3

package/dist/http-status-BHYL507g.d.cts

@@ -1,435 +0,0 @@
-/**
- * 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: the data moat. Prefer fast labels first. */
-type Outcome = "credit_burn" | "multi_account_cluster" | "abuse_confirmed" | "converted" | "chargeback" | "churned" | "false_positive";
-/** Asymmetric-cost challenge methods (best → worst for anti-abuse). */
-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 resolution: mostly populated for good signed agents;
- * sparse for farmers.
- */
-interface Principal {
-    resolved: boolean;
-    /** Bot maker from Web Bot Auth Signature-Agent (e.g. "openai"). */
-    operator?: string;
-    /** End-user principal ("on whose behalf"); often null at the wedge. */
-    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;
-    /** 0..1 */
-    confidence: number;
-    /** Human-readable; always populated for ops teams. */
-    reasons: string[];
-    principal: Principal;
-    /** ES256 JWT decision receipt, bound to session. */
-    verdictToken: string;
-    /** Store on the account row: feedback join key. */
-    eventId: string;
-    /** true → served under timeout/error → decision forced to challenge. */
-    degraded: boolean;
-    /** log_only verdicts are for dashboards/observation, not partner-side blocking. */
-    enforcementMode: EnforcementMode;
-    /** true → this allow honors a challenge completed for the session (context.challengeId). */
-    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>;
-}
-/**
- * Cost ratio that repositions the allow/challenge/deny boundaries for a
- * single verify. 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 the
- * 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. */
-    logOnly?: boolean;
-    /** Reposition the allow/challenge/deny boundaries (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;
-    /** Binds any resulting challenge + verdictToken to THIS session. */
-    session?: string;
-    surface?: string;
-    subject: Subject;
-    context?: VerifyContext;
-}
-/** Request body for POST /v1/feedback. */
-interface FeedbackRequest {
-    eventId: string;
-    outcome: Outcome;
-    /** $ of infra/credit burned, or ARR: units in `unit`. */
-    value?: number;
-    unit?: string;
-    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".
- */
-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;
-    /** Uniquely represents one action attempt. Required for issue and completion. */
-    session: string;
-    /** Ranked method preference, best → worst. Never defaults to 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 the issued proof-of-work difficulty
-     * so the challenge's economic tax rises with risk; completion is always
-     * validated against the difficulty that was issued.
-     */
-    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 the issued instructions; status must be succeeded. */
-    setupIntentId: string;
-};
-/** Response from POST /v1/challenge (issue mode). */
-interface ChallengeResponse {
-    challengeId: string;
-    method: ChallengeMethod;
-    instructions: {
-        type: "pow";
-        /** Leading zero nibbles required in the sha256 hex digest. */
-        difficulty: number;
-        /** Combine as `${challengeId}:${seed}:${nonce}`. */
-        seed: string;
-        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). */
-    boundTo: string;
-    expiresAt: string;
-}
-/** Response from POST /v1/challenge (completion mode). */
-interface ChallengeCompletionResponse {
-    ok: true;
-    challengeId: string;
-    /** Session that was cleared (single use, anti-replay). */
-    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 `jti`
- * with a short `exp`. This module validates shape, signature (against the JWKS
- * served from GET /.well-known/jwks.json), expiry, session binding, and, when
- * expected values are supplied, tenant and origin binding. `aud` reflects
- * request headers and is attacker influenced: always verify `session` and
- * `tenantId`, never `aud` alone. Rejection reasons are surfaced as
- * `VerdictTokenError.code`.
- */
-
-interface VerdictTokenClaims {
-    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;
-    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_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;
-    /** JWKS URL; defaults to https://api.chitmark.com/.well-known/jwks.json. */
-    jwksUrl?: string;
-    /** Pre-fetched JWKS; skips the network fetch when provided. */
-    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;
-}
-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 / …).
-     * Hot path at the edge; client budget defaults to 800ms.
-     * On timeout/transport error, or a malformed verdict shape from the API,
-     * returns a 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.
-     * This is the data moat: attribution is a schema contract, not a fuzzy match.
-     * `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. Re-verify with `context.challengeId` to have the next
-     * verify honor the cleared session.
-     */
-    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. Rejects expired tokens, unknown kids, and
-     * invalid signatures with `VerdictTokenError`. Pass `session` and `tenantId`
-     * to enforce session and tenant binding (recommended); `aud` 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 was reused with a materially different payload.";
-    readonly preconditionRequired: "Verify returned challenge or degraded; require friction before continuing.";
-    readonly tooManyRequests: "Request was rate limited.";
-};
-declare function verdictToHttpStatus(verdict: Verdict): ChitmarkHttpStatus;
-
-export { type Action as A, enforceDegradedNeverAllow as B, Chitmark as C, type Decision as D, type EnforcementMode as E, type FeedbackRequest as F, hashEmailSha256 as G, minimizeFormData as H, truncateIp as I, verdictToHttpStatus as J, verifyVerdictToken as K, type OnDegraded as O, type PiiMode as P, type Subject as S, 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 FeedbackResponse as s, type Outcome as t, type Principal as u, type VerdictTokenClaims as v, VerdictTokenError as w, type VerdictTokenErrorCode as x, type VerifyVerdictTokenOptions as y, degradedChallengeVerdict as z };