@quickback-dev/cli 0.46.0 → 0.47.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.
@@ -19,54 +19,46 @@ a stable, greppable **code**:
19
19
  [quickback:authz] AUTHZ_EMPTY_PERMISSION: permission "event:locked" can never be satisfied — it requires organizerOf AND its negation simultaneously.
20
20
  at resource=sessions authz.permissions["event:locked"]
21
21
  hint: Remove the contradictory arm, or split into separate permissions.
22
+ override: authz: { analyzer: { allow: [{ check: 'AUTHZ_EMPTY_PERMISSION', target: 'event:locked', reason: '<why this is acceptable>' }] } }
22
23
  ```
23
24
 
24
25
  The first line stays greppable (`[quickback:<channel>] CODE: message`); the
25
- source location and fix hint render on continuation lines.
26
+ source location, fix hint, and — for promoted errors — the exact override
27
+ recipe render on continuation lines.
26
28
 
27
- ## Warn by default, opt-in strict
29
+ ## Errors vs warnings (v0.47+)
28
30
 
29
- The analyzer is **warn-by-default, compile-continues**. This is deliberate:
30
- the analyzer runs on the shared compiler that serves every project, so a new
31
- check must never break an existing build on upgrade. In the default path
32
- every diagnostic — *including* the one check authored at `error` severity
33
- (the capability ceiling) — is rendered as a warning line and the compile
34
- proceeds.
31
+ The checks split into two tiers:
35
32
 
36
- Set **`QUICKBACK_AUTHZ_STRICT=true`** to promote every `warn` to `error`.
37
- Under strict mode the compile **fails** (throws an aggregate error listing the
38
- codes) if any diagnostic is — after promotion — an error. `info` lines
39
- (the pushdown-cost report) stay informational and never fail a build.
33
+ - **Promoted (compile errors).** A trip is a *definite misconfiguration* —
34
+ never a legitimate config. These fail the build by default. Each one can be
35
+ explicitly accepted per finding via
36
+ [`authz.analyzer.allow`](#the-override-surface).
37
+ - **Heuristic (warnings) and reports (info).** Advisory findings where a
38
+ legitimate config could trip the detector. These print and the compile
39
+ continues. Set **`QUICKBACK_AUTHZ_STRICT=true`** to promote these warnings
40
+ to errors as well (overridden findings stay warnings even under strict —
41
+ an override is an explicit, reasoned acceptance).
40
42
 
41
- ```bash
42
- # warn-only (default): prints diagnostics, compile succeeds
43
- quickback compile
44
-
45
- # strict: any warn or error fails the compile
46
- QUICKBACK_AUTHZ_STRICT=true quickback compile
47
- ```
48
-
49
- > The analyzer is compile-time only — zero runtime blast radius. A defect in
50
- > the analyzer itself is caught and downgraded to a single warning in the
51
- > default path, so an analyzer bug can never take down an otherwise-valid
52
- > compile. (Strict mode re-raises, because there the throw is the intended
53
- > hard failure.)
43
+ The analyzer remains compile-time only — zero runtime blast radius. A defect
44
+ in the analyzer *itself* is caught and downgraded to a single warning, so an
45
+ analyzer bug can never take down an otherwise-valid compile. Only real
46
+ findings fail builds.
54
47
 
55
48
  ## Authz codes
56
49
 
57
- These read the permission graph projected from the policy IR. All are `warn`
58
- severity (so `info` for the pushdown report) **except** the capability ceiling,
59
- which is authored as `error`.
50
+ These read the permission graph projected from the policy IR and run on every
51
+ compile.
60
52
 
61
- | Code | Severity | What it catches |
53
+ | Code | Tier | What it catches |
62
54
  |---|---|---|
63
- | `AUTHZ_EMPTY_PERMISSION` | warn | A permission that can never be satisfied — e.g. `allOf(a, not(a))`, which requires a fact and its negation at the same AND-level. |
55
+ | `AUTHZ_EMPTY_PERMISSION` | **error** | A permission that can never be satisfied — `allOf(a, not(a))`, a fact and its exact negation at the same AND-level. The detector is conservative (exact-leaf contradictions only), so a trip is structurally unsatisfiable. |
56
+ | `AUTHZ_CAPABILITY_CEILING` | **error** | A resource's firewall grants a `scope:<kind>:<role>` role read access **beyond its capability profile** — either the role has no profile at all, or the profile doesn't list this resource. The M0.2 pillar guarantee. |
64
57
  | `AUTHZ_SHADOWED_ARM` | warn | An `anyOf` arm subsumed by a broader arm: a leaf `X` and an `allOf(X, …)` in the same union — the narrower arm can never widen the result. |
65
- | `AUTHZ_UNREACHABLE_ROLE` | warn | A scoped role declared under `authz.scopes` with **no grant profile** — it can authorize no read, action, or channel, so it's dead config. |
66
- | `AUTHZ_UNREACHABLE_VIEW` | warn | A grant's `read` names a `resource:view` whose resource has no firewall — no role can reach that view. |
67
- | `AUTHZ_PUSHDOWN_COST` | info | Per-permission report: how many SQL subqueries the permission lowers to, plus the max recursive-CTE depth (from recursive arrows). Advisory, never fails a build. |
68
- | `AUTHZ_CAPABILITY_CEILING` | **error** | A resource's firewall grants a `scope:<kind>:<role>` role read access **beyond its capability profile** — either the role has no profile at all, or the profile doesn't list this resource. |
69
- | `AUTHZ_NOT_OVER_RESOURCE` | warn | A `not` whose operand resolves to a **resource (SQL) site** — `NOT EXISTS` over a nullable join can silently pass (the null-trap). The analyzer resolves the operand's site from its leaves, so it fires even when the lowering left the site unset. |
58
+ | `AUTHZ_UNREACHABLE_ROLE` | warn | A scoped role declared under `authz.scopes` with **no grant profile** — it can authorize no read, action, or channel. Dead config, deny-safe. |
59
+ | `AUTHZ_UNREACHABLE_VIEW` | warn | A grant's `read` names a `resource:view` whose resource has no firewall — no role can reach that view. (A reachability proxy — heuristic by design.) |
60
+ | `AUTHZ_NOT_OVER_RESOURCE` | warn | A `not` whose operand resolves to a **resource (SQL) site** — `NOT EXISTS` over a nullable join can silently pass (the null-trap). The site resolution is conservative, so this stays advisory. |
61
+ | `AUTHZ_PUSHDOWN_COST` | info | Per-permission report: how many SQL subqueries the permission lowers to, plus the max recursive-CTE depth. Advisory, never fails a build. |
70
62
 
71
63
  A few codes are reserved in the diagnostic enum for the milestones that emit
72
64
  them and don't fire on a shipped config today: `AUTHZ_UNBOUNDED_RECURSION`
@@ -76,38 +68,78 @@ error raised at config validation, before the analyzer runs),
76
68
 
77
69
  ### The capability ceiling
78
70
 
79
- The one `error`-severity authz check. It is the M0.2 deliverable that backs
80
- [scope grant profiles](/compiler/definitions/scopes): a scoped role is
81
- deny-by-default and may touch only what its `grants` profile lists. The
82
- analyzer walks every resource firewall, follows each `{ permission }` arm
83
- into the permission graph to find the scope roles it references, and fails the
84
- build (in strict mode) if a resource grants a scope role access the profile
85
- doesn't cover. In the default path it warns loudly. This is what makes the
86
- grant profile the single auditable manifest of what an external principal can
87
- see.
71
+ The check that backs [scope grant profiles](/compiler/definitions/scopes): a
72
+ scoped role is deny-by-default and may touch only what its `grants` profile
73
+ lists. The analyzer walks every resource firewall, follows each
74
+ `{ permission }` arm into the permission graph to find the scope roles it
75
+ references, and **fails the build** if a resource grants a scope role access
76
+ the profile doesn't cover. This is what makes the grant profile the single
77
+ auditable manifest of what an external principal can see.
88
78
 
89
79
  ## Authn codes
90
80
 
91
- Four **structural authentication** checks — proving properties over the
92
- generated route + credential surface rather than the authz policy:
81
+ Five **structural authentication** checks — proving properties over the
82
+ generated route + credential surface rather than the authz policy. All are
83
+ promoted (compile errors):
93
84
 
94
- | Code | Severity | What it catches |
85
+ | Code | Tier | What it catches |
95
86
  |---|---|---|
96
- | `AUTHN_ROUTE_COVERAGE` | warn | A route that reaches data with an **unclassified** auth gate and isn't declared `PUBLIC` — the signup / flag-gap bug class (data delivered to an unauthenticated ctx). |
97
- | `AUTHN_SECRET_CONSISTENCY` | error | A credential's mint site and verify site don't share key / issuer / audience — every minted token would fail verification (the ws-ticket "401 on every upgrade" trap). |
98
- | `AUTHN_CREDENTIAL_DELIVERY` | error | A fire-and-forget credential send (the OTP-email shape) not anchored to `waitUntil` / `await` — the Worker may drop the promise and never deliver (the OTP-500 bug class). |
99
- | `AUTHN_CLAIM_PROVENANCE` | error | An identity `ctx` field written from **request input** rather than a credential verifier — client-asserted identity, which is forbidden. |
100
- | `AUTHN_SURFACE_INVARIANT` | warn / error | A surface contract breach: an `/mcp` or agent route not gated bearer-only (warn), or an `INTERNAL`-gated route mounted on an HTTP-reachable surface (error). |
87
+ | `AUTHN_ROUTE_COVERAGE` | **error** | A route that reaches data with an **unclassifiable** auth gate and isn't declared `PUBLIC` — the signup / flag-gap bug class (data delivered to an unauthenticated ctx). Fires only on a gate the compiler cannot classify; zero-FP by construction. |
88
+ | `AUTHN_SURFACE_INVARIANT` | **error** | A surface contract breach: an `/mcp` or agent route not gated bearer-only, or an `INTERNAL`-gated route mounted on an HTTP-reachable surface. |
89
+ | `AUTHN_SECRET_CONSISTENCY` | **error** | A credential's mint site and verify site don't share key / issuer / audience — every minted token would fail verification (the ws-ticket "401 on every upgrade" trap). |
90
+ | `AUTHN_CREDENTIAL_DELIVERY` | **error** | A fire-and-forget credential send (the OTP-email shape) not anchored to `waitUntil` / `await` — the Worker may drop the promise and never deliver (the OTP-500 bug class). |
91
+ | `AUTHN_CLAIM_PROVENANCE` | **error** | An identity `ctx` field written from **request input** rather than a credential verifier — client-asserted identity, which is forbidden. Unprovable provenance also fails (fail closed). |
101
92
 
102
93
  These check definitions are **wired and fully unit-tested**, but their inputs
103
94
  — the per-route and per-credential metadata (`RouteNode` / `MintSite` /
104
95
  `VerifySite` / `ClaimWrite`) — are not yet emitted by the route, middleware,
105
96
  and credential generators. Until those generators emit that metadata the
106
97
  analyzer runs the authn checks against **empty** route/credential graphs, so
107
- they are effectively no-ops on a real compile. The check logic needs no change
108
- when the metadata lands — the route/credential coverage activates the moment
109
- the generators emit it. The authz / permission-graph checks above run
110
- unconditionally today, because the policy IR is always present.
98
+ they are effectively no-ops on a real compile. The severity contract is
99
+ locked in now: they fail builds the moment they can fire. (The emitted route
100
+ surface is separately guarded today by the IR's unbound-route invariant — a
101
+ hard error that predates this promotion and owns that surface; one subject,
102
+ one error.)
103
+
104
+ ## The override surface
105
+
106
+ Every promoted finding can be explicitly accepted — per finding, with a
107
+ required reason:
108
+
109
+ ```ts
110
+ authz: {
111
+ analyzer: {
112
+ allow: [
113
+ {
114
+ check: 'AUTHZ_CAPABILITY_CEILING',
115
+ target: 'sessions/scope:event:organizer',
116
+ reason: 'organizer grant profile lands with the v2 rollout (TICKET-123)',
117
+ },
118
+ ],
119
+ },
120
+ }
121
+ ```
122
+
123
+ An entry downgrades the exact `(check, target)` finding back to a warning
124
+ that cites the reason. The rendered error prints the exact recipe — copy the
125
+ `check` and `target` from it. Target formats:
126
+
127
+ | Check | `target` format |
128
+ |---|---|
129
+ | `AUTHZ_EMPTY_PERMISSION` | the permission name — `event:locked` |
130
+ | `AUTHZ_CAPABILITY_CEILING` | `<resource>/scope:<kind>:<role>` — `sessions/scope:event:organizer` |
131
+ | `AUTHN_ROUTE_COVERAGE`, `AUTHN_SURFACE_INVARIANT` | `<METHOD> <path>` — `GET /mcp` |
132
+ | `AUTHN_SECRET_CONSISTENCY`, `AUTHN_CREDENTIAL_DELIVERY` | the credential kind — `ws-ticket` |
133
+ | `AUTHN_CLAIM_PROVENANCE` | the ctx field — `ctx.userId` |
134
+
135
+ Guard rails, all compile errors:
136
+
137
+ - `check` must be a **promoted** id — unknown ids and keep-warn ids (there is
138
+ nothing to override) are rejected at config validation.
139
+ - `reason` is required and non-empty: overrides are self-documenting.
140
+ - An `allow` entry that matches **no current finding** is a *dead override*
141
+ and fails the compile — fix or remove the stale entry. Override lists can
142
+ never silently outlive the problems they suppressed.
111
143
 
112
144
  ## Reading the pushdown-cost report
113
145
 
@@ -133,4 +165,3 @@ not an error, but worth a look.
133
165
  profiles the capability-ceiling check enforces.
134
166
  - [Firewall](/compiler/definitions/firewall) — the `{ permission }` arms the
135
167
  ceiling check follows into the permission graph.
136
- ```
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@quickback-dev/cli",
3
- "version": "0.46.0",
3
+ "version": "0.47.0",
4
4
  "description": "CLI for Quickback — define your backend in TypeScript, compile to a fully wired Cloudflare Worker (or Bun / Node) with auth, database, migrations, security, CMS, and Account UI.",
