owenloop 0.3.1 → 0.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/hub.d.ts CHANGED
@@ -10,6 +10,34 @@
10
10
  * etc.) so this module stays trivially testable and `cli.ts` doesn't widen its
11
11
  * export surface.
12
12
  *
13
+ * The keychain backend selection and the read side of credential storage also
14
+ * live here (`defaultKeychain` / `resolveKeychain` / `credentialBackend` /
15
+ * `readStoredCredential`): the `security` shell-out is synchronous and
16
+ * injectable, so it stays consistent with this module's network-free, testable
17
+ * charter, and it lets the public barrel (`src/index.ts`) export a supported
18
+ * read-only `readStoredCredential` without pulling in `cli.ts` (which the
19
+ * core/hub boundary lint forbids). `cli.ts` keeps thin wrappers so there is one
20
+ * implementation of backend selection, not two.
21
+ *
22
+ * Backend precedence is **external → keychain → file**, resolved once in
23
+ * `credentialBackend`. The external backend is an OPTIONAL, explicitly
24
+ * configured command (`OWENLOOP_CREDENTIAL_COMMAND`) that prints a credential
25
+ * for the requested `(origin, slot)` — it gives non-macOS workers, CI, and
26
+ * users whose secrets live in a secret manager a supported way to feed owenloop
27
+ * a credential without owenloop learning about any specific manager. When it is
28
+ * configured it is AUTHORITATIVE: a failure of any kind is a loud error and
29
+ * never a fallthrough to a store (see `runCredentialCommand`). When it is not
30
+ * configured, behaviour is byte-for-byte what it was before it existed.
31
+ *
32
+ * Credentials are keyed by **slot**, not by origin alone: one stored credential
33
+ * per `(normalized origin, principal-account)` pair, the slot being `human` or
34
+ * `agent:<account>` (account defaults to `default`). See `CredentialSlotSelector`
35
+ * and `credentialSlot`. A reader must always name the slot it wants — it can
36
+ * never guess — so a host or CLI verb can never accidentally read the wrong
37
+ * principal's credential. There is deliberately NO migration from the older
38
+ * one-slot-per-origin keying: entries written under it are simply never found
39
+ * and read as absent; the upgrade step is re-running `login`.
40
+ *
13
41
  * `.owenloop/hub.json` is a pure binding (which hub this project publishes to)
14
42
  * — there is no client-side push ledger. `push` diffs local defs against the
15
43
  * server's own `hash` (`GET /api/workflows`, see `computeServerDiff`), and
@@ -106,9 +134,11 @@ export declare function pkcePair(): PkcePair;
106
134
  /** A random anti-CSRF `state` token for the authorization request. */
107
135
  export declare function randomState(): string;
108
136
  /**
109
- * Stored per hub origin. Never logged or echoed. `oauth` carries a refreshable
110
- * pair (loopback flow); `agent` is a pasted `olp_` token and `oauth-pasted` a
111
- * pasted `mcpat_` access token — neither refreshes.
137
+ * Stored per **slot** — one credential per `(normalized origin, slot)` pair,
138
+ * the slot being `human` or `agent:<account>` (see `CredentialSlotSelector`).
139
+ * Never logged or echoed. `oauth` carries a refreshable pair (loopback flow);
140
+ * `agent` is a pasted `olp_` token and `oauth-pasted` a pasted `mcpat_` access
141
+ * token — neither refreshes.
112
142
  */
