@chitmark/sdk 0.1.0

package/dist/index.cjs

@@ -0,0 +1,601 @@
+'use strict';
+
+// src/errors.ts
+var ChitmarkError = class extends Error {
+  name = "ChitmarkError";
+  status;
+  code;
+  body;
+  constructor(message, options) {
+    super(message);
+    this.status = options?.status;
+    this.code = options?.code;
+    this.body = options?.body;
+  }
+};
+var ChitmarkApiError = class extends ChitmarkError {
+  name = "ChitmarkApiError";
+  constructor(status, body, message) {
+    const msg = message ?? (typeof body === "string" ? body : body.message || body.error || `Chitmark API error (${status})`);
+    super(msg, {
+      status,
+      code: typeof body === "object" ? body.code ?? body.error : void 0,
+      body
+    });
+  }
+};
+function degradedChallengeVerdict(reason, session) {
+  return {
+    decision: "challenge",
+    actorType: "unknown",
+    confidence: 0,
+    reasons: [reason],
+    principal: {
+      resolved: false,
+      identityBasis: ["degraded"]
+    },
+    verdictToken: "",
+    eventId: `evt_degraded_${session ?? "unknown"}`,
+    degraded: true,
+    enforcementMode: "enforce"
+  };
+}
+function enforceDegradedNeverAllow(verdict) {
+  if (verdict.degraded && verdict.decision === "allow") {
+    return {
+      ...verdict,
+      decision: "challenge",
+      reasons: [
+        ...verdict.reasons,
+        "Client enforced: degraded decision must not be allow"
+      ]
+    };
+  }
+  return verdict;
+}
+
+// src/internal/constants.ts
+var DEFAULT_BASE_URLS = {
+  production: "https://api.chitmark.com",
+  staging: "https://api.staging.chitmark.com",
+  development: "http://127.0.0.1:8787"
+};
+var DEFAULT_TIMEOUT_MS = 800;
+var SDK_VERSION = "0.1.0";
+function resolveBaseUrl(env = "production", baseUrl) {
+  return (baseUrl ?? DEFAULT_BASE_URLS[env]).replace(/\/$/, "");
+}
+function envBaseUrl() {
+  if (typeof process === "undefined") return void 0;
+  const value = process.env?.CHITMARK_BASE_URL;
+  return value ? value.trim() : void 0;
+}
+
+// src/pii.ts
+async function hashEmailSha256(email) {
+  const normalized = email.trim().toLowerCase();
+  const data = new TextEncoder().encode(normalized);
+  const digest = await crypto.subtle.digest("SHA-256", data);
+  return bufferToHex(digest);
+}
+function truncateIp(ip) {
+  const trimmed = ip.trim();
+  const first = trimmed.split(",")[0]?.trim() ?? trimmed;
+  if (first.includes(".") && !first.includes(":")) {
+    const parts = first.split(".");
+    if (parts.length === 4) {
+      return `${parts[0]}.${parts[1]}.${parts[2]}.0/24`;
+    }
+  }
+  if (first.includes(":")) {
+    const hextets = first.split(":").filter(Boolean);
+    const head = hextets.slice(0, 3).join(":");
+    return `${head}::/48`;
+  }
+  return first;
+}
+function minimizeFormData(formData) {
+  if (!formData) return void 0;
+  const allowed = /* @__PURE__ */ new Set([
+    "companyDomain",
+    "company_domain",
+    "domain",
+    "plan",
+    "referrer",
+    "utm_source",
+    "utm_medium",
+    "utm_campaign"
+  ]);
+  const out = {};
+  for (const [key, value] of Object.entries(formData)) {
+    if (allowed.has(key) && value != null) {
+      out[key] = value;
+    }
+  }
+  return Object.keys(out).length > 0 ? out : void 0;
+}
+function bufferToHex(buffer) {
+  const bytes = new Uint8Array(buffer);
+  let hex = "";
+  for (const b of bytes) {
+    hex += b.toString(16).padStart(2, "0");
+  }
+  return hex;
+}
+
+// src/internal/prepare.ts
+async function prepareSubject(subject, piiMode) {
+  if (piiMode === "raw") {
+    return subject;
+  }
+  if (piiMode === "none") {
+    return {
+      userAgent: subject.userAgent,
+      headers: pickWebBotAuthHeaders(subject.headers)
+    };
+  }
+  const prepared = {
+    userAgent: subject.userAgent,
+    headers: subject.headers
+  };
+  if (subject.emailSha256) {
+    prepared.emailSha256 = subject.emailSha256;
+  } else if (subject.email) {
+    prepared.emailSha256 = await hashEmailSha256(subject.email);
+  }
+  if (subject.ipTrunc) {
+    prepared.ipTrunc = subject.ipTrunc;
+  } else if (subject.ip) {
+    prepared.ipTrunc = truncateIp(subject.ip);
+  }
+  const hashedForm = subject.formDataHashed ?? minimizeFormData(subject.formData);
+  if (hashedForm) {
+    prepared.formDataHashed = hashedForm;
+  }
+  return prepared;
+}
+function pickWebBotAuthHeaders(headers) {
+  if (!headers) return void 0;
+  const keys = ["signature-agent", "signature-input", "signature", "signature-agent"];
+  const out = {};
+  for (const [k, v] of Object.entries(headers)) {
+    const lower = k.toLowerCase();
+    if (keys.includes(lower) && typeof v === "string") {
+      out[lower] = v;
+    } else if (keys.includes(lower) && Array.isArray(v) && v[0]) {
+      out[lower] = v[0];
+    }
+  }
+  return Object.keys(out).length > 0 ? out : void 0;
+}
+function flattenHeaders(headers) {
+  if (!headers) return void 0;
+  if (headers instanceof Headers) {
+    const out2 = {};
+    headers.forEach((value, key) => {
+      out2[key.toLowerCase()] = value;
+    });
+    return out2;
+  }
+  const out = {};
+  for (const [k, v] of Object.entries(headers)) {
+    if (typeof v === "string") out[k.toLowerCase()] = v;
+    else if (Array.isArray(v) && v[0]) out[k.toLowerCase()] = v[0];
+  }
+  return out;
+}
+
+// src/verify-token.ts
+var VerdictTokenError = class extends ChitmarkError {
+  name = "VerdictTokenError";
+  constructor(code, message) {
+    super(message, { code });
+  }
+};
+var DEFAULT_JWKS_URL = "https://api.chitmark.com/.well-known/jwks.json";
+var DEFAULT_LEEWAY_SECONDS = 30;
+async function verifyVerdictToken(token, options = {}) {
+  const nowMs = options.nowMs ?? Date.now();
+  const leewaySeconds = options.leewaySeconds ?? DEFAULT_LEEWAY_SECONDS;
+  const parts = token.split(".");
+  if (parts.length !== 3) {
+    throw new VerdictTokenError("malformed_token", "verdictToken must be a JWT");
+  }
+  const [headerB64, payloadB64, signatureB64] = parts;
+  let header;
+  let payload;
+  try {
+    header = JSON.parse(decodeBase64Url(headerB64));
+    payload = JSON.parse(decodeBase64Url(payloadB64));
+  } catch {
+    throw new VerdictTokenError("malformed_token", "verdictToken is not valid JWT JSON");
+  }
+  if (header["alg"] !== "ES256") {
+    throw new VerdictTokenError(
+      "wrong_algorithm",
+      `verdictToken must use ES256, got ${String(header["alg"])}`
+    );
+  }
+  const kid = typeof header["kid"] === "string" ? header["kid"] : "";
+  if (!kid) {
+    throw new VerdictTokenError("unknown_kid", "verdictToken is missing kid");
+  }
+  const exp = typeof payload["exp"] === "number" ? payload["exp"] : NaN;
+  const iat = typeof payload["iat"] === "number" ? payload["iat"] : NaN;
+  const nowSeconds = Math.floor(nowMs / 1e3);
+  if (Number.isFinite(exp) && exp < nowSeconds - leewaySeconds) {
+    throw new VerdictTokenError("expired", "verdictToken has expired");
+  }
+  if (Number.isFinite(iat) && iat > nowSeconds + leewaySeconds) {
+    throw new VerdictTokenError("not_yet_valid", "verdictToken iat is in the future");
+  }
+  const expectedSession = options.session;
+  if (expectedSession !== void 0 && payload["sub"] !== expectedSession) {
+    throw new VerdictTokenError(
+      "wrong_session",
+      "verdictToken was minted for a different session"
+    );
+  }
+  const expectedAud = options.aud;
+  if (expectedAud !== void 0 && payload["aud"] !== expectedAud) {
+    throw new VerdictTokenError(
+      "wrong_aud",
+      "verdictToken was minted for a different origin"
+    );
+  }
+  const jwk = await findJwk(kid, options);
+  if (!jwk) {
+    throw new VerdictTokenError("unknown_kid", `JWKS has no key for kid ${kid}`);
+  }
+  let publicKey;
+  try {
+    publicKey = await crypto.subtle.importKey(
+      "jwk",
+      jwk,
+      { name: "ECDSA", namedCurve: "P-256" },
+      false,
+      ["verify"]
+    );
+  } catch {
+    throw new VerdictTokenError(
+      "invalid_signature",
+      "JWKS key is not a valid P-256 public key"
+    );
+  }
+  const signatureBytes = decodeBase64UrlBytes(signatureB64);
+  const signatureBuffer = new ArrayBuffer(signatureBytes.byteLength);
+  new Uint8Array(signatureBuffer).set(signatureBytes);
+  const valid = await crypto.subtle.verify(
+    { name: "ECDSA", hash: "SHA-256" },
+    publicKey,
+    signatureBuffer,
+    new TextEncoder().encode(`${headerB64}.${payloadB64}`)
+  );
+  if (!valid) {
+    throw new VerdictTokenError(
+      "invalid_signature",
+      "verdictToken signature failed verification"
+    );
+  }
+  return payload;
+}
+async function findJwk(kid, options) {
+  let jwks = options.jwks;
+  if (!jwks) {
+    const jwksUrl = options.jwksUrl ?? DEFAULT_JWKS_URL;
+    try {
+      const fetchImpl = options.fetch ?? globalThis.fetch.bind(globalThis);
+      const res = await fetchImpl(jwksUrl);
+      if (!res.ok) {
+        throw new Error(`JWKS fetch failed with ${res.status}`);
+      }
+      jwks = await res.json();
+    } catch (err) {
+      throw new VerdictTokenError(
+        "jwks_unavailable",
+        `Failed to load JWKS from ${jwksUrl}: ${err instanceof Error ? err.message : "unknown error"}`
+      );
+    }
+  }
+  if (!Array.isArray(jwks.keys)) {
+    throw new VerdictTokenError("jwks_unavailable", "JWKS response has no keys array");
+  }
+  return jwks.keys.find((key) => key["kid"] === kid);
+}
+function decodeBase64Url(value) {
+  const normalized = value.replace(/-/g, "+").replace(/_/g, "/");
+  const padded = normalized + "=".repeat((4 - normalized.length % 4) % 4);
+  const binary = atob(padded);
+  return new TextDecoder().decode(Uint8Array.from(binary, (ch) => ch.charCodeAt(0)));
+}
+function decodeBase64UrlBytes(value) {
+  const normalized = value.replace(/-/g, "+").replace(/_/g, "/");
+  const padded = normalized + "=".repeat((4 - normalized.length % 4) % 4);
+  const binary = atob(padded);
+  const out = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i += 1) out[i] = binary.charCodeAt(i);
+  return out;
+}
+
+// src/client.ts
+var Chitmark = class {
+  apiKey;
+  baseUrl;
+  timeoutMs;
+  piiMode;
+  onDegraded;
+  fetchImpl;
+  clientName;
+  constructor(options) {
+    if (!options.apiKey) {
+      throw new ChitmarkError("Chitmark apiKey is required");
+    }
+    if (options.onDegraded && options.onDegraded !== "challenge") {
+      throw new ChitmarkError(
+        'onDegraded must be "challenge" \u2014 fail to challenge, never to allow'
+      );
+    }
+    this.apiKey = options.apiKey;
+    this.baseUrl = resolveBaseUrl(options.env, options.baseUrl ?? envBaseUrl());
+    this.timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    this.piiMode = options.piiMode ?? "hashed";
+    this.onDegraded = "challenge";
+    this.fetchImpl = options.fetch ?? globalThis.fetch.bind(globalThis);
+    this.clientName = options.clientName ?? `chitmark-node/${SDK_VERSION}`;
+  }
+  /**
+   * 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.
+   */
+  async verify(request) {
+    const subject = await prepareSubject(
+      {
+        ...request.subject,
+        headers: flattenHeaders(request.subject.headers)
+      },
+      this.piiMode
+    );
+    const body = {
+      ...request,
+      subject
+    };
+    try {
+      const verdict = await this.request("/v1/verify", {
+        method: "POST",
+        body,
+        idempotencyKey: request.idempotencyKey
+      });
+      if (!isWellFormedVerdict(verdict)) {
+        return degradedChallengeVerdict(
+          "Degraded: verify returned a malformed verdict shape",
+          request.session
+        );
+      }
+      return enforceDegradedNeverAllow(verdict);
+    } catch (err) {
+      if (err instanceof ChitmarkApiError) {
+        throw err;
+      }
+      return degradedChallengeVerdict(
+        err instanceof Error ? `Degraded: ${err.message}` : "Degraded: verify failed",
+        request.session
+      );
+    }
+  }
+  /**
+   * 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.
+   */
+  async feedback(request) {
+    return this.request("/v1/feedback", {
+      method: "POST",
+      body: request
+    });
+  }
+  /**
+   * Issue an asymmetric-cost challenge after decision === challenge | degraded.
+   */
+  async challenge(request) {
+    return this.request("/v1/challenge", {
+      method: "POST",
+      body: request
+    });
+  }
+  /**
+   * 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.
+   */
+  async completeChallenge(request) {
+    return this.request("/v1/challenge", {
+      method: "POST",
+      body: request
+    });
+  }
+  /**
+   * 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.
+   */
+  async verifyVerdictToken(token, options = {}) {
+    return verifyVerdictToken(token, {
+      ...options,
+      jwksUrl: `${this.baseUrl}/.well-known/jwks.json`,
+      fetch: this.fetchImpl
+    });
+  }
+  /**
+   * Low-level HTTP helper. Prefer verify / feedback / challenge.
+   */
+  async request(path, init) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+    try {
+      const headers = {
+        Authorization: `Bearer ${this.apiKey}`,
+        "Content-Type": "application/json",
+        Accept: "application/json",
+        "User-Agent": this.clientName,
+        "X-Chitmark-Client": this.clientName
+      };
+      if (init.idempotencyKey) {
+        headers["Idempotency-Key"] = init.idempotencyKey;
+      }
+      const res = await this.fetchImpl(`${this.baseUrl}${path}`, {
+        method: init.method,
+        headers,
+        body: init.body !== void 0 ? JSON.stringify(init.body) : void 0,
+        signal: controller.signal
+      });
+      const text = await res.text();
+      let parsed = void 0;
+      if (text) {
+        try {
+          parsed = JSON.parse(text);
+        } catch {
+          parsed = text;
+        }
+      }
+      if (!res.ok) {
+        const errBody = typeof parsed === "object" && parsed !== null ? parsed : text;
+        const normalized = typeof errBody === "string" ? errBody : {
+          error: errBody.error ?? `http_${res.status}`,
+          message: errBody.message,
+          code: errBody.code
+        };
+        throw new ChitmarkApiError(res.status, normalized);
+      }
+      return parsed;
+    } catch (err) {
+      if (err instanceof ChitmarkApiError) throw err;
+      if (err instanceof Error && err.name === "AbortError") {
+        throw new ChitmarkError(`Request timed out after ${this.timeoutMs}ms`, {
+          code: "timeout"
+        });
+      }
+      throw err instanceof Error ? new ChitmarkError(err.message, { code: "transport" }) : new ChitmarkError("Unknown transport error", { code: "transport" });
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+  /** Public accessors for inspection / tests. */
+  get config() {
+    return {
+      baseUrl: this.baseUrl,
+      timeoutMs: this.timeoutMs,
+      piiMode: this.piiMode,
+      onDegraded: this.onDegraded
+    };
+  }
+};
+var VERDICT_DECISIONS = /* @__PURE__ */ new Set(["allow", "challenge", "deny"]);
+function isWellFormedVerdict(value) {
+  if (typeof value !== "object" || value === null) return false;
+  const v = value;
+  return typeof v.decision === "string" && VERDICT_DECISIONS.has(v.decision) && typeof v.eventId === "string" && v.eventId.length > 0 && typeof v.degraded === "boolean";
+}
+
+// src/http-status.ts
+var CHITMARK_HTTP_STATUS = {
+  ok: 200,
+  created: 201,
+  badRequest: 400,
+  unauthorized: 401,
+  forbidden: 403,
+  notFound: 404,
+  conflict: 409,
+  preconditionRequired: 428,
+  tooManyRequests: 429
+};
+var CHITMARK_HTTP_STATUS_MEANING = {
+  ok: "Request succeeded. For verify gates, continue only after an explicit non-degraded allow.",
+  created: "Resource was created after an explicit non-degraded allow.",
+  badRequest: "Required request fields are missing or malformed.",
+  unauthorized: "API key is missing or invalid.",
+  forbidden: "Verify returned deny; block the action.",
+  notFound: "Referenced Chitmark resource was not found.",
+  conflict: "Idempotency key was reused with a materially different payload.",
+  preconditionRequired: "Verify returned challenge or degraded; require friction before continuing.",
+  tooManyRequests: "Request was rate limited."
+};
+function verdictToHttpStatus(verdict) {
+  if (verdict.degraded || verdict.decision === "challenge") {
+    return CHITMARK_HTTP_STATUS.preconditionRequired;
+  }
+  if (verdict.decision === "deny") return CHITMARK_HTTP_STATUS.forbidden;
+  return CHITMARK_HTTP_STATUS.ok;
+}
+
+// src/middleware/express.ts
+function chitmarkGate(client, action, options = {}) {
+  return async (req, res, next) => {
+    try {
+      const surface = options.surface?.(req) ?? `${req.hostname ?? ""}${req.path ?? ""}`;
+      const session = options.session?.(req);
+      const v = await client.verify({
+        action,
+        surface,
+        session,
+        subject: {
+          email: req.body?.email,
+          ip: req.ip,
+          userAgent: (typeof req.headers["user-agent"] === "string" ? req.headers["user-agent"] : void 0) ?? "",
+          headers: req.headers,
+          formData: req.body
+        }
+      });
+      res.locals.chitmark = v;
+      if (v.degraded || v.decision === "challenge") {
+        res.status(CHITMARK_HTTP_STATUS.preconditionRequired).json({ challenge: true, eventId: v.eventId });
+        return;
+      }
+      if (v.decision === "deny") {
+        res.status(CHITMARK_HTTP_STATUS.forbidden).json({ error: "blocked", eventId: v.eventId });
+        return;
+      }
+      next();
+    } catch (err) {
+      next(err);
+    }
+  };
+}
+
+// src/middleware/next.ts
+async function verifyNextRequest(client, req, options) {
+  const url = new URL(req.url);
+  return client.verify({
+    action: options.action,
+    surface: options.surface ?? `${url.host}${url.pathname}`,
+    session: options.session,
+    subject: {
+      email: options.body?.email,
+      ip: req.headers.get("x-forwarded-for") ?? "",
+      userAgent: req.headers.get("user-agent") ?? "",
+      headers: Object.fromEntries(req.headers),
+      formData: options.body
+    }
+  });
+}
+
+exports.CHITMARK_HTTP_STATUS = CHITMARK_HTTP_STATUS;
+exports.CHITMARK_HTTP_STATUS_MEANING = CHITMARK_HTTP_STATUS_MEANING;
+exports.Chitmark = Chitmark;
+exports.ChitmarkApiError = ChitmarkApiError;
+exports.ChitmarkError = ChitmarkError;
+exports.VerdictTokenError = VerdictTokenError;
+exports.chitmarkGate = chitmarkGate;
+exports.degradedChallengeVerdict = degradedChallengeVerdict;
+exports.enforceDegradedNeverAllow = enforceDegradedNeverAllow;
+exports.hashEmailSha256 = hashEmailSha256;
+exports.minimizeFormData = minimizeFormData;
+exports.truncateIp = truncateIp;
+exports.verdictToHttpStatus = verdictToHttpStatus;
+exports.verifyNextRequest = verifyNextRequest;
+exports.verifyVerdictToken = verifyVerdictToken;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map