5
5
  "author": "Kardoe Incorporated <paul@kardoe.com>",
6
6
  "license": "MIT",
@@ -1,5 +1,66 @@
1
1
  # Changelog
2
2
 
3
+ ## v0.47.0 — June 11, 2026
4
+
5
+ ### Breaking: zero-false-positive analyzer checks are now compile errors
6
+
7
+ The authz/authn analyzer (v0.37) shipped warn-only. After a release cycle of
8
+ data, the checks whose every trip is a definite misconfiguration — never a
9
+ legitimate config — are **promoted to compile errors**. Warnings nobody is
10
+ forced to read are documentation; the pillar guarantees are now enforced.
11
+
12
+ **Breaking** — a config that previously compiled with one of these warnings
13
+ now fails the compile:
14
+
15
+ - `AUTHZ_EMPTY_PERMISSION` — a permission that is structurally unsatisfiable
16
+ (`allOf(a, not(a))`: a fact AND its exact negation at the same AND-level).
17
+ - `AUTHZ_CAPABILITY_CEILING` — a resource's firewall grants a
18
+ `scope:<kind>:<role>` role access beyond its capability profile (or the
19
+ role has no profile at all). This is the M0.2 pillar guarantee — it was
20
+ authored as an error all along and is now enforced.
21
+ - `AUTHN_ROUTE_COVERAGE`, `AUTHN_SURFACE_INVARIANT`,
22
+ `AUTHN_SECRET_CONSISTENCY`, `AUTHN_CREDENTIAL_DELIVERY`,
23
+ `AUTHN_CLAIM_PROVENANCE` — the structural-authn set (route auth coverage,
24
+ bearer-only `/mcp`/agent surfaces + INTERNAL unreachability, mint↔verify
25
+ key/issuer/audience pairing, anchored credential delivery, verifier-only
26
+ identity claims). These still run against empty route/credential metadata
27
+ on a real compile (no-ops until the generators emit it), but the severity
28
+ contract is locked in now — they fail the build the moment they can fire.
29
+
30
+ The heuristic/advisory checks are unchanged: `AUTHZ_SHADOWED_ARM`,
31
+ `AUTHZ_UNREACHABLE_ROLE`, `AUTHZ_UNREACHABLE_VIEW`, and
32
+ `AUTHZ_NOT_OVER_RESOURCE` stay warnings; `AUTHZ_PUSHDOWN_COST` stays an info
33
+ report. `QUICKBACK_AUTHZ_STRICT=true` still promotes those warnings too.
34
+
35
+ **The override escape hatch** — every promoted finding can be explicitly
36
+ accepted, per finding, with a required reason:
37
+
38
+ ```ts
39
+ authz: {
40
+ analyzer: {
41
+ allow: [
42
+ {
43
+ check: 'AUTHZ_CAPABILITY_CEILING',
44
+ target: 'sessions/scope:event:organizer', // from the rendered finding
45
+ reason: 'organizer grant profile lands with the v2 rollout (TICKET-123)',
46
+ },
47
+ ],
48
+ },
49
+ }
50
+ ```
51
+
52
+ An override downgrades that exact `(check, target)` finding back to a warning
53
+ that cites the reason — even under strict mode (it's an explicit, reasoned
54
+ acceptance). Every rendered error prints its exact override recipe. Guard
55
+ rails: `check` must be one of the promoted ids (unknown or keep-warn ids are
56
+ rejected at config validation), `reason` is required, and an `allow` entry
57
+ that matches no current finding is itself a compile error — no dead
58
+ overrides accumulating after the underlying issue is fixed.
59
+
60
+ Analyzer-internal defects are still fail-open: a bug in the analyzer itself
61
+ downgrades to a single warning and the compile continues. Only real findings
62
+ fail builds.
63
+
3
64
  ## v0.46.0 — June 11, 2026
