@sheaf-labs/kya 0.4.0 → 0.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +19 -0
  2. package/lib/door.mjs +43 -2
  3. package/package.json +1 -1
package/README.md CHANGED
@@ -75,6 +75,7 @@ const guard = door({
75
75
  origin: "https://tools.acme.example", // this service's own public address
76
76
  require: "verified", // "identified" (the default), "verified" or "proof"
77
77
  approved: new Set(), // IDs a person has approved
78
+ refused: new Set(), // IDs a person has refused
78
79
  onHold: held => notifyAPerson(held) // without this, an agent that falls short is refused
79
80
  });
80
81
  app.use(guard.middleware()); // a request that gets through carries req.kya.id
@@ -102,6 +103,24 @@ Three things to know:
102
103
  If your service runs as several processes, pass `seen` with `has(key)` and `add(key, seconds)` backed
103
104
  by a store they share.
104
105
 
106
+ **A page where a person decides.** `approved` and `onHold` can come from a service that keeps the list of
107
+ held agents and shows it to a person:
108
+
109
+ ```js
110
+ import { door, approvals } from "@sheaf-labs/kya";
111
+
112
+ const guard = door({
113
+ origin: "https://tools.acme.example",
114
+ require: "verified",
115
+ ...approvals({ url: "https://approvals.example/door", secret: process.env.KYA_DOOR_SECRET })
116
+ });
117
+ ```
118
+
119
+ `approvals` needs the address of the service and this door's secret there. It has no default. The service
120
+ answers two calls, each with `Authorization: Bearer <secret>`: `GET <url>/approved` gives
121
+ `{ approved: [ids], refused: [ids] }`, and `POST <url>/hold` takes `{ id, reason, path }` when an agent is
122
+ held. Anyone can run such a service. [TheGuardianAgent](https://theguardianagent.ai/door.html) is one.
123
+
105
124
  Without the middleware: `await guard.check({ path, headers })` answers
106
125
  `{ decision: "allow" | "hold" | "refuse", reason, id, agent, owner }`.
107
126
 
package/lib/door.mjs CHANGED
@@ -89,6 +89,7 @@ export function checkRequestProof(proof, audience, { now = Date.now(), maxAgeSec
89
89
  * approved Agent IDs a person has approved: an array, a Set, or a function (id) => true/false (may be
90
90
  * async). An approved agent comes in whatever `require` says, unless the register says it
91
91
  * is revoked, retired or expired.
92
+ * refused Agent IDs a person has refused, in the same forms as `approved`. A refused agent stays out.
92
93
  * onHold If set, an agent with a valid proof that does not meet `require` is held instead of refused,
93
94
  * and this function is called with the details so a person can decide. To let it in next
94
95
  * time, add its ID to `approved`.
@@ -100,14 +101,15 @@ export function checkRequestProof(proof, audience, { now = Date.now(), maxAgeSec
100
101
  * Each proof works once: the door remembers the id and nonce of each proof it has let through the checks,
101
102
  * for 70 seconds. That memory is per process. Behind several processes, pass `seen` (has/add, may be
102
103
  * async) backed by a shared store. */
103
- export function door({ origin, require: req = "identified", approved, onHold, register = DEFAULT_REGISTER, lookupSeconds = 60, seen, fetch: fetchFn = globalThis.fetch, now = () => Date.now() } = {}) {
104
+ export function door({ origin, require: req = "identified", approved, refused, onHold, register = DEFAULT_REGISTER, lookupSeconds = 60, seen, fetch: fetchFn = globalThis.fetch, now = () => Date.now() } = {}) {
104
105
  const base = canonicalAudience(origin);
105
106
  if (!base || !/^https?:\/\/[^/]+\/$/.test(base)) throw new Error('door({ origin }): set origin to this service\'s own address, for example "https://tools.acme.example".');
106
107
  if (!["identified", "verified", "proof"].includes(req)) throw new Error('door({ require }): "identified", "verified" or "proof".');
107
108
  const root = base.slice(0, -1), reg = String(register).replace(/\/$/, "");
108
109
  const used = new Map(), looked = new Map();
109
110
  const sweep = t => { for (const [k, exp] of used) if (exp <= t) used.delete(k); for (const [k, v] of looked) if (v.exp <= t) looked.delete(k); };
110
- const isApproved = async id => !approved ? false : typeof approved === "function" ? !!(await approved(id)) : approved instanceof Set ? approved.has(id) : Array.isArray(approved) && approved.includes(id);
111
+ const inList = async (list, id) => !list ? false : typeof list === "function" ? !!(await list(id)) : list instanceof Set ? list.has(id) : Array.isArray(list) && list.includes(id);
112
+ const isApproved = id => inList(approved, id);
111
113
  const lookup = async id => {
112
114
  const t = now(), hit = looked.get(id);
113
115
  if (hit && hit.exp > t) return hit.value;
@@ -139,6 +141,7 @@ export function door({ origin, require: req = "identified", approved, onHold, re
139
141
  if (seen ? await seen.has(key) : used.has(key)) return { decision: "refuse", reason: "this proof was already used", id, audience };
140
142
  if (seen) await seen.add(key, MAX_AGE_SECONDS + AHEAD_SECONDS); else used.set(key, t + (MAX_AGE_SECONDS + AHEAD_SECONDS) * 1000);
141
143
 
144
+ if (await inList(refused, id)) return { decision: "refuse", reason: "a person refused this agent at this door", id, audience };
142
145
  const ok = await isApproved(id);
143
146
  if (req === "proof" && !ok) return { decision: "allow", reason: "its proof is valid", id, audience };
144
147
  const l = await lookup(id);
@@ -173,3 +176,41 @@ export function door({ origin, require: req = "identified", approved, onHold, re
173
176
  }
174
177
  return { check, middleware, origin: root };
175
178
  }
179
+
180
+ /** Approvals kept by a service outside this process, so a person can decide about held agents on a page.
181
+ *
182
+ * door({ origin, require, ...approvals({ url, secret }) })
183
+ *
184
+ * `url` is the address of the approvals service and `secret` is this door's secret there. Both are yours to
185
+ * set; there is no default. The service answers two calls, each with "Authorization: Bearer <secret>":
186
+ *
187
+ * GET <url>/approved -> { approved: [ids], refused: [ids] }
188
+ * POST <url>/hold { id, reason, path } an agent was held; the service tells a person
189
+ *
190
+ * The lists are read at most every `refreshSeconds` (30 by default). If the service cannot be reached, the
191
+ * last lists read are used, and before any have been read nobody counts as approved. */
192
+ export function approvals({ url, secret, refreshSeconds = 30, fetch: fetchFn = globalThis.fetch, now = () => Date.now() } = {}) {
193
+ if (!url || !secret) throw new Error("approvals({ url, secret }): the approvals service's address and this door's secret.");
194
+ const base = String(url).replace(/\/$/, ""), auth = { authorization: "Bearer " + secret };
195
+ let lists = { approved: new Set(), refused: new Set() }, readAt = -Infinity, reading = null;
196
+ const read = () => {
197
+ if (now() - readAt < refreshSeconds * 1000) return Promise.resolve(lists);
198
+ if (!reading) reading = (async () => {
199
+ try {
200
+ const r = await fetchFn(base + "/approved", { headers: auth });
201
+ const j = await r.json();
202
+ if (r.status === 200 && j && Array.isArray(j.approved)) lists = { approved: new Set(j.approved), refused: new Set(Array.isArray(j.refused) ? j.refused : []) };
203
+ } catch { /* keep the last lists read */ }
204
+ readAt = now(); reading = null; return lists;
205
+ })();
206
+ return reading;
207
+ };
208
+ return {
209
+ approved: async id => (await read()).approved.has(id),
210
+ refused: async id => (await read()).refused.has(id),
211
+ onHold: async held => {
212
+ let path = ""; try { path = new URL(held.audience).pathname; } catch { /* no path to report */ }
213
+ await fetchFn(base + "/hold", { method: "POST", headers: { ...auth, "content-type": "application/json" }, body: JSON.stringify({ id: held.id, reason: held.reason, path }) });
214
+ }
215
+ };
216
+ }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@sheaf-labs/kya",
3
- "version": "0.4.0",
3
+ "version": "0.5.0",
4
4
  "description": "Know Your Agent. Put an AI agent on the Know Your Agent register, prove who it is, write its record, check other agents before dealing with them, and check agents at the door of your own service.",
5
5
  "type": "module",
6
6
  "bin": {