@theholocron/holocron-plugin-axiom 5.0.0-alpha.434 → 5.0.0-alpha.436
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/index.d.mts +3 -2
- package/dist/index.mjs +242 -14
- package/package.json +7 -7
package/dist/index.d.mts
CHANGED
|
@@ -2,7 +2,7 @@ import { AuthError, Logs, LogsDataset, PluginToken, ResolveTokenInput, VerifyTok
|
|
|
2
2
|
import { AxiomClient, AxiomClientOptions, AxiomDataset, AxiomUser, CreateAxiomDatasetInput, createAxiomClient } from "@theholocron/axiom-client";
|
|
3
3
|
/** Resolves the Axiom token from `--token`, `HOLOCRON_AXIOM_TOKEN`, `AXIOM_TOKEN` or the keyring, and throws an `AuthError` when none is set. */
|
|
4
4
|
export declare const resolveToken: import("@theholocron/cli").TokenResolver;
|
|
5
|
-
/** Every token this plugin takes, for `holocron doctor secrets --verify
|
|
5
|
+
/** Every token this plugin takes, for `holocron doctor secrets --verify`, with what each layer's token must and must not be able to do. */
|
|
6
6
|
export declare const tokens: PluginToken[];
|
|
7
7
|
/** Options for the Axiom `logs` capability. */
|
|
8
8
|
interface AxiomLogsOptions {
|
|
@@ -78,10 +78,11 @@ export interface PluginContext {
|
|
|
78
78
|
export declare function createContext(options: AxiomPluginOptions): PluginContext;
|
|
79
79
|
/** Builds the `logs` capability from a plugin context. */
|
|
80
80
|
export declare function logs(ctx: PluginContext): Logs;
|
|
81
|
-
/** Creates the Axiom plugin:
|
|
81
|
+
/** Creates the Axiom plugin: the `connection` and `token` probes and the `logs` capability. */
|
|
82
82
|
export declare function createPlugin(options: AxiomPluginOptions): {
|
|
83
83
|
name: string;
|
|
84
84
|
probes: {
|
|
85
|
+
token: import("@theholocron/cli").Probe;
|
|
85
86
|
connection: import("@theholocron/cli").Probe;
|
|
86
87
|
};
|
|
87
88
|
capabilities: {
|
package/dist/index.mjs
CHANGED
|
@@ -1,7 +1,36 @@
|
|
|
1
|
-
import { AuthError, ProviderApiError, connectionProbe, createResolveToken } from "@theholocron/cli";
|
|
1
|
+
import { AuthError, ProviderApiError, connectionProbe, createResolveToken, tokenExpectations } from "@theholocron/cli";
|
|
2
2
|
import { createEnvLookup, firstEnv } from "@theholocron/env-utils/lookup";
|
|
3
|
-
import { createAxiomClient } from "@theholocron/axiom-client";
|
|
4
3
|
import { errorMessage } from "@theholocron/misc-utils";
|
|
4
|
+
import { createAxiomClient } from "@theholocron/axiom-client";
|
|
5
|
+
// src/probes/token/expectations.ts
|
|
6
|
+
/**
|
|
7
|
+
* Datasets the logging setup retired (ADR-0019): one dataset per service now, split by the `env` field. A token that
|
|
8
|
+
* still reaches one is shown, so a layer pointed at the wrong dataset (`holocron-local` on a laptop) is visible.
|
|
9
|
+
*/
|
|
10
|
+
const RETIRED_DATASETS = [
|
|
11
|
+
"holocron-local",
|
|
12
|
+
"holocron-ci",
|
|
13
|
+
"holocron-global"
|
|
14
|
+
];
|
|
15
|
+
const RULES = {
|
|
16
|
+
read: "required",
|
|
17
|
+
ingest: "required",
|
|
18
|
+
query: "absent"
|
|
19
|
+
};
|
|
20
|
+
/**
|
|
21
|
+
* What each layer's Axiom token is meant to carry, the same as "What each Axiom token needs" in
|
|
22
|
+
* `docs/src/content/docs/tokens.mdx`. Every layer ships to the same dataset and only passes the environment as a field,
|
|
23
|
+
* so it is one token with the same permissions everywhere: it ingests (the logger) and reads the dataset (`doctor
|
|
24
|
+
* logs`), and does not query, because nothing in the repo reads logs back, so a leaked token cannot either. The probe
|
|
25
|
+
* still tries query, so a token that can is flagged. This is the plugin's `tokens` declaration, read through
|
|
26
|
+
* `tokenExpectations()`; change it and that table together.
|
|
27
|
+
*/
|
|
28
|
+
const EXPECTED = { permissions: {
|
|
29
|
+
local: RULES,
|
|
30
|
+
dev: RULES,
|
|
31
|
+
ci: RULES,
|
|
32
|
+
prod: RULES
|
|
33
|
+
} };
|
|
5
34
|
// src/auth.ts
|
|
6
35
|
/** Resolves the Axiom token from `--token`, `HOLOCRON_AXIOM_TOKEN`, `AXIOM_TOKEN` or the keyring, and throws an `AuthError` when none is set. */
|
|
7
36
|
const resolveToken = createResolveToken({
|
|
@@ -10,8 +39,11 @@ const resolveToken = createResolveToken({
|
|
|
10
39
|
keyringService: "axiom",
|
|
11
40
|
errorMessage: "no Axiom token found. Pass --token <TOKEN>, set HOLOCRON_AXIOM_TOKEN / AXIOM_TOKEN, or run: holocron new token axiom <TOKEN>"
|
|
12
41
|
});
|
|
13
|
-
/** Every token this plugin takes, for `holocron doctor secrets --verify
|
|
14
|
-
const tokens = [
|
|
42
|
+
/** Every token this plugin takes, for `holocron doctor secrets --verify`, with what each layer's token must and must not be able to do. */
|
|
43
|
+
const tokens = [{
|
|
44
|
+
...resolveToken.token,
|
|
45
|
+
expect: EXPECTED
|
|
46
|
+
}];
|
|
15
47
|
// src/capabilities/logs.ts
|
|
16
48
|
/** A dataset that does not exist: asking for it tells a token Axiom accepts (404) from one it refuses (401). */
|
|
17
49
|
const PROBE_DATASET$1 = "holocron-token-check";
|
|
@@ -88,6 +120,195 @@ var AxiomLogs = class {
|
|
|
88
120
|
return { alreadyExists: false };
|
|
89
121
|
}
|
|
90
122
|
};
|
|
123
|
+
// src/probes/token/parse-token-args.ts
|
|
124
|
+
/** Reads the words after the probe name: `--layer <word>`, `--token-name <VAR>` and any number of dataset names. */
|
|
125
|
+
function parseTokenArgs(args) {
|
|
126
|
+
const datasets = [];
|
|
127
|
+
let layer;
|
|
128
|
+
let tokenName;
|
|
129
|
+
for (let i = 0; i < args.length; i++) {
|
|
130
|
+
const arg = args[i];
|
|
131
|
+
if (arg === "--layer") layer = args[++i];
|
|
132
|
+
else if (arg.startsWith("--layer=")) layer = arg.slice(8);
|
|
133
|
+
else if (arg === "--token-name") tokenName = args[++i];
|
|
134
|
+
else if (arg.startsWith("--token-name=")) tokenName = arg.slice(13);
|
|
135
|
+
else if (!arg.startsWith("--")) datasets.push(arg);
|
|
136
|
+
}
|
|
137
|
+
return {
|
|
138
|
+
...layer ? { layer } : {},
|
|
139
|
+
...tokenName ? { tokenName } : {},
|
|
140
|
+
datasets
|
|
141
|
+
};
|
|
142
|
+
}
|
|
143
|
+
// src/probes/token/token.ts
|
|
144
|
+
/** How many names to show before "(+N more)". */
|
|
145
|
+
const SHOWN = 8;
|
|
146
|
+
/** The time a query looks back over: a minute is enough, the query reads nothing the probe prints. */
|
|
147
|
+
const QUERY_WINDOW_MS = 6e4;
|
|
148
|
+
/** `a, b, c (+2 more)`. */
|
|
149
|
+
function summarise(names) {
|
|
150
|
+
return names.length <= SHOWN ? names.join(", ") : `${names.slice(0, SHOWN).join(", ")} (+${names.length - SHOWN} more)`;
|
|
151
|
+
}
|
|
152
|
+
/**
|
|
153
|
+
* Runs one request and says what came back. Axiom answers a token without the permission with a 401 or 403, and a
|
|
154
|
+
* dataset the token cannot see (or that does not exist) with a 404; all three are `none`. A request that fails for
|
|
155
|
+
* another reason (the network, a 5xx) is an `error`.
|
|
156
|
+
*/
|
|
157
|
+
async function reach(request) {
|
|
158
|
+
try {
|
|
159
|
+
await request();
|
|
160
|
+
return { kind: "has" };
|
|
161
|
+
} catch (err) {
|
|
162
|
+
if (err instanceof ProviderApiError && (err.status === 401 || err.status === 403)) return {
|
|
163
|
+
kind: "none",
|
|
164
|
+
detail: `no access (${err.status})`
|
|
165
|
+
};
|
|
166
|
+
if (err instanceof ProviderApiError && err.status === 404) return {
|
|
167
|
+
kind: "none",
|
|
168
|
+
detail: "no such dataset, or the token cannot see it (404)"
|
|
169
|
+
};
|
|
170
|
+
return {
|
|
171
|
+
kind: "error",
|
|
172
|
+
detail: errorMessage(err)
|
|
173
|
+
};
|
|
174
|
+
}
|
|
175
|
+
}
|
|
176
|
+
/** The APL query that reads one row of a dataset; the name is quoted the way APL quotes an identifier. */
|
|
177
|
+
function queryFor(dataset) {
|
|
178
|
+
return `['${dataset.replaceAll("\\", "\\\\").replaceAll("'", "\\'")}'] | take 1`;
|
|
179
|
+
}
|
|
180
|
+
/**
|
|
181
|
+
* One row for what was tried. With no rule it only describes (`ok` for access, `info` for none). Under a layer's rule it
|
|
182
|
+
* judges: a required permission the token lacks fails, and one the layer must not have fails when the token has it; a
|
|
183
|
+
* permission that is rightly absent is a bare `ok`.
|
|
184
|
+
*/
|
|
185
|
+
function rowFor({ label, outcome }, rule) {
|
|
186
|
+
const detail = outcome.detail === void 0 ? {} : { detail: outcome.detail };
|
|
187
|
+
if (outcome.kind === "error") return {
|
|
188
|
+
status: "fail",
|
|
189
|
+
label,
|
|
190
|
+
...detail
|
|
191
|
+
};
|
|
192
|
+
const has = outcome.kind === "has";
|
|
193
|
+
if (rule === "required") return {
|
|
194
|
+
status: has ? "ok" : "fail",
|
|
195
|
+
label,
|
|
196
|
+
...detail
|
|
197
|
+
};
|
|
198
|
+
if (rule === "absent") return has ? {
|
|
199
|
+
status: "fail",
|
|
200
|
+
label,
|
|
201
|
+
...detail
|
|
202
|
+
} : {
|
|
203
|
+
status: "ok",
|
|
204
|
+
label
|
|
205
|
+
};
|
|
206
|
+
return {
|
|
207
|
+
status: has ? "ok" : "info",
|
|
208
|
+
label,
|
|
209
|
+
...detail
|
|
210
|
+
};
|
|
211
|
+
}
|
|
212
|
+
/**
|
|
213
|
+
* The `token` probe: tries each permission Holocron uses with the Axiom token on a dataset (reading it, ingesting and
|
|
214
|
+
* querying) and reports which ones the token has, then lists the datasets the token can see, so a token that reaches a
|
|
215
|
+
* retired dataset (`holocron-local`) is visible. Ingesting sends an empty list, which writes no event, and the query
|
|
216
|
+
* reads one row it never prints, so the probe changes nothing. The token is the one the plugin resolves, so
|
|
217
|
+
* `--token axiom=<token>` or `--environment <layer>` checks another one; the dataset is the plugin's own, or the names
|
|
218
|
+
* after the probe name.
|
|
219
|
+
*
|
|
220
|
+
* A token with no layer is only described. When the CLI passes `--layer` (because `--environment` named `ci`, `dev` or
|
|
221
|
+
* `local`), the results are judged against what that layer's token is meant to carry (the plugin's `tokens` declaration,
|
|
222
|
+
* read with `tokenExpectations()`) and shown in two groups, what it should have and what it should not, where a
|
|
223
|
+
* missing or extra permission fails.
|
|
224
|
+
*/
|
|
225
|
+
function tokenProbe(ctx) {
|
|
226
|
+
return {
|
|
227
|
+
summary: "Try each Axiom permission Holocron uses (read, ingest, query) on a dataset with a token, and list the datasets the token can see; for a ci or dev Environment, check it against what that layer should carry. Read-only: ingest sends no event.",
|
|
228
|
+
writes: false,
|
|
229
|
+
acceptsToken: true,
|
|
230
|
+
async run(probe) {
|
|
231
|
+
const token = ctx.token();
|
|
232
|
+
probe.secret(token);
|
|
233
|
+
const client = ctx.client();
|
|
234
|
+
const { layer, tokenName, datasets: named } = parseTokenArgs(probe.args ?? []);
|
|
235
|
+
const rules = layer ? tokenExpectations(tokens, {
|
|
236
|
+
layer,
|
|
237
|
+
...tokenName ? { envName: tokenName } : {}
|
|
238
|
+
})[0]?.rules : void 0;
|
|
239
|
+
if (layer && !rules) probe.say({
|
|
240
|
+
status: "info",
|
|
241
|
+
label: layer,
|
|
242
|
+
detail: "no expectations are declared for it, so the token is only described"
|
|
243
|
+
});
|
|
244
|
+
const targets = named.length > 0 ? named : ctx.options.dataset ? [ctx.options.dataset] : [];
|
|
245
|
+
if (targets.length === 0) probe.say({
|
|
246
|
+
status: rules ? "fail" : "info",
|
|
247
|
+
label: "dataset",
|
|
248
|
+
detail: "none given: name one after the probe, or set HOLOCRON_AXIOM_DATASET or the plugin's dataset option"
|
|
249
|
+
});
|
|
250
|
+
const tried = [];
|
|
251
|
+
for (const dataset of targets) {
|
|
252
|
+
const now = Date.now();
|
|
253
|
+
tried.push({
|
|
254
|
+
label: `Read (${dataset})`,
|
|
255
|
+
permission: "read",
|
|
256
|
+
outcome: await reach(() => client.datasets.get(dataset))
|
|
257
|
+
}, {
|
|
258
|
+
label: `Ingest (${dataset})`,
|
|
259
|
+
permission: "ingest",
|
|
260
|
+
outcome: await reach(() => client.datasets.ingest(dataset, []))
|
|
261
|
+
}, {
|
|
262
|
+
label: `Query (${dataset})`,
|
|
263
|
+
permission: "query",
|
|
264
|
+
outcome: await reach(() => client.datasets.query({
|
|
265
|
+
apl: queryFor(dataset),
|
|
266
|
+
startTime: (/* @__PURE__ */ new Date(now - QUERY_WINDOW_MS)).toISOString(),
|
|
267
|
+
endTime: new Date(now).toISOString()
|
|
268
|
+
}))
|
|
269
|
+
});
|
|
270
|
+
}
|
|
271
|
+
if (!rules) for (const t of tried) probe.say(rowFor(t, void 0));
|
|
272
|
+
else for (const [heading, rule] of [["Should have", "required"], ["Should not have", "absent"]]) {
|
|
273
|
+
const inGroup = tried.filter((t) => rules[t.permission] === rule);
|
|
274
|
+
if (inGroup.length === 0) continue;
|
|
275
|
+
probe.say({
|
|
276
|
+
status: "heading",
|
|
277
|
+
label: heading
|
|
278
|
+
});
|
|
279
|
+
for (const t of inGroup) probe.say(rowFor(t, rule));
|
|
280
|
+
}
|
|
281
|
+
probe.say({
|
|
282
|
+
status: "heading",
|
|
283
|
+
label: "Datasets this token can see"
|
|
284
|
+
});
|
|
285
|
+
try {
|
|
286
|
+
const names = (await client.datasets.list()).map((d) => d.name);
|
|
287
|
+
probe.say(names.length === 0 ? {
|
|
288
|
+
status: "info",
|
|
289
|
+
label: "datasets",
|
|
290
|
+
detail: "none visible"
|
|
291
|
+
} : {
|
|
292
|
+
status: "info",
|
|
293
|
+
label: "datasets",
|
|
294
|
+
detail: `${names.length}: ${summarise(names)}`
|
|
295
|
+
});
|
|
296
|
+
for (const name of names.filter((n) => RETIRED_DATASETS.includes(n))) probe.say({
|
|
297
|
+
status: "info",
|
|
298
|
+
label: name,
|
|
299
|
+
detail: "retired (one dataset per service now, ADR-0019): the token still reaches it"
|
|
300
|
+
});
|
|
301
|
+
} catch (err) {
|
|
302
|
+
const denied = err instanceof ProviderApiError && (err.status === 401 || err.status === 403);
|
|
303
|
+
probe.say({
|
|
304
|
+
status: denied ? "info" : "fail",
|
|
305
|
+
label: "datasets",
|
|
306
|
+
detail: denied ? `the token cannot list datasets (${err.status})` : errorMessage(err)
|
|
307
|
+
});
|
|
308
|
+
}
|
|
309
|
+
}
|
|
310
|
+
};
|
|
311
|
+
}
|
|
91
312
|
// src/verify-token.ts
|
|
92
313
|
/**
|
|
93
314
|
* `verifyToken` — plugin-level export used by `holocron new token axiom`
|
|
@@ -164,21 +385,28 @@ function createContext(options) {
|
|
|
164
385
|
function logs(ctx) {
|
|
165
386
|
return new AxiomLogs(ctx.client, { dataset: ctx.options.dataset });
|
|
166
387
|
}
|
|
167
|
-
/** Creates the Axiom plugin:
|
|
388
|
+
/** Creates the Axiom plugin: the `connection` and `token` probes and the `logs` capability. */
|
|
168
389
|
function createPlugin(options) {
|
|
169
390
|
const ctx = createContext(options);
|
|
170
391
|
return {
|
|
171
392
|
name: "@theholocron/holocron-plugin-axiom",
|
|
172
|
-
probes: {
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
393
|
+
probes: {
|
|
394
|
+
token: tokenProbe({
|
|
395
|
+
options: ctx.options,
|
|
396
|
+
client: ctx.client,
|
|
397
|
+
token: () => resolveToken(options)
|
|
398
|
+
}),
|
|
399
|
+
connection: connectionProbe({
|
|
400
|
+
provider: "Axiom",
|
|
401
|
+
url: options.baseUrl ?? "https://api.axiom.co",
|
|
402
|
+
fetch: options.fetch,
|
|
403
|
+
token: () => resolveToken(options),
|
|
404
|
+
verify: (token) => verifyToken(token, {
|
|
405
|
+
baseUrl: options.baseUrl,
|
|
406
|
+
fetch: options.fetch
|
|
407
|
+
})
|
|
180
408
|
})
|
|
181
|
-
}
|
|
409
|
+
},
|
|
182
410
|
capabilities: { logs: () => logs(ctx) }
|
|
183
411
|
};
|
|
184
412
|
}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@theholocron/holocron-plugin-axiom",
|
|
3
|
-
"version": "5.0.0-alpha.
|
|
3
|
+
"version": "5.0.0-alpha.436",
|
|
4
4
|
"description": "Holocron plugin for Axiom. Implements the logs capability against Axiom's REST API — dataset provisioning and connectivity checks, plus verifyToken + AUTH_HINT for `holocron auth`.",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"axiom",
|
|
@@ -43,19 +43,19 @@
|
|
|
43
43
|
"tsx": "4.23.15",
|
|
44
44
|
"typescript": "^5.9.3",
|
|
45
45
|
"vitest": "^5.1.0",
|
|
46
|
-
"@theholocron/axiom-client": "^1.58.0-alpha.
|
|
46
|
+
"@theholocron/axiom-client": "^1.58.0-alpha.32",
|
|
47
|
+
"@theholocron/cli": "5.0.0-alpha.436",
|
|
47
48
|
"@theholocron/eslint-config": "^8.9.0-alpha.17",
|
|
48
|
-
"@theholocron/
|
|
49
|
+
"@theholocron/misc-utils": "^1.17.0-alpha.4",
|
|
50
|
+
"@theholocron/http-client": "^1.58.0-alpha.32",
|
|
49
51
|
"@theholocron/tsconfig": "^8.9.0-alpha.17",
|
|
50
52
|
"@theholocron/tsdown-config": "^8.9.0-alpha.17",
|
|
51
|
-
"@theholocron/vitest-config": "^8.9.0-alpha.17"
|
|
52
|
-
"@theholocron/misc-utils": "^1.17.0-alpha.4",
|
|
53
|
-
"@theholocron/cli": "5.0.0-alpha.434"
|
|
53
|
+
"@theholocron/vitest-config": "^8.9.0-alpha.17"
|
|
54
54
|
},
|
|
55
55
|
"peerDependencies": {
|
|
56
56
|
"@theholocron/axiom-client": "^1.43.1",
|
|
57
57
|
"@theholocron/misc-utils": "^1.16.0",
|
|
58
|
-
"@theholocron/cli": "5.0.0-alpha.
|
|
58
|
+
"@theholocron/cli": "5.0.0-alpha.436"
|
|
59
59
|
},
|
|
60
60
|
"engines": {
|
|
61
61
|
"node": ">=22"
|