4
65
 
5
66
  ### Breaking: "no organization context" responses unified on HTTP 403
@@ -19,54 +19,46 @@ a stable, greppable **code**:
19
19
  [quickback:authz] AUTHZ_EMPTY_PERMISSION: permission "event:locked" can never be satisfied — it requires organizerOf AND its negation simultaneously.
20
20
  at resource=sessions authz.permissions["event:locked"]
21
21
  hint: Remove the contradictory arm, or split into separate permissions.
22
+ override: authz: { analyzer: { allow: [{ check: 'AUTHZ_EMPTY_PERMISSION', target: 'event:locked', reason: '<why this is acceptable>' }] } }
22
23
  ```
23
24
 
24
25
  The first line stays greppable (`[quickback:<channel>] CODE: message`); the
25
- source location and fix hint render on continuation lines.
26
+ source location, fix hint, and — for promoted errors — the exact override
27
+ recipe render on continuation lines.
26
28
 
27
- ## Warn by default, opt-in strict
29
+ ## Errors vs warnings (v0.47+)
28
30
 
29
- The analyzer is **warn-by-default, compile-continues**. This is deliberate:
30
- the analyzer runs on the shared compiler that serves every project, so a new
31
- check must never break an existing build on upgrade. In the default path
32
- every diagnostic — *including* the one check authored at `error` severity
33
- (the capability ceiling) — is rendered as a warning line and the compile
34
- proceeds.
31
+ The checks split into two tiers:
35
32
 
36
- Set **`QUICKBACK_AUTHZ_STRICT=true`** to promote every `warn` to `error`.
37
- Under strict mode the compile **fails** (throws an aggregate error listing the
38
- codes) if any diagnostic is — after promotion — an error. `info` lines
39
- (the pushdown-cost report) stay informational and never fail a build.
33
+ - **Promoted (compile errors).** A trip is a *definite misconfiguration* —
34
+ never a legitimate config. These fail the build by default. Each one can be
35
+ explicitly accepted per finding via
36
+ [`authz.analyzer.allow`](#the-override-surface).
37
+ - **Heuristic (warnings) and reports (info).** Advisory findings where a
38
+ legitimate config could trip the detector. These print and the compile
39
+ continues. Set **`QUICKBACK_AUTHZ_STRICT=true`** to promote these warnings
40
+ to errors as well (overridden findings stay warnings even under strict —
41
+ an override is an explicit, reasoned acceptance).
40
42
 
41
- ```bash
42
- # warn-only (default): prints diagnostics, compile succeeds
43
- quickback compile
44
-
45
- # strict: any warn or error fails the compile
46
- QUICKBACK_AUTHZ_STRICT=true quickback compile
47
- ```
48
-
49
- > The analyzer is compile-time only — zero runtime blast radius. A defect in
50
- > the analyzer itself is caught and downgraded to a single warning in the
51
- > default path, so an analyzer bug can never take down an otherwise-valid
52
- > compile. (Strict mode re-raises, because there the throw is the intended
53
- > hard failure.)
43
+ The analyzer remains compile-time only — zero runtime blast radius. A defect
44
+ in the analyzer *itself* is caught and downgraded to a single warning, so an
45
+ analyzer bug can never take down an otherwise-valid compile. Only real
46
+ findings fail builds.
54
47
 
55
48
  ## Authz codes
56
49
 
57
- These read the permission graph projected from the policy IR. All are `warn`
58
- severity (so `info` for the pushdown report) **except** the capability ceiling,
59
- which is authored as `error`.
50
+ These read the permission graph projected from the policy IR and run on every
51
+ compile.
60
52
 
61
- | Code | Severity | What it catches |
53
+ | Code | Tier | What it catches |
62
54
  |---|---|---|
63
- | `AUTHZ_EMPTY_PERMISSION` | warn | A permission that can never be satisfied — e.g. `allOf(a, not(a))`, which requires a fact and its negation at the same AND-level. |
55
+ | `AUTHZ_EMPTY_PERMISSION` | **error** | A permission that can never be satisfied — `allOf(a, not(a))`, a fact and its exact negation at the same AND-level. The detector is conservative (exact-leaf contradictions only), so a trip is structurally unsatisfiable. |
56
+ | `AUTHZ_CAPABILITY_CEILING` | **error** | A resource's firewall grants a `scope:<kind>:<role>` role read access **beyond its capability profile** — either the role has no profile at all, or the profile doesn't list this resource. The M0.2 pillar guarantee. |
64
57
  | `AUTHZ_SHADOWED_ARM` | warn | An `anyOf` arm subsumed by a broader arm: a leaf `X` and an `allOf(X, …)` in the same union — the narrower arm can never widen the result. |
65
- | `AUTHZ_UNREACHABLE_ROLE` | warn | A scoped role declared under `authz.scopes` with **no grant profile** — it can authorize no read, action, or channel, so it's dead config. |
66
- | `AUTHZ_UNREACHABLE_VIEW` | warn | A grant's `read` names a `resource:view` whose resource has no firewall — no role can reach that view. |
67
- | `AUTHZ_PUSHDOWN_COST` | info | Per-permission report: how many SQL subqueries the permission lowers to, plus the max recursive-CTE depth (from recursive arrows). Advisory, never fails a build. |
68
- | `AUTHZ_CAPABILITY_CEILING` | **error** | A resource's firewall grants a `scope:<kind>:<role>` role read access **beyond its capability profile** — either the role has no profile at all, or the profile doesn't list this resource. |
69
- | `AUTHZ_NOT_OVER_RESOURCE` | warn | A `not` whose operand resolves to a **resource (SQL) site** — `NOT EXISTS` over a nullable join can silently pass (the null-trap). The analyzer resolves the operand's site from its leaves, so it fires even when the lowering left the site unset. |
58
+ | `AUTHZ_UNREACHABLE_ROLE` | warn | A scoped role declared under `authz.scopes` with **no grant profile** — it can authorize no read, action, or channel. Dead config, deny-safe. |
59
+ | `AUTHZ_UNREACHABLE_VIEW` | warn | A grant's `read` names a `resource:view` whose resource has no firewall — no role can reach that view. (A reachability proxy — heuristic by design.) |
60
+ | `AUTHZ_NOT_OVER_RESOURCE` | warn | A `not` whose operand resolves to a **resource (SQL) site** — `NOT EXISTS` over a nullable join can silently pass (the null-trap). The site resolution is conservative, so this stays advisory. |
61
+ | `AUTHZ_PUSHDOWN_COST` | info | Per-permission report: how many SQL subqueries the permission lowers to, plus the max recursive-CTE depth. Advisory, never fails a build. |
70
62
 
71
63
  A few codes are reserved in the diagnostic enum for the milestones that emit
72
64
  them and don't fire on a shipped config today: `AUTHZ_UNBOUNDED_RECURSION`
@@ -76,38 +68,78 @@ error raised at config validation, before the analyzer runs),
76
68
 
77
69
  ### The capability ceiling
78
70
 
79
- The one `error`-severity authz check. It is the M0.2 deliverable that backs
80
- [scope grant profiles](/compiler/definitions/scopes): a scoped role is
81
- deny-by-default and may touch only what its `grants` profile lists. The
82
- analyzer walks every resource firewall, follows each `{ permission }` arm
83
- into the permission graph to find the scope roles it references, and fails the
84
- build (in strict mode) if a resource grants a scope role access the profile
85
- doesn't cover. In the default path it warns loudly. This is what makes the
86
- grant profile the single auditable manifest of what an external principal can
87
- see.
71
+ The check that backs [scope grant profiles](/compiler/definitions/scopes): a
72
+ scoped role is deny-by-default and may touch only what its `grants` profile
73
+ lists. The analyzer walks every resource firewall, follows each
74
+ `{ permission }` arm into the permission graph to find the scope roles it
75
+ references, and **fails the build** if a resource grants a scope role access
76
+ the profile doesn't cover. This is what makes the grant profile the single
77
+ auditable manifest of what an external principal can see.
88
78
 
89
79
  ## Authn codes
90
80
 
91
- Four **structural authentication** checks — proving properties over the
92
- generated route + credential surface rather than the authz policy:
81
+ Five **structural authentication** checks — proving properties over the
82
+ generated route + credential surface rather than the authz policy. All are
83
+ promoted (compile errors):
93
84
 
94
- | Code | Severity | What it catches |
85
+ | Code | Tier | What it catches |
95
86
  |---|---|---|
96
- | `AUTHN_ROUTE_COVERAGE` | warn | A route that reaches data with an **unclassified** auth gate and isn't declared `PUBLIC` — the signup / flag-gap bug class (data delivered to an unauthenticated ctx). |
97
- | `AUTHN_SECRET_CONSISTENCY` | error | A credential's mint site and verify site don't share key / issuer / audience — every minted token would fail verification (the ws-ticket "401 on every upgrade" trap). |
98
- | `AUTHN_CREDENTIAL_DELIVERY` | error | A fire-and-forget credential send (the OTP-email shape) not anchored to `waitUntil` / `await` — the Worker may drop the promise and never deliver (the OTP-500 bug class). |
99
- | `AUTHN_CLAIM_PROVENANCE` | error | An identity `ctx` field written from **request input** rather than a credential verifier — client-asserted identity, which is forbidden. |
100
- | `AUTHN_SURFACE_INVARIANT` | warn / error | A surface contract breach: an `/mcp` or agent route not gated bearer-only (warn), or an `INTERNAL`-gated route mounted on an HTTP-reachable surface (error). |
87
+ | `AUTHN_ROUTE_COVERAGE` | **error** | A route that reaches data with an **unclassifiable** auth gate and isn't declared `PUBLIC` — the signup / flag-gap bug class (data delivered to an unauthenticated ctx). Fires only on a gate the compiler cannot classify; zero-FP by construction. |
88
+ | `AUTHN_SURFACE_INVARIANT` | **error** | A surface contract breach: an `/mcp` or agent route not gated bearer-only, or an `INTERNAL`-gated route mounted on an HTTP-reachable surface. |
89
+ | `AUTHN_SECRET_CONSISTENCY` | **error** | A credential's mint site and verify site don't share key / issuer / audience — every minted token would fail verification (the ws-ticket "401 on every upgrade" trap). |
90
+ | `AUTHN_CREDENTIAL_DELIVERY` | **error** | A fire-and-forget credential send (the OTP-email shape) not anchored to `waitUntil` / `await` — the Worker may drop the promise and never deliver (the OTP-500 bug class). |
91
+ | `AUTHN_CLAIM_PROVENANCE` | **error** | An identity `ctx` field written from **request input** rather than a credential verifier — client-asserted identity, which is forbidden. Unprovable provenance also fails (fail closed). |
101
92
 
102
93
  These check definitions are **wired and fully unit-tested**, but their inputs
103
94
  — the per-route and per-credential metadata (`RouteNode` / `MintSite` /
104
95
  `VerifySite` / `ClaimWrite`) — are not yet emitted by the route, middleware,
105
96
  and credential generators. Until those generators emit that metadata the
106
97
  analyzer runs the authn checks against **empty** route/credential graphs, so
107
- they are effectively no-ops on a real compile. The check logic needs no change
108
- when the metadata lands — the route/credential coverage activates the moment
109
- the generators emit it. The authz / permission-graph checks above run
110
- unconditionally today, because the policy IR is always present.
98
+ they are effectively no-ops on a real compile. The severity contract is
99
+ locked in now: they fail builds the moment they can fire. (The emitted route
100
+ surface is separately guarded today by the IR's unbound-route invariant — a
101
+ hard error that predates this promotion and owns that surface; one subject,
102
+ one error.)
103
+
104
+ ## The override surface
105
+
106
+ Every promoted finding can be explicitly accepted — per finding, with a
107
+ required reason:
108
+
109
+ ```ts
110
+ authz: {
111
+ analyzer: {
112
+ allow: [
113
+ {
114
+ check: 'AUTHZ_CAPABILITY_CEILING',
115
+ target: 'sessions/scope:event:organizer',
116
+ reason: 'organizer grant profile lands with the v2 rollout (TICKET-123)',
117
+ },
118
+ ],
119
+ },
120
+ }
121
+ ```
122
+
123
+ An entry downgrades the exact `(check, target)` finding back to a warning
124
+ that cites the reason. The rendered error prints the exact recipe — copy the
125
+ `check` and `target` from it. Target formats:
126
+
127
+ | Check | `target` format |
128
+ |---|---|
129
+ | `AUTHZ_EMPTY_PERMISSION` | the permission name — `event:locked` |
130
+ | `AUTHZ_CAPABILITY_CEILING` | `<resource>/scope:<kind>:<role>` — `sessions/scope:event:organizer` |
131
+ | `AUTHN_ROUTE_COVERAGE`, `AUTHN_SURFACE_INVARIANT` | `<METHOD> <path>` — `GET /mcp` |
132
+ | `AUTHN_SECRET_CONSISTENCY`, `AUTHN_CREDENTIAL_DELIVERY` | the credential kind — `ws-ticket` |
133
+ | `AUTHN_CLAIM_PROVENANCE` | the ctx field — `ctx.userId` |
134
+
135
+ Guard rails, all compile errors:
136
+
137
+ - `check` must be a **promoted** id — unknown ids and keep-warn ids (there is
138
+ nothing to override) are rejected at config validation.
139
+ - `reason` is required and non-empty: overrides are self-documenting.
140
+ - An `allow` entry that matches **no current finding** is a *dead override*
141
+ and fails the compile — fix or remove the stale entry. Override lists can
142
+ never silently outlive the problems they suppressed.
111
143
 
112
144
  ## Reading the pushdown-cost report
113
145
 
@@ -133,4 +165,3 @@ not an error, but worth a look.
133
165
  profiles the capability-ceiling check enforces.
134
166
  - [Firewall](/compiler/definitions/firewall) — the `{ permission }` arms the
135
167
  ceiling check follows into the permission graph.
136
- ```
@@ -1,6 +0,0 @@
1
- interface InitOptions {
2
- path?: string;
3
- }
4
- export declare function init(options?: InitOptions): Promise<void>;
5
- export {};
6
- //# sourceMappingURL=init.d.ts.map
@@ -1 +0,0 @@
1
- {"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../../src/commands/init.ts"],"names":[],"mappings":"AAIA,UAAU,WAAW;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,wBAAsB,IAAI,CAAC,OAAO,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CA2Z/D"}