@prampta/sdk 0.3.2 → 0.4.0

package/dist/index.js

@@ -1,2 +1,707 @@
-export { Prampta, PramptaError } from './client.js';
-//# sourceMappingURL=index.js.map
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  HARD_REFUSAL_CODES: () => HARD_REFUSAL_CODES,
+  Prampta: () => Prampta,
+  PramptaApiError: () => PramptaApiError,
+  PramptaError: () => PramptaError,
+  PramptaFailClosedError: () => PramptaFailClosedError,
+  PramptaNetworkError: () => PramptaNetworkError,
+  PramptaRefusalError: () => PramptaRefusalError,
+  PramptaSchemaError: () => PramptaSchemaError,
+  PramptaSignatureError: () => PramptaSignatureError,
+  PramptaTimeoutError: () => PramptaTimeoutError,
+  REFUSAL_DESCRIPTIONS: () => REFUSAL_DESCRIPTIONS,
+  SOFT_REFUSAL_CODES: () => SOFT_REFUSAL_CODES,
+  canonicalJson: () => canonicalJson,
+  hashPrompt: () => hashPrompt,
+  matchSubjects: () => matchSubjects,
+  normalizeForMatch: () => normalizeForMatch
+});
+module.exports = __toCommonJS(index_exports);
+var ed = __toESM(require("@noble/ed25519"));
+var PramptaError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "PramptaError";
+  }
+};
+var PramptaNetworkError = class extends PramptaError {
+  constructor(cause_) {
+    super(`PRAMPTA backend unreachable: ${cause_}`);
+    this.cause_ = cause_;
+    this.name = "PramptaNetworkError";
+  }
+  cause_;
+};
+var PramptaTimeoutError = class extends PramptaError {
+  constructor(timeoutMs) {
+    super(`PRAMPTA request timed out after ${timeoutMs}ms`);
+    this.timeoutMs = timeoutMs;
+    this.name = "PramptaTimeoutError";
+  }
+  timeoutMs;
+};
+var PramptaApiError = class extends PramptaError {
+  constructor(status, detail) {
+    super(`PRAMPTA API error ${status}: ${detail}`);
+    this.status = status;
+    this.detail = detail;
+    this.name = "PramptaApiError";
+  }
+  status;
+  detail;
+};
+var PramptaSchemaError = class extends PramptaError {
+  constructor(message) {
+    super(`PRAMPTA schema error: ${message}`);
+    this.name = "PramptaSchemaError";
+  }
+};
+var PramptaSignatureError = class extends PramptaError {
+  constructor(message) {
+    super(`PRAMPTA signature verification failed: ${message}`);
+    this.name = "PramptaSignatureError";
+  }
+};
+var PramptaRefusalError = class extends PramptaError {
+  constructor(decision) {
+    const desc = REFUSAL_DESCRIPTIONS[decision.reason || ""] || decision.reason;
+    super(`Generation refused: ${desc}`);
+    this.decision = decision;
+    this.name = "PramptaRefusalError";
+  }
+  decision;
+  get reason() {
+    return this.decision.reason || "UNKNOWN";
+  }
+  get isHardRefusal() {
+    return this.decision.isHardRefusal;
+  }
+  get decisionId() {
+    return this.decision.decisionId;
+  }
+  get licenseId() {
+    return this.decision.licenseId;
+  }
+};
+var PramptaFailClosedError = class extends PramptaError {
+  constructor(cause_) {
+    super(`PRAMPTA fail-closed: generation blocked because verification failed (${cause_})`);
+    this.cause_ = cause_;
+    this.name = "PramptaFailClosedError";
+  }
+  cause_;
+};
+var REFUSAL_DESCRIPTIONS = {
+  PG_NO_SUBJECT: "Subject not found in registry",
+  PG_SUBJECT_PENDING: "Subject registration is pending approval",
+  PG_SUBJECT_DISPUTED: "Subject is under dispute \u2014 generation blocked",
+  PG_SUBJECT_WITHDRAWN: "Subject has been withdrawn from registry",
+  PG_SUBJECT_OPTED_OUT: "Subject has opted out of AI generation",
+  PG_NO_LICENSE: "No valid license for this subject/licensee pair",
+  PG_NO_PAIR: "Provider-licensee pair not established",
+  PG_INVALID_SIGNATURE: "License signature verification failed",
+  PG_IMMUTABLE_DENIAL: "Content category permanently denied by subject",
+  PG_SCOPE_VIOLATION: "Intended use outside license scope",
+  PG_EXTENSION_REFUSED: "License extension constraint not satisfied",
+  PG_BACKEND_UNAVAILABLE: "Backend unreachable \u2014 fail-closed"
+};
+var HARD_REFUSAL_CODES = /* @__PURE__ */ new Set([
+  "PG_SUBJECT_OPTED_OUT",
+  "PG_IMMUTABLE_DENIAL",
+  "PG_INVALID_SIGNATURE",
+  "PG_SUBJECT_DISPUTED",
+  "PG_SUBJECT_WITHDRAWN"
+]);
+var SOFT_REFUSAL_CODES = /* @__PURE__ */ new Set([
+  "PG_NO_LICENSE",
+  "PG_SCOPE_VIOLATION"
+]);
+function envVar(key) {
+  if (typeof process !== "undefined" && process.env) return process.env[key] ?? "";
+  return "";
+}
+async function hashPrompt(prompt) {
+  return sha256(prompt);
+}
+async function sha256(input) {
+  const data = new TextEncoder().encode(input);
+  return sha256Bytes(data);
+}
+var TOFU_WARNING = "PRAMPTA: verifying operator signatures WITHOUT a pinned key (trust-on-first-use). This provides no protection against a malicious or compromised endpoint. Set operatorPublicKeyHex (from PRAMPTA's docs) before production.";
+function parsePins(raw) {
+  return raw ? raw.split(/[\s,]+/).filter(Boolean) : [];
+}
+async function keyFingerprint(publicKeyHex) {
+  return `pg-ed25519:${(await sha256Bytes(hexToBytes(publicKeyHex))).slice(0, 32)}`;
+}
+async function sha256Bytes(data) {
+  if (typeof globalThis.crypto?.subtle !== "undefined") {
+    const exact = data.buffer.slice(data.byteOffset, data.byteOffset + data.byteLength);
+    const hash = await globalThis.crypto.subtle.digest("SHA-256", exact);
+    return Array.from(new Uint8Array(hash)).map((b) => b.toString(16).padStart(2, "0")).join("");
+  }
+  const { createHash } = await import("crypto");
+  return createHash("sha256").update(data).digest("hex");
+}
+function canonicalJson(obj) {
+  if (obj === null || obj === void 0) return "null";
+  if (typeof obj === "number" || typeof obj === "boolean") return JSON.stringify(obj);
+  if (typeof obj === "string") return JSON.stringify(obj);
+  if (Array.isArray(obj)) return "[" + obj.map(canonicalJson).join(",") + "]";
+  const keys = Object.keys(obj).sort();
+  const parts = keys.map((k) => JSON.stringify(k) + ":" + canonicalJson(obj[k]));
+  return "{" + parts.join(",") + "}";
+}
+function hexToBytes(hex) {
+  const bytes = new Uint8Array(hex.length / 2);
+  for (let i = 0; i < hex.length; i += 2) {
+    bytes[i / 2] = parseInt(hex.substring(i, i + 2), 16);
+  }
+  return bytes;
+}
+var LEET = { "0": "o", "1": "i", "3": "e", "4": "a", "5": "s", "7": "t", "@": "a", "$": "s" };
+var SQUEEZE_MIN = 5;
+function stripDiacritics(t) {
+  let out = "";
+  for (const ch of t.normalize("NFC")) {
+    const base = ch.normalize("NFKD")[0] || ch;
+    if (/[a-zA-Z]/.test(base)) out += base;
+    else out += ch;
+  }
+  return out;
+}
+function normalizeForMatch(text) {
+  let t = stripDiacritics(text.toLowerCase());
+  t = t.replace(/[0134578@$]/g, (c) => LEET[c] || c);
+  return t.replace(/[-_]+/g, " ").replace(/[^\p{L}\p{N} ]+/gu, " ").replace(/ +/g, " ").trim();
+}
+var squeeze = (t) => t.replace(/ /g, "");
+function matchSubjects(text, entries) {
+  const norm = normalizeForMatch(text);
+  const haystack = ` ${norm} `;
+  const squeezedHaystack = squeeze(norm);
+  const hits = [];
+  for (const entry of entries) {
+    const candidates = [entry.subject_id, ...entry.aliases || []];
+    for (const cand of candidates) {
+      const needle = normalizeForMatch(cand);
+      if (!needle) continue;
+      if (haystack.includes(` ${needle} `)) {
+        hits.push(entry);
+        break;
+      }
+      const sq = squeeze(needle);
+      if (sq.length >= SQUEEZE_MIN && squeezedHaystack.includes(sq)) {
+        hits.push(entry);
+        break;
+      }
+    }
+  }
+  return hits;
+}
+var Prampta = class _Prampta {
+  baseUrl;
+  providerId;
+  licenseeId;
+  token;
+  timeoutMs;
+  maxRetries;
+  retryBackoffMs;
+  failClosed;
+  verifySignature;
+  enforce;
+  pinnedKeys;
+  keySetCache = null;
+  keySetPromise = null;
+  tofuWarned = false;
+  constructor(config = {}) {
+    this.baseUrl = (config.baseUrl || envVar("PRAMPTA_BASE_URL")).replace(/\/+$/, "");
+    this.providerId = config.providerId || envVar("PRAMPTA_PROVIDER_ID");
+    this.licenseeId = config.licenseeId || envVar("PRAMPTA_LICENSEE_ID");
+    this.token = config.token || envVar("PRAMPTA_TOKEN");
+    this.timeoutMs = config.timeoutMs ?? 3e3;
+    this.maxRetries = Math.max(0, config.maxRetries ?? 2);
+    this.retryBackoffMs = config.retryBackoffMs ?? 200;
+    this.failClosed = config.failClosed ?? true;
+    this.verifySignature = config.verifyDecisionSignature ?? true;
+    this.enforce = config.enforce ?? true;
+    this.pinnedKeys = parsePins(config.operatorPublicKeyHex || envVar("PRAMPTA_OPERATOR_PUBLIC_KEY") || "");
+    if (!this.baseUrl) throw new PramptaError("baseUrl is required (or set PRAMPTA_BASE_URL)");
+    if (!this.providerId) throw new PramptaError("providerId is required (or set PRAMPTA_PROVIDER_ID)");
+    if (!this.licenseeId) throw new PramptaError("licenseeId is required (or set PRAMPTA_LICENSEE_ID)");
+    if (!this.token) throw new PramptaError("token is required (or set PRAMPTA_TOKEN)");
+  }
+  // ── Key Discovery ───────────────────────────────────────────────────
+  /** Fetch /keys and check it is self-signed by its current key. Cached. */
+  async fetchVerifiedKeySet() {
+    if (this.keySetCache) return this.keySetCache;
+    if (!this.keySetPromise) {
+      this.keySetPromise = (async () => {
+        const ks = await this.get("/keys");
+        const entries = {};
+        for (const e of ks.keys || []) entries[e.key_id] = e.public_key_hex || "";
+        const currentHex = entries[ks.current_key_id] || "";
+        const sig = ks.signature || "";
+        if (!currentHex || !sig) throw new PramptaSignatureError("Operator key set from /keys is malformed");
+        const body = { ...ks };
+        delete body.signature;
+        const ok = await ed.verifyAsync(hexToBytes(sig), new TextEncoder().encode(canonicalJson(body)), hexToBytes(currentHex));
+        if (!ok) throw new PramptaSignatureError("Operator key set signature is invalid");
+        this.keySetCache = ks;
+        return ks;
+      })();
+    }
+    return this.keySetPromise;
+  }
+  /**
+   * Public key hex to verify a decision signed by `keyId`, enforcing the
+   * pinning trust model. A pinned match returns immediately (no network); an
+   * unpinned key id fails closed in pinned mode; unpinned/TOFU mode resolves
+   * from the self-consistent /keys set with a warning.
+   */
+  async resolveOperatorKey(keyId) {
+    for (const hex of this.pinnedKeys) {
+      if (await keyFingerprint(hex) === keyId) return hex;
+    }
+    if (this.pinnedKeys.length > 0) {
+      throw new PramptaSignatureError(
+        `Decision was signed by operator key '${keyId}', which is not in your pinned set. If PRAMPTA rotated keys, confirm the new key out of band and add it to operatorPublicKeyHex (pin current + next to rotate without downtime). Refusing to trust an unpinned key.`
+      );
+    }
+    const ks = await this.fetchVerifiedKeySet();
+    const entries = {};
+    for (const e of ks.keys || []) entries[e.key_id] = e.public_key_hex || "";
+    const match = entries[keyId];
+    if (!match) {
+      throw new PramptaSignatureError(`Decision key '${keyId}' is not present in the operator key set from /keys.`);
+    }
+    if (!this.tofuWarned) {
+      console.warn(TOFU_WARNING);
+      this.tofuWarned = true;
+    }
+    return match;
+  }
+  // ── Subject Detection ────────────────────────────────────────────────
+  subjectIndexEntries = null;
+  subjectIndexFetchedAt = 0;
+  static SUBJECT_INDEX_TTL_MS = 3e5;
+  /** Fetch the raw subject detection index (/v1/subjects/index). */
+  async fetchSubjectIndex() {
+    return this.get("/v1/subjects/index");
+  }
+  /**
+   * Detect registered subjects mentioned in `text`, using a TTL-cached
+   * copy of the subject index. Call verify()/assertAllowed() per hit.
+   */
+  async matchSubjects(text, opts) {
+    const now = Date.now();
+    if (opts?.forceRefresh || !this.subjectIndexEntries || now - this.subjectIndexFetchedAt > _Prampta.SUBJECT_INDEX_TTL_MS) {
+      const payload = await this.fetchSubjectIndex();
+      this.subjectIndexEntries = payload.subjects || [];
+      this.subjectIndexFetchedAt = now;
+    }
+    return matchSubjects(text, this.subjectIndexEntries);
+  }
+  // ── Signature Verification ──────────────────────────────────────────
+  /**
+   * Verify operator Ed25519 signature over decision body.
+   * Fails closed on any error.
+   */
+  async verifyDecision(raw, decision) {
+    if (!this.verifySignature) return;
+    const sig = decision.operatorSignature;
+    if (!sig) throw new PramptaSignatureError("Decision missing operator_signature");
+    const keyId = decision.operatorKeyId;
+    if (!keyId) throw new PramptaSignatureError("Decision missing operator_key_id");
+    const pubKeyHex = await this.resolveOperatorKey(keyId);
+    const bodyForSigning = { ...raw };
+    delete bodyForSigning.operator_signature;
+    const canonical = canonicalJson(bodyForSigning);
+    const messageBytes = new TextEncoder().encode(canonical);
+    const pubKeyBytes = hexToBytes(pubKeyHex);
+    const sigBytes = hexToBytes(sig);
+    let valid;
+    try {
+      valid = await ed.verifyAsync(sigBytes, messageBytes, pubKeyBytes);
+    } catch (e) {
+      throw new PramptaSignatureError(`Ed25519 verification error: ${e}`);
+    }
+    if (!valid) {
+      throw new PramptaSignatureError(
+        "Operator signature is invalid \u2014 decision cannot be trusted. This may indicate a compromised backend, proxy tampering, or key mismatch."
+      );
+    }
+    const now = Math.floor(Date.now() / 1e3);
+    if (decision.expiresAt > 0 && decision.expiresAt < now) {
+      throw new PramptaSignatureError(
+        `Decision expired at ${decision.expiresAt}, current time ${now}`
+      );
+    }
+  }
+  /**
+   * Verify that the signed decision is bound to the correct request context.
+   * Prevents replay attacks where a valid decision for one context is used in another.
+   */
+  verifyContextBinding(decision, expected) {
+    if (decision.promptHash && decision.promptHash !== expected.promptHash) {
+      throw new PramptaSignatureError(
+        `Decision prompt_hash mismatch: sent ${expected.promptHash}, got ${decision.promptHash}`
+      );
+    }
+    if (decision.subjectId && decision.subjectId !== expected.subjectId) {
+      throw new PramptaSignatureError(
+        `Decision subject_id mismatch: sent ${expected.subjectId}, got ${decision.subjectId}`
+      );
+    }
+    if (decision.providerId && decision.providerId !== expected.providerId) {
+      throw new PramptaSignatureError(
+        `Decision provider_id mismatch: sent ${expected.providerId}, got ${decision.providerId}`
+      );
+    }
+    if (decision.licenseeId && decision.licenseeId !== expected.licenseeId) {
+      throw new PramptaSignatureError(
+        `Decision licensee_id mismatch: sent ${expected.licenseeId}, got ${decision.licenseeId}`
+      );
+    }
+    if (decision.modality && expected.modality && decision.modality !== expected.modality) {
+      throw new PramptaSignatureError(
+        `Decision modality mismatch: sent ${expected.modality}, got ${decision.modality}`
+      );
+    }
+    if (decision.model && expected.model && decision.model !== expected.model) {
+      throw new PramptaSignatureError(
+        `Decision model mismatch: sent ${expected.model}, got ${decision.model}`
+      );
+    }
+    if (expected.intendedUse) {
+      const iu = decision.intendedUse || {};
+      const pairs = [
+        ["product_name", String(iu.product_name || ""), expected.intendedUse.productName],
+        ["project_name", String(iu.project_name || ""), expected.intendedUse.projectName],
+        ["channel", String(iu.channel || ""), expected.intendedUse.channel],
+        ["territory", String(iu.territory || ""), expected.intendedUse.territory]
+      ];
+      for (const [name, got, sent] of pairs) {
+        if (got && sent && got !== sent) {
+          throw new PramptaSignatureError(`Decision ${name} mismatch: sent ${sent}, got ${got}`);
+        }
+      }
+      const gotCats = new Set((Array.isArray(iu.categories) ? iu.categories : []).map(String));
+      const sentCats = new Set(expected.intendedUse.categories || []);
+      if (gotCats.size && sentCats.size) {
+        const same = gotCats.size === sentCats.size && [...sentCats].every((c) => gotCats.has(c));
+        if (!same) {
+          throw new PramptaSignatureError(
+            `Decision categories mismatch: sent ${[...sentCats].sort()}, got ${[...gotCats].sort()}`
+          );
+        }
+      }
+    }
+  }
+  // ── Core API ─────────────────────────────────────────────────────────
+  async verifyGeneration(request) {
+    const promptHash = request.promptHash || (request.prompt ? await sha256(request.prompt) : null);
+    if (!promptHash) {
+      throw new PramptaSchemaError(
+        "Either prompt or promptHash is required. SDK does not allow empty prompt hashes to prevent unbound decisions."
+      );
+    }
+    const payload = {
+      subject_id: request.subjectId,
+      prompt_hash: promptHash,
+      modality: request.modality || "",
+      model: request.model || "",
+      intended_use: {
+        channel: request.intendedUse?.channel || "",
+        product_name: request.intendedUse?.productName || "",
+        project_name: request.intendedUse?.projectName || "",
+        categories: request.intendedUse?.categories || [],
+        modality: request.modality || "",
+        territory: request.intendedUse?.territory || ""
+      }
+    };
+    try {
+      const data = await this.post("/v1/verify/", payload);
+      const decision = this.parseDecision(data);
+      await this.verifyDecision(data, decision);
+      this.verifyContextBinding(decision, {
+        promptHash,
+        subjectId: request.subjectId,
+        providerId: this.providerId,
+        licenseeId: this.licenseeId,
+        modality: request.modality || "",
+        model: request.model || "",
+        intendedUse: {
+          productName: request.intendedUse?.productName || "",
+          projectName: request.intendedUse?.projectName || "",
+          channel: request.intendedUse?.channel || "",
+          territory: request.intendedUse?.territory || "",
+          categories: request.intendedUse?.categories || []
+        }
+      });
+      return decision;
+    } catch (e) {
+      if (this.failClosed) {
+        if (e instanceof PramptaRefusalError || e instanceof PramptaSchemaError || e instanceof PramptaSignatureError) {
+          throw e;
+        }
+        throw new PramptaFailClosedError(e);
+      }
+      throw e;
+    }
+  }
+  /** Flat convenience API mirroring the Python SDK: intended-use fields
+   * (categories, channel, productName, …) are accepted at the top level.
+   * Either `prompt` or `promptHash` is REQUIRED — decisions are bound to
+   * the prompt hash and the SDK refuses to request unbound ones. */
+  async verify(subjectId, options = {}) {
+    const { categories, channel, productName, projectName, territory, intendedUse, ...rest } = options;
+    const iu = intendedUse ?? {
+      ...channel ? { channel } : {},
+      ...productName ? { productName } : {},
+      ...projectName ? { projectName } : {},
+      ...categories ? { categories } : {},
+      ...territory ? { territory } : {}
+    };
+    return this.verifyGeneration({
+      subjectId,
+      ...rest,
+      ...Object.keys(iu).length ? { intendedUse: iu } : {}
+    });
+  }
+  async assertAllowed(subjectId, options = {}) {
+    const decision = await this.verifyGeneration({ subjectId, ...options });
+    if (!decision.allowed) {
+      if (this.enforce) throw new PramptaRefusalError(decision);
+      console.warn(`PRAMPTA monitor mode: would REFUSE (${decision.reason}) but enforce=false \u2014 proceeding.`);
+    }
+    return decision;
+  }
+  async withAuthorization(request, generateFn) {
+    const decision = await this.assertAllowed(request.subjectId, request);
+    const output = await generateFn(decision);
+    const metadata = this.createOutputMetadata(decision);
+    return { output, decision, metadata };
+  }
+  // ── Subject Resolution ───────────────────────────────────────────────
+  async getSubject(subjectId) {
+    try {
+      const data = await this.get(`/v1/subjects/${encodeURIComponent(subjectId)}`);
+      return {
+        subjectId: data.subject_id,
+        status: data.status,
+        visibility: data.visibility || "public",
+        rulesText: data.rules_text || "",
+        aliases: data.aliases || [],
+        publicKeyHex: data.public_key_hex,
+        registeredAt: data.registered_at
+      };
+    } catch {
+      return null;
+    }
+  }
+  // ── License Request ──────────────────────────────────────────────────
+  async requestLicense(input) {
+    const data = await this.post("/v1/license-requests/", {
+      subject_id: input.subjectId,
+      use_case: input.useCase,
+      purpose: input.purpose || "",
+      duration_days: input.durationDays || 365,
+      message: input.message || ""
+    });
+    return { requestId: data.request_id, status: data.status };
+  }
+  // ── Provenance / Output Metadata ─────────────────────────────────────
+  createOutputMetadata(decision) {
+    return {
+      prampta_decision_id: decision.decisionId,
+      prampta_license_id: decision.licenseId,
+      prampta_watermark: decision.watermarkPayload,
+      prampta_obligations: decision.obligations,
+      prampta_issued_at: decision.issuedAt
+    };
+  }
+  /**
+   * Submit a generation receipt AFTER generating — the provider's enforcement
+   * proof, bound to the decision it acted on. Records that this generation was
+   * authorized and executed under the decision's terms (verifiable post-hoc).
+   */
+  async submitReceipt(decision, result = {}) {
+    return this.post("/v1/receipts/", {
+      decision_id: decision.decisionId,
+      prompt_hash: decision.promptHash,
+      output_hash: result.outputHash ?? "",
+      model: result.model ?? decision.model,
+      watermark_embedded: result.watermarkEmbedded ?? false,
+      obligations_applied: result.obligationsApplied ?? decision.obligations ?? {},
+      generated_at: result.generatedAt ?? Math.floor(Date.now() / 1e3)
+    });
+  }
+  // ── Utility ──────────────────────────────────────────────────────────
+  async health() {
+    try {
+      await this.get("/healthz");
+      return true;
+    } catch {
+      return false;
+    }
+  }
+  async version() {
+    return this.get("/version");
+  }
+  static async hashPrompt(prompt) {
+    return sha256(prompt);
+  }
+  // ── Internal ─────────────────────────────────────────────────────────
+  parseDecision(data) {
+    if (!data.decision_id) throw new PramptaSchemaError("Response missing decision_id");
+    return {
+      schemaVersion: data.schema_version || "pg.decision.v1",
+      decisionId: data.decision_id,
+      allowed: data.allowed ?? false,
+      reason: data.reason ?? null,
+      subjectId: data.subject_id || "",
+      licenseeId: data.licensee_id || "",
+      providerId: data.provider_id || "",
+      licenseId: data.license_id ?? null,
+      promptHash: data.prompt_hash || "",
+      model: data.model || "",
+      modality: data.modality || "",
+      intendedUse: data.intended_use || {},
+      obligations: data.obligations || {},
+      rulesText: data.rules_text || "",
+      rulesTextHash: data.rules_text_hash || "",
+      watermarkPayload: data.watermark_payload ?? null,
+      isHardRefusal: data.is_hard_refusal ?? false,
+      issuedAt: data.issued_at || 0,
+      expiresAt: data.expires_at || 0,
+      operatorKeyId: data.operator_key_id || "",
+      operatorSignature: data.operator_signature || "",
+      subjectAuthority: data.subject_authority || "",
+      denied: !(data.allowed ?? false)
+    };
+  }
+  headers() {
+    return {
+      "Content-Type": "application/json",
+      "X-Provider-ID": this.providerId,
+      "X-Licensee-ID": this.licenseeId,
+      Authorization: `Bearer ${this.token}`
+    };
+  }
+  /** Transient errors worth retrying: connectivity, timeout, 429, and 5xx. */
+  isRetryable(e) {
+    if (e instanceof PramptaNetworkError || e instanceof PramptaTimeoutError) return true;
+    if (e instanceof PramptaApiError) return e.status >= 500 || e.status === 429;
+    return false;
+  }
+  async withRetry(fn) {
+    let lastErr;
+    for (let attempt = 0; attempt <= this.maxRetries; attempt++) {
+      try {
+        return await fn();
+      } catch (e) {
+        lastErr = e;
+        if (attempt >= this.maxRetries || !this.isRetryable(e)) throw e;
+        const delay = this.retryBackoffMs * Math.pow(2, attempt);
+        await new Promise((r) => setTimeout(r, delay));
+      }
+    }
+    throw lastErr;
+  }
+  async post(path, payload) {
+    return this.withRetry(() => this.postOnce(path, payload));
+  }
+  async postOnce(path, payload) {
+    let resp;
+    try {
+      resp = await fetch(`${this.baseUrl}${path}`, {
+        method: "POST",
+        headers: this.headers(),
+        body: JSON.stringify(payload),
+        signal: AbortSignal.timeout(this.timeoutMs)
+      });
+    } catch (e) {
+      if (e?.name === "TimeoutError" || e?.name === "AbortError") throw new PramptaTimeoutError(this.timeoutMs);
+      throw new PramptaNetworkError(e);
+    }
+    if (!resp.ok) {
+      const text = await resp.text();
+      let detail = text;
+      try {
+        detail = JSON.parse(text).detail ?? text;
+      } catch {
+      }
+      throw new PramptaApiError(resp.status, String(detail));
+    }
+    return resp.json();
+  }
+  async get(path) {
+    return this.withRetry(() => this.getOnce(path));
+  }
+  async getOnce(path) {
+    let resp;
+    try {
+      resp = await fetch(`${this.baseUrl}${path}`, {
+        method: "GET",
+        headers: this.headers(),
+        signal: AbortSignal.timeout(this.timeoutMs)
+      });
+    } catch (e) {
+      if (e?.name === "TimeoutError" || e?.name === "AbortError") throw new PramptaTimeoutError(this.timeoutMs);
+      throw new PramptaNetworkError(e);
+    }
+    if (!resp.ok) throw new PramptaApiError(resp.status, await resp.text());
+    return resp.json();
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  HARD_REFUSAL_CODES,
+  Prampta,
+  PramptaApiError,
+  PramptaError,
+  PramptaFailClosedError,
+  PramptaNetworkError,
+  PramptaRefusalError,
+  PramptaSchemaError,
+  PramptaSignatureError,
+  PramptaTimeoutError,
+  REFUSAL_DESCRIPTIONS,
+  SOFT_REFUSAL_CODES,
+  canonicalJson,
+  hashPrompt,
+  matchSubjects,
+  normalizeForMatch
+});