113
143
  export type Credential = {
114
144
  kind: 'oauth';
@@ -123,14 +153,82 @@ export type Credential = {
123
153
  kind: 'oauth-pasted';
124
154
  accessToken: string;
125
155
  };
156
+ /**
157
+ * Which stored credential to address: the human's, or a named agent account's.
158
+ *
159
+ * A credential lives in a **slot** — `human`, or `agent:<account>` with
160
+ * `account` defaulting to `'default'`. The slot is part of the storage key on
161
+ * both backends (keychain account, and the second level of the credential
162
+ * file's `hubs` map), so `human` and `agent:default` on the same origin are
163
+ * distinct entries that never collide, and neither does `agent:ci` with
164
+ * `agent:release`.
165
+ *
166
+ * The discriminator is an **account**, never a "label" — labels are a different
167
+ * axis of the system and the word is reserved.
168
+ */
169
+ export type CredentialSlotSelector = {
170
+ principal: 'human';
171
+ } | {
172
+ principal: 'agent';
173
+ account?: string;
174
+ };
175
+ /**
176
+ * The credential file (`~/.config/owenloop/credentials.json`), v2: origin →
177
+ * slot → credential. `version` is `2`; a file carrying any other version reads
178
+ * as an EMPTY store (see `readCredentialFile`) — that is how entries under the
179
+ * older one-slot-per-origin keying become invisible without any migration code.
180
+ */
126
181
  export interface CredentialFile {
127
- version: 1;
128
- hubs: Record<string, Credential>;
182
+ version: 2;
183
+ hubs: Record<string, Record<string, Credential>>;
129
184
  }
185
+ /**
186
+ * Resolve a selector to its slot string: `'human'` or `` `agent:${account}` ``.
187
+ *
188
+ * This is the ONE place account defaulting and validation happen — every read,
189
+ * write, and delete path funnels through it, so no call site re-implements the
190
+ * `agent:` concatenation. Throws on an invalid account name, and on `account`
191
+ * supplied alongside `principal: 'human'`: TypeScript's excess-property check
192
+ * does not reliably reject that against a union, so it is a runtime error too
193
+ * rather than a silently ignored argument.
194
+ *
195
+ * `agent:human` cannot collide with `human` by construction — the `agent:`
196
+ * prefix differs — so no extra guard is needed.
197
+ */
198
+ export declare function credentialSlot(sel: CredentialSlotSelector): string;
199
+ /**
200
+ * The keychain SERVICE for a hub origin; the slot is the keychain ACCOUNT.
201
+ * `origin` must already be `normalizeOrigin`d — every call site normalizes
202
+ * first, so SEC-2 (remote plaintext rejected) happens before any keychain or
203
+ * filesystem access.
204
+ */
205
+ export declare function keychainServiceFor(normalizedOrigin: string): string;
206
+ /**
207
+ * Shape-guard a stored credential value, returning `null` when it is not a
208
+ * well-formed `Credential`. Used on BOTH backends so "a corrupt entry reads as
209
+ * absent" is symmetric: previously the keychain path did an unchecked
210
+ * `JSON.parse(...) as Credential` and the file path validated nothing at all,
211
+ * so a truncated or hand-edited entry could surface as a bogus credential
212
+ * instead of a clean miss.
213
+ */
214
+ export declare function parseCredential(raw: unknown): Credential | null;
130
215
  /** The user-level config dir (never the project dir). Derives from the caller's env. */
131
216
  export declare function configDir(env: Record<string, string | undefined>): string;
132
217
  export declare function credentialFilePath(env: Record<string, string | undefined>): string;
133
- /** Read the credential file; a missing file is an empty store, not an error. */
218
+ /**
219
+ * Read the credential file; a missing file is an empty store, not an error.
220
+ *
221
+ * A file whose `version` is not `2` also reads as an EMPTY store — no throw, no
222
+ * migration, no hybrid write. That is how entries under the older
223
+ * one-slot-per-origin keying become invisible (there are no external users, so
224
+ * the documented upgrade step is re-running `login`). Stated deliberately: the
225
+ * next write then replaces such a file wholesale, which is acceptable because
226
+ * its entries are unreachable by design.
227
+ *
228
+ * Genuinely broken JSON, or a `hubs` that is not an object, still throws —
229
+ * "corrupt reads as absent" is about a corrupt ENTRY (see `parseCredential`),
230
+ * not a destroyed file.
231
+ */
134
232
  export declare function readCredentialFile(path: string): CredentialFile;
135
233
  /**
136
234
  * Write `data` to `path` atomically, refusing a symlinked (or directory)
@@ -165,6 +263,132 @@ export declare function writeFileAtomic(path: string, data: string, opts?: {
165
263
  * is refused (SEC-3).
166
264
  */
167
265
  export declare function writeCredentialFile(path: string, file: CredentialFile): void;
266
+ /**
267
+ * An OS keychain backend, keyed by `(service, account)` — the service is
268
+ * `keychainServiceFor(origin)` (`owenloop:<origin>`) and the account is the
269
+ * credential slot (`human` / `agent:<name>`). The pair mirrors macOS
270
+ * `security`'s own `-s`/`-a` arguments. The default implementation (macOS
271
+ * `security` generic passwords) is `defaultKeychain`; tests and embedding hosts
272
+ * inject their own. Never logs or echoes the secret.
273
+ */
274
+ export interface Keychain {
275
+ get(service: string, account: string): string | null;
276
+ set(service: string, account: string, value: string): void;
277
+ delete(service: string, account: string): void;
278
+ }
279
+ /**
280
+ * The default macOS keychain backend (generic passwords under service
281
+ * `owenloop:<origin>`, account = the credential slot). The secret is fed through
282
+ * the `security -i` command stream on stdin, never as a `-w` argv value, so it
283
+ * never appears in `ps`/shell history. Returns `undefined` off macOS or when
284
+ * `OWENLOOP_NO_KEYCHAIN=1`, so callers fall back to the 0600 credential file.
285
+ */
286
+ export declare function defaultKeychain(env: Record<string, string | undefined>): Keychain | undefined;
287
+ /**
288
+ * The configured external credential command, or `undefined` when it is unset
289
+ * or blank.
290
+ *
291
+ * Configuration is a single environment variable, `OWENLOOP_CREDENTIAL_COMMAND`,
292
+ * read off the caller-supplied `env` record like every other knob in this module
293
+ * (`OWENLOOP_NO_KEYCHAIN`, `OWENLOOP_HUB`, the `*_TIMEOUT_MS` overrides) — never
294
+ * `process.env` directly, so hosts and tests stay hermetic. Explicit config
295
+ * only: there is deliberately no discovery, no scanning for helper binaries, and
296
+ * no implicit default.
297
+ *
298
+ * An all-whitespace value is treated as NOT configured, and that decision is
299
+ * made HERE rather than at each call site, so "is the external backend active?"
300
+ * has exactly one answer.
301
+ */
302
+ export declare function externalCredentialCommand(env: Record<string, string | undefined>): string | undefined;
303
+ /**
304
+ * Resolve the keychain backend for this env, honoring the hard override:
305
+ * `OWENLOOP_NO_KEYCHAIN=1` forces the file backend (`undefined`) EVEN when a
306
+ * keychain is injected; otherwise the injected backend wins, else the platform
307
+ * default.
308
+ */
309
+ export declare function resolveKeychain(env: Record<string, string | undefined>, injected?: Keychain): Keychain | undefined;
310
+ /**
311
+ * The credential backend, decided ONCE from env/config and then used
312
+ * consistently for read and write. Deciding once — rather than per-operation —
313
+ * is the REL-6 fix: the old error-driven fallback let a write land in the file
314
+ * while a later read hit the (absent/stale) keychain, so a credential could
315
+ * shadow itself across backends.
316
+ *
317
+ * Precedence is **external → keychain → file**. Resolving all three here, in one
318
+ * place, is what makes "decided once" and "a configured external command wins
319
+ * over a populated keychain or file entry" the same fact, with no second
320
+ * decision point that could drift.
321
+ */
322
+ export type CredentialBackend = {
323
+ kind: 'external';
324
+ command: string;
325
+ } | {
326
+ kind: 'keychain';
327
+ kc: Keychain;
328
+ } | {
329
+ kind: 'file';
330
+ };
331
+ /**
332
+ * `OWENLOOP_NO_KEYCHAIN=1` deliberately does NOT affect the external branch: it
333
+ * selects between the two LOCAL stores, and the external command sits in front
334
+ * of both.
335
+ */
336
+ export declare function credentialBackend(env: Record<string, string | undefined>, injected?: Keychain): CredentialBackend;
337
+ /**
338
+ * Options for `readStoredCredential`. The slot selector is REQUIRED (it is
339
+ * spread into this type, not optional): the caller must name which principal's
340
+ * credential it wants.
341
+ */
342
+ export type ReadStoredCredentialOpts = CredentialSlotSelector & {
343
+ /** Environment to consult (OWENLOOP_NO_KEYCHAIN, HOME/XDG_CONFIG_HOME). Default: `process.env`. */
344
+ env?: Record<string, string | undefined>;
345
+ /** Injectable keychain backend (tests / embedding hosts). Ignored when OWENLOOP_NO_KEYCHAIN=1. */
346
+ keychain?: Keychain;
347
+ };
348
+ /**
349
+ * Read the stored hub credential for `origin` **in the named slot** from the
350
+ * chosen backend ONLY — the supported, read-only programmatic surface
351
+ * (owenwork's CredentialReader seam wires to this once released). Secret hygiene
352
+ * is unchanged: this function never logs or echoes the returned credential, and
353
+ * there is deliberately no write/delete companion on the public surface —
354
+ * `login` / `logout` remain the only way to store or remove a credential.
355
+ *
356
+ * `opts` and its `principal` are both required, so a caller can never
357
+ * accidentally read the wrong principal's credential:
358
+ *
359
+ * ```ts
360
+ * readStoredCredential(origin, { principal: 'human' });
361
+ * readStoredCredential(origin, { principal: 'agent' }); // agent:default
362
+ * readStoredCredential(origin, { principal: 'agent', account: 'ci' }); // agent:ci
363
+ * ```
364
+ *
365
+ * Passing `account` with `principal: 'human'` throws (see `credentialSlot`),
366
+ * because TypeScript's excess-property check does not reliably reject it
367
+ * against a union.
368
+ *
369
+ * `origin` is normalized (idempotent on already-normalized input, so the CLI's
370
+ * pre-normalized callers are unaffected) BEFORE any keychain or filesystem
371
+ * access, so the storage key matches what `login` persisted and an invalid or
372
+ * plaintext-remote origin throws at normalization (SEC-2), exactly as the CLI
373
+ * would.
374
+ *
375
+ * Backend is selected once (`credentialBackend`), with precedence external →
376
+ * keychain → file. A keychain-backed read NEVER falls through to the file (that
377
+ * fallback was the REL-6 shadowing bug), and a corrupt entry reads as absent
378
+ * (`null`) on either store — never as a reason to consult the other. The file
379
+ * backend derives its path from the supplied `env` (HOME / XDG_CONFIG_HOME),
380
+ * never `process.env` directly, so a caller passing `opts.env` stays hermetic;
381
+ * only the top-level default falls back to `process.env`.
382
+ *
383
+ * **When `OWENLOOP_CREDENTIAL_COMMAND` is configured this function can THROW
384
+ * instead of returning `null`**, and it does not consult a store at all. The
385
+ * command is authoritative, so a nonzero exit, a timeout, empty output, or
386
+ * output that is not a well-formed credential is a loud error naming the origin
387
+ * and the slot — never a silent fallthrough to a stale local entry. See
388
+ * `runCredentialCommand`. When it is NOT configured, behaviour is exactly what
389
+ * it has always been.
390
+ */
391
+ export declare function readStoredCredential(origin: string, opts: ReadStoredCredentialOpts): Credential | null;
168
392
  /**
169
393
  * `.owenloop/hub.json` — written by `connect`. Safe to commit: contains no
170
394
  * secrets, only the bound hub origin. Purely a binding — `push` diffs against