owenloop 0.4.1 → 0.5.1

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 (282) hide show
  1. package/CHANGELOG.md +71 -0
  2. package/README.md +182 -53
  3. package/bin/owenloop.mjs +50 -2
  4. package/dist/packages/work/src/agent/brief.d.ts +176 -0
  5. package/dist/packages/work/src/agent/brief.js +197 -0
  6. package/dist/packages/work/src/agent/loop.d.ts +141 -0
  7. package/dist/packages/work/src/agent/loop.js +669 -0
  8. package/dist/packages/work/src/agent/model-policy.d.ts +49 -0
  9. package/dist/packages/work/src/agent/model-policy.js +138 -0
  10. package/dist/packages/work/src/agent/workdir.d.ts +210 -0
  11. package/dist/packages/work/src/agent/workdir.js +319 -0
  12. package/dist/packages/work/src/bundle/cache.d.ts +92 -0
  13. package/dist/packages/work/src/bundle/cache.js +338 -0
  14. package/dist/packages/work/src/bundle/fetch.d.ts +87 -0
  15. package/dist/packages/work/src/bundle/fetch.js +345 -0
  16. package/dist/packages/work/src/bundle/types.d.ts +164 -0
  17. package/dist/packages/work/src/bundle/types.js +1 -0
  18. package/dist/packages/work/src/consumed-verifier.d.ts +45 -0
  19. package/dist/packages/work/src/consumed-verifier.js +205 -0
  20. package/dist/packages/work/src/credentials/owenloop.d.ts +11 -0
  21. package/dist/packages/work/src/credentials/owenloop.js +28 -0
  22. package/dist/packages/work/src/credentials/reader.d.ts +36 -0
  23. package/dist/packages/work/src/credentials/reader.js +32 -0
  24. package/dist/packages/work/src/credentials/resolve.d.ts +19 -0
  25. package/dist/packages/work/src/credentials/resolve.js +56 -0
  26. package/dist/packages/work/src/exec/instructions.d.ts +99 -0
  27. package/dist/packages/work/src/exec/instructions.js +323 -0
  28. package/dist/packages/work/src/exec/loop.d.ts +40 -0
  29. package/dist/packages/work/src/exec/loop.js +332 -0
  30. package/dist/packages/work/src/exec/payload.d.ts +29 -0
  31. package/dist/packages/work/src/exec/payload.js +54 -0
  32. package/dist/packages/work/src/exec/receipt.d.ts +41 -0
  33. package/dist/packages/work/src/exec/receipt.js +32 -0
  34. package/dist/packages/work/src/exec/runner.d.ts +71 -0
  35. package/dist/packages/work/src/exec/runner.js +256 -0
  36. package/dist/packages/work/src/harness/child-env.d.ts +100 -0
  37. package/dist/packages/work/src/harness/child-env.js +134 -0
  38. package/dist/packages/work/src/harness/claude.d.ts +140 -0
  39. package/dist/packages/work/src/harness/claude.js +837 -0
  40. package/dist/packages/work/src/harness/codex.d.ts +111 -0
  41. package/dist/packages/work/src/harness/codex.js +1024 -0
  42. package/dist/packages/work/src/harness/contract.d.ts +308 -0
  43. package/dist/packages/work/src/harness/contract.js +32 -0
  44. package/dist/packages/work/src/harness/fake.d.ts +59 -0
  45. package/dist/packages/work/src/harness/fake.js +91 -0
  46. package/dist/packages/work/src/harness/jsonrpc-stdio.d.ts +108 -0
  47. package/dist/packages/work/src/harness/jsonrpc-stdio.js +351 -0
  48. package/dist/packages/work/src/harness/permissions.d.ts +75 -0
  49. package/dist/packages/work/src/harness/permissions.js +182 -0
  50. package/dist/packages/work/src/harness/registry.d.ts +47 -0
  51. package/dist/packages/work/src/harness/registry.js +45 -0
  52. package/dist/packages/work/src/harness/session-store.d.ts +181 -0
  53. package/dist/packages/work/src/harness/session-store.js +523 -0
  54. package/dist/packages/work/src/harness/types.d.ts +29 -0
  55. package/dist/packages/work/src/harness/types.js +14 -0
  56. package/dist/packages/work/src/harnesses.d.ts +38 -0
  57. package/dist/packages/work/src/harnesses.js +38 -0
  58. package/dist/packages/work/src/hold/loop.d.ts +36 -0
  59. package/dist/packages/work/src/hold/loop.js +23 -0
  60. package/dist/packages/work/src/hold/mcp.d.ts +75 -0
  61. package/dist/packages/work/src/hold/mcp.js +264 -0
  62. package/dist/packages/work/src/hub/client.d.ts +23 -0
  63. package/dist/packages/work/src/hub/client.js +91 -0
  64. package/dist/packages/work/src/hub/types.d.ts +326 -0
  65. package/dist/packages/work/src/hub/types.js +26 -0
  66. package/dist/packages/work/src/lease/loop.d.ts +94 -0
  67. package/dist/packages/work/src/lease/loop.js +277 -0
  68. package/dist/packages/work/src/main.d.ts +1 -0
  69. package/dist/packages/work/src/main.js +48 -0
  70. package/dist/packages/work/src/mcp/server.d.ts +125 -0
  71. package/dist/packages/work/src/mcp/server.js +320 -0
  72. package/dist/packages/work/src/owenloop-bin.d.ts +1 -0
  73. package/dist/packages/work/src/owenloop-bin.js +18 -0
  74. package/dist/packages/work/src/roles/agent-run.d.ts +124 -0
  75. package/dist/packages/work/src/roles/agent-run.js +529 -0
  76. package/dist/packages/work/src/roles/exec.d.ts +48 -0
  77. package/dist/packages/work/src/roles/exec.js +228 -0
  78. package/dist/packages/work/src/roles/hold.d.ts +72 -0
  79. package/dist/packages/work/src/roles/hold.js +363 -0
  80. package/dist/packages/work/src/roles/join.d.ts +18 -0
  81. package/dist/packages/work/src/roles/join.js +204 -0
  82. package/dist/packages/work/src/roles/lint.d.ts +58 -0
  83. package/dist/packages/work/src/roles/lint.js +234 -0
  84. package/dist/packages/work/src/roles/prepare.d.ts +1 -0
  85. package/dist/packages/work/src/roles/prepare.js +249 -0
  86. package/dist/packages/work/src/roles/release.d.ts +48 -0
  87. package/dist/packages/work/src/roles/release.js +137 -0
  88. package/dist/packages/work/src/roles/sessions.d.ts +61 -0
  89. package/dist/packages/work/src/roles/sessions.js +180 -0
  90. package/dist/packages/work/src/roles/settings.d.ts +6 -0
  91. package/dist/packages/work/src/roles/settings.js +71 -0
  92. package/dist/packages/work/src/roles/shift.d.ts +13 -0
  93. package/dist/packages/work/src/roles/shift.js +250 -0
  94. package/dist/packages/work/src/roles/signals.d.ts +55 -0
  95. package/dist/packages/work/src/roles/signals.js +62 -0
  96. package/dist/packages/work/src/settings/provision.d.ts +21 -0
  97. package/dist/packages/work/src/settings/provision.js +47 -0
  98. package/dist/packages/work/src/settings/settings.d.ts +136 -0
  99. package/dist/packages/work/src/settings/settings.js +155 -0
  100. package/dist/packages/work/src/shift/client.d.ts +24 -0
  101. package/dist/packages/work/src/shift/client.js +124 -0
  102. package/dist/packages/work/src/shift/loop.d.ts +131 -0
  103. package/dist/packages/work/src/shift/loop.js +751 -0
  104. package/dist/packages/work/src/shift/protocol.d.ts +95 -0
  105. package/dist/packages/work/src/shift/protocol.js +24 -0
  106. package/dist/packages/work/src/shift/routing.d.ts +35 -0
  107. package/dist/packages/work/src/shift/routing.js +50 -0
  108. package/dist/packages/work/src/shift/runtime.d.ts +45 -0
  109. package/dist/packages/work/src/shift/runtime.js +337 -0
  110. package/dist/packages/work/src/shift/server.d.ts +23 -0
  111. package/dist/packages/work/src/shift/server.js +716 -0
  112. package/dist/packages/work/src/shift/spawn.d.ts +109 -0
  113. package/dist/packages/work/src/shift/spawn.js +158 -0
  114. package/dist/packages/work/src/shift/state.d.ts +79 -0
  115. package/dist/packages/work/src/shift/state.js +385 -0
  116. package/dist/packages/work/src/submit-proof.d.ts +36 -0
  117. package/dist/packages/work/src/submit-proof.js +93 -0
  118. package/dist/packages/work/src/usage.d.ts +6 -0
  119. package/dist/packages/work/src/usage.js +175 -0
  120. package/dist/src/add.d.ts +189 -0
  121. package/dist/src/add.js +300 -0
  122. package/dist/src/archive.d.ts +97 -0
  123. package/dist/src/archive.js +591 -0
  124. package/dist/src/bundle/index.d.ts +64 -0
  125. package/dist/src/bundle/index.js +508 -0
  126. package/dist/src/bundle/manifest.d.ts +50 -0
  127. package/dist/src/bundle/manifest.js +435 -0
  128. package/dist/src/bundle/runtime.d.ts +26 -0
  129. package/dist/src/bundle/runtime.js +64 -0
  130. package/dist/src/bundle/tar.d.ts +62 -0
  131. package/dist/src/bundle/tar.js +238 -0
  132. package/dist/src/bundle/types.d.ts +105 -0
  133. package/dist/src/bundle/types.js +21 -0
  134. package/dist/{cli.d.ts → src/cli.d.ts} +92 -7
  135. package/dist/src/cli.js +5968 -0
  136. package/dist/{credentials.d.ts → src/credentials.d.ts} +22 -15
  137. package/dist/{credentials.js → src/credentials.js} +35 -31
  138. package/dist/src/crypto/allowed-signers.d.ts +68 -0
  139. package/dist/src/crypto/allowed-signers.js +307 -0
  140. package/dist/src/crypto/canonical.d.ts +8 -0
  141. package/dist/src/crypto/canonical.js +92 -0
  142. package/dist/src/crypto/chain.d.ts +65 -0
  143. package/dist/src/crypto/chain.js +377 -0
  144. package/dist/src/crypto/dsse.d.ts +209 -0
  145. package/dist/src/crypto/dsse.js +282 -0
  146. package/dist/src/crypto/enrollment.d.ts +78 -0
  147. package/dist/src/crypto/enrollment.js +186 -0
  148. package/dist/src/crypto/index.d.ts +48 -0
  149. package/dist/src/crypto/index.js +44 -0
  150. package/dist/src/crypto/keys.d.ts +258 -0
  151. package/dist/src/crypto/keys.js +908 -0
  152. package/dist/src/crypto/org-root.d.ts +33 -0
  153. package/dist/src/crypto/org-root.js +78 -0
  154. package/dist/src/crypto/origin-rules.d.ts +56 -0
  155. package/dist/src/crypto/origin-rules.js +143 -0
  156. package/dist/src/crypto/policy-floor.d.ts +98 -0
  157. package/dist/src/crypto/policy-floor.js +353 -0
  158. package/dist/src/crypto/records.d.ts +316 -0
  159. package/dist/src/crypto/records.js +157 -0
  160. package/dist/src/crypto/scope.d.ts +49 -0
  161. package/dist/src/crypto/scope.js +83 -0
  162. package/dist/src/crypto/ssh.d.ts +171 -0
  163. package/dist/src/crypto/ssh.js +396 -0
  164. package/dist/src/crypto/submission.d.ts +33 -0
  165. package/dist/src/crypto/submission.js +47 -0
  166. package/dist/src/crypto/trust-roots.d.ts +29 -0
  167. package/dist/src/crypto/trust-roots.js +39 -0
  168. package/dist/src/crypto/verify-consumed.d.ts +67 -0
  169. package/dist/src/crypto/verify-consumed.js +259 -0
  170. package/dist/src/crypto/verify-origin.d.ts +50 -0
  171. package/dist/src/crypto/verify-origin.js +151 -0
  172. package/dist/src/crypto/verify-publication.d.ts +60 -0
  173. package/dist/src/crypto/verify-publication.js +150 -0
  174. package/dist/{defs.d.ts → src/defs.d.ts} +24 -1
  175. package/dist/{defs.js → src/defs.js} +181 -61
  176. package/dist/{engine.d.ts → src/engine.d.ts} +105 -9
  177. package/dist/{engine.js → src/engine.js} +251 -47
  178. package/dist/{factory.d.ts → src/factory.d.ts} +16 -0
  179. package/dist/{factory.js → src/factory.js} +16 -4
  180. package/dist/src/global-config.d.ts +59 -0
  181. package/dist/src/global-config.js +84 -0
  182. package/dist/{hub.d.ts → src/hub.d.ts} +280 -31
  183. package/dist/{hub.js → src/hub.js} +493 -52
  184. package/dist/src/index.d.ts +47 -0
  185. package/dist/src/index.js +41 -0
  186. package/dist/src/install.d.ts +538 -0
  187. package/dist/src/install.js +1981 -0
  188. package/dist/src/lock.d.ts +38 -0
  189. package/dist/src/lock.js +325 -0
  190. package/dist/src/mcp/serve.d.ts +109 -0
  191. package/dist/{mcp → src/mcp}/serve.js +335 -75
  192. package/dist/{mcp → src/mcp}/server.d.ts +6 -9
  193. package/dist/{mcp → src/mcp}/server.js +18 -10
  194. package/dist/{model.d.ts → src/model.d.ts} +15 -0
  195. package/dist/{model.js → src/model.js} +112 -2
  196. package/dist/src/order-resolver.d.ts +184 -0
  197. package/dist/src/order-resolver.js +252 -0
  198. package/dist/src/package-version.d.ts +10 -0
  199. package/dist/src/package-version.js +42 -0
  200. package/dist/{paths.d.ts → src/paths.d.ts} +14 -1
  201. package/dist/{paths.js → src/paths.js} +18 -0
  202. package/dist/src/schemas/enrollment-grant.v1.schema.json +90 -0
  203. package/dist/src/schemas/index.d.ts +1416 -0
  204. package/dist/src/schemas/index.js +31 -0
  205. package/dist/src/schemas/order.v1.schema.json +106 -0
  206. package/dist/src/schemas/origin.v1.schema.json +68 -0
  207. package/dist/src/schemas/policy-floor.v1.schema.json +29 -0
  208. package/dist/src/schemas/publication.v1.schema.json +31 -0
  209. package/dist/src/schemas/revocation.v1.schema.json +39 -0
  210. package/dist/src/schemas/submission.v1.schema.json +61 -0
  211. package/dist/src/store/def-source.d.ts +52 -0
  212. package/dist/src/store/def-source.js +335 -0
  213. package/dist/src/store/index-file.d.ts +69 -0
  214. package/dist/src/store/index-file.js +151 -0
  215. package/dist/src/store/index.d.ts +27 -0
  216. package/dist/src/store/index.js +22 -0
  217. package/dist/src/store/ingestor.d.ts +43 -0
  218. package/dist/src/store/ingestor.js +211 -0
  219. package/dist/src/store/install.d.ts +228 -0
  220. package/dist/src/store/install.js +555 -0
  221. package/dist/src/store/instruction-source.d.ts +49 -0
  222. package/dist/src/store/instruction-source.js +298 -0
  223. package/dist/src/store/origin-evidence.d.ts +21 -0
  224. package/dist/src/store/origin-evidence.js +66 -0
  225. package/dist/src/store/pre-commit-verifier.d.ts +68 -0
  226. package/dist/src/store/pre-commit-verifier.js +418 -0
  227. package/dist/src/store/resolve.d.ts +138 -0
  228. package/dist/src/store/resolve.js +363 -0
  229. package/dist/src/store/types.d.ts +288 -0
  230. package/dist/src/store/types.js +356 -0
  231. package/dist/{types.d.ts → src/types.d.ts} +58 -24
  232. package/dist/{untar.d.ts → src/untar.d.ts} +8 -23
  233. package/dist/src/untar.js +38 -0
  234. package/dist/{util.d.ts → src/util.d.ts} +3 -2
  235. package/dist/{util.js → src/util.js} +3 -2
  236. package/dist/{owenwork.d.ts → src/work-settings.d.ts} +22 -22
  237. package/dist/{owenwork.js → src/work-settings.js} +27 -27
  238. package/docs/agent-runner.md +86 -0
  239. package/docs/authoring.md +150 -59
  240. package/docs/bundles.md +250 -0
  241. package/docs/cli.md +1758 -163
  242. package/docs/crypto.md +816 -0
  243. package/docs/design.md +374 -52
  244. package/docs/embedding.md +135 -27
  245. package/docs/wire-contracts.md +380 -0
  246. package/examples/workflows/{command-worker.yaml → command-executor.yaml} +15 -15
  247. package/examples/workflows/compile-dev-playbook.yaml +338 -0
  248. package/examples/workflows/judges/gate-sharpness.md +39 -0
  249. package/examples/workflows/judges/security.md +34 -0
  250. package/package.json +22 -8
  251. package/plugins/claude-code/.claude-plugin/marketplace.json +14 -0
  252. package/plugins/claude-code/plugin/.claude-plugin/plugin.json +8 -0
  253. package/plugins/claude-code/plugin/.mcp.json +14 -0
  254. package/plugins/claude-code/plugin/hooks/hooks.json +26 -0
  255. package/plugins/claude-code/plugin/hooks/session-end.sh +40 -0
  256. package/plugins/claude-code/plugin/hooks/session-start.sh +52 -0
  257. package/plugins/claude-code/plugin/skills/author/SKILL.md +181 -0
  258. package/plugins/claude-code/plugin/skills/conduct/SKILL.md +106 -0
  259. package/plugins/claude-code/plugin/skills/shift/SKILL.md +105 -0
  260. package/plugins/codex/.agents/plugins/marketplace.json +21 -0
  261. package/plugins/codex/plugins/owenloop/.codex-plugin/plugin.json +7 -0
  262. package/plugins/codex/plugins/owenloop/.mcp.json +20 -0
  263. package/plugins/codex/plugins/owenloop/hooks/hooks.json +26 -0
  264. package/plugins/codex/plugins/owenloop/hooks/session-end.sh +40 -0
  265. package/plugins/codex/plugins/owenloop/hooks/session-start.sh +52 -0
  266. package/plugins/codex/plugins/owenloop/skills/author/SKILL.md +181 -0
  267. package/plugins/codex/plugins/owenloop/skills/conduct/SKILL.md +106 -0
  268. package/plugins/codex/plugins/owenloop/skills/shift/SKILL.md +105 -0
  269. package/dist/add.d.ts +0 -384
  270. package/dist/add.js +0 -834
  271. package/dist/cli.js +0 -3270
  272. package/dist/index.d.ts +0 -32
  273. package/dist/index.js +0 -23
  274. package/dist/lock.d.ts +0 -80
  275. package/dist/lock.js +0 -217
  276. package/dist/mcp/serve.d.ts +0 -84
  277. package/dist/untar.js +0 -164
  278. /package/dist/{schema.d.ts → src/schema.d.ts} +0 -0
  279. /package/dist/{schema.js → src/schema.js} +0 -0
  280. /package/dist/{store.d.ts → src/store.d.ts} +0 -0
  281. /package/dist/{store.js → src/store.js} +0 -0
  282. /package/dist/{types.js → src/types.js} +0 -0
