owenloop 0.5.0 → 0.5.2

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