@niscorp/charter 0.1.0 → 0.1.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +7 -0
- package/DESIGN.md +9 -5
- package/DOCS.md +28 -15
- package/README.md +1 -0
- package/package.json +1 -1
package/CHANGELOG.md
ADDED
|
@@ -0,0 +1,7 @@
|
|
|
1
|
+
# @niscorp/charter
|
|
2
|
+
|
|
3
|
+
## 0.1.1
|
|
4
|
+
|
|
5
|
+
### Patch Changes
|
|
6
|
+
|
|
7
|
+
- b67a125: Documentation only: each package's README, reference and design docs checked against its source and corrected — install lines and peers, signatures, defaults, status codes, licenses (loom, signal: Apache-2.0), and API that existed but was not documented.
|
package/DESIGN.md
CHANGED
|
@@ -417,11 +417,15 @@ verifier carries the opinions:
|
|
|
417
417
|
reported
|
|
418
418
|
- flags re-allows of an ancestor's deny (F1)
|
|
419
419
|
- flags roles referenced in `without` that are also assigned (F2)
|
|
420
|
-
- enforces id conventions (leaves only)
|
|
421
|
-
|
|
422
|
-
-
|
|
423
|
-
|
|
424
|
-
-
|
|
420
|
+
- enforces id conventions (leaves only); overlay rules (no shadowing) are not
|
|
421
|
+
built — there are no overlays yet (F7)
|
|
422
|
+
- checks `assert` invariants (F6) — not built: `verifyCharter` takes no
|
|
423
|
+
assertions
|
|
424
|
+
- runs the reachability closure per role through the injected auditor; moss's
|
|
425
|
+
keeps the push targets that fall outside the role's closure
|
|
426
|
+
- and above all (not built in this package — `perRole` in the report is the
|
|
427
|
+
concrete per-role sets a diff would be rendered from): **the diff renders in
|
|
428
|
+
concrete actions, not globs** — "this
|
|
425
429
|
change: intern +`crm.import`, −`confirm-delete`; ray unchanged." A human
|
|
426
430
|
approves *that*. This is only possible because the permissions are closed data
|
|
427
431
|
over closed artifacts.
|
package/DOCS.md
CHANGED
|
@@ -121,7 +121,8 @@ Every id in `ids` selected by any pattern in `patterns`.
|
|
|
121
121
|
|
|
122
122
|
Resolve one role in one section against `universe`. Applies the algebra
|
|
123
123
|
(`extends` ∪ `allow` − `deny` − `without`). `memo` and `visiting` are internal
|
|
124
|
-
accumulators for recursion and cycle detection; callers pass neither.
|
|
124
|
+
accumulators for recursion and cycle detection; callers pass neither. (`memo` is
|
|
125
|
+
keyed by role name alone, so one is never shared across sections or universes.)
|
|
125
126
|
|
|
126
127
|
Throws `CharterError` on an unknown role reference or a role cycle.
|
|
127
128
|
|
|
@@ -136,6 +137,12 @@ resolvePrincipal(charter, actionIds, ['sales', 'dev'], 'actions'); // granted ac
|
|
|
136
137
|
resolvePrincipal(charter, verbLeaves, ['sales', 'dev'], 'data'); // granted table.verb caps
|
|
137
138
|
```
|
|
138
139
|
|
|
140
|
+
### `resolveScoping(charter, role): string | undefined`
|
|
141
|
+
|
|
142
|
+
The `scoping` name one role declares, or `undefined` — for a role that declares
|
|
143
|
+
none, a bare-array role, and a role the charter does not define (it does not
|
|
144
|
+
throw). Not composed by `extends`; see [`scoping`](#scoping--how-far-a-role-reaches).
|
|
145
|
+
|
|
139
146
|
### `normalizeRole(def, section): { allow, deny, extends, without }`
|
|
140
147
|
|
|
141
148
|
The atoms of one role for one section, with sugar expanded. Exposed for tools
|
|
@@ -151,18 +158,20 @@ catches these and reports them as `resolution` errors rather than throwing.
|
|
|
151
158
|
|
|
152
159
|
## Verification
|
|
153
160
|
|
|
154
|
-
### `verifyCharter(charter, universes,
|
|
161
|
+
### `verifyCharter(charter, universes, wearable?, closure?): VerifyReport`
|
|
155
162
|
|
|
156
|
-
Run every coherence check against
|
|
157
|
-
serve if `report.errors` is non-empty.
|
|
163
|
+
Run every coherence check, per section, against that section's universe. Call
|
|
164
|
+
at boot/CI; refuse to serve if `report.errors` is non-empty.
|
|
158
165
|
|
|
159
166
|
- `universes: { actions: readonly string[]; data: readonly string[]; layouts?: readonly string[] }`
|
|
160
167
|
— the id sets each section resolves against, handed in by the composer. The
|
|
161
168
|
`layouts` universe is optional: absent, the section is inert (a charter's
|
|
162
169
|
`layouts` keys resolve against nothing and are not verified); handed in, its
|
|
163
170
|
dead-deny/dead-allow/orphan/leaves-only checks run like any other section.
|
|
164
|
-
- `
|
|
165
|
-
|
|
171
|
+
- `wearable?: readonly (readonly string[])[]` — the role combinations a principal
|
|
172
|
+
may wear, one entry per combination (not one per person). Defaults to `[]`.
|
|
173
|
+
Read only by the `subtractive-assigned` check. A composer that has an
|
|
174
|
+
assignment map (`principal → roles`) passes `Object.values(map)`.
|
|
166
175
|
- `closure?: ClosureAuditor` — the injected per-role cross-action audit.
|
|
167
176
|
|
|
168
177
|
### `ClosureAuditor`
|
|
@@ -173,9 +182,10 @@ type ClosureAuditor = (grantedIds: readonly string[], layoutIds?: readonly strin
|
|
|
173
182
|
|
|
174
183
|
Given a role's resolved action ids (and, when the app governs layouts, its
|
|
175
184
|
granted variant ids), return the cross-action wiring problems inside that
|
|
176
|
-
closure. Supplied by the consumer that owns actions (
|
|
177
|
-
`auditClosure(definitions)
|
|
178
|
-
the audit sees each role's effective
|
|
185
|
+
closure. Supplied by the consumer that owns actions (moss exports
|
|
186
|
+
`auditClosure(definitions, variants?)`, built on Nova's `auditAction`; it
|
|
187
|
+
substitutes granted variants so the audit sees each role's effective
|
|
188
|
+
definitions). Absent, every role's `issues` is empty.
|
|
179
189
|
|
|
180
190
|
### `VerifyReport`
|
|
181
191
|
|
|
@@ -183,7 +193,7 @@ the audit sees each role's effective definitions).
|
|
|
183
193
|
type VerifyReport = {
|
|
184
194
|
errors: VerifyIssue[]; // refuse to boot if non-empty
|
|
185
195
|
warnings: VerifyIssue[]; // deploy, but review
|
|
186
|
-
perRole: RoleClosure[]; // resolved actions + data + closure issues, per role
|
|
196
|
+
perRole: RoleClosure[]; // resolved actions + data + layouts (sorted) + closure issues, per role
|
|
187
197
|
};
|
|
188
198
|
|
|
189
199
|
type VerifyIssue = { level: 'error' | 'warning'; rule: string; detail: string };
|
|
@@ -195,13 +205,13 @@ type RoleClosure = { role: string; actions: string[]; data: string[]; layouts: s
|
|
|
195
205
|
| rule | level | meaning |
|
|
196
206
|
|---|---|---|
|
|
197
207
|
| `resolution` | error | a cycle or unknown-role reference (per section) |
|
|
198
|
-
| `leaves-only` | error | an id is a namespace of another id — namespaces are never actions |
|
|
208
|
+
| `leaves-only` | error | an id is a namespace of another id — namespaces are never actions (checked in the `actions` universe, and in `layouts` when handed in; not in `data`) |
|
|
199
209
|
| `ambiguous-selection` | error | a role has both top-level `allow`/`deny` and an explicit `actions:` |
|
|
200
210
|
| `dead-deny` | error | a deny glob matches nothing — silent means unprotected |
|
|
201
211
|
| `dead-allow` | warning | an allow glob matches nothing — noise |
|
|
202
|
-
| `orphan` | warning | an action granted by no role — deployed but unreachable |
|
|
212
|
+
| `orphan` | warning | an action (or, when `layouts` is handed in, a layout variant) granted by no role — deployed but unreachable. An ungranted `data` id is not reported |
|
|
203
213
|
| `re-allow` | warning | a role re-allows an id an ancestor denied |
|
|
204
|
-
| `subtractive-assigned` | warning | a role used in `without`
|
|
214
|
+
| `subtractive-assigned` | warning | a role used in `without` also appears in a `wearable` combination |
|
|
205
215
|
| *(closure)* | via `RoleClosure.issues` | cross-action wiring problems from the injected auditor |
|
|
206
216
|
|
|
207
217
|
---
|
|
@@ -210,13 +220,16 @@ type RoleClosure = { role: string; actions: string[]; data: string[]; layouts: s
|
|
|
210
220
|
|
|
211
221
|
```typescript
|
|
212
222
|
import { resolvePrincipal, verifyCharter } from '@niscorp/charter';
|
|
223
|
+
import { auditClosure } from '@niscorp/moss';
|
|
224
|
+
import { createScopePolicy, scopeGrants } from '@niscorp/vex';
|
|
213
225
|
|
|
214
226
|
// 1. Boot: derive the universes from the governed targets, refuse incoherence.
|
|
215
227
|
const universes = {
|
|
216
228
|
actions: Object.keys(app.actions), // the shell's dialect
|
|
217
|
-
data: scopeGrants(
|
|
229
|
+
data: scopeGrants(tableNames), // vex's dialect — `table.verb` leaves
|
|
218
230
|
};
|
|
219
|
-
const
|
|
231
|
+
const wearable = Object.values(app.assignments); // the role combinations in use
|
|
232
|
+
const report = verifyCharter(app.charter, universes, wearable, auditClosure(app.actions));
|
|
220
233
|
if (report.errors.length > 0) {
|
|
221
234
|
throw new Error(report.errors.map((e) => `${e.rule}: ${e.detail}`).join('\n'));
|
|
222
235
|
}
|
package/README.md
CHANGED
|
@@ -44,6 +44,7 @@ if (report.errors.length > 0) throw new Error('charter is incoherent');
|
|
|
44
44
|
|
|
45
45
|
- **Universe-blind.** `resolvePrincipal(charter, universe, roles, section)` runs the same resolution against any universe. `actions` selects Nova action ids; `data` selects `table.verb` capabilities (the vex-policy dialect); `layouts` selects layout-variant ids (ring 2 — moss's dialect: which variant of an action's layout a principal is served). Adding a governed domain is adding a universe, never new grammar.
|
|
46
46
|
- **A small algebra.** `resolved(role) = (∪ extends ∪ match(allow)) − match(deny) − ∪ without`. Order-independent, deny wins within a role, denies don't inherit. Roles compose whole roles; each section resolves independently.
|
|
47
|
+
- **Reach is named, not composed.** A role may carry `scoping` — a name the governed target resolves (vex: which scope behaviors apply). Unlike every section it is not inherited through `extends`: `resolveScoping(charter, role)` is that role's own answer or none, and a principal with several roles is resolved one role at a time.
|
|
47
48
|
- **One glob rule.** `*` matches any run of characters including dots — `crm.*` matches `crm.deal.form`. No `**`, no braces, no regex. When a pattern can't be expressed, the fix is a better id.
|
|
48
49
|
- **A verifier that refuses.** `verifyCharter` runs the opinions the grammar deliberately omits: a dead deny is an **error** (a typo'd deny fails silent, and silent means unprotected); a dead allow is a warning; ambiguous selections, namespace-as-action, orphan actions, re-allowed ancestor denies all surface. "If it boots, it's coherent."
|
|
49
50
|
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@niscorp/charter",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.1",
|
|
4
4
|
"description": "A universe-blind policy engine — roles resolve glob selections over opaque string universes; the verifier refuses incoherence. Zero dependencies.",
|
|
5
5
|
"license": "Apache-2.0",
|
|
6
6
|
"repository": {
|