ax 0.7.4 → 0.8.0

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 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`, which exchanges
7
- # it for a short-lived bearer token. `webmcp-audit` sends it as a bearer token to
8
- # lift the anonymous ingest limits (10/min, 20 per 24h per IP); optional there.
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
- # Tunnel command for auditing a local target (same as --tunnel-cmd):
20
- # a command that exposes the local server and prints its public https URL.
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/LICENSE CHANGED
@@ -1,6 +1,6 @@
1
1
  MIT License
2
2
 
3
- Copyright (c) 2026 era labs
3
+ Copyright (c) 2026 Era AI Labs
4
4
 
5
5
  Permission is hereby granted, free of charge, to any person obtaining a copy
6
6
  of this software and associated documentation files (the "Software"), to deal
package/README.md CHANGED
@@ -1,23 +1,41 @@
1
- # ax — the ora CLI
1
+ <p align="center">
2
+ <a href="https://ora.ai"><img src="https://raw.githubusercontent.com/ora/ax/main/.github/assets/ora-mark.svg" width="72" height="72" alt="ora" /></a>
3
+ </p>
2
4
 
3
- Score any site's agent readiness — and watch real AI agents navigate it. Powered by [ora](https://ora.ai)'s hosted APIs.
5
+ <h1 align="center">ax</h1>
6
+
7
+ <p align="center">Score any site's agent readiness from your terminal or CI — and watch real AI agents navigate it.<br />The open-source CLI for <a href="https://ora.ai">ora</a>.</p>
8
+
9
+ <p align="center">
10
+ <a href="https://www.npmjs.com/package/ax"><img src="https://img.shields.io/npm/v/ax?label=npm&color=14B8A6" alt="npm version" /></a>
11
+ <a href="https://www.npmjs.com/package/ax"><img src="https://img.shields.io/npm/dm/ax?color=14B8A6" alt="npm downloads" /></a>
12
+ <a href="https://github.com/ora/ax/actions/workflows/ci.yml"><img src="https://github.com/ora/ax/actions/workflows/ci.yml/badge.svg?branch=main" alt="CI" /></a>
13
+ <a href="https://www.npmjs.com/package/ax#provenance"><img src="https://img.shields.io/badge/npm-provenance-14B8A6" alt="npm provenance" /></a>
14
+ <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-1A1A1A" alt="MIT license" /></a>
15
+ </p>
4
16
 
5
17
  ```
6
18
  npx ax audit https://stripe.com
7
19
  ```
8
20
 
21
+ **No account, no API key.** Everything below works out of the box — the one exception is [`journey`](#for-ora-partners), which drives ora's partner platform.
22
+
23
+ <p align="center">
24
+ <img src="https://raw.githubusercontent.com/ora/ax/main/.github/assets/demo.gif" width="880" alt="ax audit https://stripe.com — live progress, then the layered report and ora's ranked top fixes" />
25
+ </p>
26
+
9
27
  Five commands:
10
28
 
11
29
  - **`audit <url>`** — run ora's hosted agent-readiness audit against a site: live progress, then a layered report of what passed, what's broken, and ora's ranked list of the highest-impact fixes (or `--json` for the raw contract payload). No account or API key needed. Gate CI with `--min-score`.
12
30
  - **`webmcp-audit <url>`** — audit a page's `document.modelContext` tools in a real browser. Works on any http(s) URL, localhost included, so you can check a surface before you publish it. Measures the page the way ora's capture worker does and has ora score it; nothing is stored, published, or ranked.
13
31
  - **`deep-journey <url>`** — run a real AI agent at a site on one of ora's curated tasks through the public journey API: no key, no workspace. A partner API key unlocks free-text tasks (`--task`) and a larger allowance.
14
- - **`journey "<intent>"`** — send a real AI agent (claude-code, codex, …) at a site and watch its navigation live as a boxed node-graph, then get the scored insight, tokens, and cost. Requires an `ORA_API_KEY`.
32
+ - **`journey "<intent>"`** — send a real AI agent (claude-code, codex, …) at a site and watch its navigation live as a boxed node-graph, then get the scored insight, tokens, and cost. Partner-only: needs an `ORA_API_KEY` (see [For ora partners](#for-ora-partners)).
15
33
  - **`skill [name]`** — list, print, or install ora's agent skills, digest-verified from the public registry.
16
34
 
17
35
  ## audit
18
36
 
19
37
  ```
20
- 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]
21
39
  ```
22
40
 
23
41
  ```
