@leashkit/grant 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Media Yard LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,56 @@
-# Temporary Holding Version
+# @leashkit/grant
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Let your customer set the limits on what your agent may do on their account, and hold the agent to them.
+Guide and a live demo: https://leashkit.com/grants
+
+```js
+import { grantRequestUrl, verifyGrant, fetchGrantStatus, withStatus, evaluate, ZERO_CONSUMPTION, LEASH_GRANT_KEY } from '@leashkit/grant';
+
+// 1. Ask. Send the customer here.
+const url = grantRequestUrl({
+  v: 1,
+  vendor: { id: 'acme-crm', name: 'Acme CRM', class: 'crm' },
+  agent: { id: 'acme-assistant' },
+  subjectRef: 'cust_8f3a',                       // your opaque handle, never an email
+  scopes: [{ tool: 'email.outbox', action: 'send' }],
+  budget: { maxSends: 20 },
+  ttlSeconds: 7 * 86400,
+  returnUrl: 'https://app.acme.dev/leash/return',
+  state: 'abc123',
+});
+
+// 2. Receive. The customer comes back with #grant=<token>&state=abc123.
+const signed = await verifyGrant(token, LEASH_GRANT_KEY);
+if (!signed || signed.host !== 'app.acme.dev') throw new Error('not a grant for us');
+let grant = signed.grant;
+let consumed = ZERO_CONSUMPTION;                 // keep this per grant, in your own storage
+
+// 3. Enforce, before every action.
+const status = await fetchGrantStatus(grant.id, fetch);   // reuse an answer for up to 60 seconds
+if (status) grant = withStatus(grant, status);            // undefined = unknown: keep your last answer
+const result = evaluate({ permit: grant, consumed, scope: { tool: 'email.outbox', action: 'send' }, at: Date.now() });
+consumed = result.consumed;
+if (result.decision.verdict === 'allow') await sendTheEmail();
+// result.decision.summary is a plain sentence for the customer; result.outcome is the record of the decision.
+```
+
+## Let the customer see what the agent did (optional)
+
+Each decision has a receipt, and each receipt carries the hash of the one before it. Send them, and the customer can
+read the log from their own grant page.
+
+```js
+import { append, sendReceipts } from '@leashkit/grant';
+
+chain = append(chain, { permitId: grant.id, decision: result.decision, outcome: result.outcome, at: Date.now() });
+const { ok, stored, problem } = await sendReceipts(permitToken, chain.slice(alreadySent), fetch);
+if (ok) alreadySent = stored;
+```
+
+The signed grant is what entitles you to write to its log. A receipt holds a time, the decision, the tool, the action
+and the ids already in the grant; Leash refuses one that holds anything else. The log is deleted 30 days after the
+grant ends.
+
+A grant holds an agent only where your code checks it. Leash signs what the customer allowed and publishes whether
+they switched it off; it is not in the path of your agent's calls. Your counts stay with you, and so do your receipts
+unless you choose to send them.

package/index.d.ts

@@ -0,0 +1 @@
+export * from './permit-client.js';

package/index.js

