@common-agent/agentdoc 0.0.0-stage → 0.2.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/LICENSE +202 -0
- package/NOTICE +4 -0
- package/README.md +142 -2
- package/dist/assemble.d.ts +36 -0
- package/dist/assemble.js +951 -0
- package/dist/bin.d.ts +2 -0
- package/dist/bin.js +9 -0
- package/dist/check.d.ts +14 -0
- package/dist/check.js +358 -0
- package/dist/cli.d.ts +11 -0
- package/dist/cli.js +368 -0
- package/dist/descriptor.d.ts +21 -0
- package/dist/descriptor.js +114 -0
- package/dist/index.d.ts +17 -0
- package/dist/index.js +17 -0
- package/dist/paths.d.ts +23 -0
- package/dist/paths.js +58 -0
- package/dist/render.d.ts +21 -0
- package/dist/render.js +405 -0
- package/dist/signatures.d.ts +41 -0
- package/dist/signatures.js +176 -0
- package/dist/types.d.ts +105 -0
- package/dist/types.js +26 -0
- package/dist/util.d.ts +35 -0
- package/dist/util.js +80 -0
- package/dist/version.d.ts +2 -0
- package/dist/version.js +2 -0
- package/package.json +60 -4
- package/schema/agentdoc-v1.schema.json +200 -0
package/dist/render.js
ADDED
|
@@ -0,0 +1,405 @@
|
|
|
1
|
+
import { arr, isObj, joinWords, str } from "./util.js";
|
|
2
|
+
const esc = (s) => String(s ?? "").replace(/[&<>"']/g, (c) => ({ "&": "&", "<": "<", ">": ">", '"': """, "'": "'" })[c]);
|
|
3
|
+
const utc = (iso) => {
|
|
4
|
+
const m = str(iso).match(/^(\d{4}-\d{2}-\d{2})T(\d{2}:\d{2})(?::(\d{2}))?/);
|
|
5
|
+
return m ? `${m[1]} ${m[2]}${m[3] ? `:${m[3]}` : ""} UTC` : str(iso);
|
|
6
|
+
};
|
|
7
|
+
const shortDigest = (d) => {
|
|
8
|
+
const s = str(d);
|
|
9
|
+
return s.length > 24 ? `${s.slice(0, 15)}…${s.slice(-6)}` : s;
|
|
10
|
+
};
|
|
11
|
+
const words = (v) => (Array.isArray(v) ? joinWords(v.map((x) => String(x))) : typeof v === "object" && v !== null ? JSON.stringify(v) : String(v ?? ""));
|
|
12
|
+
/** What a source is, in words. */
|
|
13
|
+
function sourceLabel(s, id) {
|
|
14
|
+
if (!s)
|
|
15
|
+
return id;
|
|
16
|
+
switch (s.kind) {
|
|
17
|
+
case "a2a-card": return "the agent card";
|
|
18
|
+
case "agent-descriptor": return "the Descriptor";
|
|
19
|
+
case "sow-standing-proposal": return "signed terms";
|
|
20
|
+
case "eval-record": return "an evaluation record";
|
|
21
|
+
case "attestation": return "an attestation";
|
|
22
|
+
case "plugin-package": return "the package manifest";
|
|
23
|
+
case "interface-definition": return `the ${id.replace(/^iface-/, "")} interface definition`;
|
|
24
|
+
case "observation": return "an observation";
|
|
25
|
+
default: return id;
|
|
26
|
+
}
|
|
27
|
+
}
|
|
28
|
+
const SIG_WORDS = {
|
|
29
|
+
verified: "signature verified",
|
|
30
|
+
unsigned: "not signed",
|
|
31
|
+
failed: "signature does not verify",
|
|
32
|
+
not_checked: "signature not checked",
|
|
33
|
+
};
|
|
34
|
+
/** What a `not_stated` path means to a reader. */
|
|
35
|
+
function notStatedWords(p) {
|
|
36
|
+
const table = {
|
|
37
|
+
identity: ["who it is", "nothing says who runs it or what it is called"],
|
|
38
|
+
"identity.name": ["its name", "no source gives it a name"],
|
|
39
|
+
"identity.operator": ["who runs it", "no operator is named"],
|
|
40
|
+
"identity.acts_for": ["whom it acts for", "it has not said whether it acts for a person, an organization or anyone. Nothing here guesses."],
|
|
41
|
+
shape: ["whether a person attends it", "it has not said whether it runs as a service or with a person in the loop"],
|
|
42
|
+
"shape.visibility": ["how much of it can be checked", "no record here says what stands behind its door"],
|
|
43
|
+
asked: ["which standard questions it answers", "it declares no standard interface"],
|
|
44
|
+
role: ["which standard role it holds", "it declares no role"],
|
|
45
|
+
sells: ["what it offers", "no offerings are declared"],
|
|
46
|
+
"sells.samples": ["samples of its work", "no samples were read for this document"],
|
|
47
|
+
"sells.offerings.price": ["its prices", "no signed terms give a price. That does not mean it is free."],
|
|
48
|
+
access: ["how to reach it and who it lets in", "nothing says where to send a message or what to present. That is not an open door."],
|
|
49
|
+
"access.schemes": ["what a caller presents", "its card does not say. Do not assume nothing is needed."],
|
|
50
|
+
"access.admission": ["who it lets in", "no admission policy is published. It may still refuse you."],
|
|
51
|
+
refuses: ["what it refuses", "no refusals are stated. That is silence, not a promise to do anything asked."],
|
|
52
|
+
reaches: ["what systems it reaches", "no standing systems are declared. That is not a promise that it reaches nothing."],
|
|
53
|
+
leaves: ["what records a job leaves", "no records are declared"],
|
|
54
|
+
configs: ["what a job may set", "nothing says which settings a job may choose"],
|
|
55
|
+
"configs.tested_models": ["which models were tested", "settings are declared, and no tested models are listed, so treat every model as untested"],
|
|
56
|
+
triggers: ["what makes it act when nobody asks", "it has not said. That is no promise that it waits to be asked."],
|
|
57
|
+
"triggers.events": ["which events it watches", "it has not said which events make it act"],
|
|
58
|
+
"triggers.schedules": ["which schedules it keeps", "it has not said whether it acts on a schedule"],
|
|
59
|
+
"triggers.sets_own": ["whether it sets schedules of its own", "it has not said whether it may set reminders for itself"],
|
|
60
|
+
"triggers.contacts": ["whom it contacts when it acts", "it has not said whom it contacts when it acts on its own"],
|
|
61
|
+
handling: ["where your content goes and how long it is kept", "nothing says where content is processed or kept. It has promised to delete nothing."],
|
|
62
|
+
"handling.processed_in": ["where your content is processed", "no place is named, so it may be anywhere"],
|
|
63
|
+
"handling.retention_max_days": ["how long it keeps what you send", "it has promised to delete nothing"],
|
|
64
|
+
"handling.processors": ["which services see your content", "no processors are named"],
|
|
65
|
+
"handling.memory": ["whether it remembers one job in the next", "it has not said, so do not assume each job starts clean"],
|
|
66
|
+
"handling.memory_pool": ["whose jobs it learns from", "it remembers across jobs and has not said whether what it keeps from one caller's jobs is used for another's"],
|
|
67
|
+
standing: ["what others have published about it", "no attestation, evaluation or report was read"],
|
|
68
|
+
subject: ["which agent this is", "a package describes no running agent until someone installs it"],
|
|
69
|
+
};
|
|
70
|
+
if (table[p])
|
|
71
|
+
return table[p];
|
|
72
|
+
const off = p.match(/^sells\.offerings\.(.+)\.(inputs|outputs|price|deliverables)$/);
|
|
73
|
+
if (off)
|
|
74
|
+
return [`${off[2] === "price" ? "the price" : off[2] === "inputs" ? "what to send" : "what comes back"} for ${off[1]}`, off[2] === "price" ? "no signed terms price it. That does not mean it is free." : "nothing says, so it has not promised it"];
|
|
75
|
+
const m = p.match(/^sells\.offerings\.(inputs|outputs)$/);
|
|
76
|
+
if (m)
|
|
77
|
+
return [m[1] === "inputs" ? "what to send each offering" : "what each offering returns", "no offering says, so none has promised it"];
|
|
78
|
+
if (p.startsWith("asked."))
|
|
79
|
+
return [`the ${p.slice(6)} interface's questions`, "it declares the interface, and its definition could not be read"];
|
|
80
|
+
return [p, ""];
|
|
81
|
+
}
|
|
82
|
+
const AUTHORITY_WORDS = {
|
|
83
|
+
"reads-files": "reads files in its workspace",
|
|
84
|
+
"writes-files": "creates, changes and deletes files in its workspace",
|
|
85
|
+
"reads-systems": "reads a standing system",
|
|
86
|
+
"updates-systems": "changes the records a standing system holds",
|
|
87
|
+
"triggers-systems": "sets off actions in a standing system",
|
|
88
|
+
"runs-commands": "runs programs on its host or in its workspace",
|
|
89
|
+
"reaches-network": "reaches network addresses no declared system names",
|
|
90
|
+
"sends-messages": "sends messages to parties other than you",
|
|
91
|
+
"spends-money": "commits money on your or its owner's behalf",
|
|
92
|
+
};
|
|
93
|
+
const EVERY_WORDS = { hour: "every hour", day: "every day", week: "every week", month: "every month" };
|
|
94
|
+
const CONTACT_WORDS = {
|
|
95
|
+
owner: "its owner",
|
|
96
|
+
callers: "the parties it holds work for",
|
|
97
|
+
named: "parties its owner names",
|
|
98
|
+
anyone: "parties it has not dealt with before",
|
|
99
|
+
};
|
|
100
|
+
const MEMORY_WORDS = {
|
|
101
|
+
"remembers-across-jobs": "it keeps what a job was given or learned for later jobs",
|
|
102
|
+
"starts-clean-each-job": "every job starts with nothing from an earlier one",
|
|
103
|
+
};
|
|
104
|
+
const POOL_WORDS = {
|
|
105
|
+
"each-caller": "what it keeps from your jobs is used only in your later jobs",
|
|
106
|
+
"every-caller": "what it keeps from every caller's jobs is used in every caller's later jobs, yours included",
|
|
107
|
+
};
|
|
108
|
+
const CEILING_WORDS = {
|
|
109
|
+
job_seconds: "seconds one job runs",
|
|
110
|
+
cost_per_job: "what one job costs you",
|
|
111
|
+
spend_per_job: "what one job may spend for you",
|
|
112
|
+
messages_per_job: "messages one job sends to others",
|
|
113
|
+
};
|
|
114
|
+
const KIND_WORDS = {
|
|
115
|
+
text: "text",
|
|
116
|
+
"text/plain": "text",
|
|
117
|
+
"text/markdown": "text (Markdown)",
|
|
118
|
+
"text/html": "a web page",
|
|
119
|
+
"application/json": "data (JSON)",
|
|
120
|
+
"application/pdf": "a PDF",
|
|
121
|
+
"text/csv": "a table (CSV)",
|
|
122
|
+
url: "a link",
|
|
123
|
+
identifier: "a name or id",
|
|
124
|
+
document: "a file",
|
|
125
|
+
};
|
|
126
|
+
const kindWords = (k) => KIND_WORDS[str(k).toLowerCase()] ?? (str(k) || "not stated");
|
|
127
|
+
const money = (v) => {
|
|
128
|
+
if (isObj(v) && Number.isInteger(v.amount_micro))
|
|
129
|
+
return `${(v.amount_micro / 1e6).toFixed(2)} ${str(v.currency) || ""}`.trim();
|
|
130
|
+
return typeof v === "number" ? String(v) : words(v);
|
|
131
|
+
};
|
|
132
|
+
function table(head, rows) {
|
|
133
|
+
return `<table><thead><tr>${head.map((h) => `<th>${esc(h)}</th>`).join("")}</tr></thead><tbody>${rows.map((r) => `<tr>${r.map((c) => `<td>${c}</td>`).join("")}</tr>`).join("")}</tbody></table>`;
|
|
134
|
+
}
|
|
135
|
+
const p = (s) => `<p>${s}</p>`;
|
|
136
|
+
const note = (s) => `<p class="note">${s}</p>`;
|
|
137
|
+
/** Render an AgentDoc as a self-contained page. */
|
|
138
|
+
export function render(doc) {
|
|
139
|
+
const s = isObj(doc.sections) ? doc.sections : {};
|
|
140
|
+
const sources = arr(doc.sources).filter(isObj);
|
|
141
|
+
const byId = new Map(sources.map((x) => [x.id, x]));
|
|
142
|
+
const notStated = arr(doc.not_stated).filter((x) => typeof x === "string");
|
|
143
|
+
const isPackage = doc.package !== undefined && doc.subject === undefined;
|
|
144
|
+
const identity = s.identity ?? {};
|
|
145
|
+
const visibility = str(s.shape?.visibility);
|
|
146
|
+
const name = str(identity.name) || str(doc.subject?.name) || str(doc.package?.name) || str(doc.subject?.handle) || "An agent with no name stated";
|
|
147
|
+
const fromLine = (sec) => {
|
|
148
|
+
const ids = arr(sec?.from).filter((x) => typeof x === "string");
|
|
149
|
+
return ids.length ? `from ${joinWords(ids.map((id) => sourceLabel(byId.get(id), id)))}` : "";
|
|
150
|
+
};
|
|
151
|
+
const absent = (path) => {
|
|
152
|
+
const [w, means] = notStatedWords(path);
|
|
153
|
+
return `<p class="absent"><span class="tag">not stated</span> ${esc(w)}${means ? `: ${esc(means)}` : ""}.</p>`;
|
|
154
|
+
};
|
|
155
|
+
const band = (id, title, sec, body, path = id) => `
|
|
156
|
+
<details open id="${esc(id)}" class="band">
|
|
157
|
+
<summary><h2>${esc(title)}</h2><span class="from">${sec ? esc(fromLine(sec)) : "not stated"}</span></summary>
|
|
158
|
+
<div class="body">${sec ? body : absent(path)}</div>
|
|
159
|
+
</details>`;
|
|
160
|
+
const enforcedWords = (c) => {
|
|
161
|
+
if (c.enforced === true && c.decided_by === "rule" && visibility === "verifiable")
|
|
162
|
+
return "enforced, as a record about this deploy shows";
|
|
163
|
+
if (c.decided_by === "rule")
|
|
164
|
+
return "the operator says a rule holds it to this; nobody here saw it applied";
|
|
165
|
+
if (c.decided_by === "model")
|
|
166
|
+
return "a limit the model is asked to keep";
|
|
167
|
+
return "what holds it to this is not stated";
|
|
168
|
+
};
|
|
169
|
+
// ── reaching it ──
|
|
170
|
+
const access = s.access;
|
|
171
|
+
let accessBody = "";
|
|
172
|
+
if (access) {
|
|
173
|
+
const rows = [];
|
|
174
|
+
if (str(access.address))
|
|
175
|
+
rows.push(["Address", `<code>${esc(access.address)}</code>`, "Where a message to it is sent."]);
|
|
176
|
+
if (str(access.protocol))
|
|
177
|
+
rows.push(["Protocol", esc(str(access.protocol).toUpperCase() === "A2A" ? "A2A (Agent2Agent)" : access.protocol), str(access.transport) ? `Over ${esc(access.transport)}${str(access.protocol_version) ? `, protocol version ${esc(access.protocol_version)}` : ""}.` : ""]);
|
|
178
|
+
const schemes = Array.isArray(access.schemes) ? access.schemes : null;
|
|
179
|
+
rows.push([
|
|
180
|
+
"You present",
|
|
181
|
+
schemes === null ? `<span class="tag">not stated</span>` : schemes.length === 0 ? "nothing: it says no credential is needed" : esc(joinWords(schemes.map((x) => [str(x.id), str(x.type) || str(x.scheme)].filter(Boolean).join(", a ")))),
|
|
182
|
+
schemes === null ? "Its card does not say. That is not the same as needing nothing." : schemes.length > 1 ? "Any one of these. They are alternatives, not a checklist." : "",
|
|
183
|
+
]);
|
|
184
|
+
rows.push(["Who it lets in", str(access.admission) ? esc(access.admission) : `<span class="tag">not stated</span>`, str(access.admission) ? "" : "No admission policy is published. It may still refuse you."]);
|
|
185
|
+
if (isObj(access.capabilities)) {
|
|
186
|
+
const c = access.capabilities;
|
|
187
|
+
rows.push(["How it answers", esc([c.streaming === true ? "streams its answers" : c.streaming === false ? "does not stream" : "", c.push_notifications === true ? "can notify you when a task changes" : c.push_notifications === false ? "sends no push notifications" : ""].filter(Boolean).join("; ")), ""]);
|
|
188
|
+
}
|
|
189
|
+
if (isObj(access.limits))
|
|
190
|
+
rows.push(["Limits per caller", esc(Object.entries(access.limits).filter(([k]) => k !== "past_them").map(([k, v]) => `${k.replace(/_/g, " ")}: ${isObj(v) ? `${money(v.most)} (${enforcedWords(v)})` : `${money(v)} (what holds it to this is not stated)`}`).join("; ")), str(access.limits.past_them) ? esc(`Past them: ${access.limits.past_them}`) : ""]);
|
|
191
|
+
accessBody = table(["", "", ""], rows).replace("<thead><tr><th></th><th></th><th></th></tr></thead>", "");
|
|
192
|
+
}
|
|
193
|
+
// ── offerings ──
|
|
194
|
+
const offerings = arr(s.sells?.offerings).filter(isObj);
|
|
195
|
+
const ioRows = (list, kind) => table(kind === "in" ? ["What you send", "Form", "Needed"] : ["What comes back", "Form", "When"], list.map((x) => [esc(str(x.name) || "unnamed"), `${esc(kindWords(x.kind ?? x.media_type))} <code>${esc(str(x.kind) || str(x.media_type))}</code>`, kind === "in" ? (x.required === true ? "required" : x.required === false ? "optional" : "not stated") : esc(str(x.when) === "standing" ? "kept up across tasks" : str(x.when) === "per_task" ? "each task" : str(x.when) || "not stated")]));
|
|
196
|
+
const offeringHtml = (o, i) => {
|
|
197
|
+
const scope = str(o.scope) || "task-specific";
|
|
198
|
+
const label = scope === "open-ended" ? "open-ended: takes any instruction" : scope === "open-with-focus" ? `open, within a focus on ${str(o.focus) || "a focus it has not named"}` : "";
|
|
199
|
+
const parts = [];
|
|
200
|
+
if (scope === "open-ended")
|
|
201
|
+
parts.push(note("<b>Open-ended.</b> It takes any instruction and makes no claim about what it can do. Read it by what it can touch, its limits, and what it does with your content."));
|
|
202
|
+
else if (scope === "open-with-focus")
|
|
203
|
+
parts.push(note(`<b>Open, within a focus on ${esc(o.focus)}.</b> That says where the instructions it will try lie, not what work it can do.${str(o.role) ? ` It names the standard role <code>${esc(o.role)}</code>.` : ""}`) + (str(o.does) ? p(`Where its instructions lie: ${esc(o.does)}`) : ""));
|
|
204
|
+
else if (str(o.does))
|
|
205
|
+
parts.push(p(`${esc(o.does)} <span class="tag">the operator's words</span>`));
|
|
206
|
+
const inputs = arr(o.inputs).filter(isObj);
|
|
207
|
+
const granted = inputs.filter((x) => x.external === true || x.grant !== undefined || x.kind === "shared_resource");
|
|
208
|
+
const sent = inputs.filter((x) => !granted.includes(x));
|
|
209
|
+
if (sent.length)
|
|
210
|
+
parts.push(ioRows(sent, "in"));
|
|
211
|
+
if (granted.length) {
|
|
212
|
+
const order = [...granted].sort((a, b) => (str(b.when) === "standing" ? 1 : 0) - (str(a.when) === "standing" ? 1 : 0));
|
|
213
|
+
parts.push(`<h4>Access you grant, not files you send</h4>${table(["Resource", "It may", "How you grant it"], order.map((x) => [esc(str(x.name)), esc(str(x.access) || "not stated"), esc(str(x.grant) || words(x.via) || "not stated") + (str(x.when) === "standing" ? " (standing: still true after the work is done)" : "")]))}`);
|
|
214
|
+
}
|
|
215
|
+
if (!inputs.length && Array.isArray(o.input_modes))
|
|
216
|
+
parts.push(p(`It accepts ${esc(joinWords(o.input_modes.map(kindWords)))}. The card does not name its inputs.`));
|
|
217
|
+
const outputs = arr(o.outputs).filter(isObj);
|
|
218
|
+
if (outputs.length)
|
|
219
|
+
parts.push(ioRows(outputs, "out"));
|
|
220
|
+
else if (isObj(o.deliverables))
|
|
221
|
+
parts.push(ioRows([...arr(o.deliverables.per_task).filter(isObj).map((x) => ({ ...x, when: "per_task" })), ...arr(o.deliverables.interim).filter(isObj).map((x) => ({ ...x, when: "on a schedule" }))], "out"));
|
|
222
|
+
else if (Array.isArray(o.output_modes))
|
|
223
|
+
parts.push(p(`It returns ${esc(joinWords(o.output_modes.map(kindWords)))}. The card does not name what comes back.`));
|
|
224
|
+
if (outputs.length || inputs.length)
|
|
225
|
+
parts.push(note("The form of each input and deliverable is a promise. Its quality is not, and nothing here says the work will be good."));
|
|
226
|
+
if (Array.isArray(o.authority))
|
|
227
|
+
parts.push(o.authority.length ? `<h4>What it can touch</h4><ul>${o.authority.map((a) => `<li>${esc(AUTHORITY_WORDS[str(a)] ?? a)}</li>`).join("")}</ul>${note(o.authority_decided_by === "rule" ? "The operator says the runtime keeps a job inside this list." : o.authority_decided_by === "model" ? "The model is told this list and asked to keep to it." : "What keeps a job inside this list is not stated.")}` : p("What it can touch: nothing beyond what you send and what it returns."));
|
|
228
|
+
else if (scope !== "task-specific")
|
|
229
|
+
parts.push(p(`What it can touch: <span class="tag">not stated</span>`));
|
|
230
|
+
if (Array.isArray(o.workspace))
|
|
231
|
+
parts.push(o.workspace.length ? `<h4>Where it works</h4><ul>${o.workspace.filter(isObj).map((w) => `<li>${esc(str(w.kind) || str(w.system))}, ${esc(str(w.access) || "access not stated")}: ${esc(w.for)}</li>`).join("")}</ul>` : p("Where it works: only on what a request sends it."));
|
|
232
|
+
if (isObj(o.ceilings))
|
|
233
|
+
parts.push(`<h4>Limits on one job</h4><ul>${Object.entries(o.ceilings).filter(([, v]) => isObj(v)).map(([k, v]) => `<li>${esc(CEILING_WORDS[k] ?? k)}: at most ${esc(money(v.most))}. ${esc(enforcedWords(v))}.</li>`).join("")}</ul>`);
|
|
234
|
+
if (o.price !== undefined)
|
|
235
|
+
parts.push(p(`<b>Price</b> (${esc(str(o.arrangement).replace(/_/g, " ") || "arrangement not stated")}), from signed terms: <code>${esc(JSON.stringify(o.price))}</code>`));
|
|
236
|
+
const steps = arr(o.steps).filter(isObj);
|
|
237
|
+
if (steps.length)
|
|
238
|
+
parts.push(`<h4>How it is delivered</h4><ol>${steps.map((x) => `<li>${esc(str(x.name) || str(x.id))}${str(x.does) ? `: ${esc(x.does)}` : ""}</li>`).join("")}</ol>${note("Steps are how the offering is delivered, not things to order.")}`);
|
|
239
|
+
if (isObj(o.trial))
|
|
240
|
+
parts.push(o.trial.offered === true ? p(`<b>Trial:</b> open to ${esc(str(o.trial.who).replace("_", " "))}, ${esc(Object.entries(isObj(o.trial.limits) ? o.trial.limits : {}).map(([k, v]) => `${v} ${k.replace(/_/g, " ")}`).join(", "))}.`) : p("<b>Trial:</b> it offers no trial of this work."));
|
|
241
|
+
for (const e of arr(o.evaluated_against).filter(isObj))
|
|
242
|
+
parts.push(p(`On the evaluation set ${esc(isObj(e.set) ? `${str(e.set.name)} version ${str(e.set.version)}` : "")}, an evaluator recorded ${esc(isObj(e.result) ? Object.entries(e.result).map(([k, v]) => `${v} ${k}`).join(", ") : "")}. That is this record's result on this set, not a rating.`));
|
|
243
|
+
const state = str(o.state) || "declared";
|
|
244
|
+
return `<details class="offering"${i === 0 ? " open" : ""}><summary><code>${esc(str(o.id) || str(o.name) || `offering ${i + 1}`)}</code> ${esc(str(o.name) && str(o.name) !== str(o.id) ? str(o.name) : "")} ${label ? `<span class="tag">${esc(label)}</span>` : ""} <span class="tag">${esc(state)}</span></summary>${parts.join("")}</details>`;
|
|
245
|
+
};
|
|
246
|
+
const sellsBody = offerings.length
|
|
247
|
+
? note("Declared means the operator says so and nobody has checked. Confirmed or failed means an evaluation record says so.") + offerings.map(offeringHtml).join("")
|
|
248
|
+
: p("No offerings.");
|
|
249
|
+
// ── who it is ──
|
|
250
|
+
const ACTS = { person: "one person, its owner", organization: `an organization${str(identity.organization_name) ? `, ${str(identity.organization_name)}` : ""}`, anyone: "anyone: a public service with no principal" };
|
|
251
|
+
const whoRows = [];
|
|
252
|
+
if (str(identity.operator))
|
|
253
|
+
whoRows.push(["Run by", esc(identity.operator) + (str(identity.url) ? ` (<a href="${esc(identity.url)}">${esc(identity.url)}</a>)` : "")]);
|
|
254
|
+
if (str(identity.handle))
|
|
255
|
+
whoRows.push(["Handle", `<code>${esc(identity.handle)}</code>`]);
|
|
256
|
+
if (str(identity.version))
|
|
257
|
+
whoRows.push(["Version", esc(identity.version)]);
|
|
258
|
+
whoRows.push(["Acts for", ACTS[str(identity.acts_for)] ? esc(ACTS[str(identity.acts_for)]) : `<span class="tag">not stated</span>`]);
|
|
259
|
+
if (typeof identity.fleet === "boolean")
|
|
260
|
+
whoRows.push(["Fleet", identity.fleet ? "several processes answer as this one agent" : "one agent, not a set of copies"]);
|
|
261
|
+
if (str(s.shape?.interaction))
|
|
262
|
+
whoRows.push(["Runs as", s.shape.interaction === "service" ? "a service, with nobody attending it" : "an agent a person attends right now"]);
|
|
263
|
+
whoRows.push(["How much is checkable", visibility === "verifiable" ? "what runs can be checked against what was built" : visibility === "observed" ? "the door is watched; the inside is not" : visibility === "opaque" ? "the door alone: an address, what was sent, and what came back" : `<span class="tag">not stated</span> no record here says what stands behind its door`]);
|
|
264
|
+
if (s.role)
|
|
265
|
+
whoRows.push(["Role", `<code>${esc(s.role.name)}</code> <span class="tag">${esc(str(s.role.state) || "declared")}</span>`]);
|
|
266
|
+
if (str(identity.documentation))
|
|
267
|
+
whoRows.push(["Documentation", `<a href="${esc(identity.documentation)}">${esc(identity.documentation)}</a>`]);
|
|
268
|
+
const whoBody = `<table><tbody>${whoRows.map((r) => `<tr><th>${esc(r[0])}</th><td>${r[1]}</td></tr>`).join("")}</tbody></table>`;
|
|
269
|
+
// ── standard questions ──
|
|
270
|
+
const askedBody = arr(s.asked?.interfaces).filter(isObj).map((i) => {
|
|
271
|
+
const ex = arr(i.exchanges).filter(isObj);
|
|
272
|
+
return `<h4><code>${esc(i.name)}</code>${str(i.version) ? ` ${esc(i.version)}` : ""}${str(i.definition) ? ` <a href="${esc(i.definition)}">definition</a>` : ""}</h4>${ex.length ? table(["It may be asked", "The answer carries", "State"], ex.map((e) => [esc(str(e.asks) || str(e.id)), esc(words(e.answer_carries)), `<span class="tag">${esc(str(e.state) || "declared")}</span>`])) : note("Its definition could not be read, so its questions are not listed.")}`;
|
|
273
|
+
}).join("") + note("Each question is the agent's own claim until an evaluation record marks it confirmed or failed.");
|
|
274
|
+
// ── refuses ──
|
|
275
|
+
const refusalLines = str(s.refuses?.statement).split(/\n+/).map((l) => l.trim()).filter(Boolean);
|
|
276
|
+
const handsOver = arr(s.refuses?.hands_over).filter((x) => typeof x === "string");
|
|
277
|
+
const refusesBody = (refusalLines.length ? `<h4>It refuses</h4><ul>${refusalLines.map((l) => `<li>${esc(l)}</li>`).join("")}</ul>` : "")
|
|
278
|
+
+ (handsOver.length ? `<h4>It hands to a person</h4><ul>${handsOver.map((l) => `<li>${esc(l)}</li>`).join("")}</ul>` : "")
|
|
279
|
+
+ note(str(s.refuses?.kind) === "prose" ? "The operator's own words, not a signed clause." : "");
|
|
280
|
+
// ── reaches ──
|
|
281
|
+
const systems = arr(s.reaches?.systems).filter(isObj);
|
|
282
|
+
const ceilings = arr(s.reaches?.ceilings).filter(isObj);
|
|
283
|
+
const reachesBody = (systems.length ? table(["System", "Access", "What for", "Your content goes to it"], systems.map((y) => [esc(str(y.name) || "a system"), esc(str(y.access) || "not stated"), esc(y.needs), y.leaves === true ? "yes" : y.leaves === false ? "no" : "not stated"])) : "")
|
|
284
|
+
+ (ceilings.length ? `<h4>Suggested spending ceilings</h4>${table(["System", "Per", "Suggested"], ceilings.map((c) => [esc(c.system), esc(str(c.per) || "not stated"), esc(c.suggested ?? "not stated")]))}${note("The package suggests these. The host that installed the agent set the ones in force.")}` : "")
|
|
285
|
+
+ note("Each system is named by what it does, never by a product or an address.");
|
|
286
|
+
const recordsBody = table(["Record", "When", "File"], arr(s.leaves?.records).filter(isObj).map((r) => [esc(r.name), esc(str(r.when) === "per_task" ? "each task" : r.when), r.file ? `<code>${esc(r.file)}</code>` : ""])) + note("An evaluation checks that a real job left these records.");
|
|
287
|
+
const settings = arr(s.configs?.settings).filter(isObj);
|
|
288
|
+
const tested = arr(s.configs?.tested_models).map(String);
|
|
289
|
+
const configsBody = settings.length
|
|
290
|
+
? table(["Setting", "Kind", "Default", "Allowed", "A sender may set it"], settings.map((x) => [`<code>${esc(x.name)}</code>`, esc(x.kind), esc(words(x.default)), esc(Array.isArray(x.allowed) ? words(x.allowed.map((a) => (x.name === "model" && s.configs?.tested_models !== undefined && !tested.includes(String(a)) ? `${a} (untested)` : a))) : "not listed"), x.job_may_set === true ? "yes" : "no"]))
|
|
291
|
+
+ (arr(s.configs?.named).length ? `<h4>Named run configs</h4><ul>${arr(s.configs?.named).filter(isObj).map((n) => `<li>${esc(n.name)} <code>${esc(shortDigest(n.digest))}</code></li>`).join("")}</ul>` : "")
|
|
292
|
+
: p("It takes no settings.");
|
|
293
|
+
const trig = s.triggers ?? {};
|
|
294
|
+
const events = arr(trig.events).filter(isObj);
|
|
295
|
+
const schedules = arr(trig.schedules).filter(isObj);
|
|
296
|
+
const onlyAsked = trig.events !== undefined && trig.schedules !== undefined && !events.length && !schedules.length && trig.sets_own === false;
|
|
297
|
+
const triggersBody = (onlyAsked
|
|
298
|
+
? p("It acts only when it is sent a request.")
|
|
299
|
+
: (events.length ? `<h4>Events it watches</h4>${table(["System", "Event", "What it does"], events.map((e) => [esc(str(e.system) || "not stated"), `<code>${esc(e.kind)}</code>`, esc(e.does)]))}` : trig.events !== undefined ? p("It watches no events.") : "")
|
|
300
|
+
+ (schedules.length ? `<h4>Schedules it keeps</h4>${table(["How often", "What it does"], schedules.map((x) => [esc(EVERY_WORDS[str(x.every)] ?? "not stated"), esc(x.does)]))}` : trig.schedules !== undefined ? p("It keeps no schedules.") : "")
|
|
301
|
+
+ (typeof trig.sets_own === "boolean" ? p(trig.sets_own ? "It may set schedules and reminders of its own while it works." : "It does not set schedules of its own.") : ""))
|
|
302
|
+
+ (Array.isArray(trig.contacts) ? p(trig.contacts.length ? `When it acts on its own, it contacts ${esc(joinWords(trig.contacts.map((c) => CONTACT_WORDS[str(c)] ?? str(c))))}.` : "When it acts on its own, it contacts nobody.") : "")
|
|
303
|
+
+ note("The operator's own word. Nothing here has seen it act.");
|
|
304
|
+
const handling = s.handling ?? {};
|
|
305
|
+
const handlingRows = [];
|
|
306
|
+
if (handling.hosted_in)
|
|
307
|
+
handlingRows.push(["Runs in", esc(words(handling.hosted_in))]);
|
|
308
|
+
handlingRows.push(["Processed in", handling.processed_in ? esc(words(handling.processed_in)) : `<span class="tag">not stated</span> so it may be anywhere`]);
|
|
309
|
+
handlingRows.push(["Kept for", typeof handling.retention_max_days === "number" ? `at most ${esc(handling.retention_max_days)} days` : `<span class="tag">not stated</span> it has promised to delete nothing`]);
|
|
310
|
+
if (Array.isArray(handling.processors))
|
|
311
|
+
handlingRows.push(["Seen by", esc(joinWords(handling.processors.map((x) => (isObj(x) ? [str(x.service), str(x.purpose)].filter(Boolean).join(", for ") : String(x)))) || "no other service")]);
|
|
312
|
+
if (MEMORY_WORDS[str(handling.memory)])
|
|
313
|
+
handlingRows.push(["Between jobs", esc(MEMORY_WORDS[str(handling.memory)])]);
|
|
314
|
+
if (POOL_WORDS[str(handling.memory_pool)])
|
|
315
|
+
handlingRows.push(["Whose jobs it learns from", esc(POOL_WORDS[str(handling.memory_pool)])]);
|
|
316
|
+
if (isObj(handling.promises))
|
|
317
|
+
handlingRows.push(["It promises", esc(Object.entries(handling.promises).filter(([k, v]) => k !== "grade" && v === true).map(([k]) => k.replace(/_/g, " ")).join("; ") + (typeof handling.promises.grade === "string" ? ` (graded ${handling.promises.grade})` : ""))]);
|
|
318
|
+
const handlingBody = `<table><tbody>${handlingRows.map((r) => `<tr><th>${esc(r[0])}</th><td>${r[1]}</td></tr>`).join("")}</tbody></table>`;
|
|
319
|
+
const standingBody = arr(s.standing?.entries).filter(isObj).map((e) => p(`${esc(e.kind === "eval-record" ? "An evaluation record" : "An attestation")}${str(e.by) ? ` by <b>${esc(e.by)}</b>` : ""}${str(e.as_of) ? `, as of ${esc(utc(e.as_of))}` : ""}. ${esc(SIG_WORDS[str(e.signature)] ?? "")}.${typeof e.conforms === "boolean" ? ` Its own verdict: ${e.conforms ? "conforms" : "does not conform"}.` : ""}${isObj(e.areas) ? ` Areas: ${esc(Object.entries(e.areas).map(([k, v]) => `${k} ${String(v).replace("_", " ")}`).join("; "))}.` : ""}${str(e.words) ? ` In its words: ${esc(e.words)}` : ""}`)).join("") + note("Carried as published, never audited or averaged here.");
|
|
320
|
+
const notStatedBody = notStated.length
|
|
321
|
+
? table(["Not stated", "What that means"], notStated.map((x) => {
|
|
322
|
+
const [w, means] = notStatedWords(x);
|
|
323
|
+
return [`${esc(w)} <code>${esc(x)}</code>`, esc(means)];
|
|
324
|
+
})) + note("When something is not stated, do not assume the answer you would like.")
|
|
325
|
+
: p("Every question this document asks has an answer on record.");
|
|
326
|
+
const sourcesBody = table(["Source", "Kind", "Digest", "Fetched", "Signature"], sources.map((x) => [
|
|
327
|
+
`${x.url ? `<a href="${esc(x.url)}">${esc(sourceLabel(x, x.id))}</a>` : esc(sourceLabel(x, x.id))} <code>${esc(x.id)}</code>${arr(x.disagreements).length ? `<br><span class="warn">Disagrees: ${esc(arr(x.disagreements).join("; "))}</span>` : ""}${str(x.not_used) ? `<br><span class="warn">Not used: ${esc(x.not_used)}</span>` : ""}`,
|
|
328
|
+
`<code>${esc(x.kind)}</code>${x.agent_version ? ` ${esc(x.agent_version)}` : ""}`,
|
|
329
|
+
`<code>${esc(shortDigest(x.digest))}</code>`,
|
|
330
|
+
esc(utc(x.fetched_at ?? x.at)),
|
|
331
|
+
`<span class="${x.signature === "verified" ? "ok" : x.signature === "failed" ? "warn" : ""}">${esc(SIG_WORDS[str(x.signature)] ?? "")}</span>`,
|
|
332
|
+
])) + p(`${arr(doc.signatures).length ? "The assembler signed this document. That says it gathered these sources at this time and reported them faithfully, not that what they say is true." : "Nobody signed this assembly."} ${esc(str(doc.assembled_by))}`)
|
|
333
|
+
+ note("A digest is a fingerprint of a source's exact contents. Each fact on this page is copied from a source listed here; none is typed in.");
|
|
334
|
+
const head = isPackage
|
|
335
|
+
? `<p class="lede">This page describes a package: what any agent installed from it will declare. It says nothing about any agent that is running.</p>`
|
|
336
|
+
: "";
|
|
337
|
+
return `<!doctype html>
|
|
338
|
+
<html lang="en">
|
|
339
|
+
<head>
|
|
340
|
+
<meta charset="utf-8">
|
|
341
|
+
<meta name="viewport" content="width=device-width, initial-scale=1">
|
|
342
|
+
<title>${esc(name)} · AgentDoc</title>
|
|
343
|
+
<meta name="description" content="The AgentDoc for ${esc(name)}: how to reach it, what it offers, what it refuses, and where each line came from.">
|
|
344
|
+
<style>
|
|
345
|
+
:root{--bg:#fbfaf7;--fg:#1d2327;--dim:#5c666d;--line:#dcd8cf;--band:#ffffff;--accent:#1f6f5c;--warn:#a1402b;--tag:#eeebe3;color-scheme:light dark}
|
|
346
|
+
@media (prefers-color-scheme:dark){:root{--bg:#121619;--fg:#e4e7e9;--dim:#9aa4ab;--line:#2c343a;--band:#182024;--accent:#5fc7a6;--warn:#f08c72;--tag:#253036}}
|
|
347
|
+
*{box-sizing:border-box}
|
|
348
|
+
body{margin:0;background:var(--bg);color:var(--fg);font:16px/1.55 system-ui,-apple-system,"Segoe UI",Roboto,sans-serif}
|
|
349
|
+
main{max-width:960px;margin:0 auto;padding:24px 16px 64px}
|
|
350
|
+
header{border-bottom:1px solid var(--line);padding-bottom:16px;margin-bottom:16px}
|
|
351
|
+
h1{font-size:1.9rem;margin:0 0 4px}
|
|
352
|
+
h2{font-size:1.15rem;margin:0;display:inline}
|
|
353
|
+
h4{margin:16px 0 6px;font-size:1rem}
|
|
354
|
+
.lede{font-size:1.08rem;margin:6px 0}
|
|
355
|
+
.meta{color:var(--dim);font-size:.92rem;margin:4px 0}
|
|
356
|
+
code{font:.88em ui-monospace,SFMono-Regular,Menlo,Consolas,monospace;overflow-wrap:anywhere}
|
|
357
|
+
a{color:var(--accent)}
|
|
358
|
+
.band{background:var(--band);border:1px solid var(--line);border-radius:8px;margin:12px 0}
|
|
359
|
+
.band>summary{cursor:pointer;padding:12px 16px;list-style-position:inside}
|
|
360
|
+
.band .from{color:var(--dim);font-size:.88rem;margin-left:10px}
|
|
361
|
+
.body{padding:0 16px 14px}
|
|
362
|
+
.offering{border-top:1px solid var(--line);padding:8px 0}
|
|
363
|
+
.offering>summary{cursor:pointer;font-weight:600}
|
|
364
|
+
table{border-collapse:collapse;width:100%;margin:8px 0;font-size:.94rem;display:block;overflow-x:auto}
|
|
365
|
+
th,td{text-align:left;vertical-align:top;padding:6px 10px 6px 0;border-bottom:1px solid var(--line)}
|
|
366
|
+
th{color:var(--dim);font-weight:600;white-space:nowrap}
|
|
367
|
+
.tag{display:inline-block;background:var(--tag);border-radius:4px;padding:0 6px;font-size:.8rem;color:var(--dim);font-weight:500}
|
|
368
|
+
.note{color:var(--dim);font-size:.9rem}
|
|
369
|
+
.absent{margin:4px 0}
|
|
370
|
+
.ok{color:var(--accent)}
|
|
371
|
+
.warn{color:var(--warn)}
|
|
372
|
+
footer{color:var(--dim);font-size:.88rem;margin-top:24px}
|
|
373
|
+
</style>
|
|
374
|
+
</head>
|
|
375
|
+
<body>
|
|
376
|
+
<main>
|
|
377
|
+
<header>
|
|
378
|
+
<h1>${esc(name)}</h1>
|
|
379
|
+
${str(identity.description) ? `<p class="lede">${esc(identity.description)}</p>` : ""}
|
|
380
|
+
${head}
|
|
381
|
+
${doc.subject ? `<p class="meta">Agent <code>${esc(doc.subject.id)}</code></p>` : ""}
|
|
382
|
+
${isPackage ? `<p class="meta">Package <code>${esc(str(doc.package?.name))}</code> ${esc(str(doc.package?.version))}</p>` : ""}
|
|
383
|
+
<p class="meta">${doc.assembled_at ? `Assembled ${esc(utc(doc.assembled_at))}.` : "Fixed to its package, not to a moment."}${doc.stale_after ? ` Treat it as an old view after ${esc(utc(doc.stale_after))}, and assemble it again.` : ""} ${sources.length} source${sources.length === 1 ? "" : "s"}, ${notStated.length} thing${notStated.length === 1 ? "" : "s"} not stated.</p>
|
|
384
|
+
</header>
|
|
385
|
+
${isPackage ? "" : band("access", "Reaching it", access, accessBody)}
|
|
386
|
+
${band("sells", "What it offers", s.sells, sellsBody)}
|
|
387
|
+
${band("identity", "Who it is", s.identity, whoBody)}
|
|
388
|
+
${band("asked", "Standard questions", s.asked, askedBody)}
|
|
389
|
+
${band("refuses", "What it refuses", s.refuses, refusesBody)}
|
|
390
|
+
${band("reaches", "What it reaches", s.reaches, reachesBody)}
|
|
391
|
+
${band("leaves", "Records a job leaves", s.leaves, recordsBody)}
|
|
392
|
+
${band("configs", "What a job may set", s.configs, configsBody)}
|
|
393
|
+
${band("triggers", "When it acts on its own", s.triggers, triggersBody)}
|
|
394
|
+
${isPackage ? "" : band("handling", "Where your content goes", s.handling, handlingBody)}
|
|
395
|
+
${isPackage ? "" : band("standing", "Checked by others", s.standing, standingBody)}
|
|
396
|
+
<details open id="not-stated" class="band"><summary><h2>Not stated</h2><span class="from">${notStated.length} question${notStated.length === 1 ? "" : "s"} the sources leave open</span></summary><div class="body">${notStatedBody}</div></details>
|
|
397
|
+
<details open id="sources" class="band"><summary><h2>Sources</h2><span class="from">what was read, and whether each was signed</span></summary><div class="body">${sourcesBody}</div></details>
|
|
398
|
+
<footer>
|
|
399
|
+
<p>An AgentDoc is assembled from what an agent publishes. It carries no score and no badge. <a href="./.well-known/agentdoc.json">The document this page shows</a> is for programs. Read more at <a href="https://agentdoc.net">agentdoc.net</a>.</p>
|
|
400
|
+
</footer>
|
|
401
|
+
</main>
|
|
402
|
+
</body>
|
|
403
|
+
</html>
|
|
404
|
+
`;
|
|
405
|
+
}
|
|
@@ -0,0 +1,41 @@
|
|
|
1
|
+
import type { SignatureState } from "./types.js";
|
|
2
|
+
import { type Rec } from "./util.js";
|
|
3
|
+
export declare const DESCRIPTOR_TAG = "descriptor-statement-v1";
|
|
4
|
+
export declare const EVAL_TAG = "agent-eval-record-v1";
|
|
5
|
+
export declare const SOW_TAG = "agent-sow-v1";
|
|
6
|
+
export interface SignatureCheck {
|
|
7
|
+
state: SignatureState;
|
|
8
|
+
/** The key that signed, where one verified or was named. */
|
|
9
|
+
by?: string;
|
|
10
|
+
/** Why it is not verified, in words. */
|
|
11
|
+
note?: string;
|
|
12
|
+
}
|
|
13
|
+
/** The `descriptor-statement-v1` check of Section 6.6: by the subject's own key. */
|
|
14
|
+
export declare function checkDescriptorSignature(doc: unknown): SignatureCheck;
|
|
15
|
+
/** The `agent-eval-record-v1` check of Section 8.4: by the evaluator key inside the record, which must be the record's own `by`. */
|
|
16
|
+
export declare function checkEvalSignature(rec: unknown): SignatureCheck;
|
|
17
|
+
/** Agent SoW's provider signature on a standing proposal: by the key the provider seat names, over `agent-sow-v1`. */
|
|
18
|
+
export declare function checkTermsSignature(doc: unknown): SignatureCheck;
|
|
19
|
+
/** DSSE's pre-authentication encoding: what an envelope's signature is over. */
|
|
20
|
+
export declare function pae(payloadType: string, payload: Uint8Array): Uint8Array;
|
|
21
|
+
/** An attestation as read: what it says, and whether a signature on it verifies. */
|
|
22
|
+
export interface OpenedAttestation {
|
|
23
|
+
statement: Rec;
|
|
24
|
+
check: SignatureCheck;
|
|
25
|
+
}
|
|
26
|
+
/**
|
|
27
|
+
* Read an attestation: a DSSE envelope (`payloadType`, base64 `payload`,
|
|
28
|
+
* `signatures[{keyid, sig}]`) or a family record (`signatures[{tag, by,
|
|
29
|
+
* sig}]`). Null when it is neither.
|
|
30
|
+
*/
|
|
31
|
+
export declare function openAttestation(doc: unknown): OpenedAttestation | null;
|
|
32
|
+
/** The nkey spelling of a raw 32-byte Ed25519 seed: `SU…`, 58 characters. */
|
|
33
|
+
export declare function encodeUserSeed(raw: Uint8Array): string;
|
|
34
|
+
/**
|
|
35
|
+
* Bind a draft Descriptor to the key whose seed this is and sign it with
|
|
36
|
+
* `descriptor-statement-v1` (Section 6.6). The subject's `id` becomes the
|
|
37
|
+
* key; a handle already there is kept. Any earlier statement signature is
|
|
38
|
+
* replaced. Throws when the Descriptor is already bound to another key,
|
|
39
|
+
* because a bound Descriptor's subject never changes (Section 6.2).
|
|
40
|
+
*/
|
|
41
|
+
export declare function signDescriptor(descriptor: Rec, seed: string): Rec;
|
|
@@ -0,0 +1,176 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The signatures an assembler checks, each as its own standard defines it,
|
|
3
|
+
* and the Ed25519 key a subject signs its Descriptor with.
|
|
4
|
+
*
|
|
5
|
+
* - `descriptor-statement-v1` (Section 6.6): by the subject's own key, over
|
|
6
|
+
* the tag, one newline, and the canonical JSON of the Descriptor without
|
|
7
|
+
* `signatures`.
|
|
8
|
+
* - `agent-eval-record-v1` (Section 8.4) and every record of Section 8.1: by
|
|
9
|
+
* the issuer's key, the same way, with the by-equality rule.
|
|
10
|
+
* - Agent SoW's provider signature on a standing proposal: `agent-sow-v1`,
|
|
11
|
+
* by the key the provider seat names.
|
|
12
|
+
* - An attestation in a DSSE envelope: over DSSE's pre-authentication
|
|
13
|
+
* encoding of its payload.
|
|
14
|
+
*
|
|
15
|
+
* Each answers `verified`, `unsigned`, `failed` or `not_checked`, and never
|
|
16
|
+
* throws on what it is given. Keys are nkey user keys (`U…`).
|
|
17
|
+
*/
|
|
18
|
+
import { NKEY_PREFIX, NOT_PUBLIC_PREFIX, base32Encode, canonicalJSON, crc16, decodeSignature, encodeSignature, fromLooseBase64, rawUserKey, signTagged, signerFromUserSeed, utf8, verifyRaw, verifyTagged, } from "@common-agent/crypto";
|
|
19
|
+
import { arr, isObj, str } from "./util.js";
|
|
20
|
+
export const DESCRIPTOR_TAG = "descriptor-statement-v1";
|
|
21
|
+
export const EVAL_TAG = "agent-eval-record-v1";
|
|
22
|
+
export const SOW_TAG = "agent-sow-v1";
|
|
23
|
+
/** A 64-byte signature from padded base64, or from any base64 spelling a writer before the strict rule used. */
|
|
24
|
+
function sigBytes(s) {
|
|
25
|
+
const strict = decodeSignature(s);
|
|
26
|
+
if (strict)
|
|
27
|
+
return strict;
|
|
28
|
+
const loose = fromLooseBase64(s);
|
|
29
|
+
return loose && loose.length === 64 ? loose : null;
|
|
30
|
+
}
|
|
31
|
+
/** The canonical JSON of a document without its `signatures`, or null where it has no spelling. */
|
|
32
|
+
function bodyCanonical(doc) {
|
|
33
|
+
const { signatures: _s, ...body } = doc;
|
|
34
|
+
try {
|
|
35
|
+
return canonicalJSON(body);
|
|
36
|
+
}
|
|
37
|
+
catch {
|
|
38
|
+
return null;
|
|
39
|
+
}
|
|
40
|
+
}
|
|
41
|
+
/** A family record's tagged signature (Section 8.1), by `by`. */
|
|
42
|
+
function taggedCheck(doc, tag, by, sig) {
|
|
43
|
+
if (typeof by !== "string" || !by)
|
|
44
|
+
return { state: "failed", note: "the signature names no key" };
|
|
45
|
+
if (!rawUserKey(by))
|
|
46
|
+
return { state: "not_checked", by, note: "the key is not spelled as a user key (U…) this tool reads" };
|
|
47
|
+
const canonical = bodyCanonical(doc);
|
|
48
|
+
if (canonical === null)
|
|
49
|
+
return { state: "failed", by, note: "the document has no canonical JSON spelling" };
|
|
50
|
+
return verifyTagged(by, `${tag}\n`, canonical, sigBytes(sig))
|
|
51
|
+
? { state: "verified", by }
|
|
52
|
+
: { state: "failed", by, note: "the signature does not verify" };
|
|
53
|
+
}
|
|
54
|
+
/** The `descriptor-statement-v1` check of Section 6.6: by the subject's own key. */
|
|
55
|
+
export function checkDescriptorSignature(doc) {
|
|
56
|
+
if (!isObj(doc))
|
|
57
|
+
return { state: "failed", note: "not a document" };
|
|
58
|
+
const entry = arr(doc.signatures).find((s) => isObj(s) && s.tag === DESCRIPTOR_TAG);
|
|
59
|
+
if (!entry)
|
|
60
|
+
return { state: "unsigned" };
|
|
61
|
+
const subjectId = isObj(doc.subject) ? doc.subject.id : undefined;
|
|
62
|
+
if (entry.by !== subjectId)
|
|
63
|
+
return { state: "failed", by: str(entry.by) || undefined, note: "the signature is not by the subject's own key" };
|
|
64
|
+
return taggedCheck(doc, DESCRIPTOR_TAG, entry.by, entry.sig);
|
|
65
|
+
}
|
|
66
|
+
/** The `agent-eval-record-v1` check of Section 8.4: by the evaluator key inside the record, which must be the record's own `by`. */
|
|
67
|
+
export function checkEvalSignature(rec) {
|
|
68
|
+
if (!isObj(rec))
|
|
69
|
+
return { state: "failed", note: "not a document" };
|
|
70
|
+
const entry = arr(rec.signatures).find((s) => isObj(s) && s.tag === EVAL_TAG);
|
|
71
|
+
if (!entry)
|
|
72
|
+
return { state: "unsigned" };
|
|
73
|
+
if (rec.by !== undefined && rec.by !== entry.by)
|
|
74
|
+
return { state: "failed", by: str(entry.by) || undefined, note: "the record's by and the signature's by are different keys" };
|
|
75
|
+
return taggedCheck(rec, EVAL_TAG, entry.by, entry.sig);
|
|
76
|
+
}
|
|
77
|
+
/** Agent SoW's provider signature on a standing proposal: by the key the provider seat names, over `agent-sow-v1`. */
|
|
78
|
+
export function checkTermsSignature(doc) {
|
|
79
|
+
if (!isObj(doc))
|
|
80
|
+
return { state: "failed", note: "not a document" };
|
|
81
|
+
const entry = arr(doc.signatures).find((s) => isObj(s) && s.role === "provider");
|
|
82
|
+
if (!entry)
|
|
83
|
+
return { state: "unsigned" };
|
|
84
|
+
const parties = isObj(doc.parties) ? doc.parties : {};
|
|
85
|
+
const seat = isObj(parties.provider) ? parties.provider : {};
|
|
86
|
+
if (seat.owner_key !== undefined && seat.owner_key !== entry.key)
|
|
87
|
+
return { state: "failed", by: str(entry.key) || undefined, note: "the provider's signature is not by the key its seat names" };
|
|
88
|
+
return taggedCheck(doc, SOW_TAG, entry.key, entry.sig);
|
|
89
|
+
}
|
|
90
|
+
/** DSSE's pre-authentication encoding: what an envelope's signature is over. */
|
|
91
|
+
export function pae(payloadType, payload) {
|
|
92
|
+
const type = utf8(payloadType);
|
|
93
|
+
const head = utf8(`DSSEv1 ${type.length} ${payloadType} ${payload.length} `);
|
|
94
|
+
const out = new Uint8Array(head.length + payload.length);
|
|
95
|
+
out.set(head, 0);
|
|
96
|
+
out.set(payload, head.length);
|
|
97
|
+
return out;
|
|
98
|
+
}
|
|
99
|
+
/**
|
|
100
|
+
* Read an attestation: a DSSE envelope (`payloadType`, base64 `payload`,
|
|
101
|
+
* `signatures[{keyid, sig}]`) or a family record (`signatures[{tag, by,
|
|
102
|
+
* sig}]`). Null when it is neither.
|
|
103
|
+
*/
|
|
104
|
+
export function openAttestation(doc) {
|
|
105
|
+
if (!isObj(doc))
|
|
106
|
+
return null;
|
|
107
|
+
if (typeof doc.payloadType === "string" && typeof doc.payload === "string") {
|
|
108
|
+
const payload = fromLooseBase64(doc.payload);
|
|
109
|
+
if (!payload)
|
|
110
|
+
return null;
|
|
111
|
+
let statement;
|
|
112
|
+
try {
|
|
113
|
+
statement = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(payload));
|
|
114
|
+
}
|
|
115
|
+
catch {
|
|
116
|
+
return null;
|
|
117
|
+
}
|
|
118
|
+
if (!isObj(statement))
|
|
119
|
+
return null;
|
|
120
|
+
const sigs = arr(doc.signatures).filter(isObj);
|
|
121
|
+
if (!sigs.length)
|
|
122
|
+
return { statement, check: { state: "unsigned" } };
|
|
123
|
+
const message = pae(doc.payloadType, payload);
|
|
124
|
+
let named;
|
|
125
|
+
for (const s of sigs) {
|
|
126
|
+
const key = str(s.keyid);
|
|
127
|
+
named ??= key || undefined;
|
|
128
|
+
const raw = rawUserKey(key);
|
|
129
|
+
if (raw && verifyRaw(raw, message, sigBytes(s.sig)))
|
|
130
|
+
return { statement, check: { state: "verified", by: key } };
|
|
131
|
+
}
|
|
132
|
+
return { statement, check: named && !rawUserKey(named) ? { state: "not_checked", by: named, note: "the key is not spelled as a user key (U…) this tool reads" } : { state: "failed", by: named, note: "no signature on it verifies" } };
|
|
133
|
+
}
|
|
134
|
+
const entry = arr(doc.signatures).find((s) => isObj(s) && typeof s.tag === "string");
|
|
135
|
+
if (!entry)
|
|
136
|
+
return { statement: doc, check: { state: "unsigned" } };
|
|
137
|
+
if (doc.by !== undefined && doc.by !== entry.by)
|
|
138
|
+
return { statement: doc, check: { state: "failed", by: str(entry.by) || undefined, note: "the record's by and the signature's by are different keys" } };
|
|
139
|
+
return { statement: doc, check: taggedCheck(doc, str(entry.tag), entry.by, entry.sig) };
|
|
140
|
+
}
|
|
141
|
+
// ── the subject's key ──────────────────────────────────────────────────────
|
|
142
|
+
/** The nkey spelling of a raw 32-byte Ed25519 seed: `SU…`, 58 characters. */
|
|
143
|
+
export function encodeUserSeed(raw) {
|
|
144
|
+
if (!(raw instanceof Uint8Array) || raw.length !== 32)
|
|
145
|
+
throw new Error("an Ed25519 seed is 32 bytes");
|
|
146
|
+
const body = new Uint8Array(34);
|
|
147
|
+
body[0] = NOT_PUBLIC_PREFIX.seed | (NKEY_PREFIX.user >> 5);
|
|
148
|
+
body[1] = (NKEY_PREFIX.user & 31) << 3;
|
|
149
|
+
body.set(raw, 2);
|
|
150
|
+
const crc = crc16(body);
|
|
151
|
+
const full = new Uint8Array(36);
|
|
152
|
+
full.set(body);
|
|
153
|
+
full[34] = crc & 0xff;
|
|
154
|
+
full[35] = crc >> 8;
|
|
155
|
+
return base32Encode(full);
|
|
156
|
+
}
|
|
157
|
+
/**
|
|
158
|
+
* Bind a draft Descriptor to the key whose seed this is and sign it with
|
|
159
|
+
* `descriptor-statement-v1` (Section 6.6). The subject's `id` becomes the
|
|
160
|
+
* key; a handle already there is kept. Any earlier statement signature is
|
|
161
|
+
* replaced. Throws when the Descriptor is already bound to another key,
|
|
162
|
+
* because a bound Descriptor's subject never changes (Section 6.2).
|
|
163
|
+
*/
|
|
164
|
+
export function signDescriptor(descriptor, seed) {
|
|
165
|
+
const signer = signerFromUserSeed(seed);
|
|
166
|
+
const key = signer.getPublicKey();
|
|
167
|
+
const subject = isObj(descriptor.subject) ? descriptor.subject : {};
|
|
168
|
+
if (subject.id !== undefined && subject.id !== key) {
|
|
169
|
+
throw new Error(`this Descriptor is bound to ${String(subject.id)}, not to this key. A bound Descriptor's subject never changes; a new agent gets a new Descriptor.`);
|
|
170
|
+
}
|
|
171
|
+
const { signatures: _old, ...rest } = descriptor;
|
|
172
|
+
const others = arr(descriptor.signatures).filter((s) => !(isObj(s) && s.tag === DESCRIPTOR_TAG));
|
|
173
|
+
const body = { ...rest, subject: { ...subject, id: key } };
|
|
174
|
+
const sig = encodeSignature(signTagged(signer, `${DESCRIPTOR_TAG}\n`, canonicalJSON(body)));
|
|
175
|
+
return { ...body, signatures: [...others, { tag: DESCRIPTOR_TAG, by: key, sig, alg: "ed25519" }] };
|
|
176
|
+
}
|