package/docs/crypto.md ADDED
@@ -0,0 +1,816 @@
1
+ # Signing and key storage (WP-A2)
2
+
3
+ The engine's public crypto surface: **principal signing keys**, **SSHSIG
4
+ signing/verification**, and **DSSE envelopes**. Everything here is exported
5
+ from the package entry (`src/crypto/index.ts`), covered by the `test/crypto-*.test.ts`
6
+ suites, and interoperates with stock OpenSSH `ssh-keygen` on macOS and Linux CI.
7
+
8
+ ## Why stock OpenSSH, not a JS signature library
9
+
10
+ Signatures are produced and verified by **stock `ssh-keygen -Y`** (`sign` and
11
+ `verify`), not by a JavaScript crypto library. Every invocation uses
12
+ `shell: false` with an argument vector, through an injected process seam. The
13
+ signer also uses stock `ssh-keygen -y` to derive the public half of a private
14
+ key, and the feature probe invokes a harmless `-Y` command through the same
15
+ seam. Callers depend on the format-neutral `Signer` interface rather than on
16
+ this OpenSSH implementation. Three reasons:
17
+
18
+ 1. **Format neutrality for free.** SSHSIG's armored format, namespace binding,
19
+ and `allowed_signers` policy are implemented by OpenSSH itself; delegating
20
+ means the policy authority is the same binary every operator already trusts
21
+ for SSH. There is no custom authorization logic to keep in sync.
22
+ 2. **Private material stays out of process interfaces.** The message rides on
23
+ child stdin, the private key is referenced only by a filesystem path in
24
+ `ssh-keygen` argv, and the armored signature is the only signing output
25
+ captured. Generated private bytes may exist transiently in the manager while
26
+ a record is written or a temporary signing file is materialized; the public
27
+ API never returns those bytes, and private bytes never appear in argv,
28
+ stdout, stderr, logs, thrown errors, or test snapshots.
29
+ 3. **Portability cost is bounded and testable.** The requirement is one
30
+ binary — `ssh-keygen` with `-Y` support (OpenSSH 8.1+, present on macOS
31
+ and every mainstream Linux distro). When it is absent, crypto features fail
32
+ loudly instead of silently degrading; the test suites skip interop cases
33
+ with a named reason.
34
+
35
+ Private key bytes never appear in a repository, process arguments, stdout,
36
+ stderr, logs, thrown errors, or test snapshots. No public API returns a private
37
+ key; APIs return public descriptors or short-lived filesystem paths only.
38
+
39
+ The trade-off: every sign/verify spawns a child process (tens of
40
+ milliseconds). That is acceptable for the trust-surface call rates this layer
41
+ serves; a hot-path pure-JS signer can be added later behind the same `Signer`
42
+ interface without touching callers.
43
+
44
+ ## The `Signer` interface
45
+
46
+ `Signer` is the format-neutral seam DSSE verification programs against:
47
+
48
+ - `sign(exactBytes: Buffer) → Promise<SignatureResult>` — sign the exact bytes
49
+ (a pre-auth encoding); returns `{ keyid, sig }`.
50
+ - `verify(bytes: Buffer, sig: Buffer) → Promise<VerifiedSignature | null>` —
51
+ `null` means "not this signer's signature" (a cryptographic miss), never an
52
+ exception. A hit returns `{ keyid, principal, format }`.
53
+
54
+ `SshSigner` (created via `createSshSigner({ namespace, signKeyPath, verify })`)
55
+ is the stock-OpenSSH implementation. `verify` has the shape
56
+ `{ principal, allowedSignersText }`; omit `signKeyPath` for verify-only use, or
57
+ omit `verify` for sign-only use. Its configuration (`SshSignerConfig`) and
58
+ process seam (`SshProcessAdapter`) are exported for hermetic tests; production
59
+ callers use the defaults. All errors are `SshSignerError` with fixed messages —
60
+ child stderr is never interpolated into error text.
61
+
62
+ ## Key lifecycle and storage selection
63
+
64
+ `PrincipalKeyManager` owns one Ed25519 key per **principal key ref** —
65
+ `{ origin, kind, id }` where `kind` is one of the three local principals:
66
+
67
+ | kind | id |
68
+ |---|---|
69
+ | `human` | the hub actor id (`whoami.actor.id`) |
70
+ | `machine` | the literal `"local"` |
71
+ | `agent` | the agent identity id |
72
+
73
+ `owenloop setup` step `[4/7] signing keys` ensures all three, in that order,
74
+ idempotently: a second run performs zero writes.
75
+
76
+ **One backend is selected once and never error-fallback.** A fallback after a
77
+ selected store fails could create two different private keys for the same
78
+ principal — a shadow identity. Selection:
79
+
80
+ 1. **macOS:** `security` generic-password entries (service `owenloop-signing`,
81
+ account = SHA-256 of the canonical ref).
82
+ 2. **Linux:** `secret-tool` (libsecret) when the executable is on `PATH`.
83
+ 3. **Otherwise:** one atomic `0600` record file under
84
+ `$HOME/.owenloop/keys/<hash>.json`, with `$HOME/.owenloop` and `keys`
85
+ forced to `0700`; symlinked or non-directory paths are refused.
86
+
87
+ `OWENLOOP_NO_KEYCHAIN=1` forces the file backend on any platform — the same
88
+ explicit override the credential store honors. A `secret-tool lookup` exit
89
+ status of `1` means that the item is not found, not that libsecret failed; any
90
+ other nonzero lookup status is a backend failure. A failing selected backend
91
+ produces a fixed `signing-key storage (<backend>) failed: …` error and setup
92
+ stops. The manager does not error-fallback to another backend.
93
+
94
+ **Secrets never ride on argv or pipes.** Store writes pass the record on child
95
+ **stdin**; lookups redirect the secret-bearing stdout straight into a
96
+ pre-opened `0600` temp file descriptor. Nothing captures the secret into a
97
+ pipe, log, or error message.
98
+
99
+ `ensure(ref)` is serialized per ref by a file lock
100
+ (`$HOME/.owenloop/keys/<hash>.lock`): acquire → re-read → generate only when
101
+ still absent, so concurrent setups generate exactly once.
102
+
103
+ `inspect(ref)` returns only non-secret state, but validation of a generated
104
+ record is not a zero-byte operation: the manager temporarily writes the stored
105
+ private material to a `0600` file in a `0700` directory, runs stock
106
+ `ssh-keygen -y`, compares the derived public key and fingerprint, and removes
107
+ the directory in `finally`. The private text never appears in the inspection
108
+ result or in an exception.
109
+
110
+ ### Materialization
111
+
112
+ `withSigningKey(ref, callback)` hands the callback a **path** to a usable
113
+ private key and nothing more: a generated key materializes as a `0600` file in
114
+ a unique `0700` temp dir and is removed in `finally`; a reused key passes only
115
+ its canonical path. No API returns private-key text.
116
+
117
+ ### Publish-time signing
118
+
119
+ `owenloop publish` signs locally with the human principal key selected by the
120
+ project's bound hub origin. The signing chain is deliberately narrow:
121
+
122
+ 1. `resolveRef(origin, 'human')` discovers the non-secret principal reference
123
+ from the local `<hash>.ref` pointer.
124
+ 2. `inspect(ref)` read-only-confirms that setup already stored the key and
125
+ returns only its public descriptor, including the `publisherKeyId`
126
+ fingerprint. `publish` never calls `ensure`: publishing never creates or
127
+ repairs a signing key. During setup, an older key record created before ref
128
+ pointers existed is backfilled without changing the existing key.
129
+ 3. `withSigningKey(ref, callback)` materializes the private key only for the
130
+ callback's controlled lifetime.
131
+ 4. `createSshSigner({ namespace: DSSE_SSH_NAMESPACE, signKeyPath })` probes and
132
+ constructs the stock-OpenSSH signer.
133
+ 5. `dsseSignPublication(payloadBytes, signer)` signs the canonical JSON bytes of
134
+ the publication record under `application/vnd.owenloop.publication.v1+json`.
135
+ 6. When `--source` is present, `dsseSignOrigin(originPayloadBytes, signer)` signs
136
+ the canonical JSON bytes of a separate origin record under
137
+ `application/vnd.owenloop.origin.v1+json`, using the same signer object and
138
+ signing scope as the publication record.
139
+
140
+ Both records bind the 64-hex SHA-256 digest of the uncompressed canonical tar
141
+ returned by `packBundle`. The signer is constructed and the records are signed
142
+ before `publish` writes the `.wnlp` bundle or any sidecar. Signed output writes
143
+ the publication sidecar and, when `--source` is present, `<bundle>.origin.dsse`.
144
+ A publish without `--source` removes a stale origin sidecar; unsigned publish
145
+ also removes one because an unsigned origin would only be an unsigned label.
146
+ The hub is only a remote coordinator recorded by the project binding. The hub
147
+ stores or relays signed records but never signs, authors, derives, or defaults
148
+ origin data and cannot produce or complete either author signature.
149
+
150
+ The three origin source kinds are `git` (explicit repository identifier and
151
+ commit SHA), `console` (authoring user identity from a client-side signing
152
+ ceremony), and `agent` (agent identity and session). `attesterKeyId` is used only
153
+ to select verification candidates; verification cross-checks the hint against
154
+ the signer in the verified DSSE envelope.
155
+
156
+ ### Submit-time signing
157
+
158
+ A remote driver can sign a `submit` at the driver boundary only when the driver
159
+ has the exact artifact version that the signature must name. The key reference
160
+ is `{ origin, kind: 'machine', id: 'local' }`. The driver reads the public
161
+ fingerprint with `inspect`, materializes the private key only inside
162
+ `withSigningKey`, builds the frozen `submission.v1` record, and signs its
163
+ canonical JSON payload with `dsseSignSubmission` under the
164
+ `owenloop-dsse-v1` namespace. The target `proof` request field is the serialized
165
+ DSSE envelope for that one submitted artifact path.
166
+
167
+ A judge approval may sign the existing judged version from the claim fingerprint.
168
+ A producer submit must not infer a new version from immutable `owes[].version`
169
+ or process-local state. The producer requires a retry-safe, hub-issued target
170
+ version; without one, the driver submits without a proof and warns once per
171
+ process. As of 2026-08-10, the production hub does not carry submit `proof`,
172
+ proof acceptance, authoritative producer-version allocation, or downstream
173
+ proof projection, so owenloop does not claim end-to-end production proof support.
174
+
175
+ The engine does not sign: local `Engine.green` is synchronous and commits inside
176
+ a synchronous store transaction. `owenloop green` remains deliberately unsigned
177
+ because local green does not cross a wire; moving the command to an asynchronous
178
+ signing path would add no trust coverage.
179
+
180
+ #### Canonical submission values
181
+
182
+ `canonicalValueBytes(value)` recursively sorts plain-object keys, preserves array
183
+ order, applies each object's `toJSON(key)` hook with the same key semantics as
184
+ `JSON.stringify`, and emits separator-tight UTF-8 JSON. `valueDigestHex(value)`
185
+ is the lowercase SHA-256 digest of those bytes. The canonical bytes make a
186
+ produced-value digest reproducible after the value crosses the JSON submit
187
+ transport; the driver signs the same canonical record representation that the
188
+ wire envelope carries.
189
+
190
+ Canonicalization fails loudly with `TypeError` when a value cannot be represented
191
+ faithfully. `Map`, `Set`, `RegExp`, class instances with fields, non-finite
192
+ numbers (`NaN`, `Infinity`, and `-Infinity`), `bigint`, and circular references
193
+ are rejected rather than silently becoming `{}` or another lossy value. A
194
+ submission record also rejects an empty `produced` list and negative or
195
+ non-integer artifact versions.
196
+
197
+ `buildSubmissionRecord` constructs the frozen `submission.v1` shape without
198
+ signing. `signSubmission` canonicalizes that record, signs the payload as a DSSE
199
+ submission envelope, and returns the serialized opaque proof sent with one
200
+ artifact submission.
201
+
202
+ ## WP-D3 consume-side artifact verification
203
+
204
+ A consuming driver treats both the dynamic artifact values and the signed
205
+ submission records as untrusted transport data. The driver verifies a complete
206
+ order before the order reaches an agent prompt, an MCP model context, or a
207
+ command worker. The driver never removes only an offending path and continues
208
+ with the remaining packet; one failed link refuses the whole order.
209
+
210
+ For each entry in `order.consumes`, `verifyConsumed` applies this fixed order:
211
+
212
+ 1. A missing proof is `absent`; no unsigned value is silently treated as
213
+ verified.
214
+ 2. The driver parses the serialized envelope and verifies the DSSE signature
215
+ under `PAYLOAD_TYPE_SUBMISSION`.
216
+ 3. Only after signature verification, the driver validates the decoded
217
+ `submission.v1` schema. The unsigned `producerKeyId` is used only to select a
218
+ local verification candidate; the authenticated signer key ID must equal the
219
+ signed record's `producerKeyId`.
220
+ 4. The signed `produced[]` entry must cover the consumed artifact path. The
221
+ driver compares `valueDigestHex(deliveredValue)` with the signed
222
+ `valueDigest`, and compares the signed version with
223
+ `order.consumedFingerprint[path]` when that claim is present.
224
+ 5. The authenticated producer key must chain through locally loaded enrollment
225
+ grants to the locally configured organization-root public key. Every grant
226
+ link is signature-checked, scope attenuation is enforced, and effective
227
+ revocations are applied.
228
+ 6. When the consuming driver supplies a demand, the producer's effective scope
229
+ must satisfy that demand. A child grant can only narrow a parent grant; it
230
+ cannot widen pools, labels, namespaces, or delegation.
231
+
232
+ The same verification applies to an `owes[]` rejection thread when
233
+ `owes[].proof` is present. The proof is a `submission.v1` envelope whose one
234
+ `produced[]` entry names the owed artifact path and whose signed value digest
235
+ covers the complete `owes[].reasons` array. Verification therefore happens
236
+ before `REPLAY_TOKEN_BUDGET` truncates the thread for a resumed prompt.
237
+
238
+ The pure verifier returns four explicit verdicts:
239
+
240
+ | verdict | meaning |
241
+ | --- | --- |
242
+ | `verified` | DSSE, schema, path, value digest, version, enrollment chain, revocation, and any supplied-demand scope checks passed. |
243
+ | `absent` | No proof was supplied. |
244
+ | `unverifiable` | A required local prerequisite or verifier setup is unavailable. |
245
+ | `invalid` | Evidence was supplied but failed signature, schema, path, digest, version, chain, revocation, or scope validation. |
246
+
247
+ The consuming driver maps those verdicts according to `artifactPolicy`:
248
+
249
+ | verdict | `enforce` | `warn` | `off` |
250
+ | --- | --- | --- | --- |
251
+ | `verified` | admit | admit | admit |
252
+ | `absent` | refuse | warn and admit | admit |
253
+ | `unverifiable` | refuse | warn and admit | admit |
254
+ | `invalid` | refuse | refuse | refuse |
255
+
256
+ The `worker: command` rule is stronger than the table. Command workers refuse
257
+ `absent`, `unverifiable`, and `invalid` consumed evidence regardless of
258
+ `artifactPolicy`, including `off`. The consume-side gate runs before origin or
259
+ artifact policy lookup and before any command execution path can construct a
260
+ shell invocation. An unverified dynamic value must never reach `/bin/sh -c`.
261
+ Agent and MCP workers also fail closed when dynamic data exists but no
262
+ consume-side verifier is configured.
263
+
264
+ A refusal is an operator-facing integrity event, not an error to suppress or
265
+ work around. The refusal names the failed link and the artifact, using link
266
+ names such as `no-proof`, `signature`, `value-digest`, `version`, `chain`,
267
+ `scope`, or `prerequisite`, together with the workflow, run, and step. The gate
268
+ refuses the complete order; it never drops the offending path and serves a
269
+ partial packet.
270
+
271
+ **Decision A — version cross-check without fingerprint recomputation.** D3
272
+ checks each `consumedFingerprint[path]` version supplied by the consumer against
273
+ the signed `produced[].version`, but does not recompute the producer's complete
274
+ fingerprint map. The reduced packet does not include enough independently
275
+ authenticated upstream evidence to reconstruct every input version. A hostile
276
+ hub can therefore weaken a producer's declared lineage by supplying an explicit
277
+ empty or partial map. This is a named follow-up; the driver still verifies the
278
+ signed value and lineage evidence it does receive.
279
+
280
+ **Decision B — consumer-owned revocation anchor.** The consuming driver samples
281
+ its injected clock once per complete gate invocation and passes that instant as
282
+ `at`. Revocation is evaluated at that consumer-owned instant using
283
+ `effectiveFrom <= at`; the producer's signed timestamp is not a revocation
284
+ anchor. A key revocation that becomes effective after an earlier successful
285
+ consumption makes the same producer's artifact unconsumable on a later gate.
286
+ A producer timestamp ahead of the consumer clock is diagnostic only and does
287
+ not weaken revocation checks. Revocation cuts forward: a prior successful
288
+ decision is not rewritten, but a later consumption is checked against the cut.
289
+
290
+ **Scope enforcement status.** The pure verifier enforces `scopePermits` when a
291
+ caller supplies a pool, label, or namespace demand. The current production
292
+ `exec`, `agent-run`, and `hold` roles instantiate the verifier without a
293
+ demand, and `OrderPacket` carries no pool or label from which those roles could
294
+ derive one. Production gates therefore pass an empty demand: chain
295
+ termination, per-link signatures, attenuation-only-shrinks, and revocation are
296
+ enforced, but the demand-dependent scope-permission half of link 3 is currently
297
+ vacuous. Supplying a demand through the verifier seam enables that check. This
298
+ is a named follow-up, not a reason to bypass chain verification.
299
+ `packages/work/test/launch-gate-signer.test.ts` pins both halves of that
300
+ boundary: the chain and revocation cases run through the production command
301
+ driver, while the scope case calls the verifier directly with an explicit
302
+ demand and is named to say it is verifier-level, so wiring a demand into the
303
+ three roles later has a test to move.
304
+
305
+ ### Adversarial coverage
306
+
307
+ `packages/work/test/launch-gate-*.test.ts` models the remote coordinator as a
308
+ fully attacker-controlled component and asserts the trust properties end to end
309
+ rather than per verifier. A fixture hub serves whatever bytes each scenario
310
+ tells it to and records them, and each scenario asserts three things: that the
311
+ tampered payload really was served, that the specific named refusal kind or
312
+ link fired, and that an untampered control run still reaches the executable
313
+ surface. The properties covered are that a hostile hub cannot alter an
314
+ executing instruction or shell command, cannot forge a consumed artifact value
315
+ or a judge rejection reason that reaches an agent prompt or a shell, and cannot
316
+ introduce a trusted signer; and that when it withholds, the driver stalls
317
+ without executing anything rather than degrading to unverified execution.
318
+
319
+ ### Reusing an existing SSH key (human only)
320
+
321
+ `setup --reuse-ssh-key <path>` records the operator's own Ed25519 key for the
322
+ **human** principal instead of generating one. Before recording, the candidate
323
+ is validated with a non-secret sign/verify challenge against its own public
324
+ key (works for a private-key path, or a public-key path whose private half is
325
+ in ssh-agent). The record stores only the canonical `realpath` + public key + fingerprint —
326
+ the private bytes are never copied. For a private-key path, the public half is
327
+ derived with stock `ssh-keygen -y`; an adjacent `.pub` file is not trusted as
328
+ the identity source. Before every later signing callback, the manager resolves
329
+ the path again and checks that the current Ed25519 fingerprint still matches the
330
+ stored fingerprint.
331
+
332
+ Rules:
333
+
334
+ - **Human-only.** Machine and agent principals always get generated keys.
335
+ - **No rotation.** Passing `--reuse-ssh-key` when a human key already exists
336
+ is a hard conflict error; the existing key is kept.
337
+ - **Ed25519 only** in this work package.
338
+
339
+ ## WP-D1 machine enrollment grants
340
+
341
+ WP-D1 registers a machine public key in a signed organization roster. The
342
+ machine key is not the grantor. The local human principal signs a frozen
343
+ `EnrollmentGrantRecord` whose `newKey` is the machine's public descriptor:
344
+
345
+ ```ts
346
+ {
347
+ newKey: { keyid, keyType, openSshPublicKey, comment },
348
+ principal: { kind: 'machine', id: 'local' },
349
+ scope: {
350
+ pools: '*',
351
+ labels: '*',
352
+ namespaces: [],
353
+ delegation: { allowed: false },
354
+ },
355
+ grantedBy: '<human SHA256 fingerprint>',
356
+ validFrom: <milliseconds since Unix epoch>,
357
+ }
358
+ ```
359
+
360
+ `buildEnrollmentGrant` performs no I/O and never reads a private key. The
361
+ builder copies and freezes the public descriptor, principal, scope arrays, and
362
+ delegation object. `DEFAULT_MACHINE_SCOPE` is the least-privilege D1 scope
363
+ shown above: unrestricted pool and label matching for the machine's own
364
+ operation, no namespace grants, and delegation denied. The frozen wire shape
365
+ is specified in [`docs/wire-contracts.md`](wire-contracts.md); WP-D1 does not
366
+ change that contract.
367
+
368
+ ### Local roster verification
369
+
370
+ `verifyRosterEntry` verifies a relayed envelope in a fixed trust order:
371
+
372
+ 1. Decode and validate the DSSE envelope and enrollment-grant payload.
373
+ 2. Resolve the grantor key named by `grantedBy` from the local
374
+ `allowed_signers` trust root.
375
+ 3. Verify the DSSE signature and cross-check the authenticated signer key ID
376
+ against `grantedBy`.
377
+ 4. Call the optional `EnrollmentChainValidator` seam.
378
+
379
+ The public result is one of four explicit states:
380
+
381
+ | verdict | meaning |
382
+ |---|---|
383
+ | `enrolled` | payload, schema, signature, local signer authorization, and chain validation all succeeded; `keyid` is the enrolled machine fingerprint and `principal` is the authenticated signer principal |
384
+ | `unenrolled` | no envelope was supplied |
385
+ | `unverifiable` | a trust prerequisite is absent, including no local `allowed_signers` root or no installed chain validator |
386
+ | `invalid` | the envelope, payload, schema, signer authorization, signature, or chain-validator result failed |
387
+
388
+ The chain seam is deliberately narrow:
389
+
390
+ ```ts
391
+ interface EnrollmentChainValidator {
392
+ validate(
393
+ grant: EnrollmentGrantRecord,
394
+ verifiedSignerKeyId: string,
395
+ ): Promise<{ ok: true } | { ok: false; reason: string }>;
396
+ }
397
+ ```
398
+
399
+ WP-D1 fails closed when `chainValidator` is absent. A valid signature proves
400
+ which key signed the grant; a signature does not prove that the signer chains
401
+ to the organization root. The WP-D4 chain validator supplies the organization
402
+ root, attenuation, and revocation checks when the local driver installs that
403
+ seam. D1 entries remain `unverifiable` until a host supplies that validator.
404
+
405
+ The hub receives and relays the signed envelope only. The hub never receives a
406
+ private key, creates a grant, signs a grant, or endorses a grant. Setup's
407
+ registration path signs with `PrincipalKeyManager.withSigningKey`, so private
408
+ bytes remain inside the local key-manager callback and only `{ envelope }` is
409
+ sent over HTTP.
410
+
411
+ ## DSSE envelopes
412
+
413
+ Records that cross a trust boundary are wrapped in [DSSE](https://github.com/secure-systems-lab/dsse)
414
+ envelopes. The pre-auth encoding the signature covers:
415
+
416
+ ```
417
+ DSSEv1 SP len(typeBytes) SP typeBytes SP len(payloadBytes) SP payloadBytes
418
+ ```
419
+
420
+ `typeBytes` is the UTF-8 encoding of the payload type; `payloadBytes` is the
421
+ exact binary payload. Both lengths are ASCII decimal byte counts. Base64 on the
422
+ wire is decoded strictly — standard **and** URL-safe alphabets accepted,
423
+ malformed input rejected — because Node's built-in decoder is permissive.
424
+ SSHSIG signs and verifies this encoding under the namespace
425
+ `owenloop-dsse-v1` (`DSSE_SSH_NAMESPACE`).
426
+
427
+ Exactly six launch payload types are supported by the DSSE framing, and all six
428
+ are bound record classes in this package:
429
+
430
+ | constant | value |
431
+ |---|---|
432
+ | `PAYLOAD_TYPE_ENROLLMENT_GRANT` | `application/vnd.owenloop.enrollment-grant.v1+json` |
433
+ | `PAYLOAD_TYPE_REVOCATION` | `application/vnd.owenloop.revocation.v1+json` |
434
+ | `PAYLOAD_TYPE_SUBMISSION` | `application/vnd.owenloop.submission.v1+json` |
435
+ | `PAYLOAD_TYPE_POLICY_FLOOR` | `application/vnd.owenloop.policy-floor.v1+json` |
436
+ | `PAYLOAD_TYPE_ORIGIN` | `application/vnd.owenloop.origin.v1+json` |
437
+ | `PAYLOAD_TYPE_PUBLICATION` | `application/vnd.owenloop.publication.v1+json` |
438
+
439
+ `DSSE_RECORD_PAYLOAD_TYPES` is the frozen, exported runtime allow-list, and
440
+ `isDsseRecordPayloadType` is the exported guard. The generic
441
+ `dsseSignRecord` and `dsseVerifyRecord` wrappers apply that allow-list at
442
+ runtime: an arbitrary payload-type string, including an empty string or a
443
+ v2/attacker value, is rejected rather than accepted only by the TypeScript
444
+ union. The six fixed wrappers use their own constants; the publication wrapper
445
+ is `dsseSignPublication` / `dsseVerifyPublication`.
446
+
447
+ `dsseVerifyEnvelope` runs a fixed order — Base64 decode → PAE → signature
448
+ verification → payload-type check — and returns the payload bytes **exactly**.
449
+ A failed verification throws `DsseEnvelopeError`; a successful verification of
450
+ an empty payload returns a result with `payloadBytes.length === 0` and verified
451
+ signers, so the two outcomes are unambiguous. Malformed shapes also throw
452
+ `DsseEnvelopeError`. Duplicate signatures from the same trusted key count once;
453
+ a `threshold` option requires that many distinct signers.
454
+
455
+ ## Wire record shapes
456
+
457
+ The record shapes that ride these DSSE envelopes are documented in
458
+ [`docs/wire-contracts.md`](wire-contracts.md). That document is the public
459
+ reference for the six bound record contracts, their schemas, and the versioning
460
+ rule.
461
+
462
+ ## The role of `allowed_signers`
463
+
464
+ `parseAllowedSigners` parses the stock OpenSSH `allowed_signers` format
465
+ (principals, one comma-separated options field, key type, standard Base64 blob,
466
+ and trailing comment) **structurally**. The supported option syntax is
467
+ `cert-authority`, `namespaces="..."`, `valid-after="..."`, and
468
+ `valid-before="..."`; assignment values must use the stock quoted form.
469
+ `touch-required` is rejected because it is not a stock option supported by the
470
+ OpenSSH verifier used here. Repeated `cert-authority` options and empty option
471
+ slots between commas are retained as stock-tolerated syntax; a trailing comma
472
+ still produces a parse error. Quotes in a trailing comment are opaque after the
473
+ key blob and do not affect option parsing. The parser never throws: malformed
474
+ lines come back with their line numbers alongside the well-formed entries. It
475
+ deliberately does **not** implement OpenSSH pattern matching or authorization —
476
+ `ssh-keygen -Y verify` remains the policy authority, and accepted policy text is
477
+ fed back to it unchanged.
478
+
479
+ The Ed25519 rule applies to the key actually used for the operation, not to
480
+ every entry in the policy file. `SshSigner.sign` refuses a non-Ed25519 signing
481
+ key. During verification, OpenSSH may select an Ed25519, RSA, or ECDSA entry
482
+ from a mixed `allowed_signers` policy; `SshSigner` accepts the policy file but
483
+ refuses a successful verification when the key embedded in the verified
484
+ signature is not Ed25519. The policy file is not globally restricted to
485
+ Ed25519 entries.
486
+
487
+ ### Known parser differences from stock OpenSSH
488
+
489
+ `parseAllowedSigners` is line-tolerant, but `SshSigner.verify` currently
490
+ rejects the **entire** policy file when any line produces a parse error (or when
491
+ no entries parse). Stock OpenSSH skips an unparseable line and continues with
492
+ other lines. This is a known pre-existing divergence, including realistic
493
+ `touch-required` and `verify-required` option lines; the line-tolerant parser
494
+ result must not be read as equivalent to successful `SshSigner` verification.
495
+
496
+ The structural parser also does not cross-check the declared key type against
497
+ the key type embedded in the Base64 public-key blob. Parsed `principals` retain
498
+ literal surrounding quotes where stock OpenSSH strips them. These fields are
499
+ structural output only; OpenSSH remains the authorization authority.
500
+
501
+ ## Definition publication policy
502
+
503
+ The install path verifies the mutually exclusive publication sidecars written by
504
+ `publish`: `<bundle>.wnlp.dsse` or `<bundle>.wnlp.unsigned`. A signed publish may
505
+ also write the optional `<bundle>.origin.dsse` sidecar. The publication `.dsse`
506
+ sidecar is checked against the bundle digest and the local `allowed_signers`
507
+ trust root. Origin verification is separate: `verifyOrigin` returns `absent`
508
+ when the origin sidecar is missing, `verified` only after DSSE signature, schema,
509
+ signer-key, and bundle-digest checks pass, and `unverifiable` or `invalid` for
510
+ the corresponding failures. The trust-root path is
511
+ `$XDG_CONFIG_HOME/owenloop/allowed_signers` when
512
+ `XDG_CONFIG_HOME` is non-blank, or `$HOME/.config/owenloop/allowed_signers`
513
+ otherwise. A missing or malformed trust root produces the distinct
514
+ `unverifiable` verdict; a present signature that fails verification produces
515
+ `invalid`.
516
+
517
+ The execution and install policy is `defPolicy`, with built-in default `warn`.
518
+ Set `defPolicy` in the JSON settings file at
519
+ `$XDG_CONFIG_HOME/owenloop/settings.json` (or
520
+ `$HOME/.config/owenloop/settings.json`), for example:
521
+
522
+ ```json
523
+ {
524
+ "defPolicy": "enforce"
525
+ }
526
+ ```
527
+
528
+ `OWENLOOP_DEF_POLICY` overrides the settings file for a CLI invocation. The
529
+ precedence is explicit host-provided policy, then the environment, then the
530
+ settings file, then `warn`. An invalid policy value fails loudly rather than
531
+ weakening trust. The install-time and execution-time outcomes for `enforce`,
532
+ `warn`, and `off` are listed in [`docs/cli.md`](cli.md#definition-publication-policy).
533
+
534
+ `enforce` refuses unsigned and unverifiable definitions. `warn` warns and
535
+ permits those two verdicts for installation and agent work. `off` permits those
536
+ two verdicts silently for installation and agent work. `invalid` is refused at
537
+ every policy value. **Command workers always require `verified`; `off` never
538
+ relaxes that hard rule.** An execution resolver without a configured
539
+ publication verifier treats the definition as `unverifiable`, so command
540
+ workers refuse rather than assuming that integrity verification alone proves
541
+ publication trust.
542
+
543
+ The verifier does not write a verdict or sidecar into the immutable object
544
+ directory. The object remains governed by the bundle manifest integrity map.
545
+
546
+ ## Definition origin policy
547
+
548
+ Publication trust and provenance trust are separate controls. A signed
549
+ publication may carry a second DSSE sidecar, `<bundle>.origin.dsse`, whose
550
+ payload identifies an origin source and binds the same bundle digest as the
551
+ publication record. A hub or other remote coordinator may relay that sidecar,
552
+ but never authors, derives, defaults, or verifies the origin rule. The install
553
+ path retains the exact verified sidecar bytes outside the immutable object at
554
+ `<store-root>/.owenloop/origins/<digest>.dsse`. Execution reads that retained
555
+ file and verifies it again against the current local `allowed_signers` trust
556
+ root; a later change to local trust material therefore takes effect at the
557
+ execution boundary. Only a `verified` origin verdict is retained. A bundle
558
+ carrying only `<bundle>.origin.dsse` — with neither a publication `.dsse` nor an
559
+ unsigned marker — is refused at install for every origin-policy value, including
560
+ `off`. `publish` never emits that shape; `--unsigned` removes both sidecars.
561
+
562
+ Origin verification has four distinct verdicts:
563
+
564
+ - `verified` — the origin DSSE signature, schema, signer key, and bundle digest
565
+ all verify.
566
+ - `absent` — no origin bytes are available. For a signed file publication, this
567
+ means no sidecar was recorded. An unsigned publication or a non-file install
568
+ source also produces `absent`, but those definitions structurally cannot carry
569
+ an origin; those cases must not be described as “no origin was recorded.”
570
+ - `unverifiable` — a prerequisite such as the local trust root or verifier is
571
+ unavailable or unusable.
572
+ - `invalid` — a present origin sidecar fails its signature, schema, signer, or
573
+ digest checks. Invalid evidence is an attack signal and refuses at every
574
+ policy mode, including `off`.
575
+
576
+ `originRules` is an optional settings-file object mapping namespace patterns to
577
+ minimum origin strengths. Namespace matching has a deliberately small grammar:
578
+ `prod` is an exact namespace rule; `prod*` is a namespace-prefix rule; and a
579
+ trailing `/*` is accepted as sugar, so `prod/*` means the exact namespace
580
+ `prod`. `*` and `*/*` are catch-all rules. Interior wildcards, repeated
581
+ wildcards, `?`, `[`, empty keys, control characters, and other slash forms are
582
+ named settings errors. Exact rules beat every prefix rule; among prefixes, the
583
+ longest matching prefix wins. Keys that normalize to equal specificity, such
584
+ as `prod` and `prod/*`, are a named duplicate error rather than an arbitrary
585
+ winner.
586
+
587
+ The rule value is a minimum, not a set-membership label. Origin strength is
588
+ ordered `git` > `console` > `agent`: a `console` rule admits verified `git` and
589
+ `console` origins, while an `agent` rule admits all three. `any` imposes no
590
+ origin requirement, so `absent` and `unverifiable` pass that rule; a namespace
591
+ with no matching rule has no origin requirement. A verified origin is the only
592
+ verdict with a strength rank. `absent` and `unverifiable` fail a non-`any` rule
593
+ with distinct diagnostics. No rule may make invalid evidence acceptable.
594
+ Even with an empty `originRules` map, the default execution resolver invokes
595
+ its origin verifier once per order; the expensive index reverse-scan is skipped,
596
+ but invalid retained origin evidence still refuses.
597
+
598
+ The local origin mode uses the same vocabulary as `defPolicy`:
599
+ `enforce | warn | off`. These are policy values, not trust modes. `Seamless`,
600
+ `Strict`, and `Paranoid` are the separate trust-mode axis; `Seamless` maps to
601
+ `warn` and `Strict` maps to `enforce`. `off` is a local operator escape hatch,
602
+ not a trust mode. `originPolicy` follows explicit host option, then
603
+ `OWENLOOP_ORIGIN_POLICY`, then the settings-file value, then the built-in
604
+ `warn` default. The `originRules` map follows explicit host option, then the
605
+ settings-file value, then an empty map; there is intentionally no environment
606
+ variable spelling for the map. Origin mode remains parallel to publication
607
+ mode; an origin requirement never raises or lowers `defPolicy`.
608
+
609
+ A verified organization policy floor supplies the parallel minimum:
610
+ `originRules: advisory` maps to local `originPolicy: warn`, and
611
+ `originRules: enforced` maps to `originPolicy: enforce`. The floor is merged
612
+ monotonically after local precedence, so a local `off` cannot opt out of an
613
+ enforced origin floor. The `unsignedArtifacts` axis similarly maps `warn` to
614
+ `artifactPolicy: warn` and `refuse` to `artifactPolicy: enforce`. Both axes are
615
+ wired at the driver boundaries; the remaining unenforced floor gap is
616
+ `trustMode`.
617
+
618
+ The command-worker hard rule remains independent of origin policy. A
619
+ `worker: command` order must pass the publication verification gate before any
620
+ origin-policy lookup, and must then satisfy the origin check. Unsigned,
621
+ unverifiable, or invalid publication evidence never reaches the shell;
622
+ `originPolicy: off` and every policy-floor preset leave that publication gate
623
+ unchanged.
624
+
625
+ ## Enrollment chains, attenuation, and revocation
626
+
627
+ Enrollment trust is separate from publication-signature trust. A key is trusted
628
+ if and only if its enrollment chain terminates at the supplied local
629
+ organization-root anchor. A hub or other remote coordinator may relay signed
630
+ envelopes, but a remote assertion cannot make a key trusted.
631
+
632
+ `validateEnrollmentChain` is the pure validator. Its input contains the target
633
+ key ID, the org-root public-key text, signed grant envelopes, optional signed
634
+ revocation envelopes, and an explicit validation instant `at` in epoch
635
+ milliseconds. Every grant link is verified separately with a signer whose
636
+ `allowed_signers` text contains exactly that link's parent key. A roster entry
637
+ without a grant, a cycle, an ambiguous duplicate grant, or a chain that stops
638
+ before the anchor is `invalid`; the validator never picks a convenient chain.
639
+ A grant is also checked for its `validFrom` time and for the Ed25519 key type.
640
+
641
+ The org root is an injected local anchor, not a wire field. Neither an
642
+ `EnrollmentGrantRecord` nor a `RevocationRecord` contains an `org` field, and
643
+ the root has no grant record. The walk terminates when the current key ID
644
+ matches the key ID derived from the supplied anchor; that absence of a grant is
645
+ what makes the key the root. Asking to validate the root itself succeeds at
646
+ depth zero with `ORG_ROOT_SCOPE`.
647
+
648
+ The result has three states:
649
+
650
+ | verdict | meaning |
651
+ |---|---|
652
+ | `verified` | the chain reaches the local anchor, every link verifies, and all scope and revocation checks pass |
653
+ | `unverifiable` | a local prerequisite cannot be used, such as a missing or malformed anchor or unusable `ssh-keygen` |
654
+ | `invalid` | the supplied roster or revocation set is well-formed but does not establish the requested trust |
655
+
656
+ There is no `unsigned` chain verdict. An absent grant for a non-root target is
657
+ an invalid chain, not an unsigned one. `validateProducer` runs the same chain
658
+ validation and then checks a requested `{ pool?, label?, namespace? }` demand
659
+ against the target's effective scope.
660
+
661
+ ### Scope attenuation
662
+
663
+ A child grant may be narrower than its parent's effective grant, never wider.
664
+ For each of `pools`, `labels`, and `namespaces`, the containment rule is:
665
+
666
+ | parent | child | result |
667
+ |---|---|---|
668
+ | `"*"` | any array or `"*"` | permitted |
669
+ | string array | `"*"` | rejected as widening |
670
+ | string array | string array | permitted only when every child value is in the parent array |
671
+
672
+ An empty array is distinct from `"*"`: an empty array permits no values. The
673
+ delegation limit attenuates separately. A parent with delegation disabled cannot
674
+ sign a grant; an unbounded parent may delegate any child scope; a numeric parent
675
+ with `maxDepth: N` may sign a non-delegating child or a child with numeric
676
+ `maxDepth: M` where `M <= N - 1`. A numeric parent never permits an unbounded
677
+ child. The org root starts with `ORG_ROOT_SCOPE`: all three axes are `"*"` and
678
+ delegation is unbounded.
679
+
680
+ ### Revocation
681
+
682
+ Validation applies signed revocations at the explicit `at` instant. A verified
683
+ revocation whose `effectiveFrom <= at` kills the named key, and a chain with a
684
+ dead link is invalid. Because descendants must walk through their ancestors,
685
+ revocation cascades forward transitively without a separate descendant pass.
686
+ A grant or artifact evaluated at an earlier `at` remains valid before the cut;
687
+ revocation is forward-only.
688
+
689
+ The revocation signer must be the org root or an ancestor of the revoked key
690
+ whose delegation scope allows delegation. A backdated revocation
691
+ (`effectiveFrom < issuedAt`) is org-root-only and is reported through the
692
+ validator's injected backdated-revocation sink. The `backdated` field must agree
693
+ with the timestamp comparison before signer authority is considered. A
694
+ revocation of the org root itself is invalid rather than silently disabling the
695
+ whole organization.
696
+
697
+ ### Local anchor and envelope files
698
+
699
+ The optional filesystem loader derives paths from injected environment state:
700
+ `XDG_CONFIG_HOME` wins over `HOME`; there is no ambient home-directory lookup.
701
+ The local layout is:
702
+
703
+ ```text
704
+ <config>/owenloop/org-root.pub # public anchor, 0644
705
+ <config>/owenloop/org-root # private anchor, 0600
706
+ <config>/owenloop/roster/<sha256hex(keyid)>.grant.dsse
707
+ <config>/owenloop/revocations/<sha256hex(keyid)>.revocation.dsse
708
+ ```
709
+
710
+ The root key is stored outside `PrincipalKeyManager` because the root is not a
711
+ hub-scoped principal key. The containing directory is `0700`; the private root
712
+ is never returned by the library or placed in an envelope. `loadRoster` and
713
+ `loadRevocations` return raw envelope bytes to the pure validator and refuse
714
+ symlinked or non-regular files.
715
+
716
+ ## Admin-signed policy floors
717
+
718
+ A policy floor is an org-wide minimum for local enforcement. An org admin signs
719
+ one DSSE record with payload type
720
+ `application/vnd.owenloop.policy-floor.v1+json`. A driver verifies the exact
721
+ record against local trust material before using the record:
722
+
723
+ 1. The DSSE envelope and policy-floor schema must verify.
724
+ 2. The authenticated signer key must be present in the local enrollment
725
+ material, and the signer's enrollment chain must terminate at the local
726
+ organization-root anchor. Revocations are evaluated at the supplied
727
+ validation instant.
728
+ 3. The signer's effective scope must be unrestricted on all three axes:
729
+ `pools`, `labels`, and `namespaces` must each be `"*"`. Under scope
730
+ attenuation, that is genuine organization-wide admin scope; a narrower key
731
+ cannot sign an organization-wide floor.
732
+
733
+ A hub or other remote coordinator relays the signed record but never authors,
734
+ derives, weakens, or signs the floor. The relaying transport is not a trust
735
+ anchor.
736
+
737
+ ### Monotone merge with local policy
738
+
739
+ A verified floor can only raise local strictness, never lower it. The driver
740
+ maps the floor's `unsignedDefs` axis into the existing `defPolicy` vocabulary:
741
+
742
+ | floor `unsignedDefs` | minimum local `defPolicy` |
743
+ |---|---|
744
+ | `warn` | `warn` |
745
+ | `refuse` | `enforce` |
746
+
747
+ The effective policy is the stricter of local policy and the floor minimum:
748
+ `off < warn < enforce`. The floor vocabulary has no value that maps to `off`,
749
+ so a floor is structurally unable to lower policy. In particular, local `off`
750
+ plus a verified floor produces at least `warn`; the local operator cannot opt
751
+ out of that org floor.
752
+
753
+ ### Failure behavior and current limits
754
+
755
+ Absence is never permission. A missing or failed floor supplies no floor to the
756
+ merge, so the driver's local policy remains exactly unchanged. For a delivered
757
+ envelope, verification reports `invalid` or `unverifiable` instead of throwing
758
+ for every failure path:
759
+
760
+ | situation | result |
761
+ |---|---|
762
+ | no floor delivered | local policy unchanged; no floor is merged |
763
+ | malformed envelope or payload, including wrong payload type or schema failure | `invalid`; local policy unchanged |
764
+ | unsigned floor or signature that does not verify | `invalid`; local policy unchanged |
765
+ | signer chain does not terminate at the local org root | `invalid`; local policy unchanged |
766
+ | signer lacks unrestricted admin scope | `invalid`; local policy unchanged |
767
+ | signer key is revoked at the validation instant | `invalid`; local policy unchanged |
768
+ | local org-root anchor or other verification prerequisite is unavailable | `unverifiable`; local policy unchanged |
769
+
770
+ The frozen floor has four axes. This package enforces three of them:
771
+ `unsignedDefs` through `defPolicy`, `unsignedArtifacts` through the parallel
772
+ `artifactPolicy`, and `originRules` through the parallel `originPolicy`:
773
+
774
+ | axis | current state |
775
+ |---|---|
776
+ | `unsignedDefs` | mapped into `defPolicy` and enforced |
777
+ | `trustMode` | accepted and carried, but not evaluated |
778
+ | `unsignedArtifacts` | mapped into `artifactPolicy` and enforced at consume-side driver boundaries |
779
+ | `originRules` | mapped into `originPolicy` and enforced |
780
+
781
+ The merge result names the remaining unenforced `trustMode` axis in `gaps`
782
+ rather than silently dropping it. Installation and execution apply the
783
+ origin-policy and artifact-policy results; callers do not currently surface the
784
+ `trustMode` gap. The `policyFloor` option remains an injection seam: the floor
785
+ has effect only when a host loads and verifies a signed floor and passes the
786
+ verified record through that seam.
787
+
788
+ L0, L1, and L2 are documented bundles of concrete floor values, not alternate
789
+ policy primitives:
790
+
791
+ | preset | `trustMode` | `unsignedDefs` | `unsignedArtifacts` | `originRules` |
792
+ |---|---|---|---|---|
793
+ | L0 | `seamless` | `warn` | `warn` | `advisory` |
794
+ | L1 | `seamless` | `refuse` | `refuse` | `advisory` |
795
+ | L2 | `strict` | `refuse` | `refuse` | `enforced` |
796
+
797
+ The `trustMode` preset value is still only carried and reported as a gap in
798
+ this package. The `unsignedArtifacts` value maps to the parallel
799
+ consume-side artifact-policy minimum described above, and `originRules` maps to
800
+ the parallel origin-policy minimum.
801
+
802
+ **Command-worker hard rule.** A `worker: command` order still requires full
803
+ enforcement: a verified definition, a verified enrollment chain, and a
804
+ scope-checked signer. The gate runs before the floor-derived policy value is
805
+ read and fails closed regardless of local policy, including `off`, and
806
+ regardless of any floor. A floor cannot relax this rule.
807
+
808
+ ## Out of scope (future work)
809
+
810
+ Publish-time author-side DSSE signing is implemented by `owenloop publish`.
811
+ Transport relay and the following extensions remain out of scope:
812
+
813
+ - Key **rotation** wiring for stored principal keys.
814
+ - Certificate (`cert-authority`) chains and hardware-backed signing flows.
815
+ - A pure-JS signer for hot paths (the `Signer` seam is already in place).
816
+ - Threshold schemes beyond "N distinct trusted keys".