@@ -0,0 +1,431 @@
+// src/types.ts
+var ACTION_KINDS = ["read", "write", "send", "delete", "pay"];
+var ZERO_CONSUMPTION = Object.freeze({
+  read: 0,
+  write: 0,
+  send: 0,
+  delete: 0,
+  pay: 0,
+  usd: 0
+});
+
+// src/unlock.ts
+var ALG = { name: "ECDSA", namedCurve: "P-256" };
+var SIGN = { name: "ECDSA", hash: "SHA-256" };
+function b64url(bytes) {
+  let bin = "";
+  for (const b of bytes) bin += String.fromCharCode(b);
+  return btoa(bin).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+function fromB64url(text) {
+  if (!/^[A-Za-z0-9_-]*$/.test(text)) return void 0;
+  try {
+    const bin = atob(text.replace(/-/g, "+").replace(/_/g, "/") + "=".repeat((4 - text.length % 4) % 4));
+    return Uint8Array.from(bin, (c) => c.charCodeAt(0));
+  } catch {
+    return void 0;
+  }
+}
+async function verifyJson(token, publicJwk, maxLength = 16384) {
+  const [body, sig, extra] = token.split(".");
+  if (body === void 0 || sig === void 0 || extra !== void 0 || token.length > maxLength) return void 0;
+  const sigBytes = fromB64url(sig);
+  const bodyBytes = fromB64url(body);
+  if (sigBytes === void 0 || bodyBytes === void 0) return void 0;
+  try {
+    const key = await crypto.subtle.importKey("jwk", publicJwk, ALG, false, ["verify"]);
+    if (!await crypto.subtle.verify(SIGN, key, sigBytes, new TextEncoder().encode(body))) return void 0;
+    return JSON.parse(new TextDecoder().decode(bodyBytes));
+  } catch {
+    return void 0;
+  }
+}
+function packJson(value) {
+  return b64url(new TextEncoder().encode(JSON.stringify(value)));
+}
+function unpackJson(text) {
+  const bytes = fromB64url(text);
+  if (bytes === void 0) return void 0;
+  try {
+    return JSON.parse(new TextDecoder().decode(bytes));
+  } catch {
+    return void 0;
+  }
+}
+
+// src/permit.ts
+var MAX_SCOPES = 50;
+var MIN_TTL_SECONDS = 60;
+var MAX_TTL_SECONDS = 90 * 86400;
+var STATUS_MAX_AGE_SECONDS = 60;
+var ID = /^[A-Za-z0-9][A-Za-z0-9._:/@-]{0,99}$/;
+var TOOL = /^[A-Za-z0-9][A-Za-z0-9._:/-]{0,119}$/;
+var BUDGET_KEYS = ["maxReads", "maxWrites", "maxSends", "maxDeletes", "maxPayments", "maxUsd"];
+var isObject = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+var isText = (v, max) => typeof v === "string" && v.length > 0 && v.length <= max && !/[\u0000-\u001f\u007f]/.test(v);
+var isCount = (v) => typeof v === "number" && Number.isInteger(v) && v >= 0 && v <= 1e9;
+function returnTarget(url) {
+  if (typeof url !== "string" || url.length > 600) return void 0;
+  let parsed;
+  try {
+    parsed = new URL(url);
+  } catch {
+    return void 0;
+  }
+  const local = ["localhost", "127.0.0.1", "[::1]"].includes(parsed.hostname);
+  if (parsed.protocol !== "https:" && !(parsed.protocol === "http:" && local)) return void 0;
+  if (parsed.username !== "" || parsed.password !== "" || parsed.hash !== "") return void 0;
+  return parsed;
+}
+function parsePermitRequest(raw) {
+  const problems = [];
+  const bad = (path, message) => void problems.push({ path, message });
+  if (!isObject(raw)) return { request: void 0, problems: [{ path: "", message: "the request must be a JSON object" }] };
+  if (raw["v"] !== 1) bad("v", "must be 1");
+  const vendor = raw["vendor"];
+  if (!isObject(vendor)) bad("vendor", "is missing");
+  else {
+    if (typeof vendor["id"] !== "string" || !ID.test(vendor["id"])) bad("vendor.id", "is letters, digits and . _ : / @ -, up to 100");
+    if (!isText(vendor["name"], 80)) bad("vendor.name", "is 1 to 80 characters");
+    if (typeof vendor["class"] !== "string" || !ID.test(vendor["class"])) bad("vendor.class", 'is a short category such as "crm" or "support"');
+  }
+  const agent = raw["agent"];
+  if (!isObject(agent)) bad("agent", "is missing");
+  else {
+    if (typeof agent["id"] !== "string" || !ID.test(agent["id"])) bad("agent.id", "is letters, digits and . _ : / @ -, up to 100");
+    if (agent["model"] !== void 0 && !isText(agent["model"], 80)) bad("agent.model", "is up to 80 characters");
+  }
+  if (typeof raw["subjectRef"] !== "string" || !ID.test(raw["subjectRef"])) bad("subjectRef", "is an opaque handle: letters, digits and . _ : / -, up to 100");
+  else if (raw["subjectRef"].includes("@")) bad("subjectRef", "must not be an email address: use an opaque id");
+  const scopes = [];
+  if (!Array.isArray(raw["scopes"]) || raw["scopes"].length === 0) bad("scopes", "must list at least one capability");
+  else if (raw["scopes"].length > MAX_SCOPES) bad("scopes", `lists more than ${MAX_SCOPES} capabilities`);
+  else {
+    const seen = /* @__PURE__ */ new Set();
+    raw["scopes"].forEach((s, i) => {
+      if (!isObject(s) || typeof s["tool"] !== "string" || !TOOL.test(s["tool"])) return bad(`scopes.${i}.tool`, "is a tool name: letters, digits and . _ : / -");
+      if (!ACTION_KINDS.includes(s["action"])) return bad(`scopes.${i}.action`, "is one of read, write, send, delete, pay");
+      if (s["requiresApproval"] !== void 0 && typeof s["requiresApproval"] !== "boolean") return bad(`scopes.${i}.requiresApproval`, "is true or false");
+      const key = `${s["action"]} ${s["tool"]}`;
+      if (seen.has(key)) return bad(`scopes.${i}`, "repeats an earlier capability");
+      seen.add(key);
+      scopes.push({ tool: s["tool"], action: s["action"], ...s["requiresApproval"] === true ? { requiresApproval: true } : {} });
+    });
+  }
+  const budget = {};
+  const rawBudget = raw["budget"] ?? {};
+  if (!isObject(rawBudget)) bad("budget", "must be an object");
+  else
+    for (const [k, v2] of Object.entries(rawBudget)) {
+      if (!BUDGET_KEYS.includes(k)) bad(`budget.${k}`, "is not a limit this grant can carry");
+      else if (!isCount(v2)) bad(`budget.${k}`, "is a whole number, zero or more");
+      else budget[k] = v2;
+    }
+  const ttl = raw["ttlSeconds"];
+  if (typeof ttl !== "number" || !Number.isInteger(ttl) || ttl < MIN_TTL_SECONDS || ttl > MAX_TTL_SECONDS) {
+    bad("ttlSeconds", `is a whole number of seconds from ${MIN_TTL_SECONDS} to ${MAX_TTL_SECONDS} (90 days)`);
+  }
+  if (returnTarget(raw["returnUrl"]) === void 0) bad("returnUrl", "is an https address with no fragment (http only on localhost)");
+  if (raw["state"] !== void 0 && (typeof raw["state"] !== "string" || !/^[A-Za-z0-9._~-]{1,200}$/.test(raw["state"]))) bad("state", "is up to 200 URL-safe characters");
+  if (problems.length > 0) return { request: void 0, problems };
+  const v = vendor;
+  const a = agent;
+  return {
+    request: {
+      v: 1,
+      vendor: { id: v["id"], name: v["name"], class: v["class"] },
+      agent: { id: a["id"], ...a["model"] === void 0 ? {} : { model: a["model"] } },
+      subjectRef: raw["subjectRef"],
+      scopes,
+      budget,
+      ttlSeconds: ttl,
+      returnUrl: raw["returnUrl"],
+      ...raw["state"] === void 0 ? {} : { state: raw["state"] }
+    },
+    problems
+  };
+}
+function permitRequestUrl(request, base = "https://leashkit.com") {
+  return `${base.replace(/\/+$/, "")}/grant.html#req=${packJson(request)}`;
+}
+function readPermitRequest(packed) {
+  return parsePermitRequest(unpackJson(packed));
+}
+async function verifyPermit(token, publicJwk) {
+  const value = await verifyJson(token, publicJwk);
+  if (!isObject(value) || value["v"] !== 1 || typeof value["aud"] !== "string") return void 0;
+  const p = value["t"] === "grant" ? value["grant"] : value["t"] === "permit" ? value["permit"] : void 0;
+  if (!isObject(p)) return void 0;
+  if (typeof p["id"] !== "string" || typeof p["issuedAt"] !== "number" || typeof p["expiresAt"] !== "number" || !Array.isArray(p["scopes"]) || !isObject(p["budget"])) return void 0;
+  return { grant: p, host: value["aud"] };
+}
+function withStatus(grant, status) {
+  if (!status.revoked || status.id !== grant.id) return grant;
+  return { ...grant, revokedAt: status.revokedAt ?? grant.issuedAt, revokedBy: "customer" };
+}
+async function fetchPermitStatus(id, fetchImpl, base = "https://leashkit.com") {
+  try {
+    const res = await fetchImpl(`${base.replace(/\/+$/, "")}/api/grant-status?id=${encodeURIComponent(id)}`);
+    if (!res.ok) return void 0;
+    const body = await res.json();
+    return body.id === id && typeof body.revoked === "boolean" ? body : void 0;
+  } catch {
+    return void 0;
+  }
+}
+var RECEIPTS_PER_REQUEST = 200;
+async function sendReceipts(permitToken, receipts, fetchImpl, base = "https://leashkit.com") {
+  let stored;
+  try {
+    for (let from = 0; from < receipts.length; from += RECEIPTS_PER_REQUEST) {
+      const res = await fetchImpl(`${base.replace(/\/+$/, "")}/api/grant-receipts`, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ grant: permitToken, receipts: receipts.slice(from, from + RECEIPTS_PER_REQUEST) })
+      });
+      const body = await res.json().catch(() => ({}));
+      if (!res.ok) return { ok: false, ...stored === void 0 ? {} : { stored }, problem: body.detail ?? body.error ?? `HTTP ${res.status}` };
+      stored = body.stored;
+    }
+  } catch (error) {
+    return { ok: false, ...stored === void 0 ? {} : { stored }, problem: error instanceof Error ? error.message : "the request failed" };
+  }
+  return { ok: true, ...stored === void 0 ? {} : { stored } };
+}
+var VERB = { read: "Read from", write: "Make changes in", send: "Send through", delete: "Delete from", pay: "Move money through" };
+function describeScope(scope) {
+  return `${VERB[scope.action]} ${scope.tool}`;
+}
+
+// src/budget.ts
+var CAP_FIELD = Object.freeze({
+  read: "maxReads",
+  write: "maxWrites",
+  send: "maxSends",
+  delete: "maxDeletes",
+  pay: "maxPayments"
+});
+function capFor(budget, action) {
+  const value = budget[CAP_FIELD[action]];
+  return typeof value === "number" ? value : null;
+}
+function spentOn(consumed, action) {
+  return consumed[action];
+}
+function wouldExhaust(budget, consumed, action, units) {
+  const cap = capFor(budget, action);
+  if (cap === null) return false;
+  return spentOn(consumed, action) + units > cap;
+}
+function wouldExhaustUsd(budget, consumed, usd) {
+  if (typeof budget.maxUsd !== "number") return false;
+  return consumed.usd + usd > budget.maxUsd;
+}
+function utilization(budget, consumed, action) {
+  const cap = capFor(budget, action);
+  if (cap === null) return null;
+  if (cap === 0) return 1;
+  return Math.min(1, spentOn(consumed, action) / cap);
+}
+function applySpend(consumed, action, units, usd) {
+  return {
+    ...consumed,
+    [action]: consumed[action] + units,
+    usd: consumed.usd + usd
+  };
+}
+
+// src/outcome.ts
+var MS_PER_SECOND = 1e3;
+var FORBIDDEN_OUTCOME_FIELDS = Object.freeze([
+  "subjectRef",
+  "subject",
+  "customerId",
+  "customerEmail",
+  "email",
+  "name",
+  "phone",
+  "address",
+  "ip",
+  "userId"
+]);
+function outcomeKindFor(verdict, reasons) {
+  if (verdict === "allow") return "approved";
+  if (verdict === "escalate") return "escalated";
+  if (reasons.includes("revoked")) return "revoked-mid-run";
+  if (reasons.includes("cap-exhausted") || reasons.includes("usd-cap-exhausted")) {
+    return "cap-exhausted";
+  }
+  return "denied";
+}
+function buildOutcome(input) {
+  const { permit, scope, verdict, reasons, consumedAfter, at } = input;
+  const action = scope.action;
+  const base = {
+    recordedAt: at,
+    outcome: outcomeKindFor(verdict, reasons),
+    vendorId: permit.vendorId,
+    vendorClass: permit.vendorClass,
+    agentId: permit.agentId,
+    tool: scope.tool,
+    action,
+    ttlSeconds: Math.round((permit.expiresAt - permit.issuedAt) / MS_PER_SECOND),
+    capValue: capFor(permit.budget, action),
+    capUtilization: utilization(permit.budget, consumedAfter, action),
+    reasons
+  };
+  return permit.agentModel === void 0 ? base : { ...base, agentModel: permit.agentModel };
+}
+
+// src/policy.ts
+var DEFAULT_UNITS = 1;
+var DEFAULT_USD = 0;
+var DENY_LADDER = Object.freeze([
+  "revoked",
+  "not-yet-valid",
+  "expired",
+  "scope-not-granted",
+  "cap-exhausted",
+  "usd-cap-exhausted"
+]);
+function isRevoked(permit, at) {
+  return typeof permit.revokedAt === "number" && permit.revokedAt <= at;
+}
+function grantFor(permit, requested) {
+  return permit.scopes.find(
+    (s) => s.tool === requested.tool && s.action === requested.action
+  );
+}
+function summarize(verdict, reasons, scope) {
+  const what = `${scope.action} on ${scope.tool}`;
+  if (verdict === "allow") return `Allowed: ${what}.`;
+  if (verdict === "escalate") return `Held for your approval: ${what}.`;
+  const reason = reasons[0];
+  switch (reason) {
+    case "revoked":
+      return `Blocked: ${what}. This permission was turned off.`;
+    case "expired":
+      return `Blocked: ${what}. This permission had run out of time.`;
+    case "not-yet-valid":
+      return `Blocked: ${what}. This permission had not started yet.`;
+    case "scope-not-granted":
+      return `Blocked: ${what}. That was never allowed.`;
+    case "cap-exhausted":
+      return `Blocked: ${what}. The limit you set had been reached.`;
+    case "usd-cap-exhausted":
+      return `Blocked: ${what}. The spending limit you set had been reached.`;
+    default:
+      return `Blocked: ${what}.`;
+  }
+}
+function denyReasons(request, units, usd) {
+  const { permit, consumed, scope, at } = request;
+  const grant = grantFor(permit, scope);
+  const applies = {
+    revoked: isRevoked(permit, at),
+    "not-yet-valid": at < permit.issuedAt,
+    expired: at >= permit.expiresAt,
+    "scope-not-granted": grant === void 0,
+    "cap-exhausted": wouldExhaust(permit.budget, consumed, scope.action, units),
+    "usd-cap-exhausted": wouldExhaustUsd(permit.budget, consumed, usd)
+  };
+  return DENY_LADDER.filter((reason) => applies[reason]);
+}
+function evaluate(request) {
+  const units = request.units ?? DEFAULT_UNITS;
+  const usd = request.usd ?? DEFAULT_USD;
+  const { permit, consumed, scope, at } = request;
+  const denies = denyReasons(request, units, usd);
+  let verdict;
+  let reasons;
+  if (denies.length > 0) {
+    verdict = "deny";
+    reasons = denies;
+  } else if (grantFor(permit, scope)?.requiresApproval === true) {
+    verdict = "escalate";
+    reasons = ["scope-requires-approval"];
+  } else {
+    verdict = "allow";
+    reasons = [];
+  }
+  const consumedAfter = verdict === "allow" ? applySpend(consumed, scope.action, units, usd) : consumed;
+  const decision = {
+    verdict,
+    reasons,
+    summary: summarize(verdict, reasons, scope)
+  };
+  return {
+    decision,
+    outcome: buildOutcome({ permit, scope, verdict, reasons, consumedAfter, at }),
+    consumed: consumedAfter
+  };
+}
+
+// src/receipt.ts
+import { createHash } from "node:crypto";
+
+// src/canonical.ts
+function canonicalJson(value) {
+  if (value === null || typeof value !== "object") return JSON.stringify(value) ?? "null";
+  if (Array.isArray(value)) return `[${value.map(canonicalJson).join(",")}]`;
+  const entries = Object.entries(value).filter(([, v]) => v !== void 0).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0).map(([k, v]) => `${JSON.stringify(k)}:${canonicalJson(v)}`);
+  return `{${entries.join(",")}}`;
+}
+
+// src/receipt.ts
+var GENESIS_HASH = "0".repeat(64);
+function digest(body) {
+  return createHash("sha256").update(canonicalJson(body)).digest("hex");
+}
+function append(chain, input) {
+  const prev = chain[chain.length - 1];
+  const body = {
+    seq: chain.length,
+    at: input.at,
+    permitId: input.permitId,
+    verdict: input.decision.verdict,
+    summary: input.decision.summary,
+    outcome: input.outcome,
+    prevHash: prev?.hash ?? GENESIS_HASH
+  };
+  return [...chain, { ...body, hash: digest(body) }];
+}
+function verify(chain) {
+  const faults = [];
+  chain.forEach((receipt, index) => {
+    if (receipt.seq !== index) faults.push({ kind: "bad-sequence", at: index });
+    const expectedPrev = index === 0 ? GENESIS_HASH : chain[index - 1].hash;
+    if (receipt.prevHash !== expectedPrev) faults.push({ kind: "broken-link", at: index });
+    const { hash, ...body } = receipt;
+    if (digest(body) !== hash) faults.push({ kind: "tampered", at: index });
+  });
+  return { ok: faults.length === 0, faults };
+}
+
+// src/permit-client.ts
+var LEASH_GRANT_KEY = {
+  kty: "EC",
+  crv: "P-256",
+  x: "fGWTh5kNhl9gA2fuq53IU7-PxIhei-Nq64NOGN5l13A",
+  y: "wUWZ49qT48ZtWcagElshI78A25mFjTXTuTL3CaMo9RU"
+};
+export {
+  ACTION_KINDS,
+  GENESIS_HASH,
+  LEASH_GRANT_KEY,
+  MAX_TTL_SECONDS,
+  RECEIPTS_PER_REQUEST,
+  STATUS_MAX_AGE_SECONDS,
+  ZERO_CONSUMPTION,
+  append,
+  describeScope,
+  evaluate,
+  fetchPermitStatus as fetchGrantStatus,
+  permitRequestUrl as grantRequestUrl,
+  parsePermitRequest as parseGrantRequest,
+  readPermitRequest as readGrantRequest,
+  sendReceipts,
+  verify,
+  verifyPermit as verifyGrant,
+  withStatus
+};

