@theholocron/holocron-plugin-axiom 5.0.0-alpha.45 → 5.0.0-alpha.451

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/README.md CHANGED
@@ -4,7 +4,7 @@
4
4
 
5
5
  Axiom plugin for [Holocron](../cli). Implements the `logs` capability
6
6
  against [Axiom's REST API](https://axiom.co/docs/restapi/introduction),
7
- plus exports `verifyToken` + `AUTH_HINT` for use by `holocron auth`.
7
+ plus exports `verifyToken` + `AUTH_HINT` for use by `holocron check token`.
8
8
 
9
9
  > This plugin does **not** ship log lines. `@theholocron/observability/logger`'s
10
10
  > Axiom transport reads `HOLOCRON_AXIOM_TOKEN` / `HOLOCRON_AXIOM_DATASET`
@@ -26,14 +26,14 @@ Token resolution order:
26
26
  2. `HOLOCRON_AXIOM_TOKEN` env var (preferred — explicit intent)
27
27
  3. `AXIOM_TOKEN` env var (Axiom-native, works in CI)
28
28
  4. Keyring `axiom.<org>` — tried first when an org is active via `--org`, `HOLOCRON_ORG`, or `org` in `holocron.config.ts`
29
- 5. Keyring `axiom` — unnamespaced fallback; set via `holocron auth set axiom <token>`
29
+ 5. Keyring `axiom` — unnamespaced fallback; set via `holocron new token axiom <token>`
30
30
  6. `AuthError` naming both env vars + the auth hint
31
31
 
32
32
  Generate an API token at **app.axiom.co/settings/api-tokens** with
33
33
  permission to read and create datasets.
34
34
 
35
35
  ```bash
36
- holocron auth set axiom.theholocron <TOKEN>
36
+ holocron new token axiom.theholocron <TOKEN>
37
37
  ```
38
38
 
39
39
  **CI**: the keyring is unavailable in headless containers — expose the
@@ -49,27 +49,28 @@ token as `HOLOCRON_AXIOM_TOKEN` (or `AXIOM_TOKEN`) in the workflow env.
49
49
  }
