@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.
- package/dist/docs/content.js +2 -2
- package/dist/docs/content.js.map +1 -1
- package/dist/index.js +1 -1
- package/dist/skill/docs/changelog.md +61 -0
- package/dist/skill/docs/compiler/definitions/diagnostics.md +88 -57
- package/package.json +1 -1
- package/src/skill/docs/changelog.md +61 -0
- package/src/skill/docs/compiler/definitions/diagnostics.md +88 -57
- package/dist/commands/init.d.ts +0 -6
- package/dist/commands/init.d.ts.map +0 -1
- package/dist/commands/init.js +0 -405
- package/dist/commands/init.js.map +0 -1
- package/dist/lib/sweep-stale.d.ts +0 -25
- package/dist/lib/sweep-stale.d.ts.map +0 -1
- package/dist/lib/sweep-stale.js +0 -179
- package/dist/lib/sweep-stale.js.map +0 -1
- package/dist/lib/sweep-stale.test.d.ts +0 -2
- package/dist/lib/sweep-stale.test.d.ts.map +0 -1
- package/dist/lib/sweep-stale.test.js +0 -130
- package/dist/lib/sweep-stale.test.js.map +0 -1
|
@@ -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
|
|
26
|
+
source location, fix hint, and — for promoted errors — the exact override
|
|
27
|
+
recipe render on continuation lines.
|
|
26
28
|
|
|
27
|
-
##
|
|
29
|
+
## Errors vs warnings (v0.47+)
|
|
28
30
|
|
|
29
|
-
The
|
|
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
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
(the
|
|
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
|
-
|
|
42
|
-
|
|
43
|
-
|
|
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
|
|
58
|
-
|
|
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 |
|
|
53
|
+
| Code | Tier | What it catches |
|
|
62
54
|
|---|---|---|
|
|
63
|
-
| `AUTHZ_EMPTY_PERMISSION` |
|
|
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
|
|
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
|
-
| `
|
|
68
|
-
| `
|
|
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
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
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
|
-
|
|
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 |
|
|
85
|
+
| Code | Tier | What it catches |
|
|
95
86
|
|---|---|---|
|
|
96
|
-
| `AUTHN_ROUTE_COVERAGE` |
|
|
97
|
-
| `
|
|
98
|
-
| `
|
|
99
|
-
| `
|
|
100
|
-
| `
|
|
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
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
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.
|
|
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
|
|
26
|
+
source location, fix hint, and — for promoted errors — the exact override
|
|
27
|
+
recipe render on continuation lines.
|
|
26
28
|
|
|
27
|
-
##
|
|
29
|
+
## Errors vs warnings (v0.47+)
|
|
28
30
|
|
|
29
|
-
The
|
|
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
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
(the
|
|
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
|
-
|
|
42
|
-
|
|
43
|
-
|
|
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
|
|
58
|
-
|
|
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 |
|
|
53
|
+
| Code | Tier | What it catches |
|
|
62
54
|
|---|---|---|
|
|
63
|
-
| `AUTHZ_EMPTY_PERMISSION` |
|
|
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
|
|
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
|
-
| `
|
|
68
|
-
| `
|
|
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
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
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
|
-
|
|
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 |
|
|
85
|
+
| Code | Tier | What it catches |
|
|
95
86
|
|---|---|---|
|
|
96
|
-
| `AUTHN_ROUTE_COVERAGE` |
|
|
97
|
-
| `
|
|
98
|
-
| `
|
|
99
|
-
| `
|
|
100
|
-
| `
|
|
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
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
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/dist/commands/init.d.ts
DELETED
|
@@ -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"}
|