package/package.json

@@ -1,6 +1,32 @@
 {
   "name": "@leashkit/grant",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "license": "MIT",
+  "type": "module",
+  "description": "Leash Grant for agents: ask a customer to approve limits, verify the signed grant, and hold your agent to it.",
+  "keywords": [
+    "mcp",
+    "agents",
+    "permissions",
+    "consent",
+    "leash"
+  ],
+  "main": "index.js",
+  "types": "index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "default": "./index.js"
+    }
+  },
+  "files": [
+    "*.js",
+    "*.d.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "homepage": "https://leashkit.com/grants"
+}

package/permit-client.d.ts

@@ -0,0 +1,20 @@
+/**
+ * What a vendor needs to use Leash Grant: build a request, read the signed
+ * grant that comes back, learn whether it was revoked, and hold an agent to it
+ * with the gate. This is the public surface of the published package; the
+ * endpoints Leash itself answers are not part of it.
+ *
+ * The names here say "grant". The modules behind them were written when the
+ * product had another name and still say "permit"; nobody outside reads those.
+ * The gate's own input keeps its field: `evaluate({ permit: grant, … })`.
+ */
+export { permitRequestUrl as grantRequestUrl, parsePermitRequest as parseGrantRequest, readPermitRequest as readGrantRequest, verifyPermit as verifyGrant, fetchPermitStatus as fetchGrantStatus, withStatus, sendReceipts, RECEIPTS_PER_REQUEST, describeScope, STATUS_MAX_AGE_SECONDS, MAX_TTL_SECONDS, } from './permit.js';
+export type { PermitRequest as GrantRequest, PermitStatus as GrantStatus, Problem, SendResult } from './permit.js';
+export { evaluate } from './policy.js';
+export { append, verify, GENESIS_HASH } from './receipt.js';
+export type { Receipt, Verification, ChainFault, AppendInput } from './receipt.js';
+export { ZERO_CONSUMPTION, ACTION_KINDS } from './types.js';
+export type { ActionKind, ActionBudget, Consumption, Decision, GateRequest, Permit as Grant, Scope, Verdict } from './types.js';
+import type { Jwk } from './unlock.js';
+/** The public key Leash signs grants with. A test holds it equal to the key the site publishes. */
+export declare const LEASH_GRANT_KEY: Jwk;