50
50
  ```
51
51
 
52
- No options are required. `holocron setup` provisions the `holocron-ci`
53
- and `holocron-local` datasets; `holocron doctor` checks the dataset
54
- named by `HOLOCRON_AXIOM_DATASET` / `AXIOM_DATASET`. An explicit
55
- `logs: ["axiom", { "dataset": "holocron-ci" }]` overrides the env var
56
- for `doctor`.
52
+ No options are required. `holocron setup` provisions the CLI's dataset (`holocron`)
53
+ named by `HOLOCRON_AXIOM_DATASET` / `AXIOM_DATASET`; every environment of the CLI ships to
54
+ it and is told apart by the `env` field on each line. `holocron doctor` checks
55
+ the same dataset. An explicit `logs: ["axiom", { "dataset": "my-dataset" }]`
56
+ overrides the env var for `doctor`.
57
57
 
58
- `HOLOCRON_AXIOM_DATASET` is **not a secret** — set it in your shell
59
- profile locally (`holocron-local`) or as an org CI secret
60
- (`holocron-ci`). Leave it unset locally to skip Axiom entirely.
58
+ The dataset name is **not a secret** — it is the org variable `HOLOCRON_AXIOM_DATASET`,
59
+ synced from 1Password. Leave the token unset locally to skip Axiom entirely.
61
60
 
62
61
  ## What's implemented
63
62
 
64
- | Method | Behavior |
65
- | --------------- | ------------------------------------------------------------------------------------------------ |
66
- | `describe` | Returns `{ provider: "axiom", envKeys: ["HOLOCRON_AXIOM_TOKEN", "HOLOCRON_AXIOM_DATASET"] }`. |
67
- | `whoami` | `GET /v2/datasets/{dataset}` — verifies the token and the configured dataset's reachability. |
68
- | `ensureDataset` | `GET /v2/datasets/{name}`; on 404, `POST /v2/datasets`. Returns `{ alreadyExists }`. Idempotent. |
63
+ | Method | Behavior |
64
+ | --------------- | ------------------------------------------------------------------------------------------------------------------------- |
65
+ | `describe` | Returns `{ provider: "axiom", envKeys: ["HOLOCRON_AXIOM_TOKEN", "HOLOCRON_AXIOM_DATASET"] }`. |
66
+ | `whoami` | `GET /v2/datasets/{dataset}` — verifies the token and the configured dataset's reachability. |
67
+ | `ensureDataset` | `GET /v2/datasets/{name}`; on 404, `POST /v2/datasets`. Returns `{ alreadyExists }`. Idempotent. |
68
+ | `readDataset` | `GET /v2/datasets/{name}`; a 404 is `{ exists: false }` and nothing is created. Returns `retentionDays` when Axiom does. |
69
+ | `checkToken` | `GET` of a dataset that cannot exist: a 404 means the token is accepted, a 401 means it is refused, anything else throws. |
69
70
 
70
71
  Plugin-level exports (not capability methods, per the auth-bootstrap convention):
71
72
 
72
- | Export | Purpose |
73
- | ------------- | ------------------------------------------------------------------------------------------- |
74
- | `verifyToken` | `GET /v2/user` — returns `{ ok: true, subject: "user @ …" }` or `{ ok: false, message }`. |
75
- | `AUTH_HINT` | One-line hint printed by `holocron auth set` when no token is supplied or the token is bad. |
73
+ | Export | Purpose |
74
+ | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
75
+ | `verifyToken` | `GET /v2/user` — returns `{ ok: true, subject: "user @ …" }` or `{ ok: false, message }`. An API token cannot read the user (403), so it then reads the `dataset` option (`HOLOCRON_AXIOM_DATASET`), the dataset the token is scoped to: a 200 or a 404 is `API token`, a 403 or 401 there is rejected. |
76
+ | `AUTH_HINT` | One-line hint printed by `holocron new token` when no token is supplied or the token is bad. |
package/dist/index.d.mts CHANGED
@@ -1,39 +1,17 @@
1
- import { AuthError, Logs, ResolveTokenInput } from "@theholocron/cli";
2
- //#region src/auth.d.ts
3
- declare const resolveToken: (input?: ResolveTokenInput) => string;
4
- //#endregion
5
- //#region src/rest.d.ts
6
- /** Axiom dataset — the subset of fields Holocron reads. */
7
- interface AxiomDataset {
8
- id: string;
9
- name: string;
10
- description?: string;
11
- }
12
- /** Axiom user — the subset returned by `GET /v2/user`. */
13
- interface AxiomUser {
14
- id: string;
15
- name?: string;
16
- email?: string;
17
- emails?: string[];
18
- }
19
- interface AxiomClientOptions {
20
- token: string;
21
- /** Override the API base URL (default `https://api.axiom.co`). */
22
- baseUrl?: string;
23
- /** Override `fetch` for tests. */
24
- fetch?: typeof fetch;
25
- }
26
- interface AxiomRestClient {
27
- getDataset(name: string): Promise<AxiomDataset>;
28
- createDataset(input: {
29
- name: string;
30
- description?: string;
31
- }): Promise<AxiomDataset>;
32
- getCurrentUser(): Promise<AxiomUser>;
33
- }
34
- declare function createAxiomClient(opts: AxiomClientOptions): AxiomRestClient;
35
- //#endregion
36
- //#region src/capabilities/logs.d.ts
1
+ /**
2
+ * `@theholocron/holocron-plugin-axiom` — entrypoint.
3
+ *
4
+ * Implements the `logs` capability against Axiom's REST API. Also
5
+ * exports `verifyToken` + `AUTH_HINT` for `holocron check token`. See README
6
+ * for auth + config docs.
7
+ */
8
+ import { AuthError, Logs, LogsDataset, PluginToken, ResolveTokenInput, VerifyTokenFailure, VerifyTokenResult, VerifyTokenResult as VerifyTokenResult$1, VerifyTokenSuccess } from "@theholocron/cli";
9
+ import { AxiomClient, AxiomClientOptions, AxiomDataset, AxiomUser, CreateAxiomDatasetInput, createAxiomClient } from "@theholocron/axiom-client";
10
+ /** Resolves the Axiom token from `--token`, `HOLOCRON_AXIOM_TOKEN`, `AXIOM_TOKEN` or the keyring, and throws an `AuthError` when none is set. */
11
+ export declare const resolveToken: import("@theholocron/cli").TokenResolver;
12
+ /** Every token this plugin takes, for `holocron doctor secrets --verify`, with what each layer's token must and must not be able to do. */
13
+ export declare const tokens: PluginToken[];
14
+ /** Options for the Axiom `logs` capability. */
37
15
  interface AxiomLogsOptions {
38
16
  /**
39
17
  * Target dataset, resolved from `HOLOCRON_AXIOM_DATASET` /
@@ -42,16 +20,19 @@ interface AxiomLogsOptions {
42
20
  */
43
21
  dataset?: string;
44
22
  }
