@atbash/sdk 0.16.6-dev.0 → 0.17.0-dev.0

package/dist/index.d.ts

@@ -198,6 +198,11 @@ interface JudgeResult {
      * missing" — never infer the former from a null verdict alone.
      */
     status: string;
+    /**
+     * The judge's explicit refusal in the raw body (`explicitRefusal`): "BLOCK",
+     * "HOLD", or "" when it neither refused nor is a known refusal shape.
+     */
+    refusal?: "" | "BLOCK" | "HOLD";
 }
 interface JudgmentStatus {
     status: JudgmentState;
@@ -305,6 +310,13 @@ interface AtbashLogger {
 /** Options accepted by the `Atbash` constructor. */
 interface AtbashOptions {
     endpoint?: string;
+    /**
+     * Overall deadline for one `auditToolCall` decision, across every request
+     * it makes (org lookup, exists check, judge). Default 60 000 ms. When it
+     * passes the decision is an ERROR (denied unless `failClosed` is false).
+     * `timeoutMs` still bounds each single request.
+     */
+    decisionTimeoutMs?: number;
     timeoutMs?: number;
     /**
      * Full chain override — BRID + nodeUrls in one object. Wins over every
@@ -350,6 +362,16 @@ interface AtbashOptions {
     orgEncryptionPubKey?: string;
     /** When true (default), `auditToolCall` denies on any error. */
     failClosed?: boolean;
+    /**
+     * When true (the default), an answer that carries no enforcement decision
+     * (the audit tier's `{status:"logged"}` with no verdict) is refused:
+     * `auditToolCall` returns `{allow:false, verdict:"ERROR"}` whatever
+     * `failClosed` says, and `judgeAction().allow` / `getJudgmentStatus().allow`
+     * are false. Set it to `false` only to run deliberately in log-only mode
+     * (security review 2026-09-30, H6: an unsigned marker switched enforcement
+     * off).
+     */
+    requireEnforcement?: boolean;
     /**
      * Verbose diagnostics. Off by default. When on, a failed judge call also
      * logs the response body, which is the difference between "judge API failed"
@@ -400,6 +422,10 @@ interface FromConfigOptions {
     /** Default org name — see {@link AtbashOptions.orgName}. */
     orgName?: string;
     failClosed?: boolean;
+    /** See {@link AtbashOptions.requireEnforcement}. Default true. */
+    requireEnforcement?: boolean;
+    /** See {@link AtbashOptions.decisionTimeoutMs}. Default 60 000 ms. */
+    decisionTimeoutMs?: number;
     /** See {@link AtbashOptions.debug}. */
     debug?: boolean;
     logger?: AtbashLogger;
@@ -456,6 +482,10 @@ declare class Atbash {
     readonly orgEncryptionPubKey?: string;
     /** When true (default), `auditToolCall` denies on any error. */
     readonly failClosed: boolean;
+    /** When true (default), an unenforced (audit-tier) answer is refused. */
+    readonly requireEnforcement: boolean;
+    /** Overall deadline for one auditToolCall decision, in ms. */
+    readonly decisionTimeoutMs: number;
     /** Org key learned from the last agent-exists check, for this agent only. */
     private _orgKeyFromChain;
     private readonly debug;
@@ -559,6 +589,23 @@ declare class Atbash {
      * explicitly false.
      */
     auditToolCall(input: ToolCallInput): Promise<Decision>;
+    /**
+     * The verify key for one call (R4, governor tier-2 review). A per-call key
+     * may only narrow what the client accepts: on a client pinned to a judge
+     * key it must be that same key, never a replacement; on an unpinned client
+     * it adds the check.
+     */
+    private effectiveVerifyKey;
+    /**
+     * Collapse a judge result into a {@link Decision}. The most restrictive
+     * signal wins (security review 2026-09-30, H1): `action_type`, `verdict`
+     * and the canonical `allow` are each able to deny, and only a result where
+     * all three agree may execute. A present `allow` / `decision.allow` that is
+     * not exactly `true` is the judge declining to grant permission, so it
+     * denies even under `failClosed: false` — that option relaxes *errors*, it
+     * never overrides a refusal.
+     */
+    private decide;
     /**
      * One exit for every judge failure.
      *
@@ -568,6 +615,12 @@ declare class Atbash {
      * The response body follows only under `debug`, since it can echo the action.
      */
     private failJudge;
+    /**
+     * The canonical permission for a response body under this client's
+     * settings: {@link canonicalAllow}, minus the audit tier when
+     * `requireEnforcement` is on. Never more permissive than `auditToolCall`.
+     */
+    private executable;
     private fail;
     /**
      * Return the current status of a previously submitted judgment.

package/dist/index.js

@@ -3301,7 +3301,7 @@ function loadAgentFromFile(keyPath) {
 // src-ts/normalize.ts
 function normalizeVerdict(raw2) {
   if (raw2 === null || raw2 === void 0) return "No verdict";
-  const v = String(raw2).toUpperCase();
+  const v = String(raw2).trim().toUpperCase();
   if (v === "ALLOW" || v === "GREEN") return "ALLOW";
   if (v === "HOLD" || v === "YELLOW") return "HOLD";
   if (v === "BLOCK" || v === "RED") return "BLOCK";
@@ -3338,17 +3338,58 @@ function allowSignalsPermit(data) {
   }
   return signals.length === 0 || signals.every((value) => value === true);
 }
+function explicitRefusal(data) {
+  let hold = false;
+  for (const source of decisionSources(data)) {
+    const verdict = verdictOf(source);
+    if (verdict === "BLOCK" || verdict === "RED") return "BLOCK";
+    if (verdict === "HOLD" || verdict === "YELLOW") hold = true;
+    const actionType = actionTypeOf(source);
+    if (actionType === "block") return "BLOCK";
+    if (actionType === "hold_for_user_confirm") hold = true;
+  }
+  if (!allowSignalsPermit(data)) return "BLOCK";
+  return hold ? "HOLD" : "";
+}
+function decisionSources(data) {
+  return [data, isRecord(data.decision) ? data.decision : {}];
+}
+function verdictOf(source) {
+  return typeof source.verdict === "string" ? source.verdict.trim().toUpperCase() : "";
+}
+function actionTypeRank(actionType) {
+  if (actionType === "block") return 4;
+  if (actionType === "hold_for_user_confirm") return 3;
+  if (actionType === "") return 1;
+  if (actionType === "allow") return 0;
+  return 2;
+}
+function actionTypeOf(source) {
+  let winner = "";
+  for (const key3 of ["action_type", "actionType"]) {
+    const raw2 = source[key3];
+    if (raw2 === void 0 || raw2 === null) continue;
+    const actionType = normalizeActionType(raw2);
+    if (actionTypeRank(actionType) > actionTypeRank(winner)) winner = actionType;
+  }
+  return winner;
+}
 function wireActionType(data) {
-  if (data.action_type !== void 0)
-    return normalizeActionType(data.action_type);
-  return normalizeActionType(data.actionType);
+  for (const source of decisionSources(data)) {
+    const actionType = actionTypeOf(source);
+    if (actionType !== "") return actionType;
+  }
+  return "";
 }
 function isAuditTier(data) {
   const absentVerdict = data.verdict === null || data.verdict === void 0;
   return absentVerdict && data.status === "logged";
 }
+function isAuditTierBody(data) {
+  return isAuditTier(data);
+}
 function canonicalAllow(data) {
-  if (!allowSignalsPermit(data)) return false;
+  if (explicitRefusal(data) !== "") return false;
   const actionType = wireActionType(data);
   if (actionType && actionType !== "allow") return false;
   if (isAuditTier(data)) return true;
@@ -3578,6 +3619,10 @@ var Atbash = class _Atbash {
   orgEncryptionPubKey;
   /** When true (default), `auditToolCall` denies on any error. */
   failClosed;
+  /** When true (default), an unenforced (audit-tier) answer is refused. */
+  requireEnforcement;
+  /** Overall deadline for one auditToolCall decision, in ms. */
+  decisionTimeoutMs;
   /** Org key learned from the last agent-exists check, for this agent only. */
   _orgKeyFromChain = null;
   debug;
@@ -3651,6 +3696,8 @@ var Atbash = class _Atbash {
     this.verifyPubKey = validated.verifyPubKey ?? void 0;
     this.orgEncryptionPubKey = options.orgEncryptionPubKey;
     this.failClosed = options.failClosed !== false;
+    this.requireEnforcement = options.requireEnforcement !== false;
+    this.decisionTimeoutMs = options.decisionTimeoutMs ?? DEFAULT_DECISION_TIMEOUT_MS;
     this.debug = options.debug === true;
     this.logger = options.logger ?? {};
     this.http = new HttpClient(this.endpoint, options.timeoutMs ?? 12e4);
@@ -3741,6 +3788,8 @@ var Atbash = class _Atbash {
       orgName: options.orgName,
       verifyPubKey: validated.verifyPubKey ?? void 0,
       failClosed: options.failClosed,
+      requireEnforcement: options.requireEnforcement,
+      decisionTimeoutMs: options.decisionTimeoutMs,
       // ATBASH_DEBUG lets an operator turn diagnostics on without editing a
       // host's plugin config, which is usually the harder half.
       debug: options.debug ?? /^(1|true|yes)$/i.test(resolve("debug")),
@@ -3939,34 +3988,16 @@ var Atbash = class _Atbash {
     }
     if (!resp.ok) throw await this.httpError(resp);
     const bodyBytes = Buffer.from(await resp.arrayBuffer());
-    const verifyPubKey = options.verifyPubKey ?? this.verifyPubKey;
+    const verifyPubKey = this.effectiveVerifyKey(options.verifyPubKey);
     if (verifyPubKey !== void 0) {
-      const sig = resp.headers.get("X-Atbash-Signature");
-      if (!sig) {
-        throw new SignatureVerificationError(
-          "missing X-Atbash-Signature header"
-        );
-      }
-      let ok;
-      try {
-        ok = native.verifySignature(bodyBytes, sig, verifyPubKey);
-      } catch (err) {
-        throw new SignatureVerificationError(
-          `signature verification threw: ${errorMessage(err)}`
-        );
-      }
-      if (!ok) {
-        throw new SignatureVerificationError(
-          "signature does not verify against configured verifyPubKey"
-        );
-      }
+      verifyResponseSignature(bodyBytes, resp, verifyPubKey);
     }
     const data = parseJson(bodyBytes);
     const rawScore = data.score;
     const score = typeof rawScore === "number" && Number.isInteger(rawScore) && rawScore >= 1 && rawScore <= 10 ? rawScore : void 0;
     return {
       verdict: normalizeVerdict(data.verdict),
-      allow: canonicalAllow(data),
+      allow: this.executable(data),
       actionType: normalizeActionType(data.action_type),
       reason: String(data.reason ?? ""),
       confidence: Number(data.confidence ?? 0),
@@ -3977,7 +4008,8 @@ var Atbash = class _Atbash {
       enforced: Boolean(data.enforced),
       enforcementMode: String(data.enforcement_mode ?? ""),
       status: String(data.status ?? ""),
-      score
+      score,
+      refusal: explicitRefusal(data)
     };
   }
   /* ── audit_tool_call (redact → judge → decision) ───────────────────────── */
@@ -4010,77 +4042,125 @@ var Atbash = class _Atbash {
     }
     try {
       this.logger.info?.("[atbash] judge API called", { tool: toolName });
-      const result = await this.judgeAction(actionText, contextText, {
-        toolName,
-        toolArgsJson: argsJson,
-        orgName: this.orgName,
-        // Passed through unredacted — caller vouches for the contents.
-        resolved: input.resolved
-      });
-      if (result.verdict === "No verdict") {
-        if (result.status !== "logged") {
-          return this.failJudge(
-            `judge returned no verdict without an audit-tier marker (status: ${result.status || "absent"})`,
-            void 0,
-            result.toolCallId
-          );
-        }
-        return {
-          allow: true,
-          verdict: "ALLOW",
-          reason: result.reason || "audit tier \u2014 request logged on-chain, no AI enforcement",
-          toolCallId: result.toolCallId
-        };
-      }
-      const action = result.actionType;
-      if (action === "block") {
+      const result = await withDeadline(
+        this.judgeAction(actionText, contextText, {
+          toolName,
+          toolArgsJson: argsJson,
+          orgName: this.orgName,
+          // Passed through unredacted — caller vouches for the contents.
+          resolved: input.resolved
+        }),
+        this.decisionTimeoutMs
+      );
+      return this.decide(result);
+    } catch (err) {
+      if (err instanceof SignatureVerificationError) {
+        this.failJudge(errorMessage(err), err);
         return {
           allow: false,
-          verdict: "BLOCK",
-          reason: result.reason,
-          toolCallId: result.toolCallId
+          verdict: "ERROR",
+          reason: `The judge's reply failed its signature check (${errorMessage(err)}), so it was not trusted.`
         };
       }
-      if (action === "hold_for_user_confirm") {
-        return {
-          allow: false,
-          verdict: "HOLD",
-          reason: result.reason || "held for human confirmation",
-          toolCallId: result.toolCallId
-        };
+      return this.failJudge(errorMessage(err), err);
+    }
+  }
+  /**
+   * The verify key for one call (R4, governor tier-2 review). A per-call key
+   * may only narrow what the client accepts: on a client pinned to a judge
+   * key it must be that same key, never a replacement; on an unpinned client
+   * it adds the check.
+   */
+  effectiveVerifyKey(perCall) {
+    if (perCall === void 0) return this.verifyPubKey;
+    const key3 = perCall.trim().toLowerCase();
+    if (this.verifyPubKey !== void 0 && key3 !== this.verifyPubKey) {
+      throw new SignatureVerificationError(
+        "a per-call verifyPubKey cannot replace the judge key this client is pinned to"
+      );
+    }
+    return key3;
+  }
+  /**
+   * Collapse a judge result into a {@link Decision}. The most restrictive
+   * signal wins (security review 2026-09-30, H1): `action_type`, `verdict`
+   * and the canonical `allow` are each able to deny, and only a result where
+   * all three agree may execute. A present `allow` / `decision.allow` that is
+   * not exactly `true` is the judge declining to grant permission, so it
+   * denies even under `failClosed: false` — that option relaxes *errors*, it
+   * never overrides a refusal.
+   */
+  decide(result) {
+    const toolCallId = result.toolCallId;
+    const deny = (verdict, reason) => ({
+      allow: false,
+      verdict,
+      reason,
+      toolCallId
+    });
+    const notGranted = "the judge response did not grant permission";
+    const held = deny("HOLD", result.reason || "held for human confirmation");
+    const blocked = deny("BLOCK", result.reason || notGranted);
+    if (result.refusal === "BLOCK") return blocked;
+    if (result.verdict === "No verdict") {
+      if (result.actionType === "block") {
+        return blocked;
+      }
+      if (result.actionType === "hold_for_user_confirm") {
+        return held;
+      }
+      if (result.refusal === "HOLD") return held;
+      if (result.status !== "logged") {
+        return this.failJudge(
+          `judge returned no verdict without an audit-tier marker (status: ${result.status || "absent"})`,
+          void 0,
+          toolCallId
+        );
       }
-      if (action === "allow") {
-        if (result.verdict === "HOLD") {
-          return {
-            allow: false,
-            verdict: "HOLD",
-            reason: result.reason,
-            toolCallId: result.toolCallId
-          };
-        }
-        if (result.verdict === "BLOCK") {
-          return {
-            allow: false,
-            verdict: "BLOCK",
-            reason: result.reason,
-            toolCallId: result.toolCallId
-          };
-        }
+      if (this.requireEnforcement) {
+        this.logger.warn?.(
+          "[atbash] judge did not enforce this action (audit tier) and requireEnforcement is on: denied",
+          { toolCallId }
+        );
         return {
-          allow: true,
-          verdict: "ALLOW",
-          reason: result.reason,
-          toolCallId: result.toolCallId
+          allow: false,
+          verdict: "ERROR",
+          reason: "Atbash logged this action but did not check it (audit-tier plan), and this client requires a checked decision. Upgrade the plan, or set requireEnforcement: false for log-only mode.",
+          toolCallId
         };
       }
-      return this.failJudge(
-        "unrecognized action_type from judge",
-        void 0,
-        result.toolCallId
-      );
-    } catch (err) {
-      return this.failJudge(errorMessage(err), err);
+      if (result.allow !== true) return deny("BLOCK", notGranted);
+      return {
+        allow: true,
+        verdict: "ALLOW",
+        reason: result.reason || "audit tier \u2014 request logged on-chain, no AI enforcement",
+        toolCallId
+      };
+    }
+    const action = result.actionType;
+    if (action === "block") {
+      return deny("BLOCK", result.reason || "Blocked by your organisation's Atbash policy.");
+    }
+    if (action === "hold_for_user_confirm") {
+      return held;
+    }
+    if (result.refusal === "HOLD") return held;
+    if (action === "allow") {
+      if (result.verdict === "HOLD") return held;
+      if (result.verdict === "BLOCK") return blocked;
+      if (result.allow !== true) return deny("BLOCK", notGranted);
+      return {
+        allow: true,
+        verdict: "ALLOW",
+        reason: result.reason,
+        toolCallId
+      };
     }
+    return this.failJudge(
+      "unrecognized action_type from judge",
+      void 0,
+      toolCallId
+    );
   }
   /**
    * One exit for every judge failure.
@@ -4092,18 +4172,30 @@ var Atbash = class _Atbash {
    */
   failJudge(reason, cause, toolCallId) {
     const api2 = cause instanceof AtbashAPIError ? cause : null;
+    const userReason = userFacingReason(reason, api2);
     const status = api2 ? ` status=${api2.status || "no-response"}` : "";
+    const detail = this.debug ? ` detail=${truncate(reason, 500)}` : "";
     const body = this.debug && api2?.body ? ` body=${truncate(api2.body, 500)}` : "";
     this.logger.warn?.(
-      `[atbash] judge API failed \u2014${status} reason=${truncate(reason, 300)}${body}`,
+      `[atbash] judge API failed \u2014${status} reason=${truncate(userReason, 300)}${detail}${body}`,
       {
-        reason,
-        ...api2 ? { status: api2.status, body: api2.body } : {},
+        reason: userReason,
+        ...api2 ? { status: api2.status } : {},
+        ...this.debug && api2 ? { body: api2.body, detail: reason } : {},
         endpoint: this.endpoint,
         ...toolCallId ? { toolCallId } : {}
       }
     );
-    return this.fail(reason, toolCallId);
+    return this.fail(userReason, toolCallId);
+  }
+  /**
+   * The canonical permission for a response body under this client's
+   * settings: {@link canonicalAllow}, minus the audit tier when
+   * `requireEnforcement` is on. Never more permissive than `auditToolCall`.
+   */
+  executable(data) {
+    if (!canonicalAllow(data)) return false;
+    return !(this.requireEnforcement && isAuditTierBody(data));
   }
   fail(reason, toolCallId) {
     return { allow: !this.failClosed, verdict: "ERROR", reason, toolCallId };
@@ -4129,11 +4221,16 @@ var Atbash = class _Atbash {
         this.authHeaders(brid)
       );
       await this.raiseIfError(resp);
-      const data = await this.json(resp) ?? {};
+      const bytes = Buffer.from(await resp.arrayBuffer());
+      if (this.verifyPubKey !== void 0) {
+        verifyResponseSignature(bytes, resp, this.verifyPubKey);
+      }
+      const parsed = tryParseJson(bytes.toString("utf-8"));
+      const data = isRecord2(parsed) ? parsed : {};
       return {
         status: normalizeStatus(data.status),
         verdict: normalizeVerdict(data.verdict),
-        allow: canonicalAllow(data),
+        allow: this.executable(data),
         reason: String(data.reason ?? ""),
         judgmentId: String(data.judgmentId ?? judgmentId),
         onChain: optBool(data.onChain),
@@ -4608,6 +4705,66 @@ var Atbash = class _Atbash {
     return native.containsEvasionCharacters(text);
   }
 };
+function userFacingReason(reason, api2) {
+  if (api2 && api2.status > 0) {
+    const where = ` (HTTP ${api2.status}${api2.path ? ` from ${api2.path}` : ""})`;
+    const b = api2.body.toLowerCase();
+    if (b.includes("agent not registered")) {
+      return `Agent not registered with Atbash: onboard it in the Atbash dashboard${where}.`;
+    }
+    if (b.includes("jailed")) {
+      return `This agent is jailed; unjail it in the Atbash dashboard${where}.`;
+    }
+    if (b.includes("agent has no policy") || b.includes("no policy configured")) {
+      return `This agent has no policy; attach one in the Atbash dashboard${where}.`;
+    }
+    if (b.includes("audit tier") || b.includes("verdict disabled") || b.includes("verdict not supported")) {
+      return `The organisation's plan does not include checked decisions${where}.`;
+    }
+    return `The Atbash judge answered with an error${where}, so the action was not approved.`;
+  }
+  const text = api2 ? api2.body || reason : reason;
+  return truncate(text.replace(/https?:\/\/[^\s)]+/g, "the judge"), 300);
+}
+var DEFAULT_DECISION_TIMEOUT_MS = 6e4;
+async function withDeadline(p, ms) {
+  let timer;
+  const deadline = new Promise((_, reject) => {
+    timer = setTimeout(
+      () => reject(
+        new Error(
+          `The judge did not give a decision within ${Math.round(ms / 1e3)} s, so the action was not approved. Check the network, or raise decisionTimeoutMs.`
+        )
+      ),
+      ms
+    );
+  });
+  p.catch(() => void 0);
+  try {
+    return await Promise.race([p, deadline]);
+  } finally {
+    clearTimeout(timer);
+  }
+}
+function verifyResponseSignature(bodyBytes, resp, verifyPubKey) {
+  const sig = resp.headers.get("X-Atbash-Signature");
+  if (!sig) {
+    throw new SignatureVerificationError("missing X-Atbash-Signature header");
+  }
+  let ok;
+  try {
+    ok = native.verifySignature(bodyBytes, sig, verifyPubKey);
+  } catch (err) {
+    throw new SignatureVerificationError(
+      `signature verification threw: ${errorMessage(err)}`
+    );
+  }
+  if (!ok) {
+    throw new SignatureVerificationError(
+      "signature does not verify against configured verifyPubKey"
+    );
+  }
+}
 function baseToolCall(raw2) {
   return {
     toolCallId: String(raw2.tool_call_id ?? ""),
@@ -4821,7 +4978,11 @@ async function scanMemory(entry, auth, opts) {
   const atbash = new Atbash(auth.privkey, {
     endpoint: opts?.endpoint,
     verifyPubKey: opts?.verifyPubKey,
-    orgName: opts?.orgName
+    orgName: opts?.orgName,
+    // Memory scans keep their existing audit-tier semantics (an audit-tier
+    // scan is not a defect the scanner invents). Whether an unenforced scan
+    // may commit memory is the memory-guard PR's decision, not H6's.
+    requireEnforcement: false
   });
   const result = await atbash.judgeAction(request.prompt, request.context, {
     toolName: opts?.toolName ?? "memory_write",
@@ -4857,6 +5018,7 @@ async function scanMemory(entry, auth, opts) {
       verdict = "yellow";
     }
   }
+  if (verdict === "green" && result.allow !== true) verdict = "red";
   const parsed = native.parseScoreFromReason(result.reason);
   const score = result.score ?? parsed.score ?? native.defaultScoreForVerdict(verdict);
   return {