package/permit.d.ts

@@ -0,0 +1,167 @@
+import type { ActionBudget, ActionKind, Permit, Scope } from './types.js';
+import type { Jwk } from './unlock.js';
+/**
+ * Leash Grant: a vendor asks, the customer narrows and approves, and the
+ * vendor's agent is handed a signed grant it must obey.
+ *
+ * What Leash holds is deliberately almost nothing. The grant is a signed token
+ * the vendor keeps; the counters and receipts stay with the vendor, in the gate
+ * they run themselves. The one thing kept here is a revocation: a grant id and
+ * the moment its customer switched it off. A grant nobody revoked has no record
+ * at all.
+ *
+ * Nothing in a request is trusted for what it says about itself. The name a
+ * vendor gives is shown as a claim; the address the customer is sent back to is
+ * shown as the fact, because that is the only part a vendor cannot make up.
+ */
+export interface PermitRequest {
+    readonly v: 1;
+    readonly vendor: {
+        readonly id: string;
+        readonly name: string;
+        readonly class: string;
+    };
+    readonly agent: {
+        readonly id: string;
+        readonly model?: string;
+    };
+    /** The vendor's opaque handle for this customer. Never an email or a name; it is not shown and not stored. */
+    readonly subjectRef: string;
+    readonly scopes: readonly Scope[];
+    readonly budget: ActionBudget;
+    /** How long the grant should last. The customer may shorten it. */
+    readonly ttlSeconds: number;
+    /** Where the customer is sent with the signed grant. https, or http on localhost while developing. */
+    readonly returnUrl: string;
+    /** Echoed back unchanged, so the vendor can tie the answer to the question. */
+    readonly state?: string;
+}
+export type Problem = {
+    readonly path: string;
+    readonly message: string;
+};
+export declare const MAX_SCOPES = 50;
+export declare const MIN_TTL_SECONDS = 60;
+export declare const MAX_TTL_SECONDS: number;
+/** How long a vendor may reuse a status answer before asking again. A revocation is in force within this long. */
+export declare const STATUS_MAX_AGE_SECONDS = 60;
+export declare const BUDGET_FOR: Readonly<Record<ActionKind, keyof ActionBudget>>;
+/** The address a customer may be sent back to, or undefined. Its host is the vendor's identity on the page. */
+export declare function returnTarget(url: unknown): URL | undefined;
+/** Reads a grant request. Anything wrong and there is no request: a consent screen must not guess what was meant. */
+export declare function parsePermitRequest(raw: unknown): {
+    readonly request: PermitRequest | undefined;
+    readonly problems: readonly Problem[];
+};
+/** The link a vendor sends a customer to. The request rides in the fragment, which browsers send to no server. */
+export declare function permitRequestUrl(request: PermitRequest, base?: string): string;
+export declare function readPermitRequest(packed: string): ReturnType<typeof parsePermitRequest>;
+/** What the customer chose on the consent screen. Every field can only take away. */
+export interface Choices {
+    /** Indexes of the requested scopes the customer kept. */
+    readonly keep: readonly number[];
+    /** Indexes of kept scopes the customer wants to be asked about each time. */
+    readonly ask: readonly number[];
+    readonly budget: ActionBudget;
+    readonly ttlSeconds: number;
+}
+/**
+ * The request as the customer approved it. Nothing here can exceed what was
+ * asked: a larger cap is cut to the request's, an uncapped action stays capped
+ * if the customer set a number, and an approval the vendor asked for stays.
+ */
+export declare function narrow(request: PermitRequest, choices: Choices): PermitRequest;
+export declare function permitFrom(request: PermitRequest, id: string, nowMs: number): Permit;
+/** What the customer keeps: the right to look at and switch off one grant. Never shown to the vendor. */
+export interface ManageClaims {
+    readonly v: 1;
+    readonly t: 'manage';
+    readonly id: string;
+    readonly vendorName: string;
+    readonly host: string;
+    readonly scopes: readonly Scope[];
+    readonly budget: ActionBudget;
+    readonly issuedAt: number;
+    readonly expiresAt: number;
+}
+export declare function signPermit(grant: Permit, host: string, privateJwk: Jwk): Promise<string>;
+/**
+ * The grant inside a token, if Leash signed it. It says nothing about whether
+ * the grant has since been revoked or has run out: `evaluate()` checks the
+ * dates, and `withStatus()` carries a revocation into it.
+ */
+export declare function verifyPermit(token: string, publicJwk: Jwk): Promise<{
+    readonly grant: Permit;
+    readonly host: string;
+} | undefined>;
+export declare function verifyManage(token: string, publicJwk: Jwk): Promise<ManageClaims | undefined>;
+export interface Revocation {
+    readonly revokedAt: number;
+    /** Kept so the record can be dropped once the grant would have ended anyway. */
+    readonly expiresAt: number;
+}
+export interface PermitStatus {
+    readonly id: string;
+    readonly revoked: boolean;
+    readonly revokedAt?: number;
+}
+/** The grant as the gate should see it: a revocation becomes `revokedAt`, so `evaluate()` declines every call. */
+export declare function withStatus(grant: Permit, status: PermitStatus): Permit;
+/** Asks Leash whether a grant has been revoked. One GET, no credentials: the id is the unguessable part. */
+export declare function fetchPermitStatus(id: string, fetchImpl: (url: string) => Promise<Response>, base?: string): Promise<PermitStatus | undefined>;
+/** How many receipts one call to `sendReceipts` may carry. */
+export declare const RECEIPTS_PER_REQUEST = 200;
+/** How many receipts Leash holds for one grant. */
+export declare const MAX_RECEIPTS_PER_PERMIT = 5000;
+/** How long after a grant ends its log and any revocation are kept before the daily sweep removes them. */
+export declare const KEEP_DAYS_AFTER_END = 30;
+export interface SendResult {
+    readonly ok: boolean;
+    /** How many receipts Leash now holds for the grant. Send from this position next time. */
+    readonly stored?: number;
+    /** Why it was refused, in Leash's words. */
+    readonly problem?: string;
+}
+/**
+ * Optional: sends receipts to Leash so the customer can read what the agent did
+ * from their own grant page. `permitToken` is the signed grant you were handed,
+ * and is what entitles you to write to its log. Send the chain from wherever you
+ * left off; receipts Leash already holds are skipped, so sending again is safe.
+ * Nothing but the receipts leaves: they describe tools and decisions, never a person.
+ */
+export declare function sendReceipts(permitToken: string, receipts: readonly unknown[], fetchImpl: (url: string, init: {
+    method: string;
+    headers: Record<string, string>;
+    body: string;
+}) => Promise<Response>, base?: string): Promise<SendResult>;
+/** One capability as a customer reads it. Written here, from the action and the tool, never from words the vendor supplied. */
+export declare function describeScope(scope: Scope): string;
+export declare function describeCap(action: ActionKind, cap: number | undefined): string;
+export declare function describeDuration(seconds: number): string;
+export interface PermitEnv {
+    readonly LEASH_UNLOCK_PRIVATE_KEY?: string | undefined;
+}
+export interface PermitDeps {
+    readonly env: PermitEnv;
+    readonly nowMs: () => number;
+    readonly newId: () => string;
+    readonly revocations: {
+        get(id: string): Promise<Revocation | undefined>;
+        set(id: string, value: Revocation): Promise<void>;
+    };
+}
+export declare const PERMIT_PAGE = "/grant.html";
+export declare const MANAGE_PAGE = "/grant-manage.html";
+/**
+ * POST /api/grant-approve — the consent screen's Approve button.
+ *
+ * The form carries the request as the vendor made it and what the customer
+ * chose. The grant is built from both, so a choice can only narrow. The answer
+ * is a redirect to the customer's own page for this grant, which holds the link
+ * that carries the signed grant on to the vendor. Nothing is stored.
+ */
+export declare function grantPermit(request: Request, deps: PermitDeps): Promise<Response>;
+/** POST /api/grant-revoke — the customer's off switch. Holding the manage link is the right to use it. */
+export declare function revokePermit(request: Request, deps: PermitDeps): Promise<Response>;
+/** GET /api/grant-status?id=… — whether a grant has been revoked. Public: it says nothing else about the grant. */
+export declare function permitStatus(request: Request, deps: PermitDeps): Promise<Response>;

