@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 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) 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
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, assignments?, closure?): VerifyReport`
161
+ ### `verifyCharter(charter, universes, wearable?, closure?): VerifyReport`
155
162
 
156
- Run every coherence check against both universes. Call at boot/CI; refuse to
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
- - `assignments?: Record<string, readonly string[]>` — `principal → roles`, used
165
- by the `subtractive-assigned` check.
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 (Nova exports
177
- `auditClosure(definitions)`; moss wraps it and substitutes granted variants so
178
- the audit sees each role's effective definitions).
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` is also assigned to a principal |
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(schema.tables), // vex's dialect
229
+ data: scopeGrants(tableNames), // vex's dialect — `table.verb` leaves
218
230
  };
219
- const report = verifyCharter(app.charter, universes, app.assignments, auditClosure(app.actions));
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.0",
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": {