@chitmark/sdk 0.8.0 → 0.9.0

package/README.md

@@ -1,208 +1,77 @@
-# @chitmark/sdk
+# Chitmark SDK for TypeScript
 
-Official TypeScript and JavaScript SDK for Chitmark.
-
-- [Trust Decisions](https://chitmark.com/docs/quickstart/trust-decisions) lets you screen costly actions such as signups, credit grants, and API requests with `verify`, `feedback`, and `challenge`.
-- [Agent Attribution](https://chitmark.com/docs/guides/agent-attribution) lets you recognize returning site sessions and evaluate signed proof from linked agents.
-- [Agent Paid Access](https://chitmark.com/docs/guides/agent-paid-access) lets you buy or sell controlled access to API resources with hosted checkout and seller-controlled delivery.
+Use Chitmark from your backend to screen costly actions, recognize enrolled agents with signed proof, and manage paid API access.
 
 [![npm version](https://img.shields.io/npm/v/@chitmark/sdk.svg)](https://www.npmjs.com/package/@chitmark/sdk)
 
-Try it without a key: [run the playground](https://chitmark.com/playground). Live service health: [chitmark.com/status](https://chitmark.com/status).
-
 ## Install
 
+Requires Node.js 24 or later. The package ships TypeScript declarations and supports ESM and CommonJS.
+
 ```bash
 npm install @chitmark/sdk
-# or
-pnpm add @chitmark/sdk
 ```
 
-Requires Node >= 24. Runs on Node, browsers, Cloudflare Workers, and other edge runtimes (see the `/edge` entrypoint below).
-
-## Trust Decisions quick start
-
-```typescript
-import { Chitmark } from "@chitmark/sdk";
-
-const chitmark = new Chitmark({
-  apiKey: process.env.CHITMARK_API_KEY!,
-  // Optional, defaults shown
-  onDegraded: "challenge", // timeouts return a challenge, they never throw or allow
-  timeoutMs: 800, // local base URLs default to 2000ms
-  piiMode: "hashed", // 'hashed' | 'none' | 'raw'
-  env: "production",
-});
-
-const verdict = await chitmark.verify({
-  action: "signup",
-  session: "sess_9f3a",
-  surface: "app.acme.com/signup",
-  subject: {
-    email: "buyer@acmecorp.com", // hashed client-side before the wire
-    ip: "203.0.113.7", // truncated to /24 client-side
-    userAgent: req.headers["user-agent"],
-    headers: req.headers,
-  },
-});
-
-if (verdict.decision === "challenge") {
-  // stop and run the challenge flow (below)
-}
-// Persist verdict.eventId on the account row: feedback joins only on that id.
-```
+Create a scoped API key in the [Chitmark dashboard](https://chitmark.com/dashboard) and set `CHITMARK_API_KEY` in your server environment.
 
-## The three verbs
+## Resolve agent attribution
 
-| Verb          | Method                 | Endpoint             | When                         |
-| :------------ | :--------------------- | :------------------- | :--------------------------- |
-| **verify**    | `chitmark.verify()`    | `POST /v1/verify`    | At signup / trial / action   |
-| **feedback**  | `chitmark.feedback()`  | `POST /v1/feedback`  | After an outcome is known    |
-| **challenge** | `chitmark.challenge()` | `POST /v1/challenge` | On `challenge` or `degraded` |
+Use a key with `attribution:read`. Replace the sample request with the inbound request from your server.
 
-Store-outage degradation on verify is **HTTP 200** with a Verdict
-(`degraded: true`); the SDK deserializes it like any other Verdict. Verify
-never returns HTTP 503. Timeouts and transport errors synthesize a local
-degraded challenge Verdict and never throw on `verify`. HTTP 4xx / 429 Error
-responses throw `ChitmarkApiError`. Set `onDegraded` to `challenge` (the only
-supported value), never allow on degraded.
-
-### Report outcomes
-
-Store the `eventId` from verify on the account row, then report what happened against that same id. Never guess or derive the id from email or IP.
+```ts
+import { Chitmark } from "@chitmark/sdk";
 
-```typescript
-// At signup: persist the join key
-db.accounts.update(userId, { chitmarkEventId: verdict.eventId });
+const chitmark = new Chitmark({ apiKey: process.env.CHITMARK_API_KEY! });
+const request = new Request("https://app.example.com/agent-task");
+const result = await chitmark.attribution.resolve({ request });
 
-// Later, when a label matures:
-await chitmark.feedback({
-  eventId: account.chitmarkEventId, // the stored join key
-  outcome: "credit_burn", // converted | chargeback | abuse_confirmed | ...
-  value: 87.4, // measured magnitude: `unit` rides along (default "usd"; also "credits" | "count")
-  observedAt: "2026-08-06T04:00:00Z",
-});
+console.log(result.identity.recognized, result.principal.email);
 ```
 
-Exact duplicate feedback bodies derive the same warehouse id (`eventId` + `outcome` + `value` + `unit` + `observedAt`), so connector retries with a stable business timestamp never double-count a burned value. Prefer an `Idempotency-Key` anyway; omitting `observedAt` uses server time and is not safe for bare retries.
+The SDK reads fresh signed evidence from `Chitmark-Agent-Proof`. Without evidence, the sample returns an unknown identity and null email. An enrolled agent can sign for different recipients in a network-enabled deployment. Each site receives its own subject, and principal claims require a current grant for the recipient and purpose. Email also requires consent, `attribution:email`, and raw mode on an eligible plan.
 
-### Handle a challenge
+For relative request URLs, pass your configured HTTPS origin as `site`. See the [Attribution quickstart](https://chitmark.com/docs/guides/agent-attribution/) and [network proof guide](https://chitmark.com/docs/guides/agent-attribution-network/).
 
-When verify returns `challenge`, issue one, solve it on the client, and complete it. Proof-of-work difficulty is server-issued (4 by default, up to 6 at higher risk tiers): about 65k hashes, milliseconds for one real user, costly at farm scale.
+## Screen a signup
 
-```typescript
-import { createHash } from "node:crypto";
+Use a key with `verify:write`. Generate and retain a session ID on your server for the attempt.
 
-const issued = await chitmark.challenge({
-  eventId: verdict.eventId,
-  session: "sess_9f3a", // the challenge binds to this session
-});
-
-if (issued.instructions.type === "pow") {
-  const { challengeId, instructions } = issued;
-  const prefix = "0".repeat(instructions.difficulty);
-  let nonce = 0;
-  for (; ; nonce++) {
-    const hex = createHash("sha256")
-      .update(`${challengeId}:${instructions.seed}:${nonce}`)
-      .digest("hex");
-    if (hex.startsWith(prefix)) break;
-  }
-  await chitmark.completeChallenge({
-    eventId: verdict.eventId,
-    challengeId,
-    session: "sess_9f3a",
-    proof: { type: "proof_of_work", nonce: String(nonce) },
-  });
-  // Re-verify with context: { challengeId }; completion alone does not authorize.
-}
-```
-
-### Verify the receipt
-
-Every production verdict ships a `verdictToken`: an ES256 JWT bound to session, origin, and event. Verify authenticity, then authorize on the decision:
+```ts
+import { randomUUID } from "node:crypto";
+import { Chitmark, isEligibleAllow } from "@chitmark/sdk";
 
-```typescript
-const claims = await chitmark.verifyVerdictToken(verdict.verdictToken, {
-  session: "sess_9f3a",
-  tenantId: "org_acme",
+const chitmark = new Chitmark({ apiKey: process.env.CHITMARK_API_KEY! });
+const verdict = await chitmark.verify({
+  action: "signup",
+  session: randomUUID(),
+  surface: "app.example.com/signup",
+  subject: { email: "buyer@example.com" },
 });
 
-if (claims.degraded || claims.decision !== "allow") {
-  throw new ChallengeRequiredError(); // HTTP 428 / challenge response
-}
-
-// Only now trust the allow.
-```
-
-Rejects expired tokens, unknown keys, bad signatures, and session or origin mismatches with typed `VerdictTokenError` codes. A verified token that is not a non-degraded `allow` must still fail closed.
-
-Cache JWKS using HTTP headers: respect `Cache-Control` (`max-age=60`), and when `ETag` or `Last-Modified` are present use conditional requests (`If-None-Match` / `If-Modified-Since`) instead of a hard-coded refresh interval. Refresh immediately on unknown `kid`. Do not fetch on every verification. Every signed JWT requires `kid`. Keys are EC P-256 for ES256: require JWT `alg === "ES256"` before verifying (`wrong_algorithm` otherwise); never trust the token-requested alg. Rotation overlaps old and new keys; keep the retiring key until tokens under it expire (≥ 5 minutes + 60 seconds). An empty JWKS (`keys: []`) means verification is impossible: fail closed; never treat an empty set as proof a token is valid (local/CI may also emit `unsigned.<eventId>`). Pass a cached `jwks` option into `verifyVerdictToken` to skip the network call.
-
-### PII modes
-
-| Mode               | Behavior                                                   |
-| :----------------- | :--------------------------------------------------------- |
-| `hashed` (default) | SHA-256 email, /24 IP truncation, allowlisted form fields  |
-| `none`             | Derived/header-shape signals only (Web Bot Auth preserved) |
-| `raw`              | Tenant opt-in only; triggers higher compliance review      |
-
-## Framework integrations
-
-Express middleware and a Next.js route helper ship in the package. They normalize transient failures, challenge responses (HTTP 428), and deny (HTTP 403) for you. Handle raw status codes when using the low-level `Chitmark` client or curl.
-
-```typescript
-// Express: 403 on deny, 428 + challenge payload on challenge
-// 428 means the request is not rejected permanently; a required verification
-// precondition must be satisfied before the action can proceed.
-import { chitmarkGate } from "@chitmark/sdk";
-app.post("/signup", chitmarkGate(chitmark, "signup"), signupHandler);
-
-// Next.js App Router
-import { verifyNextRequest } from "@chitmark/sdk";
-const verdict = await verifyNextRequest(req, chitmark, { action: "signup" });
+console.log(verdict.decision, isEligibleAllow(verdict), verdict.eventId);
 ```
 
-## Cloudflare Workers
+Grant value only after an explicit, non-degraded allow. Timeouts and transport failures on `verify` produce a degraded challenge. The default data mode hashes email before sending it. Store the returned `eventId` for outcome reporting.
 
-The `/edge` entrypoint is the same client with a request-first helper:
+| Method                            | Use                                                                         |
+| --------------------------------- | --------------------------------------------------------------------------- |
+| `verify`                          | Get an allow, challenge, or deny verdict.                                   |
+| `challenge` / `completeChallenge` | Issue and complete an additional check. Reuse the attempt's session.        |
+| `feedback`                        | Report an outcome against the stored `eventId` with a `feedback:write` key. |
+| `verifyVerdictToken`              | Verify a signed receipt against the expected session and tenant.            |
 
-```typescript
-import { Chitmark } from "@chitmark/sdk/edge";
-
-const chitmark = new Chitmark({ apiKey: env.CHITMARK_API_KEY });
-const verdict = await chitmark.verifyRequest(req, { action: "signup" });
-```
-
-## Agent Attribution
-
-Use an Attribution read key to recognize site sessions or resolve an authorized principal association. Unknown is a successful outcome, and email is nullable.
-
-```ts
-const result = await chitmark.attribution.resolve({ request });
-console.log(result.identity.recognized, result.principal.email);
-```
-
-See the [Agent Attribution guide](https://chitmark.com/docs/guides/agent-attribution/) for request adapters, link grants, and disclosure rules.
+See the [Trust Decisions quickstart](https://chitmark.com/docs/quickstart/trust-decisions/), [challenge flow](https://chitmark.com/docs/api/challenge/), and [verdict token guide](https://chitmark.com/docs/guides/verdict-tokens/).
 
 ## Agent Paid Access
 
-Call `chitmark.charge(request)` to request a quote, continue through hosted checkout, or check purchase status. Sellers use separate credentials to reserve execution and record delivery. See the [Agent Paid Access guide](https://chitmark.com/docs/guides/agent-paid-access) for scopes and a complete buyer and seller example.
+Use `chitmark.charge(request)` to request a quote, continue checkout, or read purchase status. Sellers use separate scopes to reserve execution and record delivery. See the [Agent Paid Access guide](https://chitmark.com/docs/guides/agent-paid-access/).
 
-## Agent integration
-
-Using Cursor, Claude Code, Codex, or another coding agent? Point it at
-[chitmark.com/SKILL.md](https://chitmark.com/SKILL.md), or paste this into your
-prompt: `Integrate Chitmark into my app following https://chitmark.com/SKILL.md`.
-
-## Resources
+## Framework integrations
 
-- [Agent integration skill](https://chitmark.com/SKILL.md)
-- [API reference](https://chitmark.com/docs)
-- [Quickstart](https://chitmark.com/docs/quickstart)
-- [OpenAPI contract](https://chitmark.com/openapi.yaml)
-- [Examples repository](https://github.com/nonameuserd/chitmark-examples)
+- Express and Next.js use `chitmarkGate` and `verifyNextRequest`. [Framework guide](https://chitmark.com/docs/guides/drop-ins/)
+- Workers use `ChitmarkEdge` from `@chitmark/sdk/edge`. [TypeScript reference](https://chitmark.com/docs/sdk/typescript/)
+- Try a verdict without an API key in the [playground](https://chitmark.com/playground/).
 
 ## License
 
-Proprietary: see [LICENSE](LICENSE).
+Proprietary. The package includes the license terms in `LICENSE`.

package/dist/edge.cjs

@@ -2,21 +2,47 @@
 
 // src/attribution.ts
 function attributionEvidence(options, mode) {
-  const { request, agentProof, session, piiMode = mode } = options;
+  const { request, agentProof, session, purpose, piiMode = mode } = options;
   const headers = request.headers;
   const header = typeof headers.get === "function" ? headers.get("chitmark-agent-proof") : Object.entries(headers).find(
     ([name]) => name.toLowerCase() === "chitmark-agent-proof"
   )?.[1];
-  let site = options.site;
-  if (!site && request.url?.startsWith("https://")) site = new URL(request.url).origin;
-  let proof = agentProof;
-  if (!proof && typeof header === "string" && header.length <= 2048 && site) {
+  let url;
+  if (!options.site && request.url) {
     try {
-      proof = JSON.parse(header);
+      url = new URL(request.url);
     } catch {
     }
   }
-  return { site, session, piiMode, agentProof: proof };
+  const site = options.site ?? (url?.protocol === "https:" ? url.origin : void 0);
+  const proof = agentProof ?? (site ? parseProof(header) : void 0);
+  return { site, session, piiMode, purpose, agentProof: proof };
+}
+function parseProof(header) {
+  if (typeof header !== "string" || header.length > 2048) return;
+  try {
+    const value = JSON.parse(header);
+    if (!value || typeof value.nonce !== "string" || value.nonce.length > 36 || typeof value.issuedAt !== "number" || !Number.isSafeInteger(value.issuedAt) || typeof value.signature !== "string" || value.signature.length > 86)
+      return;
+    const { nonce, issuedAt, signature } = value;
+    if ("iss" in value) {
+      const key = value.agentKey;
+      if (value.iss === "chitmark-agent-key-v1" && key?.kty === "OKP" && key.crv === "Ed25519" && typeof key.x === "string" && key.x.length === 43 && !("d" in key)) {
+        return {
+          iss: value.iss,
+          agentKey: { kty: key.kty, crv: key.crv, x: key.x },
+          nonce,
+          issuedAt,
+          signature
+        };
+      }
+      return;
+    }
+    if (typeof value.linkId === "string" && value.linkId.length <= 36)
+      return { linkId: value.linkId, nonce, issuedAt, signature };
+  } catch {
+  }
+  return void 0;
 }
 
 // src/credentials.ts
@@ -153,7 +179,7 @@ var DEFAULT_BASE_URLS = {
 };
 var DEFAULT_TIMEOUT_MS = 800;
 var LOCAL_TIMEOUT_MS = 2e3;
-var SDK_VERSION = "0.8.0";
+var SDK_VERSION = "0.9.0";
 function defaultTimeoutMs(baseUrl) {
   try {
     const host = new URL(baseUrl).hostname.replace(/^\[|\]$/g, "").toLowerCase();