package/policy.d.ts

@@ -0,0 +1,11 @@
+import type { DecisionReason, GateRequest, GateResult, Scope, Verdict } from './types.js';
+/** The one sentence a decision is recorded with. A function of the decision alone, so a receipt's sentence can be checked. */
+export declare function summarize(verdict: Verdict, reasons: readonly DecisionReason[], scope: Scope): string;
+/**
+ * The gate. Pure: same inputs, same result, no clock and no I/O of its own.
+ *
+ * Returns the decision and its corpus row together, so a caller cannot obtain a
+ * verdict without also holding the OutcomeRecord it must write. Instrumentation
+ * is not a step someone can forget — it is the return type.
+ */
+export declare function evaluate(request: GateRequest): GateResult;

package/receipt.d.ts

@@ -0,0 +1,45 @@
+import type { Decision, OutcomeRecord } from './types.js';
+/**
+ * Hash-chained operational receipts.
+ *
+ * This is an integrity check on our own ledger and an audit aid for the
+ * customer. It is not court certification, not insurance, and not a guarantee
+ * that the agent behaved well — only that this log has not been edited after
+ * the fact.
+ */
+export declare const GENESIS_HASH: string;
+export interface Receipt {
+    readonly seq: number;
+    readonly at: number;
+    readonly permitId: string;
+    readonly verdict: Decision['verdict'];
+    /** Plain-English line the customer reads. */
+    readonly summary: string;
+    readonly outcome: OutcomeRecord;
+    readonly prevHash: string;
+    readonly hash: string;
+}
+export interface AppendInput {
+    readonly permitId: string;
+    readonly decision: Decision;
+    readonly outcome: OutcomeRecord;
+    readonly at: number;
+}
+/** Appends one receipt to a chain, returning a new chain. Never mutates. */
+export declare function append(chain: readonly Receipt[], input: AppendInput): readonly Receipt[];
+export type ChainFault = {
+    readonly kind: 'bad-sequence';
+    readonly at: number;
+} | {
+    readonly kind: 'broken-link';
+    readonly at: number;
+} | {
+    readonly kind: 'tampered';
+    readonly at: number;
+};
+export interface Verification {
+    readonly ok: boolean;
+    readonly faults: readonly ChainFault[];
+}
+/** Verifies sequence, linkage and per-entry digests across the whole chain. */
+export declare function verify(chain: readonly Receipt[]): Verification;

