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
@@ -0,0 +1,186 @@
1
+ /**
2
+ * Enrollment-grant construction and client-side roster verification.
3
+ *
4
+ * D1 deliberately stops at a narrow chain-validation seam. A signed grant is
5
+ * unforgeable by a hub that only relays records, but a signature alone does not
6
+ * prove that the grantor is enrolled in the organization. Until a
7
+ * `EnrollmentChainValidator` is installed, verification therefore refuses with
8
+ * `unverifiable` rather than accepting the record. The explicit early return in
9
+ * `verifyRosterEntry` is the §8.1 fail-closed gate.
10
+ */
11
+ import { keyidFromBlob } from "./keys.js";
12
+ import { decodeBase64Strict, DSSE_SSH_NAMESPACE, dsseVerifyEnrollmentGrant, DsseEnvelopeError, } from "./dsse.js";
13
+ import { parseAllowedSigners } from "./allowed-signers.js";
14
+ import { createSshSigner, SshSignerError } from "./ssh.js";
15
+ import { enrollmentGrantSchema } from "../schemas/index.js";
16
+ import { validateValue, summarizeIssues } from "../schema.js";
17
+ /** The least privilege scope carried by a self-vouched machine grant. */
18
+ export const DEFAULT_MACHINE_SCOPE = Object.freeze({
19
+ pools: '*',
20
+ labels: '*',
21
+ namespaces: Object.freeze([]),
22
+ delegation: Object.freeze({ allowed: false }),
23
+ });
24
+ /** Build one complete, immutable enrollment grant without performing I/O. */
25
+ export function buildEnrollmentGrant(args) {
26
+ const scope = Object.freeze({
27
+ pools: Array.isArray(args.scope.pools) ? Object.freeze([...args.scope.pools]) : args.scope.pools,
28
+ labels: Array.isArray(args.scope.labels) ? Object.freeze([...args.scope.labels]) : args.scope.labels,
29
+ namespaces: Array.isArray(args.scope.namespaces) ? Object.freeze([...args.scope.namespaces]) : args.scope.namespaces,
30
+ delegation: args.scope.delegation.allowed
31
+ ? Object.freeze({ allowed: true, maxDepth: args.scope.delegation.maxDepth })
32
+ : Object.freeze({ allowed: false }),
33
+ });
34
+ const newKey = Object.freeze({
35
+ keyid: args.newKey.keyid,
36
+ keyType: args.newKey.keyType,
37
+ openSshPublicKey: args.newKey.openSshPublicKey,
38
+ ...(args.newKey.comment !== undefined ? { comment: args.newKey.comment } : {}),
39
+ });
40
+ const principal = Object.freeze({ kind: args.principal.kind, id: args.principal.id });
41
+ return Object.freeze({
42
+ newKey,
43
+ principal,
44
+ scope,
45
+ grantedBy: args.grantedBy,
46
+ validFrom: args.validFrom,
47
+ });
48
+ }
49
+ function invalid(reason) {
50
+ return { kind: 'invalid', reason };
51
+ }
52
+ function unverifiable(reason) {
53
+ return { kind: 'unverifiable', reason };
54
+ }
55
+ function asJsonObject(value) {
56
+ return typeof value === 'object' && value !== null && !Array.isArray(value);
57
+ }
58
+ /**
59
+ * Decode only the unauthenticated payload needed for candidate selection. The
60
+ * record is still checked again by the DSSE verifier and by the signer-key
61
+ * cross-check below; no field decoded here authorizes a key.
62
+ */
63
+ function decodeEnrollment(input) {
64
+ const raw = input.envelope !== undefined ? input.envelope : input.dsseBytes;
65
+ if (raw === undefined)
66
+ return { kind: 'unenrolled' };
67
+ let envelope = raw;
68
+ if (typeof raw === 'string' || raw instanceof Uint8Array) {
69
+ try {
70
+ envelope = JSON.parse(Buffer.from(raw).toString('utf8'));
71
+ }
72
+ catch {
73
+ return invalid('enrollment envelope is not valid JSON');
74
+ }
75
+ }
76
+ if (!asJsonObject(envelope))
77
+ return invalid('enrollment envelope is not a JSON object');
78
+ const payload = envelope.payload;
79
+ if (typeof payload !== 'string')
80
+ return invalid("enrollment envelope is missing a string 'payload'");
81
+ let payloadBytes;
82
+ try {
83
+ payloadBytes = decodeBase64Strict(payload, { allowEmpty: true });
84
+ }
85
+ catch (error) {
86
+ return invalid(`enrollment payload is not valid Base64: ${error.message}`);
87
+ }
88
+ let decoded;
89
+ try {
90
+ decoded = JSON.parse(payloadBytes.toString('utf8'));
91
+ }
92
+ catch {
93
+ return invalid('enrollment payload is not valid JSON');
94
+ }
95
+ if (!asJsonObject(decoded))
96
+ return invalid('enrollment payload is not a JSON object');
97
+ const shape = validateValue(enrollmentGrantSchema, decoded);
98
+ if (!shape.valid) {
99
+ return invalid(`enrollment grant does not match schema: ${summarizeIssues(shape.issues)}`);
100
+ }
101
+ return { envelope, record: decoded };
102
+ }
103
+ /**
104
+ * Verify one relayed enrollment record. The operation is ordered so malformed
105
+ * input, missing trust roots, signer authorization, and missing chain support
106
+ * remain distinct verdicts instead of collapsing into a boolean.
107
+ */
108
+ export async function verifyRosterEntry(input, options = {}) {
109
+ const decoded = decodeEnrollment(input);
110
+ if ('kind' in decoded)
111
+ return decoded;
112
+ const { envelope, record } = decoded;
113
+ if (input.allowedSignersText === undefined) {
114
+ return unverifiable('no allowed_signers trust root was resolved');
115
+ }
116
+ const parsed = parseAllowedSigners(input.allowedSignersText);
117
+ if (parsed.errors.length > 0) {
118
+ return unverifiable(`allowed_signers policy is malformed: ${parsed.errors.map((error) => `line ${error.line}: ${error.message}`).join('; ')}`);
119
+ }
120
+ if (parsed.entries.length === 0)
121
+ return unverifiable('allowed_signers policy has no signer entries');
122
+ const candidates = parsed.entries.filter((entry) => keyidFromBlob(entry.keyBlob) === record.grantedBy);
123
+ if (candidates.length === 0) {
124
+ return invalid(`enrollment grantor key '${record.grantedBy}' is not present in allowed_signers`);
125
+ }
126
+ const makeSigner = options.signerForPrincipal ?? ((args) => createSshSigner({
127
+ namespace: options.namespace ?? DSSE_SSH_NAMESPACE,
128
+ verify: args,
129
+ }));
130
+ let sawCryptographicMiss = false;
131
+ for (const candidate of candidates) {
132
+ for (const principal of candidate.principals) {
133
+ let signer;
134
+ try {
135
+ signer = makeSigner({ principal, allowedSignersText: input.allowedSignersText });
136
+ }
137
+ catch (error) {
138
+ if (error instanceof SshSignerError)
139
+ return unverifiable(error.message);
140
+ return unverifiable(`enrollment verification setup failed: ${error instanceof Error ? error.message : String(error)}`);
141
+ }
142
+ try {
143
+ const result = await dsseVerifyEnrollmentGrant(envelope, signer, { threshold: 1 });
144
+ const verified = result.signers[0];
145
+ if (verified === undefined)
146
+ return invalid('enrollment signature produced no verified signer');
147
+ if (verified.keyid !== record.grantedBy) {
148
+ return invalid(`enrollment signer key '${verified.keyid}' does not match record grantedBy '${record.grantedBy}'`);
149
+ }
150
+ // §8.1: a signature proves who signed, not that the signer is enrolled.
151
+ // Refuse until WP-D4 installs the chain validator; never fail open.
152
+ if (options.chainValidator === undefined) {
153
+ return unverifiable('no enrollment chain validator is installed');
154
+ }
155
+ let chain;
156
+ try {
157
+ chain = await options.chainValidator.validate(record, verified.keyid);
158
+ }
159
+ catch (error) {
160
+ return unverifiable(`enrollment chain validation could not run: ${error instanceof Error ? error.message : String(error)}`);
161
+ }
162
+ if (!chain.ok)
163
+ return invalid(chain.reason);
164
+ return { kind: 'enrolled', keyid: record.newKey.keyid, principal: verified.principal };
165
+ }
166
+ catch (error) {
167
+ if (error instanceof SshSignerError)
168
+ return unverifiable(error.message);
169
+ if (error instanceof DsseEnvelopeError) {
170
+ if (error.message.startsWith('DSSE verification failed:')) {
171
+ sawCryptographicMiss = true;
172
+ continue;
173
+ }
174
+ return invalid(`enrollment verification failed: ${error.message}`);
175
+ }
176
+ return invalid(`enrollment verification failed: ${error instanceof Error ? error.message : String(error)}`);
177
+ }
178
+ finally {
179
+ signer.dispose?.();
180
+ }
181
+ }
182
+ }
183
+ if (sawCryptographicMiss)
184
+ return invalid('enrollment signature could not be verified by an allowed signer');
185
+ return invalid('enrollment signature did not verify');
186
+ }
@@ -0,0 +1,48 @@
1
+ /**
2
+ * The public crypto surface of the owenloop engine (WP-A2).
3
+ *
4
+ * Three narrow capabilities that later trust work builds on:
5
+ * 1. Principal signing keys — `PrincipalKeyManager` generates, stores, and
6
+ * materializes Ed25519 keys for the human/machine/agent principals
7
+ * (macOS Keychain, Linux libsecret, or a secure 0600 file store). No
8
+ * function here hands a caller private-key text.
9
+ * 2. SSHSIG signing/verification — `SshSigner` (behind the format-neutral
10
+ * `Signer` interface) drives stock OpenSSH `ssh-keygen -Y`.
11
+ * 3. DSSE envelopes — `dsseSignEnvelope`/`dsseVerifyEnvelope` plus the six
12
+ * versioned payload-type constants and record-class wrappers.
13
+ *
14
+ * Process/storage adapters stay internal unless a test seam needs the type.
15
+ */
16
+ export { PrincipalKeyManager, assertKeyRef, canonicalKeyRef, keyidFromBlob, keyRefHash, publicKeyDescriptor, } from './keys.ts';
17
+ export type { EnsureKeyResult, InspectKeyResult, KeyCommandRunner, KeyStorageBackendKind, PrincipalKeyManagerOpts, PrincipalKeyRef, PrincipalKind, PublicKeyDescriptor, } from './keys.ts';
18
+ export { SshSigner, SshSignerError, createSshSigner, assertEd25519PubText, } from './ssh.ts';
19
+ export type { DetachedSignature, Signer, SshProcessAdapter, SshSignerConfig, VerifiedSignature, } from './ssh.ts';
20
+ export { DSSE_VERSION, DSSE_SSH_NAMESPACE, DSSE_RECORD_PAYLOAD_TYPES, isDsseRecordPayloadType, PAYLOAD_TYPE_ENROLLMENT_GRANT, PAYLOAD_TYPE_POLICY_FLOOR, PAYLOAD_TYPE_ORIGIN, PAYLOAD_TYPE_PUBLICATION, PAYLOAD_TYPE_REVOCATION, PAYLOAD_TYPE_SUBMISSION, DsseEnvelopeError, decodeBase64Strict, dsseSignEnrollmentGrant, dsseSignEnvelope, dsseSignOrigin, dsseSignPolicyFloor, dsseSignPublication, dsseSignRecord, dsseSignRevocation, dsseSignSubmission, dsseVerifyEnrollmentGrant, dsseVerifyEnvelope, dsseVerifyOrigin, dsseVerifyPolicyFloor, dsseVerifyPublication, dsseVerifyRecord, dsseVerifyRevocation, dsseVerifySubmission, encodeBase64, preAuthEncode, } from './dsse.ts';
21
+ export type { DsseEnvelope, DsseRecordPayloadType, DsseSignature, DsseVerifyResult } from './dsse.ts';
22
+ export { ENROLLMENT_GRANT_FIELDS, ENROLLMENT_KEY_FIELDS, GRANT_DELEGATION_ALLOWED_FIELDS, GRANT_DELEGATION_DENIED_FIELDS, GRANT_SCOPE_FIELDS, ORDER_FIELDS, ORDER_OWED_FIELDS, ORDER_REASON_FIELDS, ORIGIN_FIELDS, ORIGIN_SOURCE_AGENT_FIELDS, ORIGIN_SOURCE_CONSOLE_FIELDS, ORIGIN_SOURCE_GIT_FIELDS, POLICY_FLOOR_FIELDS, POLICY_FLOOR_RECORD_FIELDS, PRINCIPAL_REFERENCE_FIELDS, PUBLICATION_FIELDS, RECORD_PAYLOAD_TYPES, REVOCATION_FIELDS, SUBMISSION_FIELDS, SUBMISSION_PRODUCED_FIELDS, } from './records.ts';
23
+ export type { EnrollmentGrantRecord, EnrollmentKeyDescriptor, FieldManifest, GrantDelegation, GrantDelegationAllowed, GrantDelegationDenied, GrantScope, OptionalKeys, OriginRecord, OriginSource, OriginSourceAgent, OriginSourceConsole, OriginSourceGit, PolicyFloor, PolicyFloorRecord, PrincipalReference, PublicationRecord, RequiredKeys, RevocationRecord, SubmissionProducedArtifact, SubmissionRecord, } from './records.ts';
24
+ export { parseAllowedSigners } from './allowed-signers.ts';
25
+ export type { AllowedSignerEntry, AllowedSignerOptions, AllowedSignersFile, AllowedSignersParseError, } from './allowed-signers.ts';
26
+ export { allowedSignersPath, resolveAllowedSigners, resolveAllowedSignersFile } from './trust-roots.ts';
27
+ export type { AllowedSignersResolution, AllowedSignersPresent, AllowedSignersAbsent } from './trust-roots.ts';
28
+ export { isDefPolicy, verifyPublication, verifyPublicationSidecar } from './verify-publication.ts';
29
+ export type { DefPolicy, DefVerdict, VerifyPublicationInput, VerifyPublicationOptions } from './verify-publication.ts';
30
+ export { verifyOrigin, verifyOriginSidecar } from './verify-origin.ts';
31
+ export type { OriginVerdict, VerifyOriginInput, VerifyOriginOptions } from './verify-origin.ts';
32
+ export { DEF_POLICY_RANK, POLICY_FLOOR_PRESETS, artifactPolicyMinimum, floorDefPolicyMinimum, mergePolicyFloorWithLocal, originRulesMinimum, policyFloorGaps, stricterDefPolicy, verifyPolicyFloorRecord, } from './policy-floor.ts';
33
+ export type { PolicyFloorGap, PolicyFloorMergeResult, PolicyFloorVerdict, VerifyPolicyFloorInput, VerifyPolicyFloorOptions, } from './policy-floor.ts';
34
+ export { OriginRulesError, evaluateOriginRule, matchOriginRule, parseOriginRules, ORIGIN_SOURCE_RANK, } from './origin-rules.ts';
35
+ export type { OriginPolicy, OriginRuleEvaluation, OriginRuleMatch, OriginRuleValue, OriginRules, } from './origin-rules.ts';
36
+ export { DEFAULT_MACHINE_SCOPE, buildEnrollmentGrant, verifyRosterEntry, } from './enrollment.ts';
37
+ export type { BuildEnrollmentGrantArgs, EnrollmentChainValidator, RosterVerdict, VerifyRosterEntryInput, VerifyRosterEntryOptions, } from './enrollment.ts';
38
+ export { validateEnrollmentChain, validateProducer, revocationTemporalConsistency, } from './chain.ts';
39
+ export type { ChainInput, ChainOptions, ChainVerdict } from './chain.ts';
40
+ export { attenuate, axisPermits, delegationPermits, ORG_ROOT_SCOPE, scopePermits, } from './scope.ts';
41
+ export type { ScopeAxis } from './scope.ts';
42
+ export { loadRoster, loadRevocations, orgRootPrivateKeyPath, orgRootPublicKeyPath, resolveOrgRoot, revocationsDir, rosterDir, } from './org-root.ts';
43
+ export type { OrgRootAbsent, OrgRootPresent, OrgRootResolution } from './org-root.ts';
44
+ export { canonicalValueBytes, valueDigestHex } from './canonical.ts';
45
+ export { buildSubmissionRecord, signSubmission } from './submission.ts';
46
+ export type { BuildSubmissionRecordInput, SubmissionProducedInput } from './submission.ts';
47
+ export { verifyConsumed, verifyConsumedArtifact } from './verify-consumed.ts';
48
+ export type { ConsumedVerdict, VerifyConsumedInput, VerifyConsumedOptions, } from './verify-consumed.ts';
@@ -0,0 +1,44 @@
1
+ /**
2
+ * The public crypto surface of the owenloop engine (WP-A2).
3
+ *
4
+ * Three narrow capabilities that later trust work builds on:
5
+ * 1. Principal signing keys — `PrincipalKeyManager` generates, stores, and
6
+ * materializes Ed25519 keys for the human/machine/agent principals
7
+ * (macOS Keychain, Linux libsecret, or a secure 0600 file store). No
8
+ * function here hands a caller private-key text.
9
+ * 2. SSHSIG signing/verification — `SshSigner` (behind the format-neutral
10
+ * `Signer` interface) drives stock OpenSSH `ssh-keygen -Y`.
11
+ * 3. DSSE envelopes — `dsseSignEnvelope`/`dsseVerifyEnvelope` plus the six
12
+ * versioned payload-type constants and record-class wrappers.
13
+ *
14
+ * Process/storage adapters stay internal unless a test seam needs the type.
15
+ */
16
+ // ---- keys ----
17
+ export { PrincipalKeyManager, assertKeyRef, canonicalKeyRef, keyidFromBlob, keyRefHash, publicKeyDescriptor, } from "./keys.js";
18
+ // ---- signer / SSHSIG ----
19
+ export { SshSigner, SshSignerError, createSshSigner, assertEd25519PubText, } from "./ssh.js";
20
+ // ---- DSSE ----
21
+ export { DSSE_VERSION, DSSE_SSH_NAMESPACE, DSSE_RECORD_PAYLOAD_TYPES, isDsseRecordPayloadType, PAYLOAD_TYPE_ENROLLMENT_GRANT, PAYLOAD_TYPE_POLICY_FLOOR, PAYLOAD_TYPE_ORIGIN, PAYLOAD_TYPE_PUBLICATION, PAYLOAD_TYPE_REVOCATION, PAYLOAD_TYPE_SUBMISSION, DsseEnvelopeError, decodeBase64Strict, dsseSignEnrollmentGrant, dsseSignEnvelope, dsseSignOrigin, dsseSignPolicyFloor, dsseSignPublication, dsseSignRecord, dsseSignRevocation, dsseSignSubmission, dsseVerifyEnrollmentGrant, dsseVerifyEnvelope, dsseVerifyOrigin, dsseVerifyPolicyFloor, dsseVerifyPublication, dsseVerifyRecord, dsseVerifyRevocation, dsseVerifySubmission, encodeBase64, preAuthEncode, } from "./dsse.js";
22
+ // ---- wire records ----
23
+ export { ENROLLMENT_GRANT_FIELDS, ENROLLMENT_KEY_FIELDS, GRANT_DELEGATION_ALLOWED_FIELDS, GRANT_DELEGATION_DENIED_FIELDS, GRANT_SCOPE_FIELDS, ORDER_FIELDS, ORDER_OWED_FIELDS, ORDER_REASON_FIELDS, ORIGIN_FIELDS, ORIGIN_SOURCE_AGENT_FIELDS, ORIGIN_SOURCE_CONSOLE_FIELDS, ORIGIN_SOURCE_GIT_FIELDS, POLICY_FLOOR_FIELDS, POLICY_FLOOR_RECORD_FIELDS, PRINCIPAL_REFERENCE_FIELDS, PUBLICATION_FIELDS, RECORD_PAYLOAD_TYPES, REVOCATION_FIELDS, SUBMISSION_FIELDS, SUBMISSION_PRODUCED_FIELDS, } from "./records.js";
24
+ // ---- allowed_signers ----
25
+ export { parseAllowedSigners } from "./allowed-signers.js";
26
+ // ---- publication and origin verification ----
27
+ export { allowedSignersPath, resolveAllowedSigners, resolveAllowedSignersFile } from "./trust-roots.js";
28
+ export { isDefPolicy, verifyPublication, verifyPublicationSidecar } from "./verify-publication.js";
29
+ export { verifyOrigin, verifyOriginSidecar } from "./verify-origin.js";
30
+ // ---- policy floors ----
31
+ export { DEF_POLICY_RANK, POLICY_FLOOR_PRESETS, artifactPolicyMinimum, floorDefPolicyMinimum, mergePolicyFloorWithLocal, originRulesMinimum, policyFloorGaps, stricterDefPolicy, verifyPolicyFloorRecord, } from "./policy-floor.js";
32
+ // ---- WP-E2a origin execution policy ----
33
+ export { OriginRulesError, evaluateOriginRule, matchOriginRule, parseOriginRules, ORIGIN_SOURCE_RANK, } from "./origin-rules.js";
34
+ // ---- WP-D1 enrollment ----
35
+ export { DEFAULT_MACHINE_SCOPE, buildEnrollmentGrant, verifyRosterEntry, } from "./enrollment.js";
36
+ // ---- enrollment chain ----
37
+ export { validateEnrollmentChain, validateProducer, revocationTemporalConsistency, } from "./chain.js";
38
+ export { attenuate, axisPermits, delegationPermits, ORG_ROOT_SCOPE, scopePermits, } from "./scope.js";
39
+ export { loadRoster, loadRevocations, orgRootPrivateKeyPath, orgRootPublicKeyPath, resolveOrgRoot, revocationsDir, rosterDir, } from "./org-root.js";
40
+ // ---- WP-D2 signed submission records ----
41
+ export { canonicalValueBytes, valueDigestHex } from "./canonical.js";
42
+ export { buildSubmissionRecord, signSubmission } from "./submission.js";
43
+ // ---- WP-D3 consume-side verification ----
44
+ export { verifyConsumed, verifyConsumedArtifact } from "./verify-consumed.js";
@@ -0,0 +1,258 @@
1
+ /**
2
+ * Principal signing-key management: generate, store, and materialize Ed25519
3
+ * keys for owenloop's three local principals (human, machine, agent).
4
+ *
5
+ * **Key handles are namespaced by `{ origin, kind, id }`** — the normalized
6
+ * hub origin plus a stable principal identity:
7
+ * - human: `id` = the hub actor id (`whoami.actor.id`)
8
+ * - machine: `id` = `"local"` (the local store already supplies host scope;
9
+ * origin prevents cross-hub collision and linkability)
10
+ * - agent: `id` = the agent identity id (`agentId`)
11
+ * Rekeying an existing agent credential retains the agent's signing key (the
12
+ * `agentId` is unchanged); minting a new agent gets a new key.
13
+ *
14
+ * **One selected backend, chosen once, never error-fallback** (REL-6 — a
15
+ * fallback after a selected store fails can create two different private keys
16
+ * for the same principal, a "shadow identity"):
17
+ * 1. macOS: `security` generic-password entries;
18
+ * 2. Linux: `secret-tool` when the executable is on `PATH`;
19
+ * 3. otherwise: one atomic `0600` record file under `$HOME/.owenloop/keys/`
20
+ * (both `$HOME/.owenloop` and `keys` forced to `0700`, symlinked or
21
+ * non-directory paths refused).
22
+ * `OWENLOOP_NO_KEYCHAIN=1` forces the file backend — the same explicit
23
+ * override the credential store uses.
24
+ *
25
+ * **Private bytes never leave the store.** `security`/`secret-tool` receive
26
+ * records on child stdin, and their lookup commands' secret-bearing stdout is
27
+ * redirected directly to a pre-opened `0600` temp file descriptor — never
28
+ * captured, inherited, logged, or interpolated into an error message. Child
29
+ * failures produce fixed operation/status messages. A generated key
30
+ * materializes for `ssh-keygen` only inside a unique `0700` temp dir as a
31
+ * `0600` file, removed in `finally`; a reused key passes only its canonical
32
+ * path. No public API hands a caller private-key text.
33
+ *
34
+ * `ensure` is serialized per key ref by the repo's file lock
35
+ * (`$HOME/.owenloop/keys/<hash>.lock`): acquire → re-read → generate only when
36
+ * still absent. A corrupt/unreadable existing key is a hard failure, never a
37
+ * silent rotation.
38
+ */
39
+ /** The three local principal kinds. */
40
+ export type PrincipalKind = 'human' | 'machine' | 'agent';
41
+ /**
42
+ * The stable identity of one local signing key: the normalized hub origin +
43
+ * principal kind + stable principal id (see the module doc).
44
+ */
45
+ export interface PrincipalKeyRef {
46
+ origin: string;
47
+ kind: PrincipalKind;
48
+ id: string;
49
+ }
50
+ /** Non-secret public-key descriptors. Never carries private material. */
51
+ export interface PublicKeyDescriptor {
52
+ /** The `SHA256:<unpadded-base64>` fingerprint of the public-key blob. */
53
+ keyid: string;
54
+ /** The key type, e.g. `ssh-ed25519`. */
55
+ keyType: string;
56
+ /** The full OpenSSH public-key line (`keytype base64 [comment]`). */
57
+ openSshPublicKey: string;
58
+ /** The key's comment (may be empty). */
59
+ comment: string;
60
+ }
61
+ /** Which backend stored (or would store) a key. */
62
+ export type KeyStorageBackendKind = 'macos-security' | 'secret-tool' | 'file';
63
+ /** The result of `ensure`. */
64
+ export interface EnsureKeyResult {
65
+ ref: PrincipalKeyRef;
66
+ /** `created` = generated now; `existing` = already present; `reused` = an explicit SSH key recorded. */
67
+ state: 'created' | 'existing' | 'reused';
68
+ /** The backend name, or `reused` for an explicit SSH key. */
69
+ backend: KeyStorageBackendKind | 'reused';
70
+ publicKey: PublicKeyDescriptor;
71
+ }
72
+ /** The result of `inspect` — non-secret storage state. */
73
+ export interface InspectKeyResult {
74
+ exists: boolean;
75
+ source: 'generated' | 'reused' | undefined;
76
+ backend: KeyStorageBackendKind | 'reused' | undefined;
77
+ publicKey: PublicKeyDescriptor | undefined;
78
+ }
79
+ /**
80
+ * A minimal child-process seam for the storage commands and `ssh-keygen`.
81
+ * `shell: false` always. The default implementation never captures
82
+ * secret-bearing output: stdout goes to an fd (lookup commands), to the
83
+ * caller when explicitly requested (public data only), or is discarded.
84
+ */
85
+ export interface KeyCommandRunner {
86
+ run(cmd: string, args: string[], opts: {
87
+ stdin?: Buffer;
88
+ timeoutMs?: number;
89
+ /** Redirect child stdout into this pre-opened fd (lookup commands). */
90
+ stdoutFd?: number;
91
+ /** Capture stdout (PUBLIC data only — armored signatures, keygen probes). */
92
+ captureStdout?: boolean;
93
+ }): {
94
+ status: number | null;
95
+ stdout: Buffer;
96
+ };
97
+ }
98
+ /** Injection seams for hermetic tests. All optional. */
99
+ export interface PrincipalKeyManagerOpts {
100
+ env: Record<string, string | undefined>;
101
+ /** Force a backend (fake-platform tests). */
102
+ backend?: KeyStorageBackendKind;
103
+ /** Force the platform string (`darwin`/`linux`) for selection tests. */
104
+ platform?: NodeJS.Platform;
105
+ /** `secret-tool`-on-PATH probe (defaults to a PATH scan). */
106
+ commandExists?: (cmd: string) => boolean;
107
+ /** Child-process seam (fake storage adapters in tests). */
108
+ runner?: KeyCommandRunner;
109
+ /** Override `$HOME` (defaults to `env.HOME`). */
110
+ homeDir?: string;
111
+ /** Override the OS temp dir for generation/materialization. */
112
+ tempDir?: string;
113
+ /** The ssh-keygen binary (defaults to `ssh-keygen` on PATH). */
114
+ sshKeygen?: string;
115
+ }
116
+ /** Canonical, order-stable serialization of a key ref (for hashing). */
117
+ export declare function canonicalKeyRef(ref: PrincipalKeyRef): string;
118
+ /** Validate a key ref shape. Throws a fixed `CliError` on any bad field. */
119
+ export declare function assertKeyRef(ref: PrincipalKeyRef): void;
120
+ /** The SHA-256 hex of the canonical ref — file name / keychain account. */
121
+ export declare function keyRefHash(ref: PrincipalKeyRef): string;
122
+ /** Compute the `SHA256:<unpadded-base64>` fingerprint of a public-key blob. */
123
+ export declare function keyidFromBlob(blob: Buffer): string;
124
+ /** Parse an OpenSSH public-key line into a descriptor (never reads private bytes). */
125
+ export declare function publicKeyDescriptor(pubText: string): PublicKeyDescriptor;
126
+ /**
127
+ * The principal key manager. One backend is selected at construction; all
128
+ * operations use it exclusively (no error-fallback — see the module doc).
129
+ */
130
+ export declare class PrincipalKeyManager {
131
+ private readonly env;
132
+ private readonly backendKind;
133
+ private readonly runner;
134
+ private readonly homeDir;
135
+ private readonly tempBase;
136
+ private readonly sshKeygen;
137
+ constructor(opts: PrincipalKeyManagerOpts);
138
+ /** Which backend was selected (non-secret; printable). */
139
+ get backend(): KeyStorageBackendKind;
140
+ /**
141
+ * Backend selection: `OWENLOOP_NO_KEYCHAIN=1` forces `file`; macOS uses
142
+ * `security`; Linux uses `secret-tool` when present on PATH; everything else
143
+ * falls back to the secure file store.
144
+ */
145
+ private selectBackend;
146
+ /** `$HOME/.owenloop`. */
147
+ private baseDir;
148
+ /** `$HOME/.owenloop/keys`. */
149
+ private keysDir;
150
+ /** Force `0700`, refusing symlinked / non-directory paths. */
151
+ private ensureSecureDir;
152
+ /** Ensure both storage dirs exist with the required modes. */
153
+ private ensureDirs;
154
+ /** The file-backend record path for a ref. */
155
+ private recordPath;
156
+ /** The per-ref lock path. */
157
+ private lockPath;
158
+ /** A non-secret per-ref ownership marker that prevents backend shadowing. */
159
+ private backendMarkerPath;
160
+ /** A non-secret pointer that lets offline callers recover the principal ref. */
161
+ private refPointerPath;
162
+ private readBackendOwner;
163
+ /** Refuse a selected backend that differs from the persisted owner. */
164
+ private assertBackendOwner;
165
+ /** Claim ownership before the first write; marker writes are non-secret. */
166
+ private claimBackend;
167
+ /** Read the raw record text from the selected backend, or `null` when absent. */
168
+ private readRecordText;
169
+ /** Write the raw record text to the selected backend. Loud failure, fixed message. */
170
+ private writeRecordText;
171
+ /** Derive a public key from generated private material without exposing it. */
172
+ private deriveGeneratedPublic;
173
+ /** Parse + validate a record against the requested ref. Corrupt = hard error. */
174
+ private parseRecord;
175
+ /**
176
+ * The repair command deliberately names the exact non-secret Keychain account
177
+ * handle. Deleting that one damaged item and rerunning setup is the supported
178
+ * explicit rotation path when identity-preserving migration cannot verify.
179
+ */
180
+ private damagedMacosRecordError;
181
+ /**
182
+ * Migrate the one known v1 macOS writer defect while the caller holds the
183
+ * per-ref lock. A candidate is rewritten only after full record validation
184
+ * derives the already-stored public fingerprint from the repaired private key.
185
+ */
186
+ private migrateDamagedMacosRecord;
187
+ /**
188
+ * Read + validate the stored record for a ref, or `null` when absent. macOS
189
+ * reads share the per-ref lock with `ensure`, so every normal read path can
190
+ * perform the identity-preserving v1 migration without racing key creation.
191
+ */
192
+ private readRecord;
193
+ /**
194
+ * Non-secret inspection: does a key exist for this ref, and what is its
195
+ * public descriptor / source / backend? For generated records, validation
196
+ * temporarily materializes private bytes in a 0600 file so stock ssh-keygen
197
+ * can derive and compare the public half; private bytes never enter the
198
+ * returned result.
199
+ */
200
+ inspect(ref: PrincipalKeyRef): Promise<InspectKeyResult>;
201
+ /** Write the non-secret ref pointer with strict file permissions. */
202
+ private writeRefPointer;
203
+ /**
204
+ * List valid non-secret principal-ref pointers. Malformed, symlinked, and
205
+ * mismatched entries are ignored so a stray file cannot block key discovery.
206
+ */
207
+ listRefs(): PrincipalKeyRef[];
208
+ /** Resolve one principal ref by origin and kind for offline signing. */
209
+ resolveRef(origin: string, kind: PrincipalKind): PrincipalKeyRef | null;
210
+ /**
211
+ * Idempotently ensure a key exists for `ref`.
212
+ *
213
+ * - Present key ⇒ `{ state: 'existing' }` (zero key-record writes; the
214
+ * non-secret ref pointer is backfilled when needed).
215
+ * - `opts.reuse` on an ABSENT human key ⇒ validate the candidate SSH key
216
+ * (Ed25519 only) with a non-secret sign/verify challenge, then store only
217
+ * its canonical path + public key + fingerprint (`state: 'reused'`). The
218
+ * candidate's private bytes are never copied.
219
+ * - `opts.reuse` against a PRESENT key ⇒ hard conflict error (no rotation in
220
+ * WP-A2).
221
+ * - Otherwise generate a dedicated Ed25519 key in a unique `0700` temp dir
222
+ * and store it through the selected backend (`state: 'created'`).
223
+ *
224
+ * Serialized per ref by the file lock; after acquiring, the store is
225
+ * re-read before generating.
226
+ */
227
+ ensure(ref: PrincipalKeyRef, opts?: {
228
+ reuse?: {
229
+ path: string;
230
+ };
231
+ }): Promise<EnsureKeyResult>;
232
+ /** Derive a candidate's public key from a public path, adjacent `.pub`, or private path. */
233
+ private candidatePublicText;
234
+ /** Validate + record an explicit SSH key (human principal only). */
235
+ private storeReused;
236
+ /**
237
+ * Sign a fixed challenge message with the candidate key and verify it with
238
+ * stock `ssh-keygen -Y verify` against the candidate's own public key as the
239
+ * sole allowed signer. Public-key-only inputs; the message is public.
240
+ */
241
+ private challengeSignVerify;
242
+ /** Generate a dedicated Ed25519 key and store it through the backend. */
243
+ private generate;
244
+ /**
245
+ * Materialize the signing key for `ref` as a filesystem path and pass it to
246
+ * `callback`. Generated keys on keychain backends materialize as a `0600`
247
+ * file inside a unique `0700` temp dir, removed in `finally`; the file
248
+ * backend passes its persistent `0600` record's key file path indirectly by
249
+ * materializing the record's private material the same way (one code path —
250
+ * the record file is a JSON document, not a key file). Reused keys pass only
251
+ * their canonical path. No private text is returned to the caller.
252
+ */
253
+ withSigningKey<T>(ref: PrincipalKeyRef, callback: (keyPath: string) => Promise<T>): Promise<T>;
254
+ /** Create a unique `0700` temp dir under the configured temp base. */
255
+ private mkTempKeyDir;
256
+ }
257
+ /** Convenience: the directory name helper is reused by tests. */
258
+ export declare function keysDirFor(homeDir: string): string;