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
@@ -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;