ax 0.7.5 → 0.8.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/.env.example +11 -5
- package/README.md +23 -10
- package/dist/api/audit.d.ts +22 -1
- package/dist/api/platform.d.ts +3 -0
- package/dist/api/shared.d.ts +13 -0
- package/dist/contract/types.gen.d.ts +35 -11
- package/dist/contract/version.d.ts +1 -1
- package/dist/index.cjs +29 -7
- package/dist/index.js +29 -7
- package/dist/main.cjs +68 -64
- package/package.json +2 -1
package/.env.example
CHANGED
|
@@ -3,9 +3,10 @@
|
|
|
3
3
|
# ora.ai host and need none of these — `ax audit <url>` works with zero
|
|
4
4
|
# configuration, and so does `ax webmcp-audit http://localhost:3000`.
|
|
5
5
|
|
|
6
|
-
# Secret API key (looks like ora_sk_...). Required by `journey
|
|
7
|
-
#
|
|
8
|
-
#
|
|
6
|
+
# Secret API key (looks like ora_sk_...). Required by `journey` and by
|
|
7
|
+
# `audit --tunnel ora` (needs the tunnels:write + tunnels:connect scopes), which
|
|
8
|
+
# exchange it for a short-lived bearer token. `webmcp-audit` sends it as a bearer
|
|
9
|
+
# token to lift the anonymous ingest limits (10/min, 20 per 24h per IP); optional there.
|
|
9
10
|
ORA_API_KEY=
|
|
10
11
|
|
|
11
12
|
# Platform API base. Defaults to staging if unset.
|
|
@@ -16,8 +17,13 @@ ORA_PLATFORM_URL=https://api.agentfront.sh
|
|
|
16
17
|
# one (e.g. http://localhost:3000).
|
|
17
18
|
# ORA_API_URL=https://ora.ai
|
|
18
19
|
|
|
19
|
-
#
|
|
20
|
-
#
|
|
20
|
+
# Auditing a local target. `ora` opens ora's own tunnel (same as --tunnel ora;
|
|
21
|
+
# needs ORA_API_KEY above) - the tunnel is created, audited, and deleted.
|
|
22
|
+
# ORA_TUNNEL=ora
|
|
23
|
+
|
|
24
|
+
# ...or bring your own tunnel (same as --tunnel-cmd): a command that exposes the
|
|
25
|
+
# local server and prints its public https URL. Wins over ORA_TUNNEL when both are set.
|
|
26
|
+
# ORA_TUNNEL_CMD='ora tunnel 3000 --access public'
|
|
21
27
|
# ORA_TUNNEL_CMD='ngrok http 3000 --log stdout'
|
|
22
28
|
|
|
23
29
|
# ora-issued scan API key for `ax audit` (same as --api-key): exempts the
|
package/README.md
CHANGED
|
@@ -35,7 +35,7 @@ Five commands:
|
|
|
35
35
|
## audit
|
|
36
36
|
|
|
37
37
|
```
|
|
38
|
-
ax audit <url> [--min-score n] [--max-age s] [--force] [--tunnel-cmd c] [--api-key k] [--json] [--show-passing] [--show-skipped]
|
|
38
|
+
ax audit <url> [--min-score n] [--max-age s] [--force] [--tunnel ora] [--tunnel-cmd c] [--api-key k] [--json] [--show-passing] [--show-skipped]
|
|
39
39
|
```
|
|
40
40
|
|
|
41
41
|
```
|
|
@@ -65,7 +65,8 @@ ax audit <url> [--min-score n] [--max-age s] [--force] [--tunnel-cmd c] [--api-k
|
|
|
65
65
|
| `--min-score <n>` | Exit `1` when the score is below `n` (0-100) — the CI gate |
|
|
66
66
|
| `--max-age <s>` | Accept a cached result up to `s` seconds old (server default 6h, clamped to 1-24h) |
|
|
67
67
|
| `--force` | Bypass the cache and rescan — spends the stricter 6/day force budget |
|
|
68
|
-
| `--tunnel
|
|
68
|
+
| `--tunnel ora` | Expose a local target through ora's own tunnel and audit it — needs `ORA_API_KEY` with the `tunnels:write` + `tunnels:connect` scopes (also read from `ORA_TUNNEL`) |
|
|
69
|
+
| `--tunnel-cmd <c>` | Bring your own tunnel: a command that exposes the local target and prints its public `https://` URL (also read from `ORA_TUNNEL_CMD`) |
|
|
69
70
|
| `--api-key <k>` | ora-issued scan API key — lifts every scan rate limit (also read from `ORA_SCAN_API_KEY`) |
|
|
70
71
|
| `--json` | The raw ora audit payload on stdout, exactly as the API served it |
|
|
71
72
|
| `--show-passing` | List every passing check, not just the per-layer summary bar |
|
|
@@ -89,18 +90,29 @@ Exit codes are the contract:
|
|
|
89
90
|
| `2` | usage error — bad flags, malformed URL, local target without a tunnel |
|
|
90
91
|
| `3` | API unreachable, timeout, or rate limit exhausted |
|
|
91
92
|
|
|
92
|
-
Budget notes: ora allows 30 scans + 6 `--force` scans per rolling 24h per IP (plus a 10/min burst limit). Results served from the freshness cache cost nothing, so a CI job that audits on every push stays well inside the budget — tune the window with `--max-age`, and reserve `--force` for verifying a fix you just deployed. High-volume callers can present an ora-issued scan API key (`--api-key` or `ORA_SCAN_API_KEY`), which exempts them from all of these limits; keys are issued manually by ora (no self-serve signup), and an unrecognized key silently falls back to the keyless limits rather than erroring. An auth-gated MCP target
|
|
93
|
+
Budget notes: ora allows 30 scans + 6 `--force` scans per rolling 24h per IP (plus a 10/min burst limit). Results served from the freshness cache cost nothing, so a CI job that audits on every push stays well inside the budget — tune the window with `--max-age`, and reserve `--force` for verifying a fix you just deployed. High-volume callers can present an ora-issued scan API key (`--api-key` or `ORA_SCAN_API_KEY`), which exempts them from all of these limits; keys are issued manually by ora (no self-serve signup), and an unrecognized key silently falls back to the keyless limits rather than erroring. An auth-gated MCP target is not a failure: ora answers with an `MCP_AUTH_REQUIRED` error and no score; ax prints the notice (or the error object with `--json`), skips `--min-score`, and exits `0`.
|
|
93
94
|
|
|
94
|
-
### Auditing localhost (`--tunnel-cmd`)
|
|
95
|
+
### Auditing localhost (`--tunnel ora`, `--tunnel-cmd`)
|
|
95
96
|
|
|
96
|
-
A local dev server only exists on your machine, so ora can't reach it. The simplest option is to audit a publicly reachable deployment of the same code (e.g. a preview URL). To audit localhost itself,
|
|
97
|
+
A local dev server only exists on your machine, so ora can't reach it. The simplest option is to audit a publicly reachable deployment of the same code (e.g. a preview URL). To audit localhost itself, run it through a tunnel. The result is stored as **ephemeral** either way: excluded from ora's rankings and leaderboard, served with `Cache-Control: no-store`, never indexed, and deleted after 7 days.
|
|
98
|
+
|
|
99
|
+
**ora's own tunnel.** With an ora platform key (`ora_sk_…`, scopes `tunnels:write` + `tunnels:connect`) in `ORA_API_KEY`, `ax` creates a tunnel, connects it, audits the public hostname, and deletes the tunnel when done — nothing to install, nothing left behind:
|
|
100
|
+
|
|
101
|
+
```
|
|
102
|
+
ax audit localhost:3000 --tunnel ora
|
|
103
|
+
```
|
|
104
|
+
|
|
105
|
+
The hostname is an unguessable UUID under `*.t.agentfront.sh` that stops answering the moment the audit finishes (or you press Ctrl-C). Today the tunnel is opened in `public` mode, because ora's scanner cannot yet present a per-tunnel credential; a `protected` mode the scanner can use is on the roadmap.
|
|
106
|
+
|
|
107
|
+
**Bring your own tunnel.** Pass `--tunnel-cmd` (or set `ORA_TUNNEL_CMD`) with any command that exposes the local server and prints its public `https://` URL. The CLI runs it, audits the URL it prints, and tears the tunnel down when done:
|
|
97
108
|
|
|
98
109
|
```
|
|
110
|
+
ax audit localhost:3000 --tunnel-cmd 'ora tunnel 3000 --access public' # ora's tunnel CLI (npm i -g @ora-ai/cli; ora login)
|
|
99
111
|
ax audit localhost:3000 --tunnel-cmd 'ngrok http 3000 --log stdout'
|
|
100
112
|
```
|
|
101
113
|
|
|
102
|
-
- **The CLI ships no tunnel vendor and never downloads executables at runtime** — any tunnel tool you already have works
|
|
103
|
-
-
|
|
114
|
+
- **The CLI ships no tunnel vendor and never downloads executables at runtime** — ora's own tunnel is first-party protocol code over Node's built-in WebSocket; any other tunnel tool you already have works through `--tunnel-cmd`, as long as it prints its public URL to stdout or stderr.
|
|
115
|
+
- With `ora tunnel`, `--access public` is required today: `protected` prints a tokenized link the scanner cannot use.
|
|
104
116
|
- Off-site checks (registry listings, brand search) usually fail for a throwaway tunnel hostname — the report says so. Use tunnel audits to iterate on your on-site surface, not to compare scores.
|
|
105
117
|
- Free tiers of some tunnel vendors serve an interstitial warning page to browser-like requests, which can distort what the scanner sees — prefer a vendor/plan that serves your origin directly.
|
|
106
118
|
|
|
@@ -351,10 +363,11 @@ A `.env` in the working directory is read on startup — copy `.env.example` and
|
|
|
351
363
|
| Var | Used by | Default | Purpose |
|
|
352
364
|
|---|---|---|---|
|
|
353
365
|
| `ORA_API_URL` | audit, deep-journey, skill | `https://ora.ai` | Public API base (no auth) |
|
|
354
|
-
| `ORA_PLATFORM_URL` | journey | `https://api.agentfront.sh` | Authenticated platform API base |
|
|
355
|
-
| `
|
|
366
|
+
| `ORA_PLATFORM_URL` | journey, audit `--tunnel ora` | `https://api.agentfront.sh` | Authenticated platform API base |
|
|
367
|
+
| `ORA_TUNNEL` | audit | — (optional) | `ora` opens ora's own tunnel for a local target (same as `--tunnel ora`) |
|
|
368
|
+
| `ORA_TUNNEL_CMD` | audit | — (optional) | Tunnel command for a local target (same as `--tunnel-cmd`); wins over `ORA_TUNNEL` |
|
|
356
369
|
| `ORA_API_URL` | webmcp-audit | `https://ora.ai` | Also the ingest base for `webmcp-audit` |
|
|
357
|
-
| `ORA_API_KEY` | journey, webmcp-audit | — (required for journey) | Secret key (`ora_sk_…`); journey
|
|
370
|
+
| `ORA_API_KEY` | journey, audit `--tunnel ora`, webmcp-audit | — (required for journey and `--tunnel ora`) | Secret key (`ora_sk_…`); journey and `--tunnel ora` exchange it for a bearer token (the tunnel needs the `tunnels:write` + `tunnels:connect` scopes), webmcp-audit sends it to lift the ingest rate limits |
|
|
358
371
|
| `ORA_SCAN_API_KEY` | audit, deep-journey | — (optional) | ora-issued scan API key; lifts every scan rate limit (issued manually by ora). deep-journey accepts it as a partner-key fallback |
|
|
359
372
|
| `ORA_PARTNER_API_KEY` | deep-journey | — (optional) | ora-issued partner API key; unlocks `--task` and the 1000/24h keyed allowance |
|
|
360
373
|
|
package/dist/api/audit.d.ts
CHANGED
|
@@ -1,7 +1,28 @@
|
|
|
1
1
|
import type { AuditScanResult, AuditScoreResult } from "../contract";
|
|
2
|
-
/**
|
|
2
|
+
/**
|
|
3
|
+
* Any failure to obtain a result from ora: network, HTTP, rate limit, timeout.
|
|
4
|
+
*
|
|
5
|
+
* `code` is the server's machine-readable reason where it gave one, so a
|
|
6
|
+
* caller can branch without matching on prose, and `payload` is the error
|
|
7
|
+
* object exactly as ora served it (what `--json` prints - invariant 4). Both
|
|
8
|
+
* are null/undefined for the failures ora has no code for.
|
|
9
|
+
*/
|
|
3
10
|
export declare class AuditApiError extends Error {
|
|
11
|
+
readonly code: string | null;
|
|
12
|
+
readonly payload: unknown;
|
|
13
|
+
constructor(message: string, options?: {
|
|
14
|
+
code?: string | null;
|
|
15
|
+
payload?: unknown;
|
|
16
|
+
});
|
|
4
17
|
}
|
|
18
|
+
/**
|
|
19
|
+
* ora's answer for a target whose MCP handshake needs credentials (contract
|
|
20
|
+
* 1.25.0): the scan is refused rather than scored, so there is no score to
|
|
21
|
+
* gate on. Not a failure - the CLI reports it and exits 0.
|
|
22
|
+
*/
|
|
23
|
+
export declare const MCP_AUTH_REQUIRED = "MCP_AUTH_REQUIRED";
|
|
24
|
+
/** True when ora refused the scan because the MCP server wants credentials. */
|
|
25
|
+
export declare function isMcpAuthRequired(error: unknown): error is AuditApiError;
|
|
5
26
|
/**
|
|
6
27
|
* The raw audit payload: scan-shaped from the stream's terminal event,
|
|
7
28
|
* score-shaped once deep-analysis polling has taken over.
|
package/dist/api/platform.d.ts
CHANGED
|
@@ -1,3 +1,5 @@
|
|
|
1
|
+
/** The platform API base: explicit override, else $ORA_PLATFORM_URL, else prod. */
|
|
2
|
+
export declare function platformBase(override?: string): string;
|
|
1
3
|
export interface RunSummary {
|
|
2
4
|
run_id: string;
|
|
3
5
|
domain?: string;
|
|
@@ -132,6 +134,7 @@ export interface JourneyRun {
|
|
|
132
134
|
/** The last trajectory snapshot seen — the definitive step list. */
|
|
133
135
|
trajectory: JourneyStep[];
|
|
134
136
|
}
|
|
137
|
+
export declare function exchangeKey(base: string, secret: string): Promise<string>;
|
|
135
138
|
export declare function decodeEventBlock(block: string): {
|
|
136
139
|
event: string;
|
|
137
140
|
data: string;
|
package/dist/api/shared.d.ts
CHANGED
|
@@ -9,6 +9,19 @@ export declare function watchdog(ms: number): {
|
|
|
9
9
|
disarm: () => void;
|
|
10
10
|
tripped: () => boolean;
|
|
11
11
|
};
|
|
12
|
+
/**
|
|
13
|
+
* Best-effort reading of an error response body: the human message, the
|
|
14
|
+
* server's machine-readable `code` where it gave one, and the parsed body
|
|
15
|
+
* itself. A caller that only branches on prose loses the code, and ora uses it
|
|
16
|
+
* to say things that are not failures (see MCP_AUTH_REQUIRED in ./audit).
|
|
17
|
+
* The body is read through a clone so the caller can still consume the
|
|
18
|
+
* original.
|
|
19
|
+
*/
|
|
20
|
+
export declare function errorBody(res: Response): Promise<{
|
|
21
|
+
message: string;
|
|
22
|
+
code: string | null;
|
|
23
|
+
payload: unknown;
|
|
24
|
+
}>;
|
|
12
25
|
/** Best-effort human message from an error response body. */
|
|
13
26
|
export declare function errorBodyText(res: Response): Promise<string>;
|
|
14
27
|
export declare const pause: (ms: number) => Promise<void>;
|
|
@@ -424,7 +424,7 @@ export interface components {
|
|
|
424
424
|
* @description The contract version this payload conforms to. SemVer: a major means a response-envelope break - a stable field removed, renamed, or changed in meaning, or the default response format flipping - and is safe to pin. Additive changes and check-catalog membership changes ship on a minor. See docs/api.md -> Contract and versioning.
|
|
425
425
|
* @enum {string}
|
|
426
426
|
*/
|
|
427
|
-
contractVersion: "1.
|
|
427
|
+
contractVersion: "1.25.0";
|
|
428
428
|
/**
|
|
429
429
|
* @description Present only when this body is a stored result served by the freshness gate instead of a fresh scan. Absent on a live scan.
|
|
430
430
|
* @enum {boolean}
|
|
@@ -433,7 +433,7 @@ export interface components {
|
|
|
433
433
|
/** @description Age of the served stored result in seconds (also sent as the Age response header). Present with servedFromCache. */
|
|
434
434
|
resultAgeSeconds?: number;
|
|
435
435
|
/**
|
|
436
|
-
* @description
|
|
436
|
+
* @description Legacy marker retained for compatibility with stored results. New authentication-required scans return an MCP_AUTH_REQUIRED error without score or grade; public reads of a historical marked result return the same error.
|
|
437
437
|
* @enum {boolean}
|
|
438
438
|
*/
|
|
439
439
|
mcpAuthRequired?: true;
|
|
@@ -623,11 +623,11 @@ export interface components {
|
|
|
623
623
|
* @description The contract version this payload conforms to. SemVer: a major means a response-envelope break - a stable field removed, renamed, or changed in meaning, or the default response format flipping - and is safe to pin. Additive changes and check-catalog membership changes ship on a minor. See docs/api.md -> Contract and versioning.
|
|
624
624
|
* @enum {string}
|
|
625
625
|
*/
|
|
626
|
-
contractVersion: "1.
|
|
626
|
+
contractVersion: "1.25.0";
|
|
627
627
|
/** @description Wall-clock duration of the scan that produced this stored result */
|
|
628
628
|
durationMs: number | null;
|
|
629
629
|
/**
|
|
630
|
-
* @description
|
|
630
|
+
* @description Legacy marker retained for compatibility with stored results. New authentication-required scans return an MCP_AUTH_REQUIRED error without score or grade; public reads of a historical marked result return the same error.
|
|
631
631
|
* @enum {boolean}
|
|
632
632
|
*/
|
|
633
633
|
mcpAuthRequired?: true;
|
|
@@ -667,7 +667,7 @@ export interface components {
|
|
|
667
667
|
* @description The contract version this catalog conforms to - identical to the OpenAPI info.version and the MCP server version. SemVer: a major means a response-envelope break (a stable field, or a layer id, removed or renamed or changed in meaning, or the default response format flipping) and is safe to pin; check-catalog membership changes ship on a minor. The full versioning policy is published in the API description at /api/openapi.json.
|
|
668
668
|
* @enum {string}
|
|
669
669
|
*/
|
|
670
|
-
contractVersion: "1.
|
|
670
|
+
contractVersion: "1.25.0";
|
|
671
671
|
/** @description The four scored layers in scoring order, with display name and current weight. */
|
|
672
672
|
layers: {
|
|
673
673
|
/** @description Stable layer id: discovery, accessibility, usability, or payments. Removing or renaming a layer id is a major version change. Note one intentional divergence: the id 'accessibility' carries the display name 'Access'. */
|
|
@@ -757,7 +757,7 @@ export interface components {
|
|
|
757
757
|
url: string;
|
|
758
758
|
/** @description Array of check ids from GET /api/checks - one id minimum, up to the catalogued check count. Duplicate ids are deduplicated; ids the catalog does not list are rejected with error code UNKNOWN_CHECK_IDS. */
|
|
759
759
|
checkIds: string[];
|
|
760
|
-
/** @description Optional URL of the target's MCP server, matching the same field on POST /api/scan. When omitted, ora auto-discovers MCP endpoints. An empty string is treated as absent. */
|
|
760
|
+
/** @description Optional URL of the target's MCP server, matching the same field on POST /api/scan. It pins the MCP endpoint; a failed handshake never substitutes a discovered server. When omitted, ora auto-discovers MCP endpoints. An empty string is treated as absent. */
|
|
761
761
|
mcpUrl?: unknown;
|
|
762
762
|
};
|
|
763
763
|
/** @description The outcome of a selective check run. The run always executes - results are never served from a cache. The response carries no aggregate score of any kind: per-check score and maxScore only, with GET /api/score/{domain} as the score surface. Results carry no tier or layer fields - join with GET /api/checks by id to group or rank them. */
|
|
@@ -766,7 +766,7 @@ export interface components {
|
|
|
766
766
|
* @description The contract version this response conforms to - identical to the OpenAPI info.version and the MCP server version. The full versioning policy is published in the API description at /api/openapi.json.
|
|
767
767
|
* @enum {string}
|
|
768
768
|
*/
|
|
769
|
-
contractVersion: "1.
|
|
769
|
+
contractVersion: "1.25.0";
|
|
770
770
|
/** @description The apex domain derived from the requested URL. */
|
|
771
771
|
domain: string;
|
|
772
772
|
/** @description The normalized URL the run targeted. */
|
|
@@ -1983,7 +1983,7 @@ export interface components {
|
|
|
1983
1983
|
* @enum {string}
|
|
1984
1984
|
*/
|
|
1985
1985
|
urlKind?: "domain" | "mcp" | "mcp-app" | "ephemeral";
|
|
1986
|
-
/** @description
|
|
1986
|
+
/** @description Legacy marker retained for compatibility. New authentication-required scans and reads of historical marked results return HTTP 422 MCP_AUTH_REQUIRED without score or grade. */
|
|
1987
1987
|
mcpAuthRequired?: boolean;
|
|
1988
1988
|
/**
|
|
1989
1989
|
* @description Present (and always true) only when POST /api/scan answered from the freshness window with a stored result instead of running a scan. Absent on a live scan and on GET /api/score/{domain}, which is always a cached read.
|
|
@@ -2161,6 +2161,18 @@ export interface components {
|
|
|
2161
2161
|
/** @description Optional recovery hint (e.g. /api/scan on NOT_FOUND). */
|
|
2162
2162
|
next?: string;
|
|
2163
2163
|
};
|
|
2164
|
+
McpAuthRequiredResponse: {
|
|
2165
|
+
/** @description Why the MCP server could not be inspected. */
|
|
2166
|
+
error: string;
|
|
2167
|
+
/** @constant */
|
|
2168
|
+
code: "MCP_AUTH_REQUIRED";
|
|
2169
|
+
/** @constant */
|
|
2170
|
+
mcpAuthRequired: true;
|
|
2171
|
+
/** @description The MCP endpoint that required authentication. */
|
|
2172
|
+
mcpUrl: string;
|
|
2173
|
+
/** @enum {string} */
|
|
2174
|
+
urlKind: "mcp" | "mcp-app";
|
|
2175
|
+
};
|
|
2164
2176
|
/**
|
|
2165
2177
|
* @description ora's house error envelope. `error` is always present; the other fields depend on which guard rejected the request, so a client should branch on `code` / `retry_after_ms` being present rather than assume them.
|
|
2166
2178
|
* @example {
|
|
@@ -2284,7 +2296,7 @@ export interface operations {
|
|
|
2284
2296
|
*/
|
|
2285
2297
|
url: string;
|
|
2286
2298
|
/**
|
|
2287
|
-
* @description Optional MCP server URL to
|
|
2299
|
+
* @description Optional MCP server URL to inspect as the sole MCP target. A failed endpoint is never replaced by a discovered server
|
|
2288
2300
|
* @example
|
|
2289
2301
|
*/
|
|
2290
2302
|
mcpUrl?: string;
|
|
@@ -2335,6 +2347,12 @@ export interface operations {
|
|
|
2335
2347
|
"application/json": components["schemas"]["ErrorResponse"];
|
|
2336
2348
|
};
|
|
2337
2349
|
};
|
|
2350
|
+
/** @description MCP authentication is required. No score or grade was produced. The failed attempt does not overwrite a previous measured scan. */
|
|
2351
|
+
422: {
|
|
2352
|
+
content: {
|
|
2353
|
+
"application/json": components["schemas"]["McpAuthRequiredResponse"];
|
|
2354
|
+
};
|
|
2355
|
+
};
|
|
2338
2356
|
/** @description Rate limit exceeded - either the 10-per-minute burst cap or the durable daily quota (30 scans per rolling 24h per IP; 6 per day for force=true). Cache-served responses never count against the daily quota. The response includes a Retry-After header indicating seconds until the next request is allowed, and a JSON body with error and retry_after_ms. */
|
|
2339
2357
|
429: {
|
|
2340
2358
|
headers: {
|
|
@@ -2444,7 +2462,7 @@ export interface operations {
|
|
|
2444
2462
|
query: {
|
|
2445
2463
|
/** @description The domain, MCP server URL, or MCP app URL to scan. The server detects which kind of input was provided and runs the appropriate check set. */
|
|
2446
2464
|
domain: string;
|
|
2447
|
-
/** @description Optional
|
|
2465
|
+
/** @description Optional MCP server URL to inspect as the sole MCP target; it is never replaced by a discovered server */
|
|
2448
2466
|
mcp?: string;
|
|
2449
2467
|
/** @description Same freshness window as POST /api/scan: how stale a stored result may be and still be streamed back instead of running a new scan. Defaults to 21600 (6 hours), clamped to [3600, 86400]. */
|
|
2450
2468
|
maxAgeSeconds?: number;
|
|
@@ -2457,7 +2475,7 @@ export interface operations {
|
|
|
2457
2475
|
};
|
|
2458
2476
|
};
|
|
2459
2477
|
responses: {
|
|
2460
|
-
/** @description Server-Sent Events stream of scan progress. With `?format=audit`, the terminal `scan_complete` event's `result` is `#/components/schemas/AuditScanResult`; every other event is unchanged. When a stored result inside the freshness window answers the request, the stream is a `kind_detected` frame followed by a terminal `scan_complete` event carrying `servedFromCache: true` and `resultAgeSeconds`, and the response carries an `Age` header. */
|
|
2478
|
+
/** @description Server-Sent Events stream of scan progress. If MCP authentication is required, the stream ends with an error event carrying code MCP_AUTH_REQUIRED, mcpAuthRequired: true, mcpUrl and urlKind, without scan_complete or a score. With `?format=audit`, the terminal `scan_complete` event's `result` is `#/components/schemas/AuditScanResult`; every other event is unchanged. When a stored result inside the freshness window answers the request, the stream is a `kind_detected` frame followed by a terminal `scan_complete` event carrying `servedFromCache: true` and `resultAgeSeconds`, and the response carries an `Age` header. */
|
|
2461
2479
|
200: {
|
|
2462
2480
|
content: {
|
|
2463
2481
|
"text/event-stream": string;
|
|
@@ -2558,6 +2576,12 @@ export interface operations {
|
|
|
2558
2576
|
"application/json": components["schemas"]["NotScannedResponse"];
|
|
2559
2577
|
};
|
|
2560
2578
|
};
|
|
2579
|
+
/** @description MCP authentication is required. No score or grade was produced. The failed attempt does not overwrite a previous measured scan. */
|
|
2580
|
+
422: {
|
|
2581
|
+
content: {
|
|
2582
|
+
"application/json": components["schemas"]["McpAuthRequiredResponse"];
|
|
2583
|
+
};
|
|
2584
|
+
};
|
|
2561
2585
|
/** @description Rate limit exceeded - max 10 requests per minute per IP. The response carries a Retry-After header with the seconds until the oldest request in the window ages out. */
|
|
2562
2586
|
429: {
|
|
2563
2587
|
headers: {
|
|
@@ -1,2 +1,2 @@
|
|
|
1
1
|
/** The ora contract version (spec info.version) these types were generated from. */
|
|
2
|
-
export declare const BUILT_AGAINST = "1.
|
|
2
|
+
export declare const BUILT_AGAINST = "1.25.0";
|
package/dist/index.cjs
CHANGED
|
@@ -35,7 +35,7 @@ __export(src_exports, {
|
|
|
35
35
|
module.exports = __toCommonJS(src_exports);
|
|
36
36
|
|
|
37
37
|
// src/contract/version.ts
|
|
38
|
-
var BUILT_AGAINST = "1.
|
|
38
|
+
var BUILT_AGAINST = "1.25.0";
|
|
39
39
|
|
|
40
40
|
// src/contract/index.ts
|
|
41
41
|
function minor(version) {
|
|
@@ -78,13 +78,22 @@ function watchdog(ms) {
|
|
|
78
78
|
tripped: () => fired
|
|
79
79
|
};
|
|
80
80
|
}
|
|
81
|
-
async function
|
|
81
|
+
async function errorBody(res) {
|
|
82
|
+
let payload = null;
|
|
82
83
|
try {
|
|
83
|
-
|
|
84
|
-
return payload.message || payload.error || `HTTP ${res.status}`;
|
|
84
|
+
payload = await res.clone().json();
|
|
85
85
|
} catch {
|
|
86
|
-
return `HTTP ${res.status}`;
|
|
87
86
|
}
|
|
87
|
+
res.body?.cancel().catch(() => {
|
|
88
|
+
});
|
|
89
|
+
return {
|
|
90
|
+
message: payload?.message || payload?.error || `HTTP ${res.status}`,
|
|
91
|
+
code: payload?.code ?? null,
|
|
92
|
+
payload
|
|
93
|
+
};
|
|
94
|
+
}
|
|
95
|
+
async function errorBodyText(res) {
|
|
96
|
+
return (await errorBody(res)).message;
|
|
88
97
|
}
|
|
89
98
|
var pause = (ms) => new Promise((r) => setTimeout(r, ms));
|
|
90
99
|
|
|
@@ -95,6 +104,14 @@ var POLL_EVERY_MS = 2e3;
|
|
|
95
104
|
var POLL_LIMIT = 45;
|
|
96
105
|
var BAR_CELLS = 14;
|
|
97
106
|
var AuditApiError = class extends Error {
|
|
107
|
+
code;
|
|
108
|
+
payload;
|
|
109
|
+
constructor(message, options = {}) {
|
|
110
|
+
super(message);
|
|
111
|
+
this.name = "AuditApiError";
|
|
112
|
+
this.code = options.code ?? null;
|
|
113
|
+
this.payload = options.payload;
|
|
114
|
+
}
|
|
98
115
|
};
|
|
99
116
|
function authHeaders(apiKey) {
|
|
100
117
|
return apiKey ? { authorization: `Bearer ${apiKey}` } : {};
|
|
@@ -142,7 +159,11 @@ async function consumeScanStream(base, target, options) {
|
|
|
142
159
|
}
|
|
143
160
|
if (!res.ok || !res.body) {
|
|
144
161
|
dog.disarm();
|
|
145
|
-
|
|
162
|
+
const body = await errorBody(res);
|
|
163
|
+
throw new AuditApiError(`ora audit failed: ${body.message}`, {
|
|
164
|
+
code: body.code,
|
|
165
|
+
payload: body.payload
|
|
166
|
+
});
|
|
146
167
|
}
|
|
147
168
|
const narrate = progressNarrator();
|
|
148
169
|
const utf8 = new TextDecoder();
|
|
@@ -172,7 +193,8 @@ async function consumeScanStream(base, target, options) {
|
|
|
172
193
|
if (line) options.progress?.(line);
|
|
173
194
|
if (event.type === "error") {
|
|
174
195
|
throw new AuditApiError(
|
|
175
|
-
`ora audit failed: ${typeof event.message === "string" ? event.message : "scan error"}
|
|
196
|
+
`ora audit failed: ${typeof event.message === "string" ? event.message : "scan error"}`,
|
|
197
|
+
{ code: typeof event.code === "string" ? event.code : null, payload: event }
|
|
176
198
|
);
|
|
177
199
|
}
|
|
178
200
|
if (event.type === "scan_complete" && event.result) {
|
package/dist/index.js
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
// src/contract/version.ts
|
|
2
|
-
var BUILT_AGAINST = "1.
|
|
2
|
+
var BUILT_AGAINST = "1.25.0";
|
|
3
3
|
|
|
4
4
|
// src/contract/index.ts
|
|
5
5
|
function minor(version) {
|
|
@@ -42,13 +42,22 @@ function watchdog(ms) {
|
|
|
42
42
|
tripped: () => fired
|
|
43
43
|
};
|
|
44
44
|
}
|
|
45
|
-
async function
|
|
45
|
+
async function errorBody(res) {
|
|
46
|
+
let payload = null;
|
|
46
47
|
try {
|
|
47
|
-
|
|
48
|
-
return payload.message || payload.error || `HTTP ${res.status}`;
|
|
48
|
+
payload = await res.clone().json();
|
|
49
49
|
} catch {
|
|
50
|
-
return `HTTP ${res.status}`;
|
|
51
50
|
}
|
|
51
|
+
res.body?.cancel().catch(() => {
|
|
52
|
+
});
|
|
53
|
+
return {
|
|
54
|
+
message: payload?.message || payload?.error || `HTTP ${res.status}`,
|
|
55
|
+
code: payload?.code ?? null,
|
|
56
|
+
payload
|
|
57
|
+
};
|
|
58
|
+
}
|
|
59
|
+
async function errorBodyText(res) {
|
|
60
|
+
return (await errorBody(res)).message;
|
|
52
61
|
}
|
|
53
62
|
var pause = (ms) => new Promise((r) => setTimeout(r, ms));
|
|
54
63
|
|
|
@@ -59,6 +68,14 @@ var POLL_EVERY_MS = 2e3;
|
|
|
59
68
|
var POLL_LIMIT = 45;
|
|
60
69
|
var BAR_CELLS = 14;
|
|
61
70
|
var AuditApiError = class extends Error {
|
|
71
|
+
code;
|
|
72
|
+
payload;
|
|
73
|
+
constructor(message, options = {}) {
|
|
74
|
+
super(message);
|
|
75
|
+
this.name = "AuditApiError";
|
|
76
|
+
this.code = options.code ?? null;
|
|
77
|
+
this.payload = options.payload;
|
|
78
|
+
}
|
|
62
79
|
};
|
|
63
80
|
function authHeaders(apiKey) {
|
|
64
81
|
return apiKey ? { authorization: `Bearer ${apiKey}` } : {};
|
|
@@ -106,7 +123,11 @@ async function consumeScanStream(base, target, options) {
|
|
|
106
123
|
}
|
|
107
124
|
if (!res.ok || !res.body) {
|
|
108
125
|
dog.disarm();
|
|
109
|
-
|
|
126
|
+
const body = await errorBody(res);
|
|
127
|
+
throw new AuditApiError(`ora audit failed: ${body.message}`, {
|
|
128
|
+
code: body.code,
|
|
129
|
+
payload: body.payload
|
|
130
|
+
});
|
|
110
131
|
}
|
|
111
132
|
const narrate = progressNarrator();
|
|
112
133
|
const utf8 = new TextDecoder();
|
|
@@ -136,7 +157,8 @@ async function consumeScanStream(base, target, options) {
|
|
|
136
157
|
if (line) options.progress?.(line);
|
|
137
158
|
if (event.type === "error") {
|
|
138
159
|
throw new AuditApiError(
|
|
139
|
-
`ora audit failed: ${typeof event.message === "string" ? event.message : "scan error"}
|
|
160
|
+
`ora audit failed: ${typeof event.message === "string" ? event.message : "scan error"}`,
|
|
161
|
+
{ code: typeof event.code === "string" ? event.code : null, payload: event }
|
|
140
162
|
);
|
|
141
163
|
}
|
|
142
164
|
if (event.type === "scan_complete" && event.result) {
|