@chitmark/sdk 0.7.0 → 0.9.0

package/README.md

@@ -1,191 +1,77 @@
-# @chitmark/sdk
+# Chitmark SDK for TypeScript
 
-Official TypeScript / JavaScript SDK for Chitmark: trust decisions on agent-mediated actions, tuned by business outcomes.
-
-AI agents and multi-account farms drain free tiers, trial credits, and API allowances while looking exactly like your best customers. Chitmark scores each action in under 50 ms and returns `allow`, `challenge`, or `deny`. Then your outcomes (conversion, credit burn, chargeback) come back through `feedback` and tune the next decision.
+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).
+Create a scoped API key in the [Chitmark dashboard](https://chitmark.com/dashboard) and set `CHITMARK_API_KEY` in your server environment.
 
-## Quick start
+## Resolve agent attribution
 
-```typescript
-import { Chitmark } from "@chitmark/sdk";
+Use a key with `attribution:read`. Replace the sample request with the inbound request from your server.
 
-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",
-});
+```ts
+import { Chitmark } from "@chitmark/sdk";
 
-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,
-  },
-});
+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 });
 
-if (verdict.decision === "challenge") {
-  // stop and run the challenge flow (below)
-}
-// Persist verdict.eventId on the account row: feedback joins only on that id.
+console.log(result.identity.recognized, result.principal.email);
 ```
 
-## The three verbs
-
-| 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` |
+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.
 
-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.
+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/).
 
-### Report outcomes
+## Screen a signup
 
-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.
+Use a key with `verify:write`. Generate and retain a session ID on your server for the attempt.
 
-```typescript
-// At signup: persist the join key
-db.accounts.update(userId, { chitmarkEventId: verdict.eventId });
+```ts
+import { randomUUID } from "node:crypto";
+import { Chitmark, isEligibleAllow } from "@chitmark/sdk";
 
-// 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",
-});
-```
-
-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.
-
-### Handle a challenge
-
-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.
-
-```typescript
-import { createHash } from "node:crypto";
-
-const issued = await chitmark.challenge({
-  eventId: verdict.eventId,
-  session: "sess_9f3a", // the challenge binds to this session
+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 (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.
-}
+console.log(verdict.decision, isEligibleAllow(verdict), verdict.eventId);
 ```
 
-### Verify the receipt
+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.
 
-Every production verdict ships a `verdictToken`: an ES256 JWT bound to session, origin, and event. Verify authenticity, then authorize on the decision:
+| 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
-const claims = await chitmark.verifyVerdictToken(verdict.verdictToken, {
-  session: "sess_9f3a",
-  tenantId: "org_acme",
-});
-
-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.
+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/).
 
-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.
+## Agent Paid Access
 
-### 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      |
+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/).
 
 ## 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" });
-```
-
-## Cloudflare Workers
-
-The `/edge` entrypoint is the same client with a request-first helper:
-
-```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 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
-
-- [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`.