@@ -47,7 +65,8 @@ ax audit <url> [--min-score n] [--max-age s] [--force] [--tunnel-cmd c] [--api-k
47
65
  | `--min-score <n>` | Exit `1` when the score is below `n` (0-100) — the CI gate |
48
66
  | `--max-age <s>` | Accept a cached result up to `s` seconds old (server default 6h, clamped to 1-24h) |
49
67
  | `--force` | Bypass the cache and rescan — spends the stricter 6/day force budget |
50
- | `--tunnel-cmd <c>` | Expose a local target through your own tunnel command and audit the public URL it prints (also read from `ORA_TUNNEL_CMD`) |
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`) |
51
70
  | `--api-key <k>` | ora-issued scan API key — lifts every scan rate limit (also read from `ORA_SCAN_API_KEY`) |
52
71
  | `--json` | The raw ora audit payload on stdout, exactly as the API served it |
53
72
  | `--show-passing` | List every passing check, not just the per-layer summary bar |
@@ -73,16 +92,27 @@ Exit codes are the contract:
73
92
 
74
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 reports `mcpAuthRequired` and scores 0 as "could not evaluate"; `--min-score` deliberately skips the gate rather than failing on it.
75
94
 
76
- ### Auditing localhost (`--tunnel-cmd`)
95
+ ### Auditing localhost (`--tunnel ora`, `--tunnel-cmd`)
96
+
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.
77
106
 
78
- 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, bring your own tunnel: pass `--tunnel-cmd` (or set `ORA_TUNNEL_CMD`) with a 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.
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:
79
108
 
80
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)
81
111
  ax audit localhost:3000 --tunnel-cmd 'ngrok http 3000 --log stdout'
82
112
  ```
83
113
 
84
- - **The CLI ships no tunnel vendor and never downloads executables at runtime** — any tunnel tool you already have works, as long as it prints its public URL to stdout or stderr.
85
- - The result is stored as **ephemeral**: excluded from ora's rankings and deleted after a few days.
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.
86
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.
87
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.
88
118
 
@@ -229,7 +259,41 @@ ax skill --json # the raw registry index
229
259
 
230
260
  Skills come from ora's public registry (`https://ora.ai/.well-known/agent-skills/`) and every byte is verified against the registry's sha256 digest before it is printed or installed. Skill content is never bundled into this package. `--dir <path>` overrides the install directory, and `--json` prints the registry index as JSON instead of the formatted list.
231
261
 
232
- ## journey
262
+ ## Library use
263
+
264
+ The same contract-typed client the CLI uses is importable:
265
+
266
+ ```ts
267
+ import { audit } from "ax";
268
+
269
+ const { result } = await audit("stripe.com");
270
+ console.log(result.score, result.grade, result.topFixes);
271
+ ```
272
+
273
+ `result` is the raw versioned audit payload (`AuditScanResult` / `AuditScoreResult`, generated from ora's OpenAPI spec). `fetchSkill` / `fetchSkillIndex` expose the digest-verified skill registry.
274
+
275
+ The public journey client is exported too — the same no-key path as `ax deep-journey`:
276
+
277
+ ```ts
278
+ import { deepJourney, fetchJourneyAgents } from "ax";
279
+
280
+ const { agents, defaultId } = await fetchJourneyAgents();
281
+ const agent = agents.find((a) => a.id === defaultId)!;
282
+ const { detail } = await deepJourney("stripe.com", {
283
+ intentId: "pricing",
284
+ harness: agent.harness,
285
+ model: agent.model,
286
+ });
287
+ console.log(detail.verdict, detail.step_count, detail.result?.insight.summary);
288
+ ```
289
+
290
+ `detail` is the contract's `JourneyRunDetail`; `fetchJourneyIntents` lists the curated intents. The same public caps apply — a capped target resolves with the most recent stored run (`cached: true` on the outcome), not an error.
291
+
292
+ ## For ora partners
293
+
294
+ Everything above runs without an account. The commands and flags in this section are for teams working with ora directly: they need an ora-issued API key, and there is no self-serve signup — keys are issued by ora (contact [hello@ora.ai](mailto:hello@ora.ai)). A partner key also lifts the anonymous rate limits on `audit`, `webmcp-audit`, and `deep-journey` via their `--api-key` flags.
295
+
296
+ ### journey
233
297
 
234
298
  ```
235
299
  ax journey "<intent>" [--domain d] [--harness h] [--model m] [--json]
@@ -279,7 +343,7 @@ Note: run-to-run variance is real — agents sometimes answer from search snippe
279
343
 
280
344
  Journey exit codes: `0` run outcome `success` · `1` non-success outcome · `2` any error.
281
345
 
282
- ### Setup
346
+ #### Setup
283
347
 
284
348
  `journey` needs an ora platform API key (scopes `runs:read` + `runs:write`):
285
349
 
@@ -290,36 +354,6 @@ ax journey "Find the pricing page" --domain example.com
290
354
 
291
355
  For local development, copy `.env.example` to `.env` — the CLI reads a `.env` in the working directory on startup (exported variables win over the file).
292
356
 
293
- ## Library use
294
-
295
- The same contract-typed client the CLI uses is importable:
296
-
297
- ```ts
298
- import { audit } from "ax";
299
-
300
- const { result } = await audit("stripe.com");
301
- console.log(result.score, result.grade, result.topFixes);
302
- ```
303
-
304
- `result` is the raw versioned audit payload (`AuditScanResult` / `AuditScoreResult`, generated from ora's OpenAPI spec). `fetchSkill` / `fetchSkillIndex` expose the digest-verified skill registry.
305
-
306
- The public journey client is exported too — the same no-key path as `ax deep-journey`:
307
-
308
- ```ts
309
- import { deepJourney, fetchJourneyAgents } from "ax";
310
-
311
- const { agents, defaultId } = await fetchJourneyAgents();
312
- const agent = agents.find((a) => a.id === defaultId)!;
313
- const { detail } = await deepJourney("stripe.com", {
314
- intentId: "pricing",
315
- harness: agent.harness,
316
- model: agent.model,
317
- });
318
- console.log(detail.verdict, detail.step_count, detail.result?.insight.summary);
319
- ```
320
-
321
- `detail` is the contract's `JourneyRunDetail`; `fetchJourneyIntents` lists the curated intents. The same public caps apply — a capped target resolves with the most recent stored run (`cached: true` on the outcome), not an error.
322
-
323
357
  ## Environment variables
324
358
 
325
359
  All configuration is environment-first: the consumer defines the variables, the CLI only reads them.
@@ -329,10 +363,11 @@ A `.env` in the working directory is read on startup — copy `.env.example` and
329
363
  | Var | Used by | Default | Purpose |
330
364
  |---|---|---|---|
331
365
  | `ORA_API_URL` | audit, deep-journey, skill | `https://ora.ai` | Public API base (no auth) |
332
- | `ORA_PLATFORM_URL` | journey | `https://api.agentfront.sh` | Authenticated platform API base |
333
- | `ORA_TUNNEL_CMD` | audit | — (optional) | Tunnel command for a local target (same as `--tunnel-cmd`) |
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` |
334
369
  | `ORA_API_URL` | webmcp-audit | `https://ora.ai` | Also the ingest base for `webmcp-audit` |
335
- | `ORA_API_KEY` | journey, webmcp-audit | — (required for journey) | Secret key (`ora_sk_…`); journey exchanges it for a bearer token, webmcp-audit sends it to lift the ingest rate limits |
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 |
336
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 |
337
372
  | `ORA_PARTNER_API_KEY` | deep-journey | — (optional) | ora-issued partner API key; unlocks `--task` and the 1000/24h keyed allowance |
338
373
 
@@ -390,13 +425,14 @@ The webmcp mock replays the checked-in real ingest fixture, and takes a failure
390
425
  argument — `shim`, `rate`, `scoring` or `stream` — so every error branch is reachable without the
391
426
  live endpoint.
392
427
 
393
- To exercise the published-package experience locally: `npm pack`, then `npx ./ora-ai-ax-<version>.tgz audit https://example.com`, or `pnpm link --global` and use `ax` directly.
428
+ To exercise the published-package experience locally: `npm pack`, then `npx ./ax-<version>.tgz audit https://example.com`, or `pnpm link --global` and use `ax` directly.
394
429
 
395
430
  ## Releasing
396
431
 
397
- Publishing runs from GitHub Actions only — **Actions → Release → Run workflow**,
398
- pick a `patch`/`minor`/`major` bump. See [RELEASING.md](RELEASING.md) for the
399
- runbook, required setup, and failure recovery.
432
+ Publishing runs from GitHub Actions only. Every push to `main` updates a
433
+ release-please PR; merging it tags, creates the GitHub Release, and publishes
434
+ to npm with provenance. See [RELEASING.md](RELEASING.md) for the runbook,
435
+ required setup, and failure recovery.
400
436
 
401
437
  ## License
402
438
 
@@ -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;
@@ -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.24.0";
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 Present when an MCP-family scan short-circuited because the server's handshake demanded credentials (401/403). Score 0 with empty layers then means 'could not evaluate', NOT 'failed everything' - treat the target as unscored rather than failing a gate on it.
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.24.0";
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 Present when an MCP-family scan short-circuited because the server's handshake demanded credentials (401/403). Score 0 with empty layers then means 'could not evaluate', NOT 'failed everything' - treat the target as unscored rather than failing a gate on it.
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.24.0";
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.24.0";
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 Optional. True when an MCP-family scan (urlKind 'mcp' or 'mcp-app') was short-circuited because the server returned 401/403 on the handshake. When set, 'layers' is empty and 'score' is 0; ora cannot evaluate agent-readiness for auth-gated MCP servers. UI surfaces an auth-required notice instead of the score hero. */
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 test
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 explicit MCP server URL to test alongside the scan */
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.24.0";
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.24.0";
38
+ var BUILT_AGAINST = "1.25.0";
39
39
 
40
40
  // src/contract/index.ts
41
41
  function minor(version) {
package/dist/index.js CHANGED
@@ -1,5 +1,5 @@
1
1
  // src/contract/version.ts
2
- var BUILT_AGAINST = "1.24.0";
2
+ var BUILT_AGAINST = "1.25.0";
3
3
 
4
4
  // src/contract/index.ts
5
5
  function minor(version) {