package/types.d.ts

@@ -0,0 +1,134 @@
+/**
+ * Core domain types for Leash.
+ *
+ * Two rules govern everything in this file and are enforced by tests:
+ *
+ * 1. A verdict can never be obtained without an OutcomeRecord. The corpus does
+ *    not backfill, so instrumentation is structural, not optional.
+ * 2. An OutcomeRecord describes agents, scopes and vendors — never an end
+ *    consumer. Scoring an individual in a way that influences an eligibility
+ *    decision about them risks classification as a consumer reporting agency.
+ *    The line is enforced in the schema, because a policy document is not a
+ *    control.
+ */
+/** What an agent is trying to do. Budgets are denominated in these. */
+/**
+ * `pay` is the agent moving money on the customer's behalf — a charge, a refund,
+ * a payout. Classifying an agent's money action is the opposite of Leash moving
+ * money: it is how a permit bounds it. Leash itself still has no money surface.
+ */
+export type ActionKind = 'read' | 'write' | 'send' | 'delete' | 'pay';
+export declare const ACTION_KINDS: readonly ActionKind[];
+/** A single granted capability: one action against one tool. */
+export interface Scope {
+    /** Dotted tool identifier, e.g. "crm.contacts" or "email.outbox". */
+    readonly tool: string;
+    readonly action: ActionKind;
+    /** When true, a matching request escalates to a human instead of allowing. */
+    readonly requiresApproval?: boolean;
+}
+/**
+ * Hard caps on what the agent may do inside the permit's lifetime.
+ *
+ * `maxUsd` is a POLICY NUMBER ONLY. Leash never charges a card, holds funds,
+ * or moves money. It is displayed and enforced as a limit; it is not a rail.
+ */
+export interface ActionBudget {
+    readonly maxReads?: number;
+    readonly maxWrites?: number;
+    readonly maxSends?: number;
+    readonly maxDeletes?: number;
+    /** How many money actions. Counts payments, not dollars — `maxUsd` bounds the amount. */
+    readonly maxPayments?: number;
+    readonly maxUsd?: number;
+}
+export type RevokedBy = 'customer' | 'vendor';
+/** A time-boxed, capped grant from one end customer to one vendor's agent. */
+export interface Permit {
+    readonly id: string;
+    readonly vendorId: string;
+    /** Coarse vendor category used for corpus aggregation, e.g. "crm", "support". */
+    readonly vendorClass: string;
+    readonly agentId: string;
+    /** Model behind the agent, recorded for the corpus. Optional. */
+    readonly agentModel?: string;
+    /**
+     * Opaque handle for the end customer. NEVER an email, name, or any other
+     * identifier. Present on the permit so the vendor can route; deliberately
+     * absent from every OutcomeRecord.
+     */
+    readonly subjectRef: string;
+    readonly scopes: readonly Scope[];
+    readonly budget: ActionBudget;
+    readonly issuedAt: number;
+    readonly expiresAt: number;
+    readonly revokedAt?: number;
+    readonly revokedBy?: RevokedBy;
+}
+/** Units already spent against a permit, per action kind, plus dollars. */
+export interface Consumption {
+    readonly read: number;
+    readonly write: number;
+    readonly send: number;
+    readonly delete: number;
+    readonly pay: number;
+    readonly usd: number;
+}
+export declare const ZERO_CONSUMPTION: Consumption;
+/** One attempted tool call, evaluated before it runs. */
+export interface GateRequest {
+    readonly permit: Permit;
+    readonly consumed: Consumption;
+    readonly scope: Scope;
+    /** Evaluation time, epoch ms. Injected so the gate stays pure. */
+    readonly at: number;
+    /** Units this call would spend. Defaults to 1. */
+    readonly units?: number;
+    /** Dollars this call would represent, for `maxUsd` policy display. */
+    readonly usd?: number;
+}
+export type Verdict = 'allow' | 'escalate' | 'deny';
+export type DenyReason = 'revoked' | 'expired' | 'not-yet-valid' | 'scope-not-granted' | 'cap-exhausted' | 'usd-cap-exhausted';
+export type EscalateReason = 'scope-requires-approval';
+export type DecisionReason = DenyReason | EscalateReason;
+export interface Decision {
+    readonly verdict: Verdict;
+    /** Empty for `allow`. Populated and stable for deny/escalate. */
+    readonly reasons: readonly DecisionReason[];
+    /** Plain-English line shown to the customer on the receipt. */
+    readonly summary: string;
+}
+/**
+ * The corpus row. One per gate decision, always.
+ *
+ * Note what is absent: subjectRef, and any other end-consumer field. Adding one
+ * breaks `invariants.test.ts` on purpose.
+ */
+export type OutcomeKind = 'approved' | 'denied' | 'escalated' | 'cap-exhausted' | 'revoked-mid-run' | 'reverted';
+export interface OutcomeRecord {
+    readonly recordedAt: number;
+    readonly outcome: OutcomeKind;
+    readonly vendorId: string;
+    readonly vendorClass: string;
+    readonly agentId: string;
+    readonly agentModel?: string;
+    readonly tool: string;
+    readonly action: ActionKind;
+    /** Full permit lifetime in seconds, as issued. */
+    readonly ttlSeconds: number;
+    /** Cap that applied to this action kind, or null when uncapped. */
+    readonly capValue: number | null;
+    /** Fraction of that cap consumed after this call, or null when uncapped. */
+    readonly capUtilization: number | null;
+    readonly reasons: readonly DecisionReason[];
+}
+/**
+ * What `evaluate` returns. The decision and its corpus row are produced
+ * together so a caller cannot hold a verdict without also holding the record.
+ */
+export interface GateResult {
+    readonly decision: Decision;
+    readonly outcome: OutcomeRecord;
+    /** Consumption after this call. Unchanged when the verdict is not `allow`. */
+    readonly consumed: Consumption;
+}

