@niscorp/charter 0.1.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/DESIGN.md +464 -0
- package/DOCS.md +229 -0
- package/LICENSE +202 -0
- package/README.md +54 -0
- package/dist/index.cjs +177 -0
- package/dist/index.cjs.map +1 -0
- package/dist/index.d.cts +58 -0
- package/dist/index.d.ts +58 -0
- package/dist/index.js +168 -0
- package/dist/index.js.map +1 -0
- package/package.json +48 -0
package/DESIGN.md
ADDED
|
@@ -0,0 +1,464 @@
|
|
|
1
|
+
# Charter — Design Document
|
|
2
|
+
|
|
3
|
+
## Purpose
|
|
4
|
+
|
|
5
|
+
Access control that decides **which parts of an application exist** for a
|
|
6
|
+
principal, rather than wrapping the application in checks. In this stack an
|
|
7
|
+
`ActionDefinition` is a complete behavioral unit and pure data, so a granted
|
|
8
|
+
catalog *is* the application. An ungranted action is not hidden or disabled —
|
|
9
|
+
it is absent. There is no `if (canAccess)` to forget.
|
|
10
|
+
|
|
11
|
+
**One sentence:** roles select globs over opaque string universes; the engine
|
|
12
|
+
resolves them to a concrete set per principal, and the verifier refuses an
|
|
13
|
+
incoherent charter before it ships.
|
|
14
|
+
|
|
15
|
+
## Why actions are the right altitude
|
|
16
|
+
|
|
17
|
+
Every mainstream framework authorizes at the wrong level:
|
|
18
|
+
|
|
19
|
+
- **Routes** (Spring Security, NestJS guards) are addresses, not behaviors.
|
|
20
|
+
- **Components** (frontend RBAC wrappers) hide buttons; hiding is not a
|
|
21
|
+
security model.
|
|
22
|
+
- **Rows** (RLS) cannot express "this user may not *initiate* a refund."
|
|
23
|
+
|
|
24
|
+
A Nova action is the complete contract in one serializable value: what you see
|
|
25
|
+
(`layout`), what you can do (`triggers`), what it touches (`endpoints`), what
|
|
26
|
+
it accepts (`input`). Granting at this altitude buys three properties nothing
|
|
27
|
+
else has:
|
|
28
|
+
|
|
29
|
+
- **Deny-by-nonexistence.** Navigation is push-by-id and the shell throws for
|
|
30
|
+
unknown ids. A principal's catalog — the definitions their shell ever
|
|
31
|
+
receives — *is* their application. Nothing outside it is reachable,
|
|
32
|
+
renderable, or invokable.
|
|
33
|
+
- **One gate for humans and agents.** The same resolved catalog feeds the
|
|
34
|
+
human's shell, the agent's tool policy (Cortex `policyGate`), and the
|
|
35
|
+
server-function gate. One document governs every kind of principal.
|
|
36
|
+
- **Reviewable closure.** Because actions and charters are both data, "what can
|
|
37
|
+
this role reach" is a computation, not an audit project. Run the audit
|
|
38
|
+
machinery (nav targets, channels) over a role's catalog and its reachability
|
|
39
|
+
is a verifiable, diffable fact.
|
|
40
|
+
|
|
41
|
+
---
|
|
42
|
+
|
|
43
|
+
## Core principles
|
|
44
|
+
|
|
45
|
+
### 1. Universe-blindness is the whole idea
|
|
46
|
+
|
|
47
|
+
The engine resolves globs over strings and never learns what a string means.
|
|
48
|
+
`resolveRole(charter, universe, role, section)` runs identical code whether the
|
|
49
|
+
universe is Nova action ids or vex `table.verb` leaves. This is not abstraction
|
|
50
|
+
for its own sake — it is what keeps access control *one* mechanism. A framework
|
|
51
|
+
that authorizes routes, components, and rows separately has three security
|
|
52
|
+
models and three places to be wrong. Charter has one algebra, applied per
|
|
53
|
+
section.
|
|
54
|
+
|
|
55
|
+
The consequence, enforced structurally: **the engine never manufactures a
|
|
56
|
+
universe.** It is always handed one. Each governed target exports its own
|
|
57
|
+
dialect (vex exports `SCOPE_VERBS` and `scopeGrants(tables)`; a shell's universe
|
|
58
|
+
is its action ids; moss's is its layout-variant ids), and the composing layer
|
|
59
|
+
derives the universe and passes it in. Charter imports nothing and is imported
|
|
60
|
+
by the resolution, never the reverse — so it has **zero dependencies**,
|
|
61
|
+
permanently, not incidentally.
|
|
62
|
+
|
|
63
|
+
### 2. The grammar stays small; the opinions live in the verifier
|
|
64
|
+
|
|
65
|
+
The grammar is deliberately thin: roles, `extends`/`without` (compose whole
|
|
66
|
+
roles), and a `Selection` per section (`allow`/`deny` globs, with sugar for the
|
|
67
|
+
common cases). That is all resolution needs.
|
|
68
|
+
|
|
69
|
+
Everything judgmental — what counts as a mistake — lives in `verifyCharter`,
|
|
70
|
+
run at boot/CI, not at request time. Separating the two means the hot path
|
|
71
|
+
(resolution) is a pure set operation with no policy baked in, and the opinions
|
|
72
|
+
are auditable in one place. The rule is: **if it boots, it's coherent.** A
|
|
73
|
+
charter that resolves cleanly and passes the verifier cannot silently
|
|
74
|
+
mis-grant.
|
|
75
|
+
|
|
76
|
+
### 3. Severities are asymmetric on purpose
|
|
77
|
+
|
|
78
|
+
A **dead deny** — a deny glob matching nothing in the universe — is an *error*.
|
|
79
|
+
A typo'd deny fails silent, and a silent deny means something is unprotected
|
|
80
|
+
that the author believed was protected. A **dead allow** is only a *warning*: it
|
|
81
|
+
grants nothing, so it is noise, not danger. The verifier's severity is chosen by
|
|
82
|
+
"what happens if the author is wrong here," never by symmetry.
|
|
83
|
+
|
|
84
|
+
### 4. The documents are the app's, not the package's
|
|
85
|
+
|
|
86
|
+
The charter and the assignment rows (`principal → roles`) are **artifacts the
|
|
87
|
+
application authors** — one day rows in an artifact library, versioned and
|
|
88
|
+
diffable. Charter is the engine that resolves and verifies them; it ships no
|
|
89
|
+
document, no storage, no identity. This keeps the package a pure function and
|
|
90
|
+
lets the app own its policy as data.
|
|
91
|
+
|
|
92
|
+
---
|
|
93
|
+
|
|
94
|
+
## The three rings
|
|
95
|
+
|
|
96
|
+
The charter is one ring of three. Each ring assumes the ring above it is
|
|
97
|
+
compromised:
|
|
98
|
+
|
|
99
|
+
| Ring | Question | Enforced by |
|
|
100
|
+
|---|---|---|
|
|
101
|
+
| 1 — existence | Which actions are in your universe? | The charter (`actions`) → served catalog |
|
|
102
|
+
| 2 — shape | What does *your variant* of an action do? | Served layout variants (the `layouts` section → moss substitutes the variant's layout on the definition at shell build) |
|
|
103
|
+
| 3 — data | Which **verbs** on which entity? / Which **rows/columns**? | ACL: the charter (`data`) → a compiled Vex `ScopePolicy`. RLS: the policy's own row rules, locked fingerprints, closed mutation grammar |
|
|
104
|
+
|
|
105
|
+
Ring 3 has two halves this stack keeps apart. **ACL** — *may you write deals at
|
|
106
|
+
all* — is a verb question, and it is the charter's: the `data` section resolves
|
|
107
|
+
to `table.verb` grants that **compile to a Vex `ScopePolicy`** (which read/write
|
|
108
|
+
phases exist for you). **RLS** — *which rows* — is what a granted phase then does
|
|
109
|
+
(`match`/`set` rules), and the charter never touches it. Vex is the unforgeable
|
|
110
|
+
floor either way: an ungranted phase is simply absent from your policy, and
|
|
111
|
+
Vex's own default-deny refuses it; server-injected scope, identity stamping,
|
|
112
|
+
replay-only endpoints, and a mutation grammar that rejects `$scope` and blanket
|
|
113
|
+
writes stand under it. A malicious client that fabricates its own definitions
|
|
114
|
+
still cannot cross Vex.
|
|
115
|
+
|
|
116
|
+
**Ring 2 is the charter's `layouts` section.** A variant is a distinct id
|
|
117
|
+
selecting one action's layout; holding it swaps that layout in the served tree
|
|
118
|
+
(moss binds it on the definition per principal at shell build — see
|
|
119
|
+
`@niscorp/moss`). The base layout is the *floor* — the least-privileged holder's
|
|
120
|
+
shape — and variants **enrich upward** as grants, so `extends` composes them like
|
|
121
|
+
any capability and a forgotten grant fails closed (under-serves visibly). A
|
|
122
|
+
reducing variant is authored backwards: it forces deny-it-back in every richer
|
|
123
|
+
role and a forgotten deny over-serves silently. The charter still only
|
|
124
|
+
*selects*; what a variant *looks like* lives in the artifact.
|
|
125
|
+
|
|
126
|
+
So the charter does ring-1 existence, the ring-2 **variant** choice, and the
|
|
127
|
+
ring-3 **verb** decision; it never does ring-3 **row/column** work. And it never
|
|
128
|
+
*enforces* — it **compiles**: each consumer enforces its own native contract in
|
|
129
|
+
its own language, and the charter speaks that language at the boundary (see
|
|
130
|
+
**Compilers**).
|
|
131
|
+
|
|
132
|
+
---
|
|
133
|
+
|
|
134
|
+
## The algebra
|
|
135
|
+
|
|
136
|
+
Resolution, per section, verbatim:
|
|
137
|
+
|
|
138
|
+
```
|
|
139
|
+
resolved(role) = (∪ resolved(extends) ∪ match(allow))
|
|
140
|
+
− match(deny)
|
|
141
|
+
− ∪ resolved(without)
|
|
142
|
+
```
|
|
143
|
+
|
|
144
|
+
Properties, all deliberate:
|
|
145
|
+
|
|
146
|
+
- **Order-independent.** Every subtraction is set-minus; there is no
|
|
147
|
+
first-match precedence to reason about.
|
|
148
|
+
- **Deny wins within a role.** `allow` then `deny` in the same role: the deny
|
|
149
|
+
removes. There is no re-allow within a role — to permit an exception, deny
|
|
150
|
+
more narrowly (corpus case 7).
|
|
151
|
+
- **Denies do not inherit.** `extends` unions *resolved sets*; a deny is local
|
|
152
|
+
to the role that wrote it. A child may re-add what a parent denied — the
|
|
153
|
+
*resolver* permits it (a legal composition), the *verifier* warns
|
|
154
|
+
(`re-allow`), because it is usually a mistake but occasionally intended (F1).
|
|
155
|
+
- **Cycles and unknown references are errors**, surfaced by the resolver and
|
|
156
|
+
collected by the verifier per section.
|
|
157
|
+
- **`extends` and `without` compose whole roles**, resolved in the current
|
|
158
|
+
section. A role is a reusable bundle, not a flat glob list.
|
|
159
|
+
|
|
160
|
+
The resolved set is hashed. That hash is the catalog cache key and the version
|
|
161
|
+
token pushed to connected clients — grant changes propagate mid-session over the
|
|
162
|
+
socket, and revocation is the same push with a smaller set.
|
|
163
|
+
|
|
164
|
+
### Globs
|
|
165
|
+
|
|
166
|
+
One wildcard rule, no more: `*` matches any run of characters, including dots.
|
|
167
|
+
`crm.*` matches `crm.deal.form`. There is no `**`, no brace expansion, no regex.
|
|
168
|
+
The day a pattern cannot be expressed, the answer is a better id, not a richer
|
|
169
|
+
glob.
|
|
170
|
+
|
|
171
|
+
---
|
|
172
|
+
|
|
173
|
+
## Sections
|
|
174
|
+
|
|
175
|
+
A `Section` is `'actions' | 'data' | 'layouts'` — each a universe. `actions`
|
|
176
|
+
selects Nova action ids; `data` selects `table.verb` capabilities; `layouts`
|
|
177
|
+
selects layout-variant ids (ring 2). The sugar keeps the common role terse: a
|
|
178
|
+
bare `string[]` is an actions-only role, and top-level `allow`/`deny` are the
|
|
179
|
+
`actions` section (so an actions-only role never names a section). Explicit
|
|
180
|
+
`actions:`/`data:`/`layouts:` selections address each universe directly. Having
|
|
181
|
+
*both* the sugar and an explicit `actions:` on one role is the
|
|
182
|
+
`ambiguous-selection` error — resolution would silently drop one.
|
|
183
|
+
|
|
184
|
+
The `data` verb leaves mirror vex's phases: `read`, plus the three write ops
|
|
185
|
+
under the `write` *namespace* — `deals.read`, `deals.write.insert`,
|
|
186
|
+
`deals.write.update`, `deals.write.delete`. `write` itself is never an atom
|
|
187
|
+
(leaves-only); **the umbrella is a glob** — `deals.write.*` grants every write,
|
|
188
|
+
`*.write.delete` denies deletes across the board. The universe is derived from
|
|
189
|
+
the schema, never authored.
|
|
190
|
+
|
|
191
|
+
`extends`/`without` compose **every** section at once. Resolution, deny-wins,
|
|
192
|
+
and the verifier all run per section against the right universe — one matcher,
|
|
193
|
+
one resolver, one set of lints, reused. **Adding a governed surface is adding a
|
|
194
|
+
`Section` value, a universe, and a compiler in the *target* — never a grammar
|
|
195
|
+
change here.** The `layouts` section was exactly that: one enum value, moss
|
|
196
|
+
hands the universe in, moss compiles it to substituted layouts.
|
|
197
|
+
|
|
198
|
+
---
|
|
199
|
+
|
|
200
|
+
## Compilers — charter speaks each consumer's language
|
|
201
|
+
|
|
202
|
+
The charter never enforces; it **compiles**. Each governed library keeps its
|
|
203
|
+
own native, self-sufficient contract, enforced by its own machinery — Nova has
|
|
204
|
+
the action map (an absent id throws `UnknownActionError`), Vex has `ScopePolicy`
|
|
205
|
+
(an absent phase is default-denied), Cortex has `ToolPolicy`. None of them
|
|
206
|
+
imports the charter or knows it exists.
|
|
207
|
+
|
|
208
|
+
And the charter imports none of *them* — there is no dependency in either
|
|
209
|
+
direction ("no dependencies beats optional"). The charter's output is **string
|
|
210
|
+
sets**; each governed target exports its own *grants → native contract* intake,
|
|
211
|
+
in its own string dialect, and the composing server (`@niscorp/moss`) wires the
|
|
212
|
+
two:
|
|
213
|
+
|
|
214
|
+
| section | dialect (owned by the target) | intake | consumer |
|
|
215
|
+
|---|---|---|---|
|
|
216
|
+
| `actions` | action ids | the action map, filtered by ids | Nova's shell |
|
|
217
|
+
| `data` | `SCOPE_VERBS` leaves (`deals.write.insert`) | `createScopePolicy(grants, behaviors, scoping)` | Vex |
|
|
218
|
+
| `layouts` | variant ids | substitute the variant's layout on the definition | moss / Nova |
|
|
219
|
+
| (future) | tool names | a `ToolPolicy` constructor | Cortex's `policyGate` |
|
|
220
|
+
|
|
221
|
+
Each side stays pure and standalone: the charter is a string-set engine always
|
|
222
|
+
*handed* a universe; Vex without a charter is a hand-authored `ScopePolicy`;
|
|
223
|
+
Nova is a hand-authored action map. Grafting policy onto something new is
|
|
224
|
+
additive — the target exports its dialect and intake, the app passes the
|
|
225
|
+
universe in. The test for whether a thing is charter-governable is this stack's
|
|
226
|
+
house rule: **it is configured by declarative data, and absence means denial.**
|
|
227
|
+
|
|
228
|
+
The `data` intake is the exemplar and the reason it's trivial: a Vex policy
|
|
229
|
+
already fuses two things — which *phases* an entity has (present or absent — ACL,
|
|
230
|
+
which the charter owns) and what a phase *does* (its `match`/`set` rules — row
|
|
231
|
+
behavior, static and app-owned). So `resolved data grants → which phases exist`,
|
|
232
|
+
`behaviors table → what a phase does`. The viewer's mark-won dies because their
|
|
233
|
+
compiled policy has no `deals` write phase — not a gate anyone added, one the
|
|
234
|
+
charter never emitted.
|
|
235
|
+
|
|
236
|
+
There is a third input, and it fills the gap that fusion left. A policy answered
|
|
237
|
+
*which phases exist* (the charter's) and *what a phase does* (the behavior's) —
|
|
238
|
+
but a behavior was a property of the TABLE, so every role holding any grant on
|
|
239
|
+
it got the same reach. "The desk reads every booking; a member reads their own"
|
|
240
|
+
was unsayable, and the workaround was a second table carrying the tighter rule:
|
|
241
|
+
one fact in two places, kept level by a trigger, drifting the moment the trigger
|
|
242
|
+
was wrong.
|
|
243
|
+
|
|
244
|
+
Reach is a property of the ROLE, so `scoping` is a role-level name — resolved
|
|
245
|
+
like every other string here, meaningless to the engine, handed to the target,
|
|
246
|
+
which looks it up among the behaviors a table declares. One grant, two reaches:
|
|
247
|
+
`resolved data grants → which phases exist`, `behaviors[table][scoping] → what a
|
|
248
|
+
phase does, for this role`.
|
|
249
|
+
|
|
250
|
+
It is the one thing `extends` does NOT compose, and that asymmetry is load-
|
|
251
|
+
bearing rather than an omission. Every section accumulates upward because a desk
|
|
252
|
+
holding everything a member holds is right for actions and data. Reach inverts
|
|
253
|
+
it: a desk extends a member's *screens* and must not extend a member's *"only my
|
|
254
|
+
own rows"*, or the roster it exists to read filters to whoever is operating it.
|
|
255
|
+
A role's reach is its own answer or none.
|
|
256
|
+
|
|
257
|
+
Two roles naming different profiles is a PERSON, not a contradiction — somebody
|
|
258
|
+
who teaches at a studio and also trains there. So resolution is per role and the
|
|
259
|
+
compiled policies merge: the principal may do anything any role permits, each at
|
|
260
|
+
that role's reach. The refusal that stood here briefly ("incoherence, like two
|
|
261
|
+
granted variants of one action") was an analogy standing in for a case, and the
|
|
262
|
+
domain produced the counterexample within the hour.
|
|
263
|
+
|
|
264
|
+
The trusted path is a charter artifact too: the engine's *default* policy — what
|
|
265
|
+
direct callers (dev checks, an agent's query tool) run under — compiles from a
|
|
266
|
+
`system` role in the same document, never assigned to a human. There is no
|
|
267
|
+
policy in the app the charter does not own; even the engine's own floor is a
|
|
268
|
+
resolved, verified, diffable grant, and a verb the `system` role lacks dies for
|
|
269
|
+
the engine exactly as it does for a viewer.
|
|
270
|
+
|
|
271
|
+
---
|
|
272
|
+
|
|
273
|
+
## The closure audit
|
|
274
|
+
|
|
275
|
+
`verifyCharter` accepts an optional `ClosureAuditor` — an injected hook,
|
|
276
|
+
`(grantedIds, layoutIds?) => string[]`. The verifier resolves each role's
|
|
277
|
+
granted action set (and, when the app governs layouts, its granted variant ids)
|
|
278
|
+
and hands them to the auditor; the consumer that *owns* actions supplies the
|
|
279
|
+
check. Moss builds it from Nova's action audit and substitutes granted variants
|
|
280
|
+
first, so the closure sees each role's *effective* definitions — a role that can
|
|
281
|
+
reach a screen but not the screen it pushes to is a broken closure, and a
|
|
282
|
+
variant's push targets are audited for exactly the roles that hold it. Charter
|
|
283
|
+
never imports the auditor — the dependency points inward, so the package stays
|
|
284
|
+
universe-blind even about *what a coherent closure means*.
|
|
285
|
+
|
|
286
|
+
---
|
|
287
|
+
|
|
288
|
+
## Naming is the taxonomy
|
|
289
|
+
|
|
290
|
+
The charter has no tags, no categories, no metadata predicates. **The id
|
|
291
|
+
hierarchy is the taxonomy**, and globs traverse it. This is a deliberate bet:
|
|
292
|
+
developers already maintain exactly one taxonomy with care — the one they use to
|
|
293
|
+
find their own things. A parallel tag vocabulary would drift; the namespace
|
|
294
|
+
cannot, because it is structural.
|
|
295
|
+
|
|
296
|
+
Conventions this implies (scaffolding defaults, not grammar):
|
|
297
|
+
|
|
298
|
+
- Ids shaped `area.entity.variant`: `crm.deal.form`, `chrome.sidebar`,
|
|
299
|
+
`finance.invoices`.
|
|
300
|
+
- **Ids are leaves; namespaces are never actions.** If `crm.deals` exists,
|
|
301
|
+
nothing is named bare `crm`. Removes the `crm` vs `crm.*` off-by-one.
|
|
302
|
+
- Variants are distinct ids: `crm.deal` and `crm.deal.view` are two actions. The
|
|
303
|
+
charter selects; it never shapes.
|
|
304
|
+
- A rename is a permissions change. That is a feature: the verifier diffs it.
|
|
305
|
+
|
|
306
|
+
---
|
|
307
|
+
|
|
308
|
+
## The corpus
|
|
309
|
+
|
|
310
|
+
The grammar is only as good as the cases it survives. The instructive ones,
|
|
311
|
+
typical first, then the ones that break other systems.
|
|
312
|
+
|
|
313
|
+
- **Anonymous baseline** — `"public": ["auth.login", "docs.*"]`.
|
|
314
|
+
- **The ladder** — `viewer` → `editor extends viewer allow crm.*` → `admin
|
|
315
|
+
extends editor allow settings.* charter.*`. Administering permissions is
|
|
316
|
+
itself just actions (F6).
|
|
317
|
+
- **Superadmin** — `"root": ["*"]`.
|
|
318
|
+
- **Kiosk** — `"warehouse-scanner": ["inventory.scan", "inventory.lookup"]`. This
|
|
319
|
+
terminal's *entire application* is two actions. Nothing else to attack.
|
|
320
|
+
- **Two hats** — `{ "extends": ["sales", "manager"] }`. Sets union; no diamond
|
|
321
|
+
problem — a granted action is granted, nothing to override.
|
|
322
|
+
- **Everything-except** — `{ "extends": ["sales"], "deny": ["*.delete",
|
|
323
|
+
"*.export", "finance.*"] }`. The case that kills enumerated-list systems, in
|
|
324
|
+
one line.
|
|
325
|
+
- **Exception-to-the-exception** — interns may delete nothing *except their own
|
|
326
|
+
drafts*: `"deny": ["crm.deal.delete", ...], "allow": ["drafts.delete"]`.
|
|
327
|
+
**Awkward on purpose.** You cannot `deny: ["*.delete"]` then claw back
|
|
328
|
+
`drafts.delete` — deny wins, no re-allow within a role. You deny *narrowly*.
|
|
329
|
+
The cost buys charters that never require simulating precedence in your head.
|
|
330
|
+
- **An agent narrower than its human** — `"agent-unsafe": { "allow": ["*.form",
|
|
331
|
+
"*.delete", "finance.*"] }`, worn subtractively: `"ray": { "extends":
|
|
332
|
+
["sales"], "without": ["agent-unsafe"] }`. The AI-governance story is one line
|
|
333
|
+
of the grammar that does everything else.
|
|
334
|
+
- **Plans / tiers / entitlements** — a `pro-only` role, `free-seat` wears it via
|
|
335
|
+
`without`, `pro-seat` extends without it. A downgrade is swapping one
|
|
336
|
+
assignment row. RBAC, feature flags, and billing are the same mechanism.
|
|
337
|
+
- **This one guy** — `"usr_017": { "extends": ["sales"], "deny": ["crm.export"]
|
|
338
|
+
}`. A principal-specific role is just a role.
|
|
339
|
+
- **Time-boxed / break-glass / suspension — not charter.** These are
|
|
340
|
+
**assignment rows** (`{ principal, role, expires, grantedBy, reason }`).
|
|
341
|
+
Break-glass is two ordinary actions (request/approve) whose effect writes a
|
|
342
|
+
row with an expiry; the catalog service watches assignments and pushes the new
|
|
343
|
+
catalog. Suspension is deleting rows, or assigning the empty catalog — a valid
|
|
344
|
+
application: a lock screen. The charter says what roles *are*; a table says who
|
|
345
|
+
*wears* them, when.
|
|
346
|
+
- **A new action ships** — `crm.quotes` is published; every role matching `crm.*`
|
|
347
|
+
gains it, pushed over the socket. Feature and footgun in one: the guard is not
|
|
348
|
+
grammar but the **publish-time diff** — *"crm.quotes → gained by: sales,
|
|
349
|
+
intern, ray."* If that line surprises anyone, the naming was wrong.
|
|
350
|
+
- **Same action, different depth per role** — `"support": ["crm.deal.view"]` vs
|
|
351
|
+
`"sales": ["crm.deal", "crm.deal.view"]`. Clean *because* variants are distinct
|
|
352
|
+
ids.
|
|
353
|
+
- **"Readonly for reps" / "no margin field" — ring 2.** A reduced view is a
|
|
354
|
+
variant (a distinct layout, granted via the `layouts` section); field-level
|
|
355
|
+
hiding is a patched variant with Prism redaction on the response transform.
|
|
356
|
+
Shape lives in the artifact, not the grant.
|
|
357
|
+
- **"Needs manager approval" — not charter.** Approval is part of what the action
|
|
358
|
+
*is* — a fragment composed onto it (the `confirm-delete` pattern). Reps-need,
|
|
359
|
+
managers-don't → two variants, granted respectively.
|
|
360
|
+
- **"Only their OWN deals" — not charter, loudly.** Row-level is Vex scope policy
|
|
361
|
+
(`match: owner_id → userId`). The charter decides whether the verb exists;
|
|
362
|
+
Vex decides which rows. Mixing these makes an ACL unreviewable.
|
|
363
|
+
- **A global invariant** — "nobody but finance touches `finance.*`" is awkward
|
|
364
|
+
per-role (deny in every role forever, one forgotten role breaks it). It is
|
|
365
|
+
policy *about* the charter and belongs to the verifier as an assertion
|
|
366
|
+
(`{ "only": ["finance", "root"], "may-match": "finance.*" }`) — CI lint, not a
|
|
367
|
+
runtime boundary.
|
|
368
|
+
|
|
369
|
+
---
|
|
370
|
+
|
|
371
|
+
## Known flaws, found on purpose
|
|
372
|
+
|
|
373
|
+
The design was red-teamed. None of the flaws required new grammar; all moved
|
|
374
|
+
work to the verifier.
|
|
375
|
+
|
|
376
|
+
- **F1 — Deny does not survive `extends`.** A child re-allows what a parent
|
|
377
|
+
denied. The algebra is consistent (a parent role is just a set) and viral
|
|
378
|
+
denies would break legitimate composition — but it dents "deny always wins"
|
|
379
|
+
(true only within a role). *Fix:* visibility. The verifier flags every
|
|
380
|
+
re-allow of an ancestor's deny, in every diff.
|
|
381
|
+
- **F2 — Subtractive roles are loaded guns if assigned.** `agent-unsafe` is a
|
|
382
|
+
positive list that only subtracts because `without` uses it that way. Assign
|
|
383
|
+
it by accident and the principal gains everything in it. *Fix:* the assignment
|
|
384
|
+
diff renders in concrete actions, and the verifier lints any role referenced
|
|
385
|
+
in `without` that is also assigned.
|
|
386
|
+
- **F3 — A typo'd deny fails silent.** `"deny": ["crm.deal.delte"]` matches
|
|
387
|
+
nothing, forever. *Fix:* asymmetric linting — dead deny is an error, dead
|
|
388
|
+
allow a warning.
|
|
389
|
+
- **F4 — `crm` vs `crm.*`.** Solved by convention: ids are leaves, namespaces
|
|
390
|
+
are never actions. Verifier enforces (`leaves-only`).
|
|
391
|
+
- **F5 — Orphan actions.** An action matched by no role is deployed but
|
|
392
|
+
unreachable — deny-by-default working, but usually a mistake. Verifier reports
|
|
393
|
+
orphans at publish (layout variants too).
|
|
394
|
+
- **F6 — The charter can escalate itself.** Whoever holds `charter.edit` can
|
|
395
|
+
grant themselves root. The runtime gate is the charter itself: nobody holds
|
|
396
|
+
`charter.*` unless the charter grants it, and edits execute as
|
|
397
|
+
server-authoritative actions — audited, Vex-logged, approval-fragmented where
|
|
398
|
+
wanted. The assertion pinning the meta-loop (only `root` may match `charter.*`)
|
|
399
|
+
is CI lint: a tripwire, not the enforcement.
|
|
400
|
+
- **F7 — Tenant overlays.** Per-tenant roles layer on a base charter with one
|
|
401
|
+
rule: overlays may add roles and extend base roles, **never redefine a base
|
|
402
|
+
name**. Shadowing `admin` per-tenant is how SaaS horror stories start.
|
|
403
|
+
- **F8 — Versions.** Charters name logical ids only. Which *version* of
|
|
404
|
+
`crm.deal.form` a catalog serves is the artifact library's published-pointer
|
|
405
|
+
concern. A charter that needs to pin versions is a symptom, not a feature.
|
|
406
|
+
|
|
407
|
+
---
|
|
408
|
+
|
|
409
|
+
## The verifier is the other half
|
|
410
|
+
|
|
411
|
+
The grammar stopped moving and every flaw found its fix in tooling. That is the
|
|
412
|
+
intended shape. The charter stays something a non-programmer reads aloud; the
|
|
413
|
+
verifier carries the opinions:
|
|
414
|
+
|
|
415
|
+
- resolves every role at boot / in CI — *if it boots, it's coherent*
|
|
416
|
+
- **dead deny = error**, dead allow = warning, orphan actions and variants
|
|
417
|
+
reported
|
|
418
|
+
- flags re-allows of an ancestor's deny (F1)
|
|
419
|
+
- flags roles referenced in `without` that are also assigned (F2)
|
|
420
|
+
- enforces id conventions (leaves only) and overlay rules (no shadowing)
|
|
421
|
+
- checks `assert` invariants (F6)
|
|
422
|
+
- runs the reachability closure per role (nav targets, channels) and reports
|
|
423
|
+
dead emits and unreachable grants
|
|
424
|
+
- and above all: **the diff renders in concrete actions, not globs** — "this
|
|
425
|
+
change: intern +`crm.import`, −`confirm-delete`; ray unchanged." A human
|
|
426
|
+
approves *that*. This is only possible because the permissions are closed data
|
|
427
|
+
over closed artifacts.
|
|
428
|
+
|
|
429
|
+
---
|
|
430
|
+
|
|
431
|
+
## What it refuses to do
|
|
432
|
+
|
|
433
|
+
For every temptation, the forwarding address:
|
|
434
|
+
|
|
435
|
+
| Temptation | Home |
|
|
436
|
+
|---|---|
|
|
437
|
+
| Row filtering ("only my deals") | The Vex policy's own `match` rules — a behavior of a granted phase, not the charter |
|
|
438
|
+
| Column shaping ("no margin field") | Patched variant + Prism redaction (ring 2) |
|
|
439
|
+
| Approval / confirmation flows | Fragments composed onto the action (ring 2) |
|
|
440
|
+
| Time-boxed / conditional access | Assignment rows (a table) |
|
|
441
|
+
| Break-glass elevation | Two actions + an assignment row |
|
|
442
|
+
| Feature flags, plans, entitlements | Roles + `without` |
|
|
443
|
+
| Cross-role invariants | Verifier `assert` |
|
|
444
|
+
| Version pinning | Artifact library pointers |
|
|
445
|
+
| Tags / metadata predicates | The id namespace |
|
|
446
|
+
| Grant-time shaping (`apply` a patch in a selector) | Refused — mint a variant id (ring 2) |
|
|
447
|
+
| Enforce, store, transport, or manufacture a universe | Not the package's job — resolution and verification only |
|
|
448
|
+
| Grow the glob | One `*`. A richer pattern language is a worse id scheme in disguise |
|
|
449
|
+
|
|
450
|
+
The charter maps names to selections. It decides *whether the verb exists in
|
|
451
|
+
your world*; everything about *which rows*, *which columns*, or *what a variant
|
|
452
|
+
looks like* has a home that already exists.
|
|
453
|
+
|
|
454
|
+
---
|
|
455
|
+
|
|
456
|
+
## Boundaries
|
|
457
|
+
|
|
458
|
+
Charter is consumed by the composing server (`@niscorp/moss`), which derives the
|
|
459
|
+
universes (action ids from the manifest, `table.verb` leaves from vex's
|
|
460
|
+
introspected schema, variant ids from the manifest's `layouts`), calls
|
|
461
|
+
`resolvePrincipal` per login, refuses to boot on `verifyCharter` errors, and
|
|
462
|
+
hands the resolved sets to the enforcers. Charter knows about none of that — it
|
|
463
|
+
is the algebra at the center, and nothing more. See [DOCS.md](DOCS.md) for the
|
|
464
|
+
API.
|