45
- declare class AxiomLogs implements Logs {
23
+ /** The `logs` capability for Axiom: checks a dataset is reachable and creates datasets that are missing. */
24
+ export declare class AxiomLogs implements Logs {
46
25
  private readonly client;
47
26
  private readonly opts;
27
+ /** The capability key, always `logs`. */
48
28
  readonly key: "logs";
29
+ /** The provider name, `axiom`. */
49
30
  readonly providerName = "axiom";
50
31
  /**
51
32
  * `client` is a thunk — the token is resolved on first call, so
52
33
  * `describe()` (which needs no auth) works without one.
53
34
  */
54
- constructor(client: () => AxiomRestClient, opts: AxiomLogsOptions);
35
+ constructor(client: () => AxiomClient, opts: AxiomLogsOptions);
55
36
  describe(): Promise<{
56
37
  provider: string;
57
38
  envKeys: string[];
@@ -60,43 +41,41 @@ declare class AxiomLogs implements Logs {
60
41
  ok: boolean;
61
42
  dataset: string;
62
43
  }>;
44
+ readDataset(name: string): Promise<LogsDataset>;
45
+ checkToken(): Promise<{
46
+ ok: boolean;
47
+ reason?: string;
48
+ }>;
63
49
  ensureDataset(name: string): Promise<{
64
50
  alreadyExists: boolean;
65
51
  }>;
66
52
  }
67
- //#endregion
68
- //#region src/verify-token.d.ts
69
- /**
70
- * `verifyToken` — plugin-level export used by `holocron auth set axiom`
71
- * + `holocron auth check`. Hits `GET /v2/user` and translates the
72
- * response into the normalized `VerifyTokenResult` shape.
73
- *
74
- * Kept as a standalone function (not a capability method) so the auth
75
- * command can call it without initializing the full plugin.
76
- */
77
- interface VerifyTokenSuccess {
78
- ok: true;
79
- subject: string;
80
- }
81
- interface VerifyTokenFailure {
82
- ok: false;
83
- message: string;
84
- }
85
- type VerifyTokenResult = VerifyTokenSuccess | VerifyTokenFailure;
86
53
  interface VerifyTokenOptions {
87
54
  baseUrl?: string;
88
55
  fetch?: typeof fetch;
56
+ /**
57
+ * The dataset the token is meant to read (`HOLOCRON_AXIOM_DATASET`). An API token that cannot read the user is asked
58
+ * about this one, because a token scoped per dataset is refused (403) for any other name.
59
+ */
60
+ dataset?: string;
89
61
  }
90
- declare function verifyToken(token: string, opts?: VerifyTokenOptions): Promise<VerifyTokenResult>;
91
- //#endregion
92
- //#region src/index.d.ts
93
- interface AxiomPluginOptions extends ResolveTokenInput, AxiomLogsOptions {
62
+ /**
63
+ * Checks an Axiom token by fetching the current user; the success subject is `user @` followed by the email, name or id,
64
+ * the failure carries the error message. An API token cannot read the user (403), so then it asks for a dataset: the one
65
+ * the token is meant to read (`dataset`), else one that does not exist. A 200 or a 404 means the token is accepted and
66
+ * may read datasets, and the subject says `API token`; a 403 on the dataset it is meant to read still fails.
67
+ */
68
+ export declare function verifyToken(token: string, opts?: VerifyTokenOptions): Promise<VerifyTokenResult$1>;
69
+ /** Options for the Axiom plugin: token resolution, the target dataset and test overrides. */
70
+ export interface AxiomPluginOptions extends ResolveTokenInput, AxiomLogsOptions {
94
71
  /** Override base URL for tests. */
95
72
  baseUrl?: string;
96
73
  /** Override `fetch` for tests. */
97
74
  fetch?: typeof fetch;
98
75
  }
99
- interface PluginContext {
76
+ /** What the plugin's capabilities share: the resolved options and a lazily built client. */
77
+ export interface PluginContext {
78
+ /** The options, with `dataset` resolved from config, `HOLOCRON_AXIOM_DATASET` or `AXIOM_DATASET` (in that order). */
100
79
  options: AxiomPluginOptions & {
101
80
  dataset?: string;
102
81
  };
@@ -106,20 +85,26 @@ interface PluginContext {
106
85
  * no auth (`describe`) works without a token, and the loader never
107
86
  * aborts on a plugin whose token happens to be absent.
108
87
  */
109
- client: () => AxiomRestClient;
88
+ client: () => AxiomClient;
110
89
  }
111
- declare function createContext(options: AxiomPluginOptions): PluginContext;
112
- declare function logs(ctx: PluginContext): Logs;
113
- declare function createPlugin(options: AxiomPluginOptions): {
90
+ /** Creates the shared context for the given options; no token is resolved until `client()` is first called. */
91
+ export declare function createContext(options: AxiomPluginOptions): PluginContext;
92
+ /** Builds the `logs` capability from a plugin context. */
93
+ export declare function logs(ctx: PluginContext): Logs;
94
+ /** Creates the Axiom plugin: the `connection` and `token` probes and the `logs` capability. */
95
+ export declare function createPlugin(options: AxiomPluginOptions): {
114
96
  name: string;
97
+ probes: {
98
+ token: import("@theholocron/cli").Probe;
99
+ connection: import("@theholocron/cli").Probe;
100
+ };
115
101
  capabilities: {
116
102
  logs: () => Logs;
117
103
  };
118
104
  };
119
105
  /**
120
- * One-line hint shown by `holocron auth set axiom` when no token is
106
+ * One-line hint shown by `holocron new token axiom` when no token is
121
107
  * supplied or when the supplied token is rejected.
122
108
  */
123
- declare const AUTH_HINT: string;
124
- //#endregion
125
- export { AUTH_HINT, AuthError, type AxiomClientOptions, type AxiomDataset, AxiomLogs, type AxiomLogsOptions, AxiomPluginOptions, type AxiomRestClient, type AxiomUser, PluginContext, type ResolveTokenInput, type VerifyTokenFailure, type VerifyTokenResult, type VerifyTokenSuccess, createAxiomClient, createContext, createPlugin, logs, resolveToken, verifyToken };
109
+ export declare const AUTH_HINT: string;
110
+ export { AuthError, type AxiomClient, type AxiomClientOptions, type AxiomDataset, type AxiomLogsOptions, type AxiomUser, type CreateAxiomDatasetInput, type ResolveTokenInput, type VerifyTokenFailure, type VerifyTokenResult, type VerifyTokenSuccess, createAxiomClient };
package/dist/index.mjs CHANGED
@@ -1,17 +1,115 @@
1
- import { AuthError, ProviderApiError, createResolveToken, createRestClient } from "@theholocron/cli";
2
- //#region src/auth.ts
1
+ import { AuthError, ProviderApiError, connectionProbe, createResolveToken, resolveValue, tokenExpectations } from "@theholocron/cli";
2
+ import { PREFIX, createEnvLookup, firstEnv } from "@theholocron/env-utils/lookup";
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
+ } };
34
+ // src/verify-token.ts
35
+ /**
36
+ * `verifyToken` — plugin-level export used by `holocron new token axiom`
37
+ * + `holocron check token`. Hits `GET /v2/user` and translates the
38
+ * response into the normalized `VerifyTokenResult` shape.
39
+ *
40
+ * Kept as a standalone function (not a capability method) so the auth
41
+ * command can call it without initializing the full plugin.
42
+ */
43
+ /** Asked about when no dataset is known: one that does not exist, so a token that may read datasets answers 404. */
44
+ const PROBE_DATASET$1 = "holocron-token-check";
45
+ /**
46
+ * Checks an Axiom token by fetching the current user; the success subject is `user @` followed by the email, name or id,
47
+ * the failure carries the error message. An API token cannot read the user (403), so then it asks for a dataset: the one
48
+ * the token is meant to read (`dataset`), else one that does not exist. A 200 or a 404 means the token is accepted and
49
+ * may read datasets, and the subject says `API token`; a 403 on the dataset it is meant to read still fails.
50
+ */
51
+ async function verifyToken(token, opts = {}) {
52
+ const client = createAxiomClient({
53
+ token,
54
+ baseUrl: opts.baseUrl,
55
+ fetch: opts.fetch
56
+ });
57
+ try {
58
+ const me = await client.user.me();
59
+ return {
60
+ ok: true,
61
+ subject: `user @ ${me.email ?? me.emails?.[0] ?? me.name ?? me.id ?? "unknown"}`
62
+ };
63
+ } catch (err) {
64
+ if (err instanceof ProviderApiError && err.status === 403) return verifyApiToken(client, opts.dataset);
65
+ return {
66
+ ok: false,
67
+ message: errorMessage(err)
68
+ };
69
+ }
70
+ }
71
+ async function verifyApiToken(client, dataset) {
72
+ try {
73
+ await client.datasets.get(dataset ?? PROBE_DATASET$1);
74
+ return {
75
+ ok: true,
76
+ subject: "API token"
77
+ };
78
+ } catch (err) {
79
+ if (err instanceof ProviderApiError && err.status === 404) return {
80
+ ok: true,
81
+ subject: "API token"
82
+ };
83
+ return {
84
+ ok: false,
85
+ message: errorMessage(err)
86
+ };
87
+ }
88
+ }
89
+ // src/auth.ts
90
+ /** Resolves the Axiom token from `--token`, `HOLOCRON_AXIOM_TOKEN`, `AXIOM_TOKEN` or the keyring, and throws an `AuthError` when none is set. */
3
91
  const resolveToken = createResolveToken({
4
92
  envName: "HOLOCRON_AXIOM_TOKEN",
5
93
  vendorEnvName: "AXIOM_TOKEN",
6
94
  keyringService: "axiom",
7
- errorMessage: "no Axiom token found. Pass --token <TOKEN>, set HOLOCRON_AXIOM_TOKEN / AXIOM_TOKEN, or run: holocron auth set axiom <TOKEN>"
95
+ errorMessage: "no Axiom token found. Pass --token <TOKEN>, set HOLOCRON_AXIOM_TOKEN / AXIOM_TOKEN, or run: holocron new token axiom <TOKEN>"
8
96
  });
9
- //#endregion
10
- //#region src/capabilities/logs.ts
97
+ /** Every token this plugin takes, for `holocron doctor secrets --verify`, with what each layer's token must and must not be able to do. */
98
+ const tokens = [{
99
+ ...resolveToken.token,
100
+ verify: (token) => verifyToken(token, { dataset: resolveValue(["AXIOM_DATASET"], void 0, { prefix: PREFIX }) }),
101
+ expect: EXPECTED
102
+ }];
103
+ // src/capabilities/logs.ts
104
+ /** A dataset that does not exist: asking for it tells a token Axiom accepts (404) from one it refuses (401). */
105
+ const PROBE_DATASET = "holocron-token-check";
106
+ /** The `logs` capability for Axiom: checks a dataset is reachable and creates datasets that are missing. */
11
107
  var AxiomLogs = class {
12
108
  client;
13
109
  opts;
110
+ /** The capability key, always `logs`. */
14
111
  key = "logs";
112
+ /** The provider name, `axiom`. */
15
113
  providerName = "axiom";
16
114
  /**
17
115
  * `client` is a thunk — the token is resolved on first call, so
@@ -30,76 +128,248 @@ var AxiomLogs = class {
30
128
  async whoami() {
31
129
  const dataset = this.opts.dataset;
32
130
  if (!dataset) throw new Error("@theholocron/holocron-plugin-axiom needs a dataset (HOLOCRON_AXIOM_DATASET / AXIOM_DATASET) for whoami");
33
- await this.client().getDataset(dataset);
131
+ await this.client().datasets.get(dataset);
34
132
  return {
35
133
  ok: true,
36
134
  dataset
37
135
  };
38
136
  }
137
+ async readDataset(name) {
138
+ try {
139
+ const found = await this.client().datasets.get(name);
140
+ const days = found.useRetentionPeriod === false ? void 0 : found.retentionDays;
141
+ return {
142
+ exists: true,
143
+ ...days === void 0 ? {} : { retentionDays: days }
144
+ };
145
+ } catch (err) {
146
+ if (err instanceof ProviderApiError && err.status === 404) return { exists: false };
147
+ throw err;
148
+ }
149
+ }
150
+ async checkToken() {
151
+ try {
152
+ await this.client().datasets.get(PROBE_DATASET);
153
+ return { ok: true };
154
+ } catch (err) {
155
+ if (err instanceof ProviderApiError) {
156
+ if (err.status === 404) return { ok: true };
157
+ if (err.status === 401) return {
158
+ ok: false,
159
+ reason: "Axiom refused the token (401)"
160
+ };
161
+ }
162
+ throw err;
163
+ }
164
+ }
39
165
  async ensureDataset(name) {
40
166
  try {
41
- await this.client().getDataset(name);
167
+ await this.client().datasets.get(name);
42
168
  return { alreadyExists: true };
43
169
  } catch (err) {
44
170
  if (!(err instanceof ProviderApiError) || err.status !== 404) throw err;
45
171
  }
46
- await this.client().createDataset({
172
+ await this.client().datasets.create({
47
173
  name,
48
174
  description: "Managed by holocron"
49
175
  });
50
176
  return { alreadyExists: false };
51
177
  }
52
178
  };
53
- function createAxiomClient(opts) {
54
- const rest = createRestClient({
55
- baseUrl: opts.baseUrl ?? "https://api.axiom.co",
56
- token: opts.token,
57
- vendor: "Axiom",
58
- fetch: opts.fetch
59
- });
179
+ // src/probes/token/parse-token-args.ts
180
+ /** Reads the words after the probe name: `--layer <word>`, `--token-name <VAR>` and any number of dataset names. */
181
+ function parseTokenArgs(args) {
182
+ const datasets = [];
183
+ let layer;
184
+ let tokenName;
185
+ for (let i = 0; i < args.length; i++) {
186
+ const arg = args[i];
187
+ if (arg === "--layer") layer = args[++i];
188
+ else if (arg.startsWith("--layer=")) layer = arg.slice(8);
189
+ else if (arg === "--token-name") tokenName = args[++i];
190
+ else if (arg.startsWith("--token-name=")) tokenName = arg.slice(13);
191
+ else if (!arg.startsWith("--")) datasets.push(arg);
192
+ }
60
193
  return {
61
- getDataset: (name) => rest.request(`/v2/datasets/${encodeURIComponent(name)}`),
62
- createDataset: (input) => rest.request("/v2/datasets", {
63
- method: "POST",
64
- body: input
65
- }),
66
- getCurrentUser: () => rest.request("/v2/user")
194
+ ...layer ? { layer } : {},
195
+ ...tokenName ? { tokenName } : {},
196
+ datasets
67
197
  };
68
198
  }
69
- //#endregion
70
- //#region src/verify-token.ts
199
+ // src/probes/token/token.ts
200
+ /** How many names to show before "(+N more)". */
201
+ const SHOWN = 8;
202
+ /** The time a query looks back over: a minute is enough, the query reads nothing the probe prints. */
203
+ const QUERY_WINDOW_MS = 6e4;
204
+ /** `a, b, c (+2 more)`. */
205
+ function summarise(names) {
206
+ return names.length <= SHOWN ? names.join(", ") : `${names.slice(0, SHOWN).join(", ")} (+${names.length - SHOWN} more)`;
207
+ }
71
208
  /**
72
- * `verifyToken` — plugin-level export used by `holocron auth set axiom`
73
- * + `holocron auth check`. Hits `GET /v2/user` and translates the
74
- * response into the normalized `VerifyTokenResult` shape.
75
- *
76
- * Kept as a standalone function (not a capability method) so the auth
77
- * command can call it without initializing the full plugin.
209
+ * Runs one request and says what came back. Axiom answers a token without the permission with a 401 or 403, and a
210
+ * dataset the token cannot see (or that does not exist) with a 404; all three are `none`. A request that fails for
211
+ * another reason (the network, a 5xx) is an `error`.
78
212
  */
79
- async function verifyToken(token, opts = {}) {
80
- const client = createAxiomClient({
81
- token,
82
- baseUrl: opts.baseUrl,
83
- fetch: opts.fetch
84
- });
213
+ async function reach(request) {
85
214
  try {
86
- const me = await client.getCurrentUser();
87
- return {
88
- ok: true,
89
- subject: `user @ ${me.email ?? me.emails?.[0] ?? me.name ?? me.id ?? "unknown"}`
90
- };
215
+ await request();
216
+ return { kind: "has" };
91
217
  } catch (err) {
218
+ if (err instanceof ProviderApiError && (err.status === 401 || err.status === 403)) return {
219
+ kind: "none",
220
+ detail: `no access (${err.status})`
221
+ };
222
+ if (err instanceof ProviderApiError && err.status === 404) return {
223
+ kind: "none",
224
+ detail: "no such dataset, or the token cannot see it (404)"
225
+ };
92
226
  return {
93
- ok: false,
94
- message: err instanceof Error ? err.message : String(err)
227
+ kind: "error",
228
+ detail: errorMessage(err)
95
229
  };
96
230
  }
97
231
  }
98
- //#endregion
99
- //#region src/index.ts
232
+ /** The APL query that reads one row of a dataset; the name is quoted the way APL quotes an identifier. */
233
+ function queryFor(dataset) {
234
+ return `['${dataset.replaceAll("\\", "\\\\").replaceAll("'", "\\'")}'] | take 1`;
235
+ }
236
+ /**
237
+ * One row for what was tried. With no rule it only describes (`ok` for access, `info` for none). Under a layer's rule it
238
+ * judges: a required permission the token lacks fails, and one the layer must not have fails when the token has it; a
239
+ * permission that is rightly absent is a bare `ok`.
240
+ */
241
+ function rowFor({ label, outcome }, rule) {
242
+ const detail = outcome.detail === void 0 ? {} : { detail: outcome.detail };
243
+ if (outcome.kind === "error") return {
244
+ status: "fail",
245
+ label,
246
+ ...detail
247
+ };
248
+ const has = outcome.kind === "has";
249
+ if (rule === "required") return {
250
+ status: has ? "ok" : "fail",
251
+ label,
252
+ ...detail
253
+ };
254
+ if (rule === "absent") return has ? {
255
+ status: "fail",
256
+ label,
257
+ ...detail
258
+ } : {
259
+ status: "ok",
260
+ label
261
+ };
262
+ return {
263
+ status: has ? "ok" : "info",
264
+ label,
265
+ ...detail
266
+ };
267
+ }
268
+ /**
269
+ * The `token` probe: tries each permission Holocron uses with the Axiom token on a dataset (reading it, ingesting and
270
+ * querying) and reports which ones the token has, then lists the datasets the token can see, so a token that reaches a
271
+ * retired dataset (`holocron-local`) is visible. Ingesting sends an empty list, which writes no event, and the query
272
+ * reads one row it never prints, so the probe changes nothing. The token is the one the plugin resolves, so
273
+ * `--token axiom=<token>` or `--environment <layer>` checks another one; the dataset is the plugin's own, or the names
274
+ * after the probe name.
275
+ *
276
+ * A token with no layer is only described. When the CLI passes `--layer` (because `--environment` named `ci`, `dev` or
277
+ * `local`), the results are judged against what that layer's token is meant to carry (the plugin's `tokens` declaration,
278
+ * read with `tokenExpectations()`) and shown in two groups, what it should have and what it should not, where a
279
+ * missing or extra permission fails.
280
+ */
281
+ function tokenProbe(ctx) {
282
+ return {
283
+ 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.",
284
+ writes: false,
285
+ acceptsToken: true,
286
+ async run(probe) {
287
+ const token = ctx.token();
288
+ probe.secret(token);
289
+ const client = ctx.client();
290
+ const { layer, tokenName, datasets: named } = parseTokenArgs(probe.args ?? []);
291
+ const rules = layer ? tokenExpectations(tokens, {
292
+ layer,
293
+ ...tokenName ? { envName: tokenName } : {}
294
+ })[0]?.rules : void 0;
295
+ if (layer && !rules) probe.say({
296
+ status: "info",
297
+ label: layer,
298
+ detail: "no expectations are declared for it, so the token is only described"
299
+ });
300
+ const targets = named.length > 0 ? named : ctx.options.dataset ? [ctx.options.dataset] : [];
301
+ if (targets.length === 0) probe.say({
302
+ status: rules ? "fail" : "info",
303
+ label: "dataset",
304
+ detail: "none given: name one after the probe, or set HOLOCRON_AXIOM_DATASET or the plugin's dataset option"
305
+ });
306
+ const tried = [];
307
+ for (const dataset of targets) {
308
+ const now = Date.now();
309
+ tried.push({
310
+ label: `Read (${dataset})`,
311
+ permission: "read",
312
+ outcome: await reach(() => client.datasets.get(dataset))
313
+ }, {
314
+ label: `Ingest (${dataset})`,
315
+ permission: "ingest",
316
+ outcome: await reach(() => client.datasets.ingest(dataset, []))
317
+ }, {
318
+ label: `Query (${dataset})`,
319
+ permission: "query",
320
+ outcome: await reach(() => client.datasets.query({
321
+ apl: queryFor(dataset),
322
+ startTime: (/* @__PURE__ */ new Date(now - QUERY_WINDOW_MS)).toISOString(),
323
+ endTime: new Date(now).toISOString()
324
+ }))
325
+ });
326
+ }
327
+ if (!rules) for (const t of tried) probe.say(rowFor(t, void 0));
328
+ else for (const [heading, rule] of [["Should have", "required"], ["Should not have", "absent"]]) {
329
+ const inGroup = tried.filter((t) => rules[t.permission] === rule);
330
+ if (inGroup.length === 0) continue;
331
+ probe.say({
332
+ status: "heading",
333
+ label: heading
334
+ });
335
+ for (const t of inGroup) probe.say(rowFor(t, rule));
336
+ }
337
+ probe.say({
338
+ status: "heading",
339
+ label: "Datasets this token can see"
340
+ });
341
+ try {
342
+ const names = (await client.datasets.list()).map((d) => d.name);
343
+ probe.say(names.length === 0 ? {
344
+ status: "info",
345
+ label: "datasets",
346
+ detail: "none visible"
347
+ } : {
348
+ status: "info",
349
+ label: "datasets",
350
+ detail: `${names.length}: ${summarise(names)}`
351
+ });
352
+ for (const name of names.filter((n) => RETIRED_DATASETS.includes(n))) probe.say({
353
+ status: "info",
354
+ label: name,
355
+ detail: "retired (one dataset per service now, ADR-0019): the token still reaches it"
356
+ });
357
+ } catch (err) {
358
+ const denied = err instanceof ProviderApiError && (err.status === 401 || err.status === 403);
359
+ probe.say({
360
+ status: denied ? "info" : "fail",
361
+ label: "datasets",
362
+ detail: denied ? `the token cannot list datasets (${err.status})` : errorMessage(err)
363
+ });
364
+ }
365
+ }
366
+ };
367
+ }
368
+ // src/index.ts
369
+ /** Creates the shared context for the given options; no token is resolved until `client()` is first called. */
100
370
  function createContext(options) {
101
- const env = options.env ?? process.env;
102
- const dataset = options.dataset ?? env.HOLOCRON_AXIOM_DATASET ?? env.AXIOM_DATASET;
371
+ const env = createEnvLookup(options.env);
372
+ const dataset = options.dataset ?? firstEnv(env, ["HOLOCRON_AXIOM_DATASET", "AXIOM_DATASET"]);
103
373
  let client;
104
374
  return {
105
375
  options: {
@@ -113,20 +383,39 @@ function createContext(options) {
113
383
  })
114
384
  };
115
385
  }
386
+ /** Builds the `logs` capability from a plugin context. */
116
387
  function logs(ctx) {
117
388
  return new AxiomLogs(ctx.client, { dataset: ctx.options.dataset });
118
389
  }
390
+ /** Creates the Axiom plugin: the `connection` and `token` probes and the `logs` capability. */
119
391
  function createPlugin(options) {
120
392
  const ctx = createContext(options);
121
393
  return {
122
394
  name: "@theholocron/holocron-plugin-axiom",
395
+ probes: {
396
+ token: tokenProbe({
397
+ options: ctx.options,
398
+ client: ctx.client,
399
+ token: () => resolveToken(options)
400
+ }),
401
+ connection: connectionProbe({
402
+ provider: "Axiom",
403
+ url: options.baseUrl ?? "https://api.axiom.co",
404
+ fetch: options.fetch,
405
+ token: () => resolveToken(options),
406
+ verify: (token) => verifyToken(token, {
407
+ baseUrl: options.baseUrl,
408
+ fetch: options.fetch,
409
+ dataset: ctx.options.dataset
410
+ })
411
+ })
412
+ },
123
413
  capabilities: { logs: () => logs(ctx) }
124
414
  };
125
415
  }
126
416
  /**
127
- * One-line hint shown by `holocron auth set axiom` when no token is
417
+ * One-line hint shown by `holocron new token axiom` when no token is
128
418
  * supplied or when the supplied token is rejected.
129
419
  */
130
- const AUTH_HINT = "generate an Axiom API token at https://app.axiom.co/settings/api-tokens with dataset read + create permissions, then run: holocron auth set axiom <TOKEN>";
131
- //#endregion
132
- export { AUTH_HINT, AuthError, AxiomLogs, createAxiomClient, createContext, createPlugin, logs, resolveToken, verifyToken };
420
+ const AUTH_HINT = "generate an Axiom API token at https://app.axiom.co/settings/api-tokens with dataset read + create permissions, then run: holocron new token axiom <TOKEN>";
421
+ export { AUTH_HINT, AuthError, AxiomLogs, createAxiomClient, createContext, createPlugin, logs, resolveToken, tokens, verifyToken };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@theholocron/holocron-plugin-axiom",
3
- "version": "5.0.0-alpha.45",
3
+ "version": "5.0.0-alpha.451",
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",
@@ -8,12 +8,12 @@
8
8
  "logs",
9
9
  "plugin"
10
10
  ],
11
- "homepage": "https://github.com/theholocron/holocron/tree/main/packages/holocron-plugin-axiom#readme",
11
+ "homepage": "https://docs.theholocron.dev/holocron/plugins/axiom/",
12
12
  "bugs": "https://github.com/theholocron/holocron/issues",
13
13
  "repository": {
14
14
  "type": "git",
15
15
  "url": "git+https://github.com/theholocron/holocron.git",
16
- "directory": "packages/holocron-plugin-axiom"
16
+ "directory": "plugins/holocron-plugin-axiom"
17
17
  },
18
18
  "license": "MIT",
19
19
  "author": "Newton Koumantzelis",
@@ -29,26 +29,33 @@
29
29
  "files": [
30
30
  "dist"
31
31
  ],
32
+ "dependencies": {
33
+ "@theholocron/env-utils": "^1.17.0-alpha.4"
34
+ },
32
35
  "devDependencies": {
33
- "@theholocron/eslint-config": "^8.4.5",
34
- "@theholocron/http-client": "^1.25.0",
35
- "@theholocron/tsconfig": "^8.4.5",
36
- "@theholocron/tsdown-config": "^8.4.5",
37
- "@theholocron/vitest-config": "^8.4.5",
38
36
  "@types/node": "^26",
39
- "@vitest/coverage-v8": "^4.1.11",
40
- "@vitest/eslint-plugin": "^1.6.27",
41
- "eslint": "^10.8.1",
42
- "eslint-plugin-n": "^18.3.0",
43
- "globals": "^17.11.0",
44
- "tsdown": "^0.22.14",
45
- "tsx": "4.23.12",
37
+ "@vitest/coverage-v8": "^5.1.0",
38
+ "@vitest/eslint-plugin": "^1.6.28",
39
+ "eslint": "^10.14.0",
40
+ "eslint-plugin-n": "^18.5.0",
41
+ "globals": "^17.14.0",
42
+ "tsdown": "^0.23.7",
43
+ "tsx": "4.23.15",
46
44
  "typescript": "^5.9.3",
47
- "vitest": "^4.1.11",
48
- "@theholocron/cli": "5.0.0-alpha.45"
45
+ "vitest": "^5.1.0",
46
+ "@theholocron/cli": "5.0.0-alpha.451",
47
+ "@theholocron/axiom-client": "^1.58.0-alpha.35",
48
+ "@theholocron/http-client": "^1.58.0-alpha.35",
49
+ "@theholocron/eslint-config": "^8.9.0-alpha.17",
50
+ "@theholocron/misc-utils": "^1.17.0-alpha.4",
51
+ "@theholocron/tsconfig": "^8.9.0-alpha.17",
52
+ "@theholocron/tsdown-config": "^8.9.0-alpha.17",
53
+ "@theholocron/vitest-config": "^8.9.0-alpha.17"
49
54
  },
50
55
  "peerDependencies": {
51
- "@theholocron/cli": "5.0.0-alpha.45"
56
+ "@theholocron/axiom-client": "^1.43.1",
57
+ "@theholocron/misc-utils": "^1.16.0",
58
+ "@theholocron/cli": "5.0.0-alpha.451"
52
59
  },
53
60
  "engines": {
54
61
  "node": ">=22"
@@ -57,11 +64,11 @@
57
64
  "access": "public"
58
65
  },
59
66
  "scripts": {
60
- "delivery.build": "tsdown",
61
- "sourceQuality.staticAnalysis": "holocron run sourceQuality.staticAnalysis --",
67
+ "build": "tsdown",
68
+ "lint:code": "eslint .",
69
+ "test:unit": "vitest run --coverage",
62
70
  "test:watch": "vitest",
63
- "validate": "tsx scripts/validate.mjs",
64
- "verification.typeSafety": "holocron run verification.typeSafety --",
65
- "verification.unitTests": "holocron run verification.unitTests --"
71
+ "typecheck": "tsc --noEmit",
72
+ "validate:plugin": "tsx scripts/validate.mjs"
66
73
  }
67
74
  }