owenloop 0.3.1 → 0.4.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.
- package/CHANGELOG.md +32 -0
- package/README.md +53 -1
- package/dist/add.d.ts +12 -40
- package/dist/add.js +11 -176
- package/dist/cli.d.ts +52 -7
- package/dist/cli.js +1072 -382
- package/dist/credentials.d.ts +274 -0
- package/dist/credentials.js +695 -0
- package/dist/defs.js +23 -0
- package/dist/engine.js +15 -6
- package/dist/hub.d.ts +363 -6
- package/dist/hub.js +551 -4
- package/dist/index.d.ts +4 -1
- package/dist/index.js +2 -1
- package/dist/lock.d.ts +80 -0
- package/dist/lock.js +217 -0
- package/dist/mcp/serve.d.ts +84 -0
- package/dist/mcp/serve.js +565 -0
- package/dist/mcp/server.d.ts +135 -0
- package/dist/mcp/server.js +330 -0
- package/dist/model.d.ts +59 -4
- package/dist/model.js +148 -21
- package/dist/owenwork.d.ts +57 -0
- package/dist/owenwork.js +84 -0
- package/dist/types.d.ts +48 -6
- package/dist/util.d.ts +24 -0
- package/dist/util.js +25 -0
- package/docs/authoring.md +9 -0
- package/docs/cli.md +411 -15
- package/docs/design.md +86 -12
- package/docs/embedding.md +58 -0
- package/package.json +1 -1
package/dist/defs.js
CHANGED
|
@@ -1006,6 +1006,18 @@ export function validateDef(def) {
|
|
|
1006
1006
|
errors.push(`step '${l.name}' produces a per-element output but has no map (\$i) consume to bind it`);
|
|
1007
1007
|
}
|
|
1008
1008
|
}
|
|
1009
|
+
// a reduce-mode step whose only produces are collections can never fire: eligibleFirings'
|
|
1010
|
+
// reduce branch (src/model.ts) derives the discharge set from singletonProduces(step) only,
|
|
1011
|
+
// so zero singleton produces means outs.length === 0 and no firing is ever pushed — the step
|
|
1012
|
+
// is silently dead (collection debt owed forever, absent from eligible/pending/blocked).
|
|
1013
|
+
for (const l of def.steps) {
|
|
1014
|
+
const isReduce = l.consumes.some((c) => c.mode === 'reduce');
|
|
1015
|
+
const hasCollectionProduce = l.produces.some((p) => p.kind === 'collection');
|
|
1016
|
+
const hasSingletonProduce = l.produces.some((p) => p.kind === 'singleton');
|
|
1017
|
+
if (isReduce && hasCollectionProduce && !hasSingletonProduce) {
|
|
1018
|
+
errors.push(`step ${l.name} is reduce-mode but produces only collections; reduce steps can only discharge singleton produces`);
|
|
1019
|
+
}
|
|
1020
|
+
}
|
|
1009
1021
|
// same stem in both produces: and generates: on the same step is a hard error
|
|
1010
1022
|
for (const l of def.steps) {
|
|
1011
1023
|
if (!l.generates || l.generates.length === 0)
|
|
@@ -1147,6 +1159,17 @@ export function validateDef(def) {
|
|
|
1147
1159
|
errors.push(`step '${l.name}': idleAfter is set but 'idle' is not in on:; idleAfter is only meaningful with the idle trigger`);
|
|
1148
1160
|
}
|
|
1149
1161
|
}
|
|
1162
|
+
// an allGreen/idle evaluator step that declares consumes can never commit: both firings
|
|
1163
|
+
// (src/model.ts) are built with inputs: [], so the claim fingerprint is empty, but commit-time
|
|
1164
|
+
// casCheck (src/engine.ts) derives required inputs from consumes and finds no fingerprint
|
|
1165
|
+
// entry for them — every firing is born-rejected forever. Evaluators must declare their
|
|
1166
|
+
// output under generates: with no consumes: (see examples/workflows/sla-watchdog.yaml, monitor).
|
|
1167
|
+
for (const l of def.steps) {
|
|
1168
|
+
const triggers = l.on ?? ['inputsGreen'];
|
|
1169
|
+
if (triggers.some((t) => t === 'allGreen' || t === 'idle') && l.consumes.length > 0) {
|
|
1170
|
+
errors.push(`evaluator step ${l.name} (on: allGreen/idle) must not declare consumes; its firings carry no input fingerprint`);
|
|
1171
|
+
}
|
|
1172
|
+
}
|
|
1150
1173
|
// M2-VALIDATE: calls: step per-def rules.
|
|
1151
1174
|
// Note: cross-def checks (target-def existence, child input-key validity) cannot be done here
|
|
1152
1175
|
// because validateDef is a pure per-def function with no resolver. Those checks live in loadDefs
|
package/dist/engine.js
CHANGED
|
@@ -1337,7 +1337,7 @@ export class Engine {
|
|
|
1337
1337
|
const req = requiredInputs(def, arts, art);
|
|
1338
1338
|
const cas = this.casCheck(arts, req, r.fingerprint ?? {});
|
|
1339
1339
|
if (cas.moved) {
|
|
1340
|
-
this.bornReject(art, cas.moved);
|
|
1340
|
+
this.bornReject(art, cas.moved, cas.reason);
|
|
1341
1341
|
this.releaseLeaseOnBornReject(workflow, run);
|
|
1342
1342
|
this.settle(workflow, def);
|
|
1343
1343
|
return { path, outcome: 'born-rejected', reason: cas.reason };
|
|
@@ -1419,7 +1419,7 @@ export class Engine {
|
|
|
1419
1419
|
if (cas.moved) {
|
|
1420
1420
|
const seal = arts.get(sealPath(stem));
|
|
1421
1421
|
if (seal)
|
|
1422
|
-
this.bornReject(seal, cas.moved);
|
|
1422
|
+
this.bornReject(seal, cas.moved, cas.reason);
|
|
1423
1423
|
this.releaseLeaseOnBornReject(workflow, run);
|
|
1424
1424
|
this.settle(workflow, def);
|
|
1425
1425
|
return { outcome: 'born-rejected', created: [], reason: cas.reason };
|
|
@@ -1512,7 +1512,7 @@ export class Engine {
|
|
|
1512
1512
|
const req = plainConsumes(step).map((c) => c.stem);
|
|
1513
1513
|
const cas = this.casCheck(arts, req, r.fingerprint ?? {});
|
|
1514
1514
|
if (cas.moved) {
|
|
1515
|
-
this.bornReject(sealArt, cas.moved);
|
|
1515
|
+
this.bornReject(sealArt, cas.moved, cas.reason);
|
|
1516
1516
|
this.releaseLeaseOnBornReject(workflow, run);
|
|
1517
1517
|
this.settle(workflow, def);
|
|
1518
1518
|
return { path: sealP, outcome: 'born-rejected', reason: cas.reason };
|
|
@@ -2297,13 +2297,13 @@ export class Engine {
|
|
|
2297
2297
|
});
|
|
2298
2298
|
}
|
|
2299
2299
|
}
|
|
2300
|
-
bornReject(art, movedPath) {
|
|
2300
|
+
bornReject(art, movedPath, reasonText) {
|
|
2301
2301
|
this.store.putArtifact({
|
|
2302
2302
|
...art,
|
|
2303
2303
|
acceptance: 'rejected',
|
|
2304
2304
|
reasons: [
|
|
2305
2305
|
...art.reasons,
|
|
2306
|
-
reason('born-rejected', 'structural', 'engine', `born-rejected: ${movedPath} moved during this run`, art.version),
|
|
2306
|
+
reason('born-rejected', 'structural', 'engine', `born-rejected: ${reasonText ?? `${movedPath} moved during this run`}`, art.version),
|
|
2307
2307
|
],
|
|
2308
2308
|
});
|
|
2309
2309
|
}
|
|
@@ -2315,7 +2315,16 @@ export class Engine {
|
|
|
2315
2315
|
}
|
|
2316
2316
|
if (!fingerprintMatches(arts, req, fp)) {
|
|
2317
2317
|
const moved = req.find((p) => (arts.get(p)?.version ?? -1) !== fp[p]) ?? req[0] ?? 'inputs';
|
|
2318
|
-
|
|
2318
|
+
// Two structurally different causes share this branch: (a) ABSENT — the path
|
|
2319
|
+
// was never in the claim fingerprint at all (e.g. an allGreen/idle firing whose
|
|
2320
|
+
// inputs: [] yields fp={}, but the step still declares consumes:), so there is
|
|
2321
|
+
// no claimed version to have "moved" from; (b) CHANGED — the path WAS
|
|
2322
|
+
// fingerprinted but a concurrent commit moved it since claim. Keep the wording
|
|
2323
|
+
// distinct so the diagnostic doesn't lie about case (a).
|
|
2324
|
+
if (fp[moved] === undefined) {
|
|
2325
|
+
return { moved, reason: `${moved} was not in the claim fingerprint (this firing carried no input version for it)` };
|
|
2326
|
+
}
|
|
2327
|
+
return { moved, reason: `${moved} moved version during this run (claimed v${fp[moved]}, now v${arts.get(moved)?.version ?? -1})` };
|
|
2319
2328
|
}
|
|
2320
2329
|
return {};
|
|
2321
2330
|
}
|
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
|
|
110
|
-
*
|
|
111
|
-
*
|
|
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:
|
|
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
|
-
/**
|
|
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,164 @@ 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;
|
|
392
|
+
/**
|
|
393
|
+
* Enumerate the hub origins that have a usable `human` credential stored, or
|
|
394
|
+
* `null` when the active backend cannot be enumerated.
|
|
395
|
+
*
|
|
396
|
+
* Consumer: `owenloop mcp`'s origin inference (`resolveMcpOrigin` in
|
|
397
|
+
* `src/mcp/serve.ts`). When the host spawns the server with neither `--hub` nor
|
|
398
|
+
* `OWENLOOP_HUB`, the server tries to infer the single hub the user is logged
|
|
399
|
+
* in to. That inference is only sound on the FILE backend, which can list its
|
|
400
|
+
* `hubs` map; the keychain and external-command backends cannot enumerate:
|
|
401
|
+
*
|
|
402
|
+
* - **file** → the origins in `readCredentialFile(credentialFilePath(env)).hubs`
|
|
403
|
+
* whose `human` slot parses as a well-formed `Credential` (`parseCredential`).
|
|
404
|
+
* An origin present only under an `agent:<name>` slot is NOT returned — the
|
|
405
|
+
* control plane authenticates as the human.
|
|
406
|
+
* - **keychain** → `null`. The `Keychain` interface (get/set/delete by
|
|
407
|
+
* `(service, account)`) has no list operation — macOS `security` cannot
|
|
408
|
+
* enumerate the accounts under a service without a keychain-wide dump this
|
|
409
|
+
* module deliberately does not perform. There is no way to know which origins
|
|
410
|
+
* have entries, so it returns `null` ("cannot enumerate") rather than a
|
|
411
|
+
* misleading empty list.
|
|
412
|
+
* - **external** → `null`, for the same reason: the command answers a single
|
|
413
|
+
* `(origin, slot)` query; it has no listing contract.
|
|
414
|
+
*
|
|
415
|
+
* `null` (cannot enumerate), `[]` (nothing stored), and a length>1 result are
|
|
416
|
+
* all distinct signals the caller turns into tailored exit-2 messages — this
|
|
417
|
+
* function reports the fact, it never decides the outcome. It never logs or
|
|
418
|
+
* echoes any credential; only the origin KEYS (never secrets) are returned.
|
|
419
|
+
*
|
|
420
|
+
* `env`/`keychain` are threaded exactly as `readStoredCredential` threads them,
|
|
421
|
+
* so a caller passing a fixture `env` stays hermetic.
|
|
422
|
+
*/
|
|
423
|
+
export declare function listStoredHubOrigins(env: Record<string, string | undefined>, keychain?: Keychain): string[] | null;
|
|
168
424
|
/**
|
|
169
425
|
* `.owenloop/hub.json` — written by `connect`. Safe to commit: contains no
|
|
170
426
|
* secrets, only the bound hub origin. Purely a binding — `push` diffs against
|
|
@@ -282,6 +538,107 @@ export interface WhoamiIdentity {
|
|
|
282
538
|
}
|
|
283
539
|
/** Narrow a `GET /api/whoami` 200 body to its typed shape. Throws on a malformed body. */
|
|
284
540
|
export declare function asWhoami(body: unknown): WhoamiIdentity;
|
|
541
|
+
/**
|
|
542
|
+
* Success shape of `POST /api/mint_agent_token` — the fields a caller is allowed
|
|
543
|
+
* to keep. Deliberately a WHITELIST: the real 200 body also carries a `text`
|
|
544
|
+
* field whose value CONTAINS the one-time `olp_` plaintext token ("Store this
|
|
545
|
+
* secret now …\n<olp_…>"), so a caller must never spread the raw body — it must
|
|
546
|
+
* build its result from these named fields only.
|
|
547
|
+
*
|
|
548
|
+
* `token` is the plaintext secret. It rides this typed shape exactly ONE hop:
|
|
549
|
+
* from `asMintAgentTokenOk`'s caller into `storeCredential`. It is never logged,
|
|
550
|
+
* printed, or embedded in an error — see `mintAgentCredential` (credentials.ts)
|
|
551
|
+
* and the identity model's §6 "rule of gates".
|
|
552
|
+
*/
|
|
553
|
+
export interface MintAgentTokenOk {
|
|
554
|
+
/** Token id — a non-secret revocation handle, safe to print. */
|
|
555
|
+
id: string;
|
|
556
|
+
/** The one-time `olp_` plaintext. SECRET — store-only, never echoed. */
|
|
557
|
+
token: string;
|
|
558
|
+
/** The minted agent's id — a non-secret handle, safe to print. */
|
|
559
|
+
agentId: string;
|
|
560
|
+
/** Resolved pool NAMES the token was granted on — non-secret. */
|
|
561
|
+
pools: string[];
|
|
562
|
+
}
|
|
563
|
+
/**
|
|
564
|
+
* Narrow a `POST /api/mint_agent_token` 200 body to its typed success shape,
|
|
565
|
+
* validating STRICTLY (mirrors `asWhoami`/`asCreateWorkflowOk`'s throw-on-
|
|
566
|
+
* malformed style): a 2xx is not enough — the identity fields must be present
|
|
567
|
+
* and well-typed, or the "success" is a malformed response and must be treated
|
|
568
|
+
* as a failure rather than silently coerced.
|
|
569
|
+
*
|
|
570
|
+
* **Token hygiene (load-bearing):** every error message names the offending
|
|
571
|
+
* FIELD only — it never echoes a field VALUE. A malformed body could still carry
|
|
572
|
+
* the `olp_` plaintext (in `text`, or in a mistyped `token`), so echoing values
|
|
573
|
+
* here would be the exact leak §6 forbids. `id`/`agentId` must be non-empty
|
|
574
|
+
* strings; `token` a non-empty string starting `olp_`; `pools` an array of
|
|
575
|
+
* strings (empty allowed defensively — the server always resolves at least one,
|
|
576
|
+
* but the client does not depend on that to stay leak-safe).
|
|
577
|
+
*/
|
|
578
|
+
export declare function asMintAgentTokenOk(body: unknown): MintAgentTokenOk;
|
|
579
|
+
/**
|
|
580
|
+
* One agent identity as `GET /api/agent_identities` reports it — the fields the
|
|
581
|
+
* setup converger and the doctor probe consult. The row is non-secret: it names
|
|
582
|
+
* agents and their pools, never a token.
|
|
583
|
+
*
|
|
584
|
+
* `lastContactAt` is identity-level (overwritten on EVERY authenticated contact,
|
|
585
|
+
* `olp_` or `mcpat_`). `lastUsedAt` is the edge-computed max over the identity's
|
|
586
|
+
* `agent`-kind tokens INCLUDING revoked ones — it deliberately survives a rekey.
|
|
587
|
+
* Both are epoch-ms or `null`; the succession UI shows `max(non-null of the two)`
|
|
588
|
+
* (see `lastActiveMs`). `disabled` gates whether the identity is a live
|
|
589
|
+
* succession candidate.
|
|
590
|
+
*/
|
|
591
|
+
export interface AgentIdentitySummary {
|
|
592
|
+
id: string;
|
|
593
|
+
name: string;
|
|
594
|
+
disabled: boolean;
|
|
595
|
+
pools: string[];
|
|
596
|
+
lastContactAt: number | null;
|
|
597
|
+
lastUsedAt: number | null;
|
|
598
|
+
}
|
|
599
|
+
/**
|
|
600
|
+
* Narrow `GET /api/agent_identities`'s 200 body (`{identities: [...]}`) to a
|
|
601
|
+
* typed array. Throws on a malformed body (missing `identities` array, or a row
|
|
602
|
+
* missing `id`/`name`). Non-secret shape — the rows carry no token — so errors
|
|
603
|
+
* may name indices/fields freely. `lastContactAt`/`lastUsedAt` tolerate `null`
|
|
604
|
+
* or absence (→ `null`) but reject a present non-number; `pools` defaults to an
|
|
605
|
+
* empty array when absent, rejects a present non-array-of-strings; `disabled`
|
|
606
|
+
* defaults to `false`.
|
|
607
|
+
*/
|
|
608
|
+
export declare function asAgentIdentities(body: unknown): AgentIdentitySummary[];
|
|
609
|
+
/**
|
|
610
|
+
* Success shape of `POST /api/rekey_agent_token` — the whitelist a caller may
|
|
611
|
+
* keep. Sibling of `MintAgentTokenOk`, and MUST stay a whitelist for the same
|
|
612
|
+
* reason: the real 200 body carries a `text` field whose value CONTAINS the new
|
|
613
|
+
* one-time `olp_` plaintext, so a caller must never spread the raw body.
|
|
614
|
+
*
|
|
615
|
+
* Rekey has NO `pools` field (re-keying preserves the agent's existing pool
|
|
616
|
+
* membership — the verb changes none), so `MintAgentTokenOk`/`asMintAgentTokenOk`
|
|
617
|
+
* cannot be reused. `scopes` and `revokedTokenIds` are non-secret handles.
|
|
618
|
+
*/
|
|
619
|
+
export interface RekeyAgentTokenOk {
|
|
620
|
+
/** New token id — a non-secret revocation handle, safe to print. */
|
|
621
|
+
id: string;
|
|
622
|
+
/** The new one-time `olp_` plaintext. SECRET — store-only, never echoed. */
|
|
623
|
+
token: string;
|
|
624
|
+
/** The rekeyed agent's id — a non-secret handle, safe to print. */
|
|
625
|
+
agentId: string;
|
|
626
|
+
/** Ids of the tokens this rekey revoked — non-secret. */
|
|
627
|
+
revokedTokenIds: string[];
|
|
628
|
+
/** The new token's scopes — non-secret. */
|
|
629
|
+
scopes: string[];
|
|
630
|
+
}
|
|
631
|
+
/**
|
|
632
|
+
* Narrow a `POST /api/rekey_agent_token` 200 body to its typed success shape.
|
|
633
|
+
* Mirrors `asMintAgentTokenOk`'s discipline exactly: STRICT validation of the
|
|
634
|
+
* identity fields, and every error names the offending FIELD only — never a
|
|
635
|
+
* field VALUE — because a malformed body could still carry the `olp_` plaintext
|
|
636
|
+
* (in `text`, or a mistyped `token`), and echoing values would be the exact leak
|
|
637
|
+
* §6 forbids. `id`/`agentId` non-empty strings; `token` a non-empty string
|
|
638
|
+
* starting `olp_`; `revokedTokenIds`/`scopes` arrays of strings, each tolerated
|
|
639
|
+
* absent (→ empty array) but rejected if present-and-malformed.
|
|
640
|
+
*/
|
|
641
|
+
export declare function asRekeyAgentTokenOk(body: unknown): RekeyAgentTokenOk;
|
|
285
642
|
/**
|
|
286
643
|
* Parse `GET /api/workflows`'s body into a `name -> WorkflowSummary` map for
|
|
287
644
|
* `computeServerDiff`. Throws a descriptive error (the caller wraps it in a
|