package/unlock.d.ts

@@ -0,0 +1,48 @@
+/**
+ * The unlock token for the self-serve report.
+ *
+ * The report is built in the buyer's browser from a config that must never leave
+ * it, on a page whose CSP forbids every network request. So the page cannot ask a
+ * server "has this person paid?". Instead the checkout function, after Stripe
+ * confirms payment, signs a short token with a private key only it holds, and the
+ * page verifies the signature with the public key it shipped with. No request, no
+ * account, no config sent anywhere.
+ *
+ * ECDSA P-256 over SHA-256 via WebCrypto, so the same code runs in the browser and
+ * in node. Verification never throws: a bad token is simply not valid.
+ */
+export interface UnlockClaims {
+    readonly v: 1;
+    /** A hash of the Stripe session, so a receipt can be matched without storing anything about the buyer. */
+    readonly id: string;
+    /** Issued / expires, epoch seconds. */
+    readonly iat: number;
+    readonly exp: number;
+    /** What was bought. Absent on tokens issued when the report was the only product, which are report tokens. */
+    readonly p?: UnlockProduct;
+    /** A team licence only: the Stripe subscription it belongs to, so a later token can be issued while that subscription is paid. */
+    readonly sub?: string;
+}
+/** The things a purchase can unlock. One key signs them all, so a token must say which it is for. */
+export type UnlockProduct = 'report' | 'preflight' | 'data' | 'team';
+/** How long a data licence lasts: a year of weekly updates from one purchase, with no automatic renewal. */
+export declare const DATA_LICENCE_DAYS = 365;
+/** True when a verified token was bought for this product. A cheaper product's token never opens a dearer one. */
+export declare function unlocks(claims: UnlockClaims | undefined, product: UnlockProduct): boolean;
+/** How long a purchase can regenerate its report. Long enough to fix a config and run it again. */
+export declare const UNLOCK_DAYS = 30;
+/** A JSON Web Key. Typed loosely so this module compiles without the DOM library. */
+export type Jwk = Record<string, unknown>;
+export declare function sessionFingerprint(sessionId: string): Promise<string>;
+export declare function signUnlock(claims: UnlockClaims, privateJwk: Jwk): Promise<string>;
+/** `graceSeconds` lets a token that ended that recently still verify. Only the licence renewal passes one. */
+export declare function verifyUnlock(token: string, publicJwk: Jwk, nowSeconds: number, graceSeconds?: number): Promise<UnlockClaims | undefined>;
+/** Any JSON value, signed the same way as an unlock token. The caller decides what the value must look like. */
+export declare function signJson(value: unknown, privateJwk: Jwk): Promise<string>;
+/** The value inside a token signed by `signJson`, or undefined when the signature does not hold. Never throws. */
+export declare function verifyJson(token: string, publicJwk: Jwk, maxLength?: number): Promise<unknown>;
+/** JSON carried in a URL: base64url of its UTF-8 bytes. */
+export declare function packJson(value: unknown): string;
+export declare function unpackJson(text: string): unknown;
+/** A public key fit to embed: EC P-256, public part only. Refuses anything carrying a private component. */
+export declare function isPublicJwk(value: unknown): value is Jwk;