@theholocron/holocron-plugin-axiom 5.0.0-alpha.44 → 5.0.0-alpha.441
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 +21 -20
- package/dist/index.d.mts +42 -70
- package/dist/index.mjs +321 -35
- package/package.json +30 -23
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
|
|
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
|
|
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
|
|
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
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
`logs: ["axiom", { "dataset": "
|
|
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
|
-
|
|
59
|
-
|
|
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
|
|
73
|
+
| Export | Purpose |
|
|
74
|
+
| ------------- | -------------------------------------------------------------------------------------------- |
|
|
75
|
+
| `verifyToken` | `GET /v2/user` — returns `{ ok: true, subject: "user @ …" }` or `{ ok: false, message }`. |
|
|
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,10 @@
|
|
|
1
|
-
import { AuthError, Logs, ResolveTokenInput } from "@theholocron/cli";
|
|
2
|
-
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
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
|
+
import { AuthError, Logs, LogsDataset, PluginToken, ResolveTokenInput, VerifyTokenFailure, VerifyTokenResult, VerifyTokenResult as VerifyTokenResult$1, VerifyTokenSuccess } from "@theholocron/cli";
|
|
2
|
+
import { AxiomClient, AxiomClientOptions, AxiomDataset, AxiomUser, CreateAxiomDatasetInput, createAxiomClient } from "@theholocron/axiom-client";
|
|
3
|
+
/** Resolves the Axiom token from `--token`, `HOLOCRON_AXIOM_TOKEN`, `AXIOM_TOKEN` or the keyring, and throws an `AuthError` when none is set. */
|
|
4
|
+
export declare const resolveToken: import("@theholocron/cli").TokenResolver;
|
|
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
|
+
export declare const tokens: PluginToken[];
|
|
7
|
+
/** Options for the Axiom `logs` capability. */
|
|
37
8
|
interface AxiomLogsOptions {
|
|
38
9
|
/**
|
|
39
10
|
* Target dataset, resolved from `HOLOCRON_AXIOM_DATASET` /
|
|
@@ -42,16 +13,19 @@ interface AxiomLogsOptions {
|
|
|
42
13
|
*/
|
|
43
14
|
dataset?: string;
|
|
44
15
|
}
|
|
45
|
-
|
|
16
|
+
/** The `logs` capability for Axiom: checks a dataset is reachable and creates datasets that are missing. */
|
|
17
|
+
export declare class AxiomLogs implements Logs {
|
|
46
18
|
private readonly client;
|
|
47
19
|
private readonly opts;
|
|
20
|
+
/** The capability key, always `logs`. */
|
|
48
21
|
readonly key: "logs";
|
|
22
|
+
/** The provider name, `axiom`. */
|
|
49
23
|
readonly providerName = "axiom";
|
|
50
24
|
/**
|
|
51
25
|
* `client` is a thunk — the token is resolved on first call, so
|
|
52
26
|
* `describe()` (which needs no auth) works without one.
|
|
53
27
|
*/
|
|
54
|
-
constructor(client: () =>
|
|
28
|
+
constructor(client: () => AxiomClient, opts: AxiomLogsOptions);
|
|
55
29
|
describe(): Promise<{
|
|
56
30
|
provider: string;
|
|
57
31
|
envKeys: string[];
|
|
@@ -60,43 +34,35 @@ declare class AxiomLogs implements Logs {
|
|
|
60
34
|
ok: boolean;
|
|
61
35
|
dataset: string;
|
|
62
36
|
}>;
|
|
37
|
+
readDataset(name: string): Promise<LogsDataset>;
|
|
38
|
+
checkToken(): Promise<{
|
|
39
|
+
ok: boolean;
|
|
40
|
+
reason?: string;
|
|
41
|
+
}>;
|
|
63
42
|
ensureDataset(name: string): Promise<{
|
|
64
43
|
alreadyExists: boolean;
|
|
65
44
|
}>;
|
|
66
45
|
}
|
|
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
46
|
interface VerifyTokenOptions {
|
|
87
47
|
baseUrl?: string;
|
|
88
48
|
fetch?: typeof fetch;
|
|
89
49
|
}
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
50
|
+
/**
|
|
51
|
+
* Checks an Axiom token by fetching the current user; the success subject is `user @` followed by the email, name or id,
|
|
52
|
+
* the failure carries the error message. An API token cannot read the user (403), so then it asks for a dataset that
|
|
53
|
+
* does not exist: a 404 means the token is accepted and may read datasets, and the subject says `API token`.
|
|
54
|
+
*/
|
|
55
|
+
export declare function verifyToken(token: string, opts?: VerifyTokenOptions): Promise<VerifyTokenResult$1>;
|
|
56
|
+
/** Options for the Axiom plugin: token resolution, the target dataset and test overrides. */
|
|
57
|
+
export interface AxiomPluginOptions extends ResolveTokenInput, AxiomLogsOptions {
|
|
94
58
|
/** Override base URL for tests. */
|
|
95
59
|
baseUrl?: string;
|
|
96
60
|
/** Override `fetch` for tests. */
|
|
97
61
|
fetch?: typeof fetch;
|
|
98
62
|
}
|
|
99
|
-
|
|
63
|
+
/** What the plugin's capabilities share: the resolved options and a lazily built client. */
|
|
64
|
+
export interface PluginContext {
|
|
65
|
+
/** The options, with `dataset` resolved from config, `HOLOCRON_AXIOM_DATASET` or `AXIOM_DATASET` (in that order). */
|
|
100
66
|
options: AxiomPluginOptions & {
|
|
101
67
|
dataset?: string;
|
|
102
68
|
};
|
|
@@ -106,20 +72,26 @@ interface PluginContext {
|
|
|
106
72
|
* no auth (`describe`) works without a token, and the loader never
|
|
107
73
|
* aborts on a plugin whose token happens to be absent.
|
|
108
74
|
*/
|
|
109
|
-
client: () =>
|
|
75
|
+
client: () => AxiomClient;
|
|
110
76
|
}
|
|
111
|
-
|
|
112
|
-
declare function
|
|
113
|
-
|
|
77
|
+
/** Creates the shared context for the given options; no token is resolved until `client()` is first called. */
|
|
78
|
+
export declare function createContext(options: AxiomPluginOptions): PluginContext;
|
|
79
|
+
/** Builds the `logs` capability from a plugin context. */
|
|
80
|
+
export declare function logs(ctx: PluginContext): Logs;
|
|
81
|
+
/** Creates the Axiom plugin: the `connection` and `token` probes and the `logs` capability. */
|
|
82
|
+
export declare function createPlugin(options: AxiomPluginOptions): {
|
|
114
83
|
name: string;
|
|
84
|
+
probes: {
|
|
85
|
+
token: import("@theholocron/cli").Probe;
|
|
86
|
+
connection: import("@theholocron/cli").Probe;
|
|
87
|
+
};
|
|
115
88
|
capabilities: {
|
|
116
89
|
logs: () => Logs;
|
|
117
90
|
};
|
|
118
91
|
};
|
|
119
92
|
/**
|
|
120
|
-
* One-line hint shown by `holocron
|
|
93
|
+
* One-line hint shown by `holocron new token axiom` when no token is
|
|
121
94
|
* supplied or when the supplied token is rejected.
|
|
122
95
|
*/
|
|
123
|
-
declare const AUTH_HINT: string;
|
|
124
|
-
|
|
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 };
|
|
96
|
+
export declare const AUTH_HINT: string;
|
|
97
|
+
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,59 @@
|
|
|
1
|
-
import { AuthError, ProviderApiError, createResolveToken,
|
|
2
|
-
|
|
1
|
+
import { AuthError, ProviderApiError, connectionProbe, createResolveToken, tokenExpectations } from "@theholocron/cli";
|
|
2
|
+
import { 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/auth.ts
|
|
35
|
+
/** Resolves the Axiom token from `--token`, `HOLOCRON_AXIOM_TOKEN`, `AXIOM_TOKEN` or the keyring, and throws an `AuthError` when none is set. */
|
|
3
36
|
const resolveToken = createResolveToken({
|
|
4
37
|
envName: "HOLOCRON_AXIOM_TOKEN",
|
|
5
38
|
vendorEnvName: "AXIOM_TOKEN",
|
|
6
39
|
keyringService: "axiom",
|
|
7
|
-
errorMessage: "no Axiom token found. Pass --token <TOKEN>, set HOLOCRON_AXIOM_TOKEN / AXIOM_TOKEN, or run: holocron
|
|
40
|
+
errorMessage: "no Axiom token found. Pass --token <TOKEN>, set HOLOCRON_AXIOM_TOKEN / AXIOM_TOKEN, or run: holocron new token axiom <TOKEN>"
|
|
8
41
|
});
|
|
9
|
-
|
|
10
|
-
|
|
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
|
+
}];
|
|
47
|
+
// src/capabilities/logs.ts
|
|
48
|
+
/** A dataset that does not exist: asking for it tells a token Axiom accepts (404) from one it refuses (401). */
|
|
49
|
+
const PROBE_DATASET$1 = "holocron-token-check";
|
|
50
|
+
/** The `logs` capability for Axiom: checks a dataset is reachable and creates datasets that are missing. */
|
|
11
51
|
var AxiomLogs = class {
|
|
12
52
|
client;
|
|
13
53
|
opts;
|
|
54
|
+
/** The capability key, always `logs`. */
|
|
14
55
|
key = "logs";
|
|
56
|
+
/** The provider name, `axiom`. */
|
|
15
57
|
providerName = "axiom";
|
|
16
58
|
/**
|
|
17
59
|
* `client` is a thunk — the token is resolved on first call, so
|
|
@@ -30,52 +72,259 @@ var AxiomLogs = class {
|
|
|
30
72
|
async whoami() {
|
|
31
73
|
const dataset = this.opts.dataset;
|
|
32
74
|
if (!dataset) throw new Error("@theholocron/holocron-plugin-axiom needs a dataset (HOLOCRON_AXIOM_DATASET / AXIOM_DATASET) for whoami");
|
|
33
|
-
await this.client().
|
|
75
|
+
await this.client().datasets.get(dataset);
|
|
34
76
|
return {
|
|
35
77
|
ok: true,
|
|
36
78
|
dataset
|
|
37
79
|
};
|
|
38
80
|
}
|
|
81
|
+
async readDataset(name) {
|
|
82
|
+
try {
|
|
83
|
+
const found = await this.client().datasets.get(name);
|
|
84
|
+
const days = found.useRetentionPeriod === false ? void 0 : found.retentionDays;
|
|
85
|
+
return {
|
|
86
|
+
exists: true,
|
|
87
|
+
...days === void 0 ? {} : { retentionDays: days }
|
|
88
|
+
};
|
|
89
|
+
} catch (err) {
|
|
90
|
+
if (err instanceof ProviderApiError && err.status === 404) return { exists: false };
|
|
91
|
+
throw err;
|
|
92
|
+
}
|
|
93
|
+
}
|
|
94
|
+
async checkToken() {
|
|
95
|
+
try {
|
|
96
|
+
await this.client().datasets.get(PROBE_DATASET$1);
|
|
97
|
+
return { ok: true };
|
|
98
|
+
} catch (err) {
|
|
99
|
+
if (err instanceof ProviderApiError) {
|
|
100
|
+
if (err.status === 404) return { ok: true };
|
|
101
|
+
if (err.status === 401) return {
|
|
102
|
+
ok: false,
|
|
103
|
+
reason: "Axiom refused the token (401)"
|
|
104
|
+
};
|
|
105
|
+
}
|
|
106
|
+
throw err;
|
|
107
|
+
}
|
|
108
|
+
}
|
|
39
109
|
async ensureDataset(name) {
|
|
40
110
|
try {
|
|
41
|
-
await this.client().
|
|
111
|
+
await this.client().datasets.get(name);
|
|
42
112
|
return { alreadyExists: true };
|
|
43
113
|
} catch (err) {
|
|
44
114
|
if (!(err instanceof ProviderApiError) || err.status !== 404) throw err;
|
|
45
115
|
}
|
|
46
|
-
await this.client().
|
|
116
|
+
await this.client().datasets.create({
|
|
47
117
|
name,
|
|
48
118
|
description: "Managed by holocron"
|
|
49
119
|
});
|
|
50
120
|
return { alreadyExists: false };
|
|
51
121
|
}
|
|
52
122
|
};
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
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
|
+
};
|
|
60
206
|
return {
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
body: input
|
|
65
|
-
}),
|
|
66
|
-
getCurrentUser: () => rest.request("/v2/user")
|
|
207
|
+
status: has ? "ok" : "info",
|
|
208
|
+
label,
|
|
209
|
+
...detail
|
|
67
210
|
};
|
|
68
211
|
}
|
|
69
|
-
//#endregion
|
|
70
|
-
//#region src/verify-token.ts
|
|
71
212
|
/**
|
|
72
|
-
* `
|
|
73
|
-
*
|
|
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
|
+
}
|
|
312
|
+
// src/verify-token.ts
|
|
313
|
+
/**
|
|
314
|
+
* `verifyToken` — plugin-level export used by `holocron new token axiom`
|
|
315
|
+
* + `holocron check token`. Hits `GET /v2/user` and translates the
|
|
74
316
|
* response into the normalized `VerifyTokenResult` shape.
|
|
75
317
|
*
|
|
76
318
|
* Kept as a standalone function (not a capability method) so the auth
|
|
77
319
|
* command can call it without initializing the full plugin.
|
|
78
320
|
*/
|
|
321
|
+
/** A dataset that does not exist: asking for it tells a token that may read datasets (404) from one that may not (403). */
|
|
322
|
+
const PROBE_DATASET = "holocron-token-check";
|
|
323
|
+
/**
|
|
324
|
+
* Checks an Axiom token by fetching the current user; the success subject is `user @` followed by the email, name or id,
|
|
325
|
+
* the failure carries the error message. An API token cannot read the user (403), so then it asks for a dataset that
|
|
326
|
+
* does not exist: a 404 means the token is accepted and may read datasets, and the subject says `API token`.
|
|
327
|
+
*/
|
|
79
328
|
async function verifyToken(token, opts = {}) {
|
|
80
329
|
const client = createAxiomClient({
|
|
81
330
|
token,
|
|
@@ -83,23 +332,42 @@ async function verifyToken(token, opts = {}) {
|
|
|
83
332
|
fetch: opts.fetch
|
|
84
333
|
});
|
|
85
334
|
try {
|
|
86
|
-
const me = await client.
|
|
335
|
+
const me = await client.user.me();
|
|
87
336
|
return {
|
|
88
337
|
ok: true,
|
|
89
338
|
subject: `user @ ${me.email ?? me.emails?.[0] ?? me.name ?? me.id ?? "unknown"}`
|
|
90
339
|
};
|
|
91
340
|
} catch (err) {
|
|
341
|
+
if (err instanceof ProviderApiError && err.status === 403) return verifyApiToken(client);
|
|
342
|
+
return {
|
|
343
|
+
ok: false,
|
|
344
|
+
message: errorMessage(err)
|
|
345
|
+
};
|
|
346
|
+
}
|
|
347
|
+
}
|
|
348
|
+
async function verifyApiToken(client) {
|
|
349
|
+
try {
|
|
350
|
+
await client.datasets.get(PROBE_DATASET);
|
|
351
|
+
return {
|
|
352
|
+
ok: true,
|
|
353
|
+
subject: "API token"
|
|
354
|
+
};
|
|
355
|
+
} catch (err) {
|
|
356
|
+
if (err instanceof ProviderApiError && err.status === 404) return {
|
|
357
|
+
ok: true,
|
|
358
|
+
subject: "API token"
|
|
359
|
+
};
|
|
92
360
|
return {
|
|
93
361
|
ok: false,
|
|
94
|
-
message:
|
|
362
|
+
message: errorMessage(err)
|
|
95
363
|
};
|
|
96
364
|
}
|
|
97
365
|
}
|
|
98
|
-
|
|
99
|
-
|
|
366
|
+
// src/index.ts
|
|
367
|
+
/** Creates the shared context for the given options; no token is resolved until `client()` is first called. */
|
|
100
368
|
function createContext(options) {
|
|
101
|
-
const env = options.env
|
|
102
|
-
const dataset = options.dataset ?? env
|
|
369
|
+
const env = createEnvLookup(options.env);
|
|
370
|
+
const dataset = options.dataset ?? firstEnv(env, ["HOLOCRON_AXIOM_DATASET", "AXIOM_DATASET"]);
|
|
103
371
|
let client;
|
|
104
372
|
return {
|
|
105
373
|
options: {
|
|
@@ -113,20 +381,38 @@ function createContext(options) {
|
|
|
113
381
|
})
|
|
114
382
|
};
|
|
115
383
|
}
|
|
384
|
+
/** Builds the `logs` capability from a plugin context. */
|
|
116
385
|
function logs(ctx) {
|
|
117
386
|
return new AxiomLogs(ctx.client, { dataset: ctx.options.dataset });
|
|
118
387
|
}
|
|
388
|
+
/** Creates the Axiom plugin: the `connection` and `token` probes and the `logs` capability. */
|
|
119
389
|
function createPlugin(options) {
|
|
120
390
|
const ctx = createContext(options);
|
|
121
391
|
return {
|
|
122
392
|
name: "@theholocron/holocron-plugin-axiom",
|
|
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
|
+
})
|
|
408
|
+
})
|
|
409
|
+
},
|
|
123
410
|
capabilities: { logs: () => logs(ctx) }
|
|
124
411
|
};
|
|
125
412
|
}
|
|
126
413
|
/**
|
|
127
|
-
* One-line hint shown by `holocron
|
|
414
|
+
* One-line hint shown by `holocron new token axiom` when no token is
|
|
128
415
|
* supplied or when the supplied token is rejected.
|
|
129
416
|
*/
|
|
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
|
|
131
|
-
|
|
132
|
-
export { AUTH_HINT, AuthError, AxiomLogs, createAxiomClient, createContext, createPlugin, logs, resolveToken, verifyToken };
|
|
417
|
+
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>";
|
|
418
|
+
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.
|
|
3
|
+
"version": "5.0.0-alpha.441",
|
|
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://
|
|
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": "
|
|
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": "^
|
|
40
|
-
"@vitest/eslint-plugin": "^1.6.
|
|
41
|
-
"eslint": "^10.
|
|
42
|
-
"eslint-plugin-n": "^18.
|
|
43
|
-
"globals": "^17.
|
|
44
|
-
"tsdown": "^0.
|
|
45
|
-
"tsx": "4.23.
|
|
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.5",
|
|
43
|
+
"tsx": "4.23.15",
|
|
46
44
|
"typescript": "^5.9.3",
|
|
47
|
-
"vitest": "^
|
|
48
|
-
"@theholocron/
|
|
45
|
+
"vitest": "^5.1.0",
|
|
46
|
+
"@theholocron/axiom-client": "^1.58.0-alpha.32",
|
|
47
|
+
"@theholocron/cli": "5.0.0-alpha.441",
|
|
48
|
+
"@theholocron/eslint-config": "^8.9.0-alpha.17",
|
|
49
|
+
"@theholocron/http-client": "^1.58.0-alpha.32",
|
|
50
|
+
"@theholocron/tsconfig": "^8.9.0-alpha.17",
|
|
51
|
+
"@theholocron/tsdown-config": "^8.9.0-alpha.17",
|
|
52
|
+
"@theholocron/vitest-config": "^8.9.0-alpha.17",
|
|
53
|
+
"@theholocron/misc-utils": "^1.17.0-alpha.4"
|
|
49
54
|
},
|
|
50
55
|
"peerDependencies": {
|
|
51
|
-
"@theholocron/
|
|
56
|
+
"@theholocron/axiom-client": "^1.43.1",
|
|
57
|
+
"@theholocron/misc-utils": "^1.16.0",
|
|
58
|
+
"@theholocron/cli": "5.0.0-alpha.441"
|
|
52
59
|
},
|
|
53
60
|
"engines": {
|
|
54
61
|
"node": ">=22"
|
|
@@ -57,11 +64,11 @@
|
|
|
57
64
|
"access": "public"
|
|
58
65
|
},
|
|
59
66
|
"scripts": {
|
|
60
|
-
"
|
|
61
|
-
"
|
|
67
|
+
"build": "tsdown",
|
|
68
|
+
"lint:code": "eslint .",
|
|
69
|
+
"test:unit": "vitest run --coverage",
|
|
62
70
|
"test:watch": "vitest",
|
|
63
|
-
"
|
|
64
|
-
"
|
|
65
|
-
"verification.unitTests": "holocron run verification.unitTests --"
|
|
71
|
+
"typecheck": "tsc --noEmit",
|
|
72
|
+
"validate:plugin": "tsx scripts/validate.mjs"
|
|
66
73
|
}
|
|
67
74
|
}
|