@atlasent/sdk 1.5.0 → 2.10.0

package/README.md

@@ -13,32 +13,69 @@ import { AtlaSentClient } from "@atlasent/sdk";
 
 const client = new AtlaSentClient({ apiKey: process.env.ATLASENT_API_KEY! });
 
-const result = await client.evaluate({
-  agent: "clinical-data-agent",
-  action: "modify_patient_record",
-  context: { user: "dr_smith", environment: "production" },
+const gate = await client.deployGate({
+  context: { repo: "atlasent/api", commit: process.env.GIT_SHA },
 });
 
-if (result.decision === "ALLOW") {
-  // execute the action
-} else {
-  console.warn("Blocked:", result.reason);
+if (!gate.allowed) {
+  console.error("Deploy blocked:", gate.reason);
+  process.exit(1);
 }
+
+// runDeploy();
 ```
 
-That's it. `evaluate()` calls the AtlaSent policy engine, generates a hash-chained audit entry (21 CFR Part 11 / GxP-ready), and returns a result you branch on. A clean `DENY` is **not** thrown — network / server / auth failures are.
+That's it. `deployGate()` performs the V1 Deploy Gate sequence against `production.deploy`: `evaluate()` calls `POST /v1-evaluate`, receives a permit when allowed, then `verifyPermit()` calls `POST /v1-verify-permit` before your deployment can run. A clean `deny` is returned as a block result — network / server / auth failures are thrown.
 
-## Two methods, that's the whole surface
+## Simple V1 surface
 
 ```ts
 client.evaluate({ agent, action, context? })
-  // → { decision: "ALLOW" | "DENY", permitId, reason, auditHash, timestamp }
+  // → { decision: "allow" | "deny" | "hold" | "escalate", permitId, reason, auditHash, timestamp }
 
 client.verifyPermit({ permitId, agent?, action?, context? })
   // → { verified, outcome, permitHash, timestamp }
+
+client.deployGate({ agent?, action?, context? })
+  // defaults action to "production.deploy" and returns { allowed, reason, evidence }
+```
+
+`verifyPermit()` confirms a previously-issued permit server-side. Signed/offline permit artifacts never imply deployment authorization by themselves.
+
+## Decision replay
+
+Re-evaluate a recorded decision against its originally-pinned policy bundle and engine version. **Side-effect-free**: no audit row is written, no permit is minted (ADR-016 `mode: "replay"` sentinel). Useful for compliance review, regression-testing bundle changes, and post-incident investigation.
+
+Two surfaces exist; pick the one that matches your call site:
+
+```ts
+// SDK-canonical (preferred for new code) — wire DECISION_CHANGED is normalized
+// to POLICY_DRIFT; 409 replay_not_eligible returns ENGINE_DRIFT or BUNDLE_MISSING
+// instead of throwing. You can always `switch` on the variance kind.
+const r = await client.replay({ evaluationId: "dec_abc123" });
+switch (r.varianceKind) {
+  case "NONE":             /* replay agrees */                          break;
+  case "POLICY_DRIFT":     /* same envelope/bundle, different decision */ break;
+  case "ENVELOPE_DRIFT":   /* recorded envelope no longer hashes */     break;
+  case "ENGINE_DRIFT":     /* original engine retired beyond archival */ break;
+  case "BUNDLE_MISSING":   /* original eval had no bundle pinned */     break;
+  case "CHAIN_TAMPER":     /* audit-chain v5 detector tripped */        break;
+}
 ```
 
-`verifyPermit()` confirms a previously-issued permit end-to-end — use it as a second-factor gate (e.g., in a CI deploy pipeline before side-effects run).
+```ts
+// Raw-wire surface — variance values pass through verbatim
+// (NONE / DECISION_CHANGED / ENVELOPE_DRIFT); 409 throws AtlaSentError
+const result = await client.replayDecision("dec_abc123");
+if (result.variance === "DECISION_CHANGED") {
+  console.warn(
+    `Decision ${result.decision_id} drifted: ` +
+    `${result.original_decision} → ${result.replay_decision}`,
+  );
+}
+```
+
+`/v1/decisions/:id/replay` is alpha per `atlasent-api/docs/STABLE_V2_PROMOTION.md` — wire shapes can shift without a deprecation cycle until it graduates to stable v1.
 
 ## CI deploy-gate pattern
 
@@ -49,11 +86,11 @@ const client = new AtlaSentClient({ apiKey: process.env.ATLASENT_API_KEY! });
 
 const evaluation = await client.evaluate({
   agent: "ci-deploy-bot",
-  action: "deploy_to_production",
+  action: "production.deploy",
   context: { service: "billing-api", commit: process.env.GIT_SHA },
 });
 
-if (evaluation.decision !== "ALLOW") {
+if (evaluation.decision !== "allow") {
   console.error("Deploy blocked:", evaluation.reason);
   process.exit(1);
 }
@@ -76,10 +113,10 @@ See [`examples/deploy-gate.ts`](./examples/deploy-gate.ts) for a complete CI-sha
 
 ```ts
 new AtlaSentClient({
-  apiKey: "ask_live_...",           // required
+  apiKey: "ask_live_...", // required
   baseUrl: "https://api.atlasent.io", // default
-  timeoutMs: 10_000,                  // default — per-request
-  fetch: customFetch,                 // default: globalThis.fetch
+  timeoutMs: 10_000, // default — per-request
+  fetch: customFetch, // default: globalThis.fetch
 });
 ```
 
@@ -99,16 +136,16 @@ try {
 }
 ```
 
-| `err.code`         | When it's thrown                                        |
-|--------------------|---------------------------------------------------------|
-| `invalid_api_key`  | HTTP 401                                                |
-| `forbidden`        | HTTP 403                                                |
-| `rate_limited`     | HTTP 429 (check `err.retryAfterMs`)                     |
-| `bad_request`      | HTTP 4xx (other than 401/403/429)                       |
-| `server_error`     | HTTP 5xx                                                |
-| `timeout`          | `timeoutMs` exceeded                                    |
-| `network`          | DNS / connection failure, fetch threw                   |
-| `bad_response`     | non-JSON body or missing required fields                |
+| `err.code`        | When it's thrown                         |
+| ----------------- | ---------------------------------------- |
+| `invalid_api_key` | HTTP 401                                 |
+| `forbidden`       | HTTP 403                                 |
+| `rate_limited`    | HTTP 429 (check `err.retryAfterMs`)      |
+| `bad_request`     | HTTP 4xx (other than 401/403/429)        |
+| `server_error`    | HTTP 5xx                                 |
+| `timeout`         | `timeoutMs` exceeded                     |
+| `network`         | DNS / connection failure, fetch threw    |
+| `bad_response`    | non-JSON body or missing required fields |
 
 Every `AtlaSentError` carries `err.requestId` — the UUID the SDK sent as `X-Request-ID`, correlatable in your server logs.
 
@@ -122,8 +159,85 @@ Every `AtlaSentError` carries `err.requestId` — the UUID the SDK sent as `X-Re
 ## Requirements
 
 - Node.js **20** or newer (native `fetch`, `AbortSignal.timeout`, `crypto.randomUUID`).
+- **Browser:** Chrome 103+, Firefox 100+, Safari 16+, Edge 103+. The SDK uses
+  `AbortSignal.timeout` for per-request deadlines — the constructor throws a
+  clear `AtlaSentError(code: "network")` on runtimes that lack it so the failure
+  is loud rather than silent.
 - TypeScript **5.0+** for best type-inference ergonomics (older is fine — types are plain interfaces).
 
+## Hono middleware
+
+Drop-in protection for [Hono](https://hono.dev) routes via the
+`@atlasent/sdk/hono` subpath export (requires `hono` as a peer dep):
+
+```ts
+import { Hono } from "hono";
+import { atlaSentGuard, atlaSentErrorHandler } from "@atlasent/sdk/hono";
+
+const app = new Hono();
+app.onError(atlaSentErrorHandler());
+
+app.post(
+  "/deploy/:service",
+  atlaSentGuard({
+    action: (c) => `deploy_${c.req.param("service")}`,
+    agent: (c) => c.req.header("x-agent-id") ?? "anonymous",
+    context: async (c) => ({ commit: (await c.req.json()).commit }),
+  }),
+  (c) => c.json({ ok: true, permit: c.get("atlasent") }),
+);
+```
+
+`atlaSentGuard` calls `protect()` under the hood — fail-closed
+semantics. On allow it stashes a `Permit` on the context (key:
+`"atlasent"`, override via `options.key`). On deny or transport error
+it throws; `atlaSentErrorHandler` maps those to 403 / 503 responses
+so every guarded route shares one error-handling path.
+
+> **Upcoming migration:** after `@atlasent/enforce` reaches GA the
+> guard API will change to accept a pre-constructed `Enforce` instance
+> instead of per-route `action/agent/context` options. The current API
+> is **not deprecated** until that ships. See the
+> [CHANGELOG](./CHANGELOG.md) for the full before/after and
+> [`contract/ENFORCE_PACK.md`](../contract/ENFORCE_PACK.md) for
+> migration details.
+
+## Browser support
+
+The SDK is universal and works in modern browsers with no build-time changes:
+
+```ts
+import { AtlaSentClient } from "@atlasent/sdk";
+
+const client = new AtlaSentClient({
+  apiKey: import.meta.env.VITE_ATLASENT_API_KEY,
+  baseUrl: import.meta.env.VITE_ATLASENT_API_URL,
+});
+
+const result = await client.evaluate({
+  agent: currentUser.id,
+  action: "view_sensitive_report",
+});
+```
+
+**Auth model in browser contexts.** Shipping a long-lived API key in a browser
+bundle exposes it in DevTools and makes it replayable if exfiltrated. The
+recommended options in increasing security order are:
+
+- **Option B — browser-scoped keys (short term):** Create a read-only,
+  scope-restricted, IP-allowlisted key class from the AtlaSent console.
+  Safe for internal dashboards where you control the network. Not suitable
+  for public-facing apps.
+- **Option A — session-token mode (recommended for atlasent-hosted surfaces):**
+  After SSO sign-in, the frontend obtains a short-lived (15-min) Bearer token
+  from `GET /v1-session/token` bound to the user's scopes and tenant. The SDK
+  handles token refresh transparently. See
+  [atlasent-api#144](https://github.com/AtlaSent-Systems-Inc/atlasent-api/issues/144).
+
+The `User-Agent` header is set to `@atlasent/sdk/<version> browser` in browser
+runtimes (browsers strip this header anyway — it's harmless) and
+`@atlasent/sdk/<version> node/<node-version>` in Node.
+
 ## Related
 
 - **Python SDK:** same repo, [`../python/`](../python/README.md). Wire-compatible.