@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.
- package/README.md +19 -0
- package/lib/door.mjs +43 -2
- 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
|
|
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.
|
|
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": {
|