@chitmark/sdk 0.1.0

package/dist/http-status-CwxMw-nO.d.cts

@@ -0,0 +1,384 @@
+/**
+ * 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>;
+}
+/** 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?: Record<string, unknown>;
+}
+/** 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;
+}
+/** Response from POST /v1/feedback. */
+interface FeedbackResponse {
+    ok: true;
+    eventId: string;
+}
+/** Request body for POST /v1/challenge — issue or complete. */
+interface ChallengeRequest {
+    /** eventId from the verify verdict that routed to challenge. */
+    eventId: string;
+    /** Binds the challenge to this session; completion and re-verify must match. */
+    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;
+}
+/** 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 (MVP-016).
+ *
+ * A verdictToken is an ES256 JWT decision receipt minted by the edge and bound
+ * to session (`sub`), origin (`aud`), 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 an expected
+ * audience is supplied — origin binding. Rejection reasons are surfaced as
+ * `VerdictTokenError.code`.
+ */
+
+interface VerdictTokenClaims {
+    eventId: string;
+    decision: Decision;
+    actorType: ActorType;
+    confidence: number;
+    aud: string;
+    sub: string;
+    jti: string;
+    iat: number;
+    exp: number;
+    degraded: boolean;
+}
+type VerdictTokenErrorCode = "malformed_token" | "wrong_algorithm" | "jwks_unavailable" | "unknown_kid" | "invalid_signature" | "expired" | "not_yet_valid" | "wrong_session" | "wrong_aud";
+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 origin — 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.
+     */
+    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 /
+     * origin binding (MVP-016). Rejects expired tokens, unknown kids, and
+     * invalid signatures with `VerdictTokenError`. Pass `session` to enforce
+     * session binding (recommended) and `aud` to enforce origin binding.
+     */
+    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, truncateIp as B, Chitmark as C, type Decision as D, type EnforcementMode as E, type FeedbackRequest as F, verdictToHttpStatus as G, verifyVerdictToken as H, type OnDegraded as O, type PiiMode as P, type Subject as S, type VerifyRequest as V, type Verdict as a, type ActorType as b, CHITMARK_HTTP_STATUS as c, CHITMARK_HTTP_STATUS_MEANING as d, type ChallengeCompletionResponse as e, type ChallengeMethod as f, type ChallengeProof as g, type ChallengeRequest as h, type ChallengeResponse as i, ChitmarkApiError as j, type ChitmarkEnv as k, ChitmarkError as l, type ChitmarkErrorBody as m, type ChitmarkHttpStatus as n, type ChitmarkOptions as o, type FeedbackResponse as p, type Outcome as q, type Principal as r, type VerdictTokenClaims as s, VerdictTokenError as t, type VerdictTokenErrorCode as u, type VerifyVerdictTokenOptions as v, degradedChallengeVerdict as w, enforceDegradedNeverAllow as x, hashEmailSha256 as y, minimizeFormData as z };