@agentproto/governance 0.1.0-alpha.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/AGENTGOVERNANCE.md +489 -0
- package/LICENSE +21 -0
- package/README.md +113 -0
- package/dist/chunk-5G463T6C.mjs +3 -0
- package/dist/chunk-5G463T6C.mjs.map +1 -0
- package/dist/chunk-7GHDRKSD.mjs +3 -0
- package/dist/chunk-7GHDRKSD.mjs.map +1 -0
- package/dist/chunk-J2DX2WOA.mjs +266 -0
- package/dist/chunk-J2DX2WOA.mjs.map +1 -0
- package/dist/chunk-UVBFLWSG.mjs +137 -0
- package/dist/chunk-UVBFLWSG.mjs.map +1 -0
- package/dist/chunk-VWEBMWO2.mjs +149 -0
- package/dist/chunk-VWEBMWO2.mjs.map +1 -0
- package/dist/doctypes/index.d.ts +167 -0
- package/dist/doctypes/index.mjs +4 -0
- package/dist/doctypes/index.mjs.map +1 -0
- package/dist/hash-chain/index.d.ts +40 -0
- package/dist/hash-chain/index.mjs +4 -0
- package/dist/hash-chain/index.mjs.map +1 -0
- package/dist/index.d.ts +31 -0
- package/dist/index.mjs +19 -0
- package/dist/index.mjs.map +1 -0
- package/dist/policy/index.d.ts +104 -0
- package/dist/policy/index.mjs +82 -0
- package/dist/policy/index.mjs.map +1 -0
- package/dist/policy-YqpSg3Ep.d.ts +146 -0
- package/dist/renderers/index.d.ts +73 -0
- package/dist/renderers/index.mjs +64 -0
- package/dist/renderers/index.mjs.map +1 -0
- package/dist/validators/index.d.ts +61 -0
- package/dist/validators/index.mjs +5 -0
- package/dist/validators/index.mjs.map +1 -0
- package/dist/verify-e_UfVr02.d.ts +50 -0
- package/package.json +97 -0
- package/src/spec/canvakit-templates/governance.signing-portal/template.canvakit.html +100 -0
|
@@ -0,0 +1,489 @@
|
|
|
1
|
+
# agentgovernance/v1
|
|
2
|
+
|
|
3
|
+
**Status:** alpha (1.0.0-alpha) · **Domain:** governance.sh · **License:** MIT
|
|
4
|
+
**Reference implementation:**
|
|
5
|
+
[@agentproto/governance](https://npmjs.com/package/@agentproto/governance)
|
|
6
|
+
**Repository:** https://github.com/agentproto/agentproto
|
|
7
|
+
|
|
8
|
+
---
|
|
9
|
+
|
|
10
|
+
## 1. Introduction
|
|
11
|
+
|
|
12
|
+
`agentgovernance/v1` is an **open file-format standard** for recording
|
|
13
|
+
approvals, audit logs, and autonomy policies as workspace files. It provides a
|
|
14
|
+
**vendor-neutral**, **filesystem-first**, **third-party-verifiable** primitive
|
|
15
|
+
for any system — human, agentic, or hybrid — that needs auditable decisions.
|
|
16
|
+
|
|
17
|
+
Three doctypes:
|
|
18
|
+
|
|
19
|
+
| Doctype | File path | Purpose |
|
|
20
|
+
| ------------- | ------------------------------------------------------------ | ----------------------------------------------------------- |
|
|
21
|
+
| `signature` | `<artifact>/../signatures/<signer>-<isoDate>.signature.json` | Universal approval primitive (one signature event per file) |
|
|
22
|
+
| `audit-event` | `<scope>/audit/audit-log.jsonl` (one line per event) | Append-only hash-chained event log |
|
|
23
|
+
| `policy` | `<scope>/policies/<slug>/POLICY.md` | Declarative autonomy rule |
|
|
24
|
+
|
|
25
|
+
A workspace receiving these files can validate every doctype + verify the audit
|
|
26
|
+
chain end-to-end **without our infrastructure** using the published
|
|
27
|
+
[hash-chain protocol](./src/spec/hash-chain/protocol.md). Third-party verifiers
|
|
28
|
+
can be implemented in any language.
|
|
29
|
+
|
|
30
|
+
### 1.1 Why this is its own standard
|
|
31
|
+
|
|
32
|
+
The doctypes are **domain-agnostic**: `signature.json`, `audit-log.jsonl`,
|
|
33
|
+
`POLICY.md` reference no business concepts (no services, no engagements, no
|
|
34
|
+
counterparties). They describe pure governance primitives. Any workflow that
|
|
35
|
+
needs auditable approvals — clinician overrides, approve-to-publish flows,
|
|
36
|
+
AI-agent action gates, board votes — adopts `agentgovernance/v1` directly.
|
|
37
|
+
|
|
38
|
+
`agentgovernance/v1` is a **peer standard** to `agentcompanies/v1`
|
|
39
|
+
(companies.sh) and is **extended by** `agentagencies/v1` (agencies.sh).
|
|
40
|
+
|
|
41
|
+
### 1.2 Conventions
|
|
42
|
+
|
|
43
|
+
All `agentgovernance/v1` files follow the conventions established by
|
|
44
|
+
[`agentcompanies/v1`](https://github.com/paperclipai/paperclip/blob/master/docs/companies/companies-spec.md):
|
|
45
|
+
|
|
46
|
+
- **Markdown canonical** with YAML frontmatter (for `POLICY.md`).
|
|
47
|
+
- **JSON canonical** for `signature.json` and `audit-log.jsonl` lines.
|
|
48
|
+
- **Slug-based references**, never database IDs.
|
|
49
|
+
- **`schema: agentgovernance/v1`** field on every doctype frontmatter / object.
|
|
50
|
+
- **Vendor-specific extensions** under `metadata.<vendor>.*`.
|
|
51
|
+
- **Git-native**: any git repository hosting these files is a valid governance
|
|
52
|
+
package.
|
|
53
|
+
|
|
54
|
+
A workspace using `agentgovernance/v1` doctypes does not need to be an
|
|
55
|
+
`agentcompanies/v1` package — it can be any folder containing the doctypes.
|
|
56
|
+
|
|
57
|
+
---
|
|
58
|
+
|
|
59
|
+
## 2. Doctype: `signature`
|
|
60
|
+
|
|
61
|
+
A signature is the universal approval primitive. Every approval — of an
|
|
62
|
+
agreement, a deliverable, an invoice, a policy override, an agent-issued action
|
|
63
|
+
— is a signature on an artifact, recorded as a JSON file alongside the artifact
|
|
64
|
+
being signed.
|
|
65
|
+
|
|
66
|
+
### 2.1 File location
|
|
67
|
+
|
|
68
|
+
```
|
|
69
|
+
<artifact-parent-dir>/signatures/<signer-kind>-<signer-slug>-<YYYY-MM-DD>.signature.json
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
Example:
|
|
73
|
+
|
|
74
|
+
```
|
|
75
|
+
engagements/2026-acme-website-redesign/signatures/operator-jeremy-2026-04-15.signature.json
|
|
76
|
+
```
|
|
77
|
+
|
|
78
|
+
Multiple signatures by the same signer on the same artifact (e.g., re-issuance
|
|
79
|
+
after revocation) MUST use distinct timestamps. Append-only — files are not
|
|
80
|
+
deleted; revocation is a frontmatter mutation (`revokedAt`, `revokedReason`) or
|
|
81
|
+
a fresh file with `evidence` referencing the prior.
|
|
82
|
+
|
|
83
|
+
### 2.2 Schema
|
|
84
|
+
|
|
85
|
+
```typescript
|
|
86
|
+
{
|
|
87
|
+
"schema": "agentgovernance/v1",
|
|
88
|
+
"doctype": "signature",
|
|
89
|
+
"signer": "<kind>:<slug>", // canonical: "operator:jeremy", "counterparty:acme-corp", "agent:ai-paralegal"
|
|
90
|
+
"signerKind": "operator" | "user" | "counterparty" | "agent" | "external",
|
|
91
|
+
"signerEmail"?: string,
|
|
92
|
+
"artifactPath": "engagements/2026-acme/AGREEMENT.md", // workspace-relative
|
|
93
|
+
"documentHash": "<64-char hex SHA-256 of artifact bytes>",
|
|
94
|
+
"method": "typed_name" | "agent_confirm" | "click_through" | "esign_external",
|
|
95
|
+
"evidence": <method-specific shape>,
|
|
96
|
+
"signedAt": "2026-04-15T10:23:45.000Z",
|
|
97
|
+
"revokedAt"?: string,
|
|
98
|
+
"revokedReason"?: string,
|
|
99
|
+
"metadata"?: { ... }
|
|
100
|
+
}
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
`evidence.kind` MUST equal `method` (enforced at validation time).
|
|
104
|
+
|
|
105
|
+
### 2.3 Signing methods
|
|
106
|
+
|
|
107
|
+
#### 2.3.1 `typed_name`
|
|
108
|
+
|
|
109
|
+
Human types name + nonce on a tokenized portal page. Captures IP + UA +
|
|
110
|
+
timestamp + nonce.
|
|
111
|
+
|
|
112
|
+
```json
|
|
113
|
+
{
|
|
114
|
+
"evidence": {
|
|
115
|
+
"kind": "typed_name",
|
|
116
|
+
"signerName": "Jeremy Doe",
|
|
117
|
+
"ipAddress": "192.0.2.1",
|
|
118
|
+
"userAgent": "Mozilla/5.0 …",
|
|
119
|
+
"nonce": "<one-shot URL token>",
|
|
120
|
+
"signedUrlToken": "<optional>"
|
|
121
|
+
}
|
|
122
|
+
}
|
|
123
|
+
```
|
|
124
|
+
|
|
125
|
+
#### 2.3.2 `agent_confirm`
|
|
126
|
+
|
|
127
|
+
Agent records explicit confirmation. Evidence carries `modelId` +
|
|
128
|
+
`promptContextHash` + optional reasoning summary + conversation turn id. Agents
|
|
129
|
+
MUST have the `governance.sign_as_agent` skill (or app-level equivalent) granted
|
|
130
|
+
by a `POLICY.md`.
|
|
131
|
+
|
|
132
|
+
```json
|
|
133
|
+
{
|
|
134
|
+
"evidence": {
|
|
135
|
+
"kind": "agent_confirm",
|
|
136
|
+
"modelId": "claude-sonnet-4-6",
|
|
137
|
+
"promptContextHash": "<64-char hex>",
|
|
138
|
+
"reasoningSummary": "Cap policy satisfied; under threshold.",
|
|
139
|
+
"conversationTurnId": "t_abc123",
|
|
140
|
+
"authorizedByPolicy": "auto-approve-quotes-under-200eur"
|
|
141
|
+
}
|
|
142
|
+
}
|
|
143
|
+
```
|
|
144
|
+
|
|
145
|
+
#### 2.3.3 `click_through`
|
|
146
|
+
|
|
147
|
+
Single-click confirmation from a signed URL. Lightweight; suitable for
|
|
148
|
+
low-stakes approvals.
|
|
149
|
+
|
|
150
|
+
```json
|
|
151
|
+
{
|
|
152
|
+
"evidence": {
|
|
153
|
+
"kind": "click_through",
|
|
154
|
+
"ipAddress": "192.0.2.1",
|
|
155
|
+
"userAgent": "Mozilla/5.0 …",
|
|
156
|
+
"signedUrlToken": "<one-shot>"
|
|
157
|
+
}
|
|
158
|
+
}
|
|
159
|
+
```
|
|
160
|
+
|
|
161
|
+
#### 2.3.4 `esign_external`
|
|
162
|
+
|
|
163
|
+
Wraps an external e-signature provider (DocuSeal, HelloSign, etc.). The signed
|
|
164
|
+
PDF MUST be archived alongside the agreement.
|
|
165
|
+
|
|
166
|
+
```json
|
|
167
|
+
{
|
|
168
|
+
"evidence": {
|
|
169
|
+
"kind": "esign_external",
|
|
170
|
+
"provider": "docuseal",
|
|
171
|
+
"externalRef": "<envelope-id>",
|
|
172
|
+
"signedPdfRef": "engagements/2026-acme/AGREEMENT.signed.pdf"
|
|
173
|
+
}
|
|
174
|
+
}
|
|
175
|
+
```
|
|
176
|
+
|
|
177
|
+
---
|
|
178
|
+
|
|
179
|
+
## 3. Doctype: `audit-event` (audit-log.jsonl)
|
|
180
|
+
|
|
181
|
+
Each line of `<scope>/audit/audit-log.jsonl` is one audit event, encoded as a
|
|
182
|
+
single JSON object on one line. Lines are linked by an HMAC-SHA256 chain.
|
|
183
|
+
|
|
184
|
+
### 3.1 Scope
|
|
185
|
+
|
|
186
|
+
The `<scope>` directory determines the chain's scope. Common scopes:
|
|
187
|
+
|
|
188
|
+
- `audit/audit-log.jsonl` — workspace / company-level events.
|
|
189
|
+
- `engagements/<slug>/audit/audit-log.jsonl` — engagement-scoped events
|
|
190
|
+
(recommended for `agentagencies/v1`).
|
|
191
|
+
- Any other folder may host its own log — there is no global registry.
|
|
192
|
+
|
|
193
|
+
Each scope has its own chain, its own genesis seed, and its own anchor cadence.
|
|
194
|
+
|
|
195
|
+
### 3.2 Schema
|
|
196
|
+
|
|
197
|
+
```typescript
|
|
198
|
+
{
|
|
199
|
+
"schema": "agentgovernance/v1",
|
|
200
|
+
"doctype": "audit-event",
|
|
201
|
+
"actorKind": "operator" | "user" | "counterparty" | "agent" | "system",
|
|
202
|
+
"actorId": <slug | null>, // null for actorKind=system
|
|
203
|
+
"entityType": "<known type or extension>",
|
|
204
|
+
"entityId": "<workspace path or governance-internal id>",
|
|
205
|
+
"action": "<entity>.<verb>", // lowercase, e.g., "signature.created"
|
|
206
|
+
"payload"?: { ... }, // action-specific
|
|
207
|
+
"prevSignature": "<64-char hex>", // chain link
|
|
208
|
+
"signature": "<64-char hex>", // chain link
|
|
209
|
+
"requestId"?: string,
|
|
210
|
+
"traceId"?: string,
|
|
211
|
+
"ipAddress"?: string,
|
|
212
|
+
"userAgent"?: string,
|
|
213
|
+
"createdAt": "<ISO-8601 UTC>",
|
|
214
|
+
"metadata"?: { ... }
|
|
215
|
+
}
|
|
216
|
+
```
|
|
217
|
+
|
|
218
|
+
Implementations SHOULD use known `entityType` values (`signature`,
|
|
219
|
+
`audit-event`, `policy`, `approval`, plus any from `agentagencies/v1` or
|
|
220
|
+
`agentcompanies/v1` if those specs are in use). Implementations SHOULD NOT
|
|
221
|
+
introduce new types ad-hoc — vendor-specific events go under
|
|
222
|
+
`metadata.<vendor>.*`.
|
|
223
|
+
|
|
224
|
+
### 3.3 Hash-chain protocol
|
|
225
|
+
|
|
226
|
+
See [`src/spec/hash-chain/protocol.md`](./src/spec/hash-chain/protocol.md) for
|
|
227
|
+
the full specification with reference test vectors.
|
|
228
|
+
|
|
229
|
+
Summary:
|
|
230
|
+
|
|
231
|
+
```
|
|
232
|
+
signature_n = HMAC-SHA256(
|
|
233
|
+
key = secret_bytes,
|
|
234
|
+
data = prev_signature_hex_utf8 ‖ canonical_bytes(row_n_minus_signature)
|
|
235
|
+
)
|
|
236
|
+
```
|
|
237
|
+
|
|
238
|
+
The first line uses the workspace genesis seed as `prev_signature`.
|
|
239
|
+
|
|
240
|
+
### 3.4 External anchors
|
|
241
|
+
|
|
242
|
+
Periodically (default: every 1000 lines), the latest `signature` is published to
|
|
243
|
+
an external sink (S3 with object-lock, transparency log, public Git). A
|
|
244
|
+
workspace cannot rewrite history without invalidating an external anchor.
|
|
245
|
+
|
|
246
|
+
---
|
|
247
|
+
|
|
248
|
+
## 4. Doctype: `policy` (POLICY.md)
|
|
249
|
+
|
|
250
|
+
A POLICY.md is a declarative autonomy rule with YAML frontmatter and a markdown
|
|
251
|
+
body. Frontmatter is used by the policy engine; body is human/agent-readable
|
|
252
|
+
narrative.
|
|
253
|
+
|
|
254
|
+
### 4.1 File location
|
|
255
|
+
|
|
256
|
+
```
|
|
257
|
+
<scope>/policies/<slug>/POLICY.md
|
|
258
|
+
```
|
|
259
|
+
|
|
260
|
+
### 4.2 Frontmatter schema
|
|
261
|
+
|
|
262
|
+
```yaml
|
|
263
|
+
schema: agentgovernance/v1
|
|
264
|
+
doctype: policy
|
|
265
|
+
slug: invoice-cap-500eur
|
|
266
|
+
name: Invoice cap 500 EUR
|
|
267
|
+
description:
|
|
268
|
+
Operators may issue invoices ≤ 500 EUR autonomously; founder signature
|
|
269
|
+
required above.
|
|
270
|
+
appliesTo:
|
|
271
|
+
- actorKind: operator
|
|
272
|
+
actionType: agency.issue_invoice
|
|
273
|
+
caps:
|
|
274
|
+
- field: amount
|
|
275
|
+
max: 500
|
|
276
|
+
currency: EUR
|
|
277
|
+
threshold: single # auto | single | all_of | any_of | weighted_threshold
|
|
278
|
+
requiredWeight: 0 # required when threshold=weighted_threshold
|
|
279
|
+
requiredSignatures:
|
|
280
|
+
- signer: operator:founder
|
|
281
|
+
method: typed_name
|
|
282
|
+
weight: 1 # only used by weighted_threshold
|
|
283
|
+
deadline: PT24H # ISO-8601 duration
|
|
284
|
+
escalation:
|
|
285
|
+
leadTime: PT2H
|
|
286
|
+
escalateTo: [operator:cofounder]
|
|
287
|
+
metadata:
|
|
288
|
+
agency:
|
|
289
|
+
appliesToServices: [emergency-callout, drain-cleaning]
|
|
290
|
+
```
|
|
291
|
+
|
|
292
|
+
### 4.3 Threshold semantics
|
|
293
|
+
|
|
294
|
+
| `threshold` | Resume condition |
|
|
295
|
+
| -------------------- | -------------------------------------------------------------------- |
|
|
296
|
+
| `auto` | Tool may proceed without signatures (action is logged but not gated) |
|
|
297
|
+
| `single` / `any_of` | Any one signature from `requiredSignatures` suffices |
|
|
298
|
+
| `all_of` | Every entry in `requiredSignatures` must sign |
|
|
299
|
+
| `weighted_threshold` | Sum of `weight` of collected signatures must reach `requiredWeight` |
|
|
300
|
+
|
|
301
|
+
### 4.4 Wildcard signers
|
|
302
|
+
|
|
303
|
+
A `requiredSignatures` entry may use `*` as the slug to mean "any signer of this
|
|
304
|
+
kind":
|
|
305
|
+
|
|
306
|
+
```yaml
|
|
307
|
+
requiredSignatures:
|
|
308
|
+
- signer: operator:*
|
|
309
|
+
method: typed_name
|
|
310
|
+
```
|
|
311
|
+
|
|
312
|
+
This is satisfied by any operator's signature.
|
|
313
|
+
|
|
314
|
+
---
|
|
315
|
+
|
|
316
|
+
## 5. Contractual approval framework
|
|
317
|
+
|
|
318
|
+
The framework unifies what would otherwise be three concepts (signing legal
|
|
319
|
+
documents, approval gates, audit decisions) into one: **every approval is a
|
|
320
|
+
signature on an artifact**.
|
|
321
|
+
|
|
322
|
+
### 5.1 Standard flow
|
|
323
|
+
|
|
324
|
+
A tool that needs approval for an action:
|
|
325
|
+
|
|
326
|
+
1. **Drafts** the artifact representing the action (e.g., an `INVOICE.md` with
|
|
327
|
+
`status: pending_approval`).
|
|
328
|
+
2. **Looks up** the matching `POLICY.md` (by `appliesTo.actorKind` +
|
|
329
|
+
`appliesTo.actionType`).
|
|
330
|
+
3. **Sets** `requiredSignatures` on the artifact frontmatter from the policy.
|
|
331
|
+
4. **Suspends** (workflow primitive — runtime-specific; see adapter packages).
|
|
332
|
+
5. **Notifies** required signers (channel dispatcher — see
|
|
333
|
+
`agentagencies/v1.channels` or app-level equivalent).
|
|
334
|
+
|
|
335
|
+
When a signer (human OR agent) signs:
|
|
336
|
+
|
|
337
|
+
1. The runtime writes a `signature.json` next to the artifact.
|
|
338
|
+
2. The runtime appends an `audit-event` to the relevant `audit-log.jsonl` (with
|
|
339
|
+
`action: signature.created`).
|
|
340
|
+
3. The runtime checks if all `requiredSignatures` are now collected per the
|
|
341
|
+
policy threshold.
|
|
342
|
+
4. If yes, the suspended workflow resumes; the originally-suspended tool
|
|
343
|
+
finishes (artifact is finalized, side-effects fire).
|
|
344
|
+
|
|
345
|
+
### 5.2 Pending-signature index
|
|
346
|
+
|
|
347
|
+
Implementations SHOULD maintain a regeneratable index file
|
|
348
|
+
`<workspace>/_index/pending-signatures.json` keyed by signer:
|
|
349
|
+
|
|
350
|
+
```json
|
|
351
|
+
{
|
|
352
|
+
"version": "1",
|
|
353
|
+
"updatedAt": "2026-04-26T15:00:00.000Z",
|
|
354
|
+
"bySigner": {
|
|
355
|
+
"operator:founder": [
|
|
356
|
+
{
|
|
357
|
+
"artifactPath": "engagements/2026-acme/INVOICE.md",
|
|
358
|
+
"deadline": "2026-05-15T17:00:00.000Z",
|
|
359
|
+
"requestedAt": "2026-04-26T14:00:00.000Z",
|
|
360
|
+
"method": "typed_name",
|
|
361
|
+
"weight": 1
|
|
362
|
+
}
|
|
363
|
+
]
|
|
364
|
+
}
|
|
365
|
+
}
|
|
366
|
+
```
|
|
367
|
+
|
|
368
|
+
The index is **not authoritative** — it can be rebuilt at any time by walking
|
|
369
|
+
the workspace for artifacts with `requiredSignatures`. Its sole purpose is fast
|
|
370
|
+
operator-inbox queries.
|
|
371
|
+
|
|
372
|
+
---
|
|
373
|
+
|
|
374
|
+
## 6. Composition with other specs
|
|
375
|
+
|
|
376
|
+
`agentgovernance/v1` is independent. It can be adopted by any app:
|
|
377
|
+
|
|
378
|
+
```
|
|
379
|
+
my-app/
|
|
380
|
+
├── audit/audit-log.jsonl
|
|
381
|
+
├── policies/<slug>/POLICY.md
|
|
382
|
+
├── <some-artifact>.md
|
|
383
|
+
└── <some-artifact>.signatures/
|
|
384
|
+
└── operator-jeremy-2026-04-15.signature.json
|
|
385
|
+
```
|
|
386
|
+
|
|
387
|
+
When composed with `agentcompanies/v1` (companies.sh):
|
|
388
|
+
|
|
389
|
+
- `actorKind: operator` corresponds to the org's `AGENTS.md` entries.
|
|
390
|
+
- Policies may reference operator slugs from the company package.
|
|
391
|
+
|
|
392
|
+
When composed with `agentagencies/v1` (agencies.sh):
|
|
393
|
+
|
|
394
|
+
- Engagement / agreement / deliverable / invoice artifacts use
|
|
395
|
+
`agentgovernance/v1.signature.json` for signing.
|
|
396
|
+
- Per-engagement audit logs become the canonical record of the engagement.
|
|
397
|
+
|
|
398
|
+
A workspace using `agentagencies/v1` MUST validate as a valid
|
|
399
|
+
`agentgovernance/v1` workspace wherever `signature.json`, `audit-log.jsonl`, or
|
|
400
|
+
`POLICY.md` files appear (SHALL clause).
|
|
401
|
+
|
|
402
|
+
---
|
|
403
|
+
|
|
404
|
+
## 7. SHALL / SHOULD / MAY
|
|
405
|
+
|
|
406
|
+
- **SHALL** Every `signature.json` MUST have `evidence.kind === method` (or
|
|
407
|
+
validators reject).
|
|
408
|
+
- **SHALL** Every `audit-log.jsonl` line MUST chain correctly per the hash-chain
|
|
409
|
+
protocol — verifiers report the first mismatch.
|
|
410
|
+
- **SHALL** `documentHash` MUST be lowercase 64-character hex of SHA-256 over
|
|
411
|
+
the artifact bytes at signing time.
|
|
412
|
+
- **SHALL** `signedAt` MUST be ISO-8601 with UTC timezone.
|
|
413
|
+
- **SHOULD** `audit-event.entityType` SHOULD use known values (no ad-hoc
|
|
414
|
+
strings).
|
|
415
|
+
- **SHOULD** `policies/<slug>/` SHOULD contain only `POLICY.md` and supporting
|
|
416
|
+
docs (no executable code).
|
|
417
|
+
- **MAY** Vendor-specific fields MAY appear under `metadata.<vendor>.*`.
|
|
418
|
+
- **MAY** Implementations MAY add fields to `payload`, `evidence`, `metadata`
|
|
419
|
+
objects for forward compatibility — readers MUST ignore unknown fields.
|
|
420
|
+
|
|
421
|
+
---
|
|
422
|
+
|
|
423
|
+
## 8. Vendor extensions
|
|
424
|
+
|
|
425
|
+
Vendor-specific runtime data goes under `metadata.<vendor>.*`. Examples:
|
|
426
|
+
|
|
427
|
+
```yaml
|
|
428
|
+
# In a POLICY.md frontmatter
|
|
429
|
+
metadata:
|
|
430
|
+
mastra:
|
|
431
|
+
workflowId: "issue-invoice-with-cap"
|
|
432
|
+
guilde:
|
|
433
|
+
appliesToOperatorTeams: [billing, sales]
|
|
434
|
+
```
|
|
435
|
+
|
|
436
|
+
Adapter packages (`@agentproto/governance-mastra`, etc.) are the consumer-facing
|
|
437
|
+
API for vendor-specific orchestration. The core spec stays vendor-neutral.
|
|
438
|
+
|
|
439
|
+
---
|
|
440
|
+
|
|
441
|
+
## 9. Versioning
|
|
442
|
+
|
|
443
|
+
This document specifies `agentgovernance/v1`, version 1.0.0-alpha.
|
|
444
|
+
|
|
445
|
+
Future minor versions (1.x) MAY add fields and methods (with non-breaking
|
|
446
|
+
semantics). Major versions (2.x) MAY change the chain protocol or doctype
|
|
447
|
+
shapes. Workspaces MUST emit the same version per file; mixing versions in one
|
|
448
|
+
chain is forbidden.
|
|
449
|
+
|
|
450
|
+
When version 1.0 stabilizes, this spec moves to https://agentproto.sh/docs/gov-1/v1.
|
|
451
|
+
|
|
452
|
+
---
|
|
453
|
+
|
|
454
|
+
## 10. Reference implementation
|
|
455
|
+
|
|
456
|
+
[@agentproto/governance](https://npmjs.com/package/@agentproto/governance) is the
|
|
457
|
+
reference TypeScript implementation, MIT-licensed. It ships:
|
|
458
|
+
|
|
459
|
+
- Zod schemas for all doctypes (`./doctypes`)
|
|
460
|
+
- Validators (`./validators`)
|
|
461
|
+
- Hash-chain protocol — compute + verify (`./hash-chain`)
|
|
462
|
+
- Canvakit renderers + templates for signing-portal / signature-card /
|
|
463
|
+
audit-timeline (`./renderers` after Phase 1)
|
|
464
|
+
- FS-only runtime helpers — `recordAuditEvent`, `signArtifact`,
|
|
465
|
+
`listPendingSignatures` (`./runtime`)
|
|
466
|
+
|
|
467
|
+
Test corpus lives in `test/fixtures/` and includes hash-chain test vectors that
|
|
468
|
+
any implementation MUST reproduce byte-for-byte.
|
|
469
|
+
|
|
470
|
+
---
|
|
471
|
+
|
|
472
|
+
## 11. Compatibility test corpus (TBD — Phase 1)
|
|
473
|
+
|
|
474
|
+
A frozen set of test vectors (input artifact bytes + secret + genesis seed →
|
|
475
|
+
expected canonical bytes + expected signature) will be published with v1.0
|
|
476
|
+
stable. Any implementation passing these vectors is interoperable with the
|
|
477
|
+
reference.
|
|
478
|
+
|
|
479
|
+
For alpha, integration tests in `src/spec/hash-chain/{compute,verify}.test.ts`
|
|
480
|
+
and `src/runtime/runtime.e2e.test.ts` document the expected behavior.
|
|
481
|
+
|
|
482
|
+
---
|
|
483
|
+
|
|
484
|
+
## 12. Acknowledgments
|
|
485
|
+
|
|
486
|
+
This spec extends the conventions of
|
|
487
|
+
[agentcompanies/v1](https://github.com/paperclipai/paperclip/blob/master/docs/companies/companies-spec.md)
|
|
488
|
+
(paperclipai). Hash-chain construction draws on RFC 8785 (JCS), classic
|
|
489
|
+
Merkle/append-only log designs, and transparency log practice.
|
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Jeremy (governance.sh)
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
ADDED
|
@@ -0,0 +1,113 @@
|
|
|
1
|
+
# @agentproto/governance
|
|
2
|
+
|
|
3
|
+
`agentgovernance/v1` — the universal contractual approval framework, published
|
|
4
|
+
as the open standard at [governance.sh](https://agentproto.sh/docs/gov-1).
|
|
5
|
+
|
|
6
|
+
> ⚠️ **Alpha (v0.1).** Spec stabilizing. APIs may change pre-1.0.
|
|
7
|
+
|
|
8
|
+
## Trust boundary (read this first)
|
|
9
|
+
|
|
10
|
+
`v0.1` ships an **honest internal building block**, not a fully-credible
|
|
11
|
+
contractual-approval product. Three pillars distinguish a credible standard from
|
|
12
|
+
this alpha; v0.1 has the first only:
|
|
13
|
+
|
|
14
|
+
| Pillar | v0.1 | Provided by |
|
|
15
|
+
| ----------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
|
|
16
|
+
| **Bytes integrity** — "this artifact has not changed since signing" | ✅ SHA-256 of artifact bytes recorded in `signature.json`; runtime always re-hashes from disk | `@agentproto/governance-engine` |
|
|
17
|
+
| **Identity authenticity** — "the signer was actually who the file says" | ❌ The `signer` field is a declarative string. Anyone with FS write access can author a `signature.json` claiming any signer. | Cryptographic JWS over the signature payload, bound to a per-identity key. Roadmap M4. |
|
|
18
|
+
| **History integrity vs. workspace owner** — "the workspace owner cannot rewrite the chain undetected" | ❌ The hash chain is verifiable by anyone who has the file, but the workspace owner can rewrite the file and re-chain. No external witness in v0.1. | OpenTimestamps / RFC 3161 / on-chain anchor sink. Roadmap M5. |
|
|
19
|
+
|
|
20
|
+
**Use v0.1 in trusted contexts only**: an internal workspace where everyone with
|
|
21
|
+
FS write is already inside your trust boundary, and you want a structured record
|
|
22
|
+
of approvals that's portable, type-checkable, and machine-verifiable (within
|
|
23
|
+
that trust boundary). Do **not** use v0.1 where any of the following is true:
|
|
24
|
+
|
|
25
|
+
- The workspace owner is one of the parties whose signature you need to trust.
|
|
26
|
+
- Counterparties outside your trust boundary author `signature.json` files.
|
|
27
|
+
- A regulator, court, or external auditor will be asked to rely on the chain.
|
|
28
|
+
|
|
29
|
+
The roadmap to close all three pillars (cryptographic identity in M4, external
|
|
30
|
+
anchoring in M5, RFC 8785 / cross-language conformance in M6) is published in
|
|
31
|
+
[the agentproto spec series](https://agentik.net/docs/aip-7). v1.0 of the
|
|
32
|
+
package will not ship until those three are in place.
|
|
33
|
+
|
|
34
|
+
## What this is
|
|
35
|
+
|
|
36
|
+
A small, vendor-neutral, filesystem-first standard for **recording approvals as
|
|
37
|
+
signatures, appending tamper-evident audit logs, and declaring autonomy
|
|
38
|
+
policies** — usable by any AI agent system that needs auditable decisions.
|
|
39
|
+
|
|
40
|
+
Three doctypes:
|
|
41
|
+
|
|
42
|
+
| Doctype | File | Purpose |
|
|
43
|
+
| ----------------- | ------------------------------------------------------ | --------------------------------------------------------------------------------------- |
|
|
44
|
+
| `signature.json` | `<artifact>/signatures/<signer>-<date>.signature.json` | Universal approval primitive (typed_name, agent_confirm, click_through, esign_external) |
|
|
45
|
+
| `audit-log.jsonl` | `<scope>/audit/audit-log.jsonl` | Append-only, hash-chained event log |
|
|
46
|
+
| `POLICY.md` | `<scope>/policies/<slug>/POLICY.md` | Declarative autonomy rule (caps, thresholds, requiredSignatures-when-exceeded) |
|
|
47
|
+
|
|
48
|
+
The full spec is in [`AGENTGOVERNANCE.md`](./AGENTGOVERNANCE.md).
|
|
49
|
+
|
|
50
|
+
## Why a peer standard
|
|
51
|
+
|
|
52
|
+
Governance doctypes are **domain-agnostic**: `signature.json`,
|
|
53
|
+
`audit-log.jsonl`, `POLICY.md` don't reference services, engagements, or
|
|
54
|
+
counterparties. Any workflow that needs an auditable approval — clinician
|
|
55
|
+
overrides, approve-to-publish flows, board votes, AI-agent actions — uses the
|
|
56
|
+
same files.
|
|
57
|
+
|
|
58
|
+
## Why filesystem
|
|
59
|
+
|
|
60
|
+
A client receiving a workspace folder can verify every signature + the entire
|
|
61
|
+
audit chain **without our infrastructure** using the published
|
|
62
|
+
[hash-chain protocol](./src/spec/hash-chain/protocol.md). Third-party verifiers
|
|
63
|
+
can be implemented in any language.
|
|
64
|
+
|
|
65
|
+
## Install
|
|
66
|
+
|
|
67
|
+
```bash
|
|
68
|
+
npm install @agentproto/governance
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
## Subpath exports
|
|
72
|
+
|
|
73
|
+
```ts
|
|
74
|
+
import {
|
|
75
|
+
signatureSchema,
|
|
76
|
+
auditEventSchema,
|
|
77
|
+
policySchema,
|
|
78
|
+
} from "@agentproto/governance/doctypes"
|
|
79
|
+
import {
|
|
80
|
+
computeChainSignature,
|
|
81
|
+
verifyChain,
|
|
82
|
+
} from "@agentproto/governance/hash-chain"
|
|
83
|
+
import {
|
|
84
|
+
validateSignature,
|
|
85
|
+
validateAuditEvent,
|
|
86
|
+
validatePolicy,
|
|
87
|
+
} from "@agentproto/governance/validators"
|
|
88
|
+
import {
|
|
89
|
+
recordAuditEvent,
|
|
90
|
+
signArtifact,
|
|
91
|
+
listPendingSignatures,
|
|
92
|
+
} from "@agentproto/governance/runtime"
|
|
93
|
+
```
|
|
94
|
+
|
|
95
|
+
## Vendor neutrality
|
|
96
|
+
|
|
97
|
+
This package depends only on `zod`, `gray-matter`, `yaml`, and Node's built-in
|
|
98
|
+
`crypto`. There are **zero imports** from Mastra, LangChain, Temporal, or any
|
|
99
|
+
other workflow runtime. Adapters live in separate packages:
|
|
100
|
+
|
|
101
|
+
- `@agentproto/governance-mastra` — Mastra suspend/resume hooks
|
|
102
|
+
- (future) `@agentproto/governance-langchain`, `@agentproto/governance-temporal`,
|
|
103
|
+
etc.
|
|
104
|
+
|
|
105
|
+
## Status
|
|
106
|
+
|
|
107
|
+
This is the **canonical implementation** of `agentgovernance/v1`. The spec is
|
|
108
|
+
open; alternative implementations are welcome at
|
|
109
|
+
[governance.sh](https://agentproto.sh/docs/gov-1).
|
|
110
|
+
|
|
111
|
+
## License
|
|
112
|
+
|
|
113
|
+
MIT
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"sources":[],"names":[],"mappings":"","file":"chunk-5G463T6C.mjs"}
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"sources":[],"names":[],"mappings":"","file":"chunk-7GHDRKSD.mjs"}
|