@inixiative/transitions 0.0.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/LICENSE +21 -0
- package/README.md +128 -0
- package/dist/index.cjs +2 -0
- package/dist/index.cjs.map +1 -0
- package/dist/index.d.cts +216 -0
- package/dist/index.d.ts +216 -0
- package/dist/index.js +2 -0
- package/dist/index.js.map +1 -0
- package/package.json +69 -0
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Aron Greenspan
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
ADDED
|
@@ -0,0 +1,128 @@
|
|
|
1
|
+
# @inixiative/transitions
|
|
2
|
+
|
|
3
|
+
A small, **stateless** primitive on top of [`@inixiative/json-rules`](https://github.com/inixiative/json-rules)
|
|
4
|
+
that answers two questions about an entity's lifecycle, declaratively:
|
|
5
|
+
|
|
6
|
+
- **"Can this change happen?"** — guard a proposed update (`check`).
|
|
7
|
+
- **"What changes can happen?"** — list available verbs for a record (`available`), and via
|
|
8
|
+
`toPrisma`, every record currently eligible for a verb (`eligible`).
|
|
9
|
+
|
|
10
|
+
It is **not** a state machine (no statecharts/actors/hierarchy), does **not** own state, and does
|
|
11
|
+
**not** execute the change or run side effects. It is a guard + affordance layer. A transition is
|
|
12
|
+
**pure data** → serializable → tenant-configurable at runtime (stored in the DB, edited in a UI,
|
|
13
|
+
no deploy to change a lifecycle).
|
|
14
|
+
|
|
15
|
+
> Full design: [`docs/FEAT-018-transitions.md`](./docs/FEAT-018-transitions.md).
|
|
16
|
+
|
|
17
|
+
## Model
|
|
18
|
+
|
|
19
|
+
```
|
|
20
|
+
model → verb → Action { paths: Transition[], permission?, label? }
|
|
21
|
+
Transition { from: Side, to: Side & { merge? } }
|
|
22
|
+
Side { predicate, permission?, requires? }
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
A `Transition` is one atomic `from → to` edge. An **Action** (a named verb) is the OR of its edges —
|
|
26
|
+
disjunction lives at the action level, never inside a `Transition`, so the kernel stays atomic and
|
|
27
|
+
serializable.
|
|
28
|
+
|
|
29
|
+
The `from`/`to` asymmetry is load-bearing and applies to **both** `predicate` (legality) and
|
|
30
|
+
`permission` (authz): `from.*` is evaluated against the **current** record, `to.*` against the
|
|
31
|
+
**resulting (merged)** record.
|
|
32
|
+
|
|
33
|
+
## Two failure modes, one check
|
|
34
|
+
|
|
35
|
+
```ts
|
|
36
|
+
import { checkTransition } from '@inixiative/transitions';
|
|
37
|
+
|
|
38
|
+
const approve = {
|
|
39
|
+
from: { predicate: { field: 'status', operator: 'equals', value: 'pending' } },
|
|
40
|
+
to: { predicate: { field: 'status', operator: 'equals', value: 'approved' } },
|
|
41
|
+
};
|
|
42
|
+
|
|
43
|
+
checkTransition(approve, { status: 'pending' }, { status: 'approved' });
|
|
44
|
+
// → { ok: true, path: approve }
|
|
45
|
+
|
|
46
|
+
checkTransition(approve, { status: 'approved' }, { status: 'approved' });
|
|
47
|
+
// → { ok: false, reason: { kind: 'no-from', from: 'status must equal "pending"' } }
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
`check` returns a **structured reason**, never a bare bool:
|
|
51
|
+
|
|
52
|
+
| `reason.kind` | meaning | suggested HTTP |
|
|
53
|
+
| -------------- | -------------------------------------------------- | -------------- |
|
|
54
|
+
| `no-from` | no edge starts from the current state | 409 |
|
|
55
|
+
| `no-to` | the merged state is not a valid target | 409 |
|
|
56
|
+
| `unauthorized` | a legal edge exists but a permission denied | 403 |
|
|
57
|
+
|
|
58
|
+
`describe(reason)` builds a human-readable message; `reason.kind` drives the status code.
|
|
59
|
+
|
|
60
|
+
## Permissions are injected (the seam)
|
|
61
|
+
|
|
62
|
+
The kernel never imports an authorization library. Per-side `permission` is a serializable
|
|
63
|
+
`ActionRule` (the same rebac/abac/rbac algebra as `@template/permissions`), and you inject an
|
|
64
|
+
`authorize` callback to evaluate it:
|
|
65
|
+
|
|
66
|
+
```ts
|
|
67
|
+
import { check, createRebac } from '@inixiative/transitions';
|
|
68
|
+
|
|
69
|
+
const authorize = createRebac({ schema: rebacSchema })('inquiry');
|
|
70
|
+
check(transitions, 'inquiry', 'approve', record, changes, { actor, authorize });
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
Effective authz ANDs three rules, each against the record it reads:
|
|
74
|
+
|
|
75
|
+
```
|
|
76
|
+
action.permission AND from.permission AND to.permission
|
|
77
|
+
(verb capability) (current record) (merged record)
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
Absent = open; `null` = terminal deny.
|
|
81
|
+
|
|
82
|
+
### `createRebac` / `makeRebacAuthorize` — reference implementation
|
|
83
|
+
|
|
84
|
+
This package ships a **reference** rebac evaluator (`string` delegation, relation walk with cycle
|
|
85
|
+
detection, `{ self }`, json-rules `{ rule }`, `any`/`all`, per-row `permissionRules` override). It's
|
|
86
|
+
one implementation of the `Authorize` seam, kept deliberately swappable. It is slated to graduate
|
|
87
|
+
into a standalone `@inixiative/permissions` package — when it does, inject that instead; nothing in
|
|
88
|
+
the transition core changes.
|
|
89
|
+
|
|
90
|
+
## Affordance + set query
|
|
91
|
+
|
|
92
|
+
```ts
|
|
93
|
+
import { available, eligible } from '@inixiative/transitions';
|
|
94
|
+
|
|
95
|
+
available(transitions, 'inquiry', record, { actor, authorize });
|
|
96
|
+
// → ['approve', 'reject', 'cancel'] (from-side only — `to` needs proposed changes, so it defers to check)
|
|
97
|
+
|
|
98
|
+
eligible(transitions, 'inquiry', 'approve');
|
|
99
|
+
// → { OR: [{ status: { equals: 'pending' } }] } (Prisma where for "every record eligible for approve")
|
|
100
|
+
```
|
|
101
|
+
|
|
102
|
+
## Merge strategies
|
|
103
|
+
|
|
104
|
+
`to.merge` produces the resulting record. Keyword strategies are serializable; a callback is full-power
|
|
105
|
+
but not (`isSerializable(transition)` tells you which).
|
|
106
|
+
|
|
107
|
+
- `spread` (default) — shallow overwrite
|
|
108
|
+
- `deepMerge` — recursive, arrays replaced
|
|
109
|
+
- `{ kind: 'append', path }` — concat at a field path
|
|
110
|
+
- `{ kind: 'appendUnique', path }` — concat + dedupe
|
|
111
|
+
|
|
112
|
+
## Authoring validation
|
|
113
|
+
|
|
114
|
+
`validateTransition(t, { lens?, requireSerializable? })` validates predicates (via json-rules
|
|
115
|
+
`validateRule`, plus `checkRuleAgainstLens` when a `lens` scopes referenceable fields), merge
|
|
116
|
+
strategy, and permission shape — run it on save before persisting a tenant config.
|
|
117
|
+
|
|
118
|
+
## Not built yet (designed — see the plan)
|
|
119
|
+
|
|
120
|
+
- **`requires` relation loader** — derive a Prisma `include` from a side's `requires`, auto-load, fail
|
|
121
|
+
loud on unloaded reads, respect tenancy. The kernel ignores `requires` (it's metadata).
|
|
122
|
+
- **Permission-filtered `available()`** beyond the from-side static check.
|
|
123
|
+
- **Lens-aware structural composition** check (does A's `to` lens line up with B's `from`).
|
|
124
|
+
- **Non-goals:** statecharts, side effects / on-transition callbacks, a workflow engine, a config UI.
|
|
125
|
+
|
|
126
|
+
## License
|
|
127
|
+
|
|
128
|
+
MIT
|
package/dist/index.cjs
ADDED
|
@@ -0,0 +1,2 @@
|
|
|
1
|
+
'use strict';var jsonRules=require('@inixiative/json-rules'),lodashEs=require('lodash-es');var y=e=>Array.isArray(e)?e:e===void 0?[]:[e],O=(e,t)=>Array.isArray(t)?t:void 0,l=e=>typeof e!="function",k=(e,t,n={})=>{if(typeof e=="function")return e(t,n);let i=e??"spread";if(i==="spread")return {...t,...n};if(i==="deepMerge")return lodashEs.mergeWith(lodashEs.cloneDeep(t),lodashEs.cloneDeep(n),O);let{kind:o,path:s}=i,r=lodashEs.cloneDeep({...t,...n}),p=[...y(lodashEs.get(t,s)),...y(lodashEs.get(n,s))];return lodashEs.set(r,s,o==="appendUnique"?lodashEs.uniqWith(p,lodashEs.isEqual):p),r};var A=e=>typeof e=="string"?e:"predicate not satisfied",d=(e,t,n,i)=>!e||t===void 0?false:!e(t,n,i),b=(e,t,n={},i={})=>{let{actor:o,authorize:s,basePermission:r}=i,p=k(e.to.merge,t,n),a=jsonRules.check(e.from.predicate,t);if(a!==true)return {ok:false,reason:{kind:"no-from",from:A(a)}};let u=jsonRules.check(e.to.predicate,p);return u!==true?{ok:false,reason:{kind:"no-to",to:A(u)}}:d(s,r,t,o)?{ok:false,reason:{kind:"unauthorized",authz:"action"}}:d(s,e.from.permission,t,o)?{ok:false,reason:{kind:"unauthorized",authz:"from"}}:d(s,e.to.permission,p,o)?{ok:false,reason:{kind:"unauthorized",authz:"to"}}:{ok:true,path:e}};var Y=e=>{switch(e.kind){case "no-from":return e.from??"transition is not available from the current state";case "no-to":return e.to??"the resulting state is not a valid target";case "unauthorized":return e.authz?`not authorized (${e.authz}-level permission denied)`:"not authorized";default:return e.kind}};var c=(e,t,n,i,o,s)=>{if(e.isSuperadmin?.(i))return true;if(o===null)return false;if(typeof o=="string"){let r=e.schema[t]?.actions[o]??null,a=n.permissionRules?.[o];return c(e,t,n,i,a!==void 0?{any:[r,a]}:r,s)}if("rel"in o&&"action"in o){let r=o.rel.split("."),p=n,a=t;for(let f of r){let g=p[f];if(!g)return false;a=e.resolveModel?e.resolveModel(a,f):f,p=g;}let u=`${a}:${String(p.id)}:${o.action}`;if(s.has(u))throw new Error(`Cycle detected in permission graph: ${u}`);return s.add(u),c(e,a,p,i,o.action,s)}if("self"in o){let r=i?.id??null;return r!==null&&n[o.self]===r}return "rule"in o?jsonRules.check(o.rule,n)===true:"any"in o?o.any.some(r=>c(e,t,n,i,r,new Set(s))):"all"in o?o.all.every(r=>c(e,t,n,i,r,new Set(s))):false},C=e=>{let{model:t,...n}=e;return (i,o,s)=>c(n,t,o,s,i,new Set)},H=e=>t=>C({...e,model:t});var z=(e,t,n)=>{let i=e[t]?.[n];if(!i)throw new Error(`transition: no action "${n}" registered on model "${t}"`);return i},E=e=>{let t=e.map(({kind:r,paths:p,...a})=>a),n=r=>e.find(p=>p.kind===r),i=n("unauthorized")??n("no-to")??n("no-from");if(!i)return {kind:"no-from",paths:t};let{paths:o,...s}=i;return {...s,paths:t}},te=(e,t,n,i,o={},s={})=>{let r=z(e,t,n),p={...s,basePermission:r.permission},a=[];for(let u of r.paths){let f=b(u,i,o,p);if(f.ok)return f;a.push(f.reason);}return {ok:false,reason:E(a)}},ne=(e,t,n,i={})=>{let o=e[t];if(!o)return [];let{actor:s,authorize:r}=i,p=(a,u)=>!r||a===void 0||r(a,u,s);return Object.entries(o).filter(([,a])=>a.paths.some(u=>jsonRules.check(u.from.predicate,n)===true&&p(a.permission,n)&&p(u.from.permission,n))).map(([a])=>a)},oe=(e,t,n)=>{let i=z(e,t,n),{steps:o}=jsonRules.toPrisma({any:i.paths.map(r=>r.from.predicate)}),s=o[o.length-1];if(s?.operation!=="where"||s.where===void 0)throw new Error("transition: expected a terminal WhereStep from toPrisma; got none");return s.where};var re=e=>l(e.to.merge);var _=new Set(["spread","deepMerge"]),L=new Set(["append","appendUnique"]),N=(e,t,n,i)=>{let o=jsonRules.validateRule(e);for(let s of o.errors)t.push({path:`${n}.${s.path}`,message:s.message});if(i){let s=jsonRules.checkRuleAgainstLens(e,i);for(let r of s.violations)t.push({path:`${n}.${r.path}`,message:r.reason});}},h=(e,t,n)=>{if(!(e==null||typeof e=="string")){if("rule"in e){let i=jsonRules.validateRule(e.rule);for(let o of i.errors)t.push({path:`${n}.rule.${o.path}`,message:o.message});return}if("rel"in e){(!e.rel||!e.action)&&t.push({path:n,message:"rel-rule requires non-empty `rel` and `action`"});return}if("self"in e){e.self||t.push({path:n,message:"self-rule requires a non-empty field name"});return}if("any"in e){e.any.forEach((i,o)=>{h(i,t,`${n}.any[${o}]`);});return}if("all"in e){e.all.forEach((i,o)=>{h(i,t,`${n}.all[${o}]`);});return}t.push({path:n,message:"unrecognized ActionRule shape"});}},W=(e,t,n)=>{if(!(e===void 0||typeof e=="function")){if(typeof e=="string"){_.has(e)||t.push({path:n,message:`unknown merge strategy "${e}"`});return}L.has(e.kind)?e.path||t.push({path:n,message:`merge "${e.kind}" requires a \`path\``}):t.push({path:n,message:`unknown merge kind "${e.kind}"`});}},S=(e,t,n,i)=>{N(e.predicate,t,`${n}.predicate`,i.lens),h(e.permission,t,`${n}.permission`),e.requires!==void 0&&(typeof e.requires!="object"||e.requires===null)&&t.push({path:`${n}.requires`,message:"`requires` must be a Prisma-include-shaped object"}),"merge"in e&&W(e.merge,t,`${n}.merge`);},fe=(e,t={})=>{let n=[];return S(e.from,n,"from",t),S(e.to,n,"to",t),t.requireSerializable&&!l(e.to.merge)&&n.push({path:"to.merge",message:"callback merge is not serializable; use a keyword strategy"}),{ok:n.length===0,errors:n}};exports.applyMerge=k;exports.available=ne;exports.check=te;exports.checkTransition=b;exports.createRebac=H;exports.describe=Y;exports.eligible=oe;exports.isSerializable=re;exports.isSerializableMerge=l;exports.makeRebacAuthorize=C;exports.validateTransition=fe;//# sourceMappingURL=index.cjs.map
|
|
2
|
+
//# sourceMappingURL=index.cjs.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"sources":["../src/merge.ts","../src/check.ts","../src/describe.ts","../src/rebac/authorize.ts","../src/registry.ts","../src/serializable.ts","../src/validate.ts"],"names":["toArray","value","replaceArrays","_target","source","isSerializableMerge","merge","applyMerge","record","changes","strategy","mergeWith","cloneDeep","kind","path","base","merged","get","set","uniqWith","isEqual","reasonString","result","denies","authorize","rule","actor","checkTransition","transition","options","basePermission","next","fromResult","checkRule","toResult","describe","reason","evaluate","ctx","model","visited","schemaRule","rowRule","segments","current","currentModel","segment","related","key","actorId","sub","makeRebacAuthorize","rest","createRebac","getAction","map","verb","action","aggregate","failures","paths","_kind","_paths","pick","failure","chosen","_omit","representative","check","opts","available","actions","allows","rec","eligible","steps","toPrisma","last","isSerializable","MERGE_KEYWORDS","ARRAY_KINDS","validatePredicate","predicate","errors","lens","validateRule","issue","lensCheck","checkRuleAgainstLens","violation","validatePermission","i","validateMerge","validateSide","side","validateTransition"],"mappings":"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","file":"index.cjs","sourcesContent":["import { cloneDeep, get, isEqual, mergeWith, set, uniqWith } from 'lodash-es';\nimport type { Merge, MergeStrategy, Row } from './types';\n\nconst toArray = (value: unknown): unknown[] =>\n Array.isArray(value) ? value : value === undefined ? [] : [value];\n\n// deepMerge replaces arrays wholesale rather than index-merging them (the intuitive default).\nconst replaceArrays = (_target: unknown, source: unknown): unknown[] | undefined =>\n Array.isArray(source) ? source : undefined;\n\n/** A transition is persistable iff its merge is absent or a keyword strategy (callbacks are not). */\nexport const isSerializableMerge = (merge?: Merge): boolean => typeof merge !== 'function';\n\n/**\n * Produce the resulting record from a current record + proposed changes.\n *\n * - `spread` (default) — shallow overwrite (`{ ...record, ...changes }`)\n * - `deepMerge` — recursive object merge, arrays replaced\n * - `{ kind: 'append', path }` — concat `changes[path]` onto `record[path]`\n * - `{ kind: 'appendUnique', path }` — append + dedupe (deep equality)\n * - a callback — full power, not serializable\n */\nexport const applyMerge = <R extends Row>(\n merge: Merge<R> | undefined,\n record: R,\n changes: Partial<R> = {},\n): R => {\n if (typeof merge === 'function') return merge(record, changes);\n\n const strategy: MergeStrategy = merge ?? 'spread';\n\n if (strategy === 'spread') return { ...record, ...changes };\n // clone BOTH inputs: mergeWith assigns nested objects/arrays from `changes` by reference, which\n // would alias the caller's `changes` into the returned record (a mutation footgun for a pure guard).\n if (strategy === 'deepMerge')\n return mergeWith(cloneDeep(record), cloneDeep(changes), replaceArrays);\n\n // field-scoped array strategies: spread the rest of `changes`, then concat at `path`.\n const { kind, path } = strategy;\n const base = cloneDeep({ ...record, ...changes }) as R;\n const merged = [...toArray(get(record, path)), ...toArray(get(changes, path))];\n set(base as Row, path, kind === 'appendUnique' ? uniqWith(merged, isEqual) : merged);\n return base;\n};\n","import { check as checkRule } from '@inixiative/json-rules';\nimport { applyMerge } from './merge';\nimport type {\n ActionRule,\n Actor,\n Authorize,\n CheckOptions,\n CheckResult,\n Row,\n Transition,\n} from './types';\n\nconst reasonString = (result: boolean | string): string =>\n typeof result === 'string' ? result : 'predicate not satisfied';\n\n/**\n * Does this permission DENY?\n * - no authorizer injected → can't deny (legality-only mode)\n * - `undefined` rule → permission absent → open → can't deny\n * - any other rule (incl. `null` = terminal deny) → delegate to the authorizer\n */\nconst denies = (\n authorize: Authorize | undefined,\n rule: ActionRule | undefined,\n record: Row,\n actor: Actor,\n): boolean => {\n if (!authorize || rule === undefined) return false;\n return !authorize(rule, record, actor);\n};\n\n/**\n * The kernel: evaluate one atomic transition.\n *\n * Legality (json-rules) AND authz (injected, per side), with the load-bearing asymmetry —\n * `from.*` reads the current `record`, `to.*` reads the merged `next` record. Authz order is\n * action baseline → from → to, all ANDed. Returns a structured {@link CheckResult} whose\n * `reason.kind` lets a caller map illegal → 409 vs unauthorized → 403.\n *\n * Omit `options.authorize` to check legality only.\n */\nexport const checkTransition = <R extends Row>(\n transition: Transition<R>,\n record: R,\n changes: Partial<R> = {},\n options: CheckOptions = {},\n): CheckResult<R> => {\n const { actor, authorize, basePermission } = options;\n const next = applyMerge(transition.to.merge, record, changes);\n\n const fromResult = checkRule(transition.from.predicate, record as Row);\n if (fromResult !== true)\n return { ok: false, reason: { kind: 'no-from', from: reasonString(fromResult) } };\n\n const toResult = checkRule(transition.to.predicate, next as Row);\n if (toResult !== true)\n return { ok: false, reason: { kind: 'no-to', to: reasonString(toResult) } };\n\n if (denies(authorize, basePermission, record as Row, actor))\n return { ok: false, reason: { kind: 'unauthorized', authz: 'action' } };\n if (denies(authorize, transition.from.permission, record as Row, actor))\n return { ok: false, reason: { kind: 'unauthorized', authz: 'from' } };\n if (denies(authorize, transition.to.permission, next as Row, actor))\n return { ok: false, reason: { kind: 'unauthorized', authz: 'to' } };\n\n return { ok: true, path: transition };\n};\n","import type { Reason } from './types';\n\n/** Build a human-readable message from a structured {@link Reason} (logs / UI / error bodies). */\nexport const describe = (reason: Reason): string => {\n switch (reason.kind) {\n case 'no-from':\n return reason.from ?? 'transition is not available from the current state';\n case 'no-to':\n return reason.to ?? 'the resulting state is not a valid target';\n case 'unauthorized':\n return reason.authz\n ? `not authorized (${reason.authz}-level permission denied)`\n : 'not authorized';\n default: {\n // exhaustiveness guard: a new FailureKind must be handled here, not silently return undefined\n const _exhaustive: never = reason.kind;\n return _exhaustive;\n }\n }\n};\n","import { check as checkRule } from '@inixiative/json-rules';\nimport type { ActionRule, Actor, Authorize, Row } from '../types';\nimport type { RebacOptions, RebacSchema } from './types';\n\ntype Context = {\n schema: RebacSchema;\n resolveModel?: (model: string, relationSegment: string) => string;\n isSuperadmin?: (actor: Actor) => boolean;\n};\n\nconst evaluate = (\n ctx: Context,\n model: string,\n record: Row,\n actor: Actor,\n rule: ActionRule,\n visited: Set<string>,\n): boolean => {\n if (ctx.isSuperadmin?.(actor)) return true;\n if (rule === null) return false;\n\n // string → delegate to the named action on this model, additively merged with any per-row override.\n if (typeof rule === 'string') {\n const schemaRule = ctx.schema[model]?.actions[rule] ?? null;\n const rowRules = record.permissionRules as Record<string, ActionRule> | null | undefined;\n const rowRule = rowRules?.[rule];\n const merged: ActionRule = rowRule !== undefined ? { any: [schemaRule, rowRule] } : schemaRule;\n return evaluate(ctx, model, record, actor, merged, visited);\n }\n\n // { rel, action } → walk the relation (dot-paths supported), then check `action` on the target.\n if ('rel' in rule && 'action' in rule) {\n const segments = rule.rel.split('.');\n let current: Row = record;\n let currentModel = model;\n for (const segment of segments) {\n const related = current[segment] as Row | null | undefined;\n if (!related) return false;\n currentModel = ctx.resolveModel ? ctx.resolveModel(currentModel, segment) : segment;\n current = related;\n }\n const key = `${currentModel}:${String(current.id)}:${rule.action}`;\n if (visited.has(key)) throw new Error(`Cycle detected in permission graph: ${key}`);\n visited.add(key);\n return evaluate(ctx, currentModel, current, actor, rule.action, visited);\n }\n\n // { self } → record[field] matches the current actor.\n if ('self' in rule) {\n const actorId = actor?.id ?? null;\n return actorId !== null && record[rule.self] === actorId;\n }\n\n // { rule } → ABAC predicate (json-rules) over the record.\n if ('rule' in rule) return checkRule(rule.rule, record) === true;\n\n // Fork `visited` per branch — parallel paths through any/all aren't cycles.\n if ('any' in rule)\n return rule.any.some((sub) => evaluate(ctx, model, record, actor, sub, new Set(visited)));\n if ('all' in rule)\n return rule.all.every((sub) => evaluate(ctx, model, record, actor, sub, new Set(visited)));\n\n return false;\n};\n\n/**\n * A reference rebac evaluator — one implementation of the injected {@link Authorize} seam,\n * bound to a single `model`. Faithful to `@template/permissions`' `rebac/check` (string-delegate,\n * relation walk with cycle detection, self, json-rules `{ rule }`, any/all, per-row\n * `permissionRules` override) but standalone. Swap it for a richer authorizer in production;\n * this is slated to graduate into `@inixiative/permissions`.\n */\nexport const makeRebacAuthorize = (options: RebacOptions & { model: string }): Authorize => {\n const { model, ...rest } = options;\n return (rule, record, actor) => evaluate(rest, model, record, actor, rule, new Set());\n};\n\n/** Curried form: `createRebac({ schema })(model)` → an {@link Authorize} for that model. */\nexport const createRebac =\n (options: RebacOptions) =>\n (model: string): Authorize =>\n makeRebacAuthorize({ ...options, model });\n","import { check as checkRule, toPrisma } from '@inixiative/json-rules';\nimport { checkTransition } from './check';\nimport type {\n Action,\n AuthorizeOptions,\n CheckOptions,\n CheckResult,\n PathFailure,\n Reason,\n Row,\n TransitionMap,\n} from './types';\n\nconst getAction = (map: TransitionMap, model: string, verb: string): Action => {\n const action = map[model]?.[verb];\n if (!action) throw new Error(`transition: no action \"${verb}\" registered on model \"${model}\"`);\n return action;\n};\n\n// Pick the most-progressed failure across an action's paths:\n// unauthorized (a legal edge existed but authz denied) → 403\n// no-to (from matched, target invalid) → 409\n// no-from (no edge even starts here) → 409\nconst aggregate = (failures: Reason[]): Reason => {\n const paths: PathFailure[] = failures.map(({ kind: _kind, paths: _paths, ...rest }) => rest);\n const pick = (kind: Reason['kind']) => failures.find((failure) => failure.kind === kind);\n const chosen = pick('unauthorized') ?? pick('no-to') ?? pick('no-from');\n if (!chosen) return { kind: 'no-from', paths };\n const { paths: _omit, ...representative } = chosen;\n return { ...representative, paths };\n};\n\n/**\n * Authoritative check: the FIRST path whose `from` matches the current record, whose `to`\n * matches the merged record, and whose permissions all pass, wins. If none pass, returns the\n * aggregated structured failure (see {@link aggregate}).\n */\nexport const check = (\n map: TransitionMap,\n model: string,\n verb: string,\n record: Row,\n changes: Row = {},\n options: AuthorizeOptions = {},\n): CheckResult => {\n const action = getAction(map, model, verb);\n const opts: CheckOptions = { ...options, basePermission: action.permission };\n\n const failures: Reason[] = [];\n for (const path of action.paths) {\n const result = checkTransition(path, record, changes, opts);\n if (result.ok) return result;\n failures.push(result.reason);\n }\n return { ok: false, reason: aggregate(failures) };\n};\n\n/**\n * Affordance hint: which verbs are offerable from `record` right now. Evaluates ONLY the\n * `from` side (predicate + `action`/`from` permission against the current record) — `to` needs\n * the merged record, which doesn't exist without proposed changes, so it defers to {@link check}.\n */\nexport const available = (\n map: TransitionMap,\n model: string,\n record: Row,\n options: AuthorizeOptions = {},\n): string[] => {\n const actions = map[model];\n if (!actions) return [];\n const { actor, authorize } = options;\n\n const allows = (rule: Action['permission'], rec: Row): boolean =>\n !authorize || rule === undefined || authorize(rule, rec, actor);\n\n return Object.entries(actions)\n .filter(([, action]) =>\n action.paths.some(\n (path) =>\n checkRule(path.from.predicate, record) === true &&\n allows(action.permission, record) &&\n allows(path.from.permission, record),\n ),\n )\n .map(([verb]) => verb);\n};\n\n/**\n * Set query: one OR'd Prisma `where` matching every record currently eligible for `verb`\n * (the union of all its paths' `from` predicates). Empty action → match-nothing.\n */\nexport const eligible = (map: TransitionMap, model: string, verb: string): Row => {\n const action = getAction(map, model, verb);\n const { steps } = toPrisma({ any: action.paths.map((path) => path.from.predicate) });\n // json-rules guarantees the last step is the WhereStep. Assert it loudly rather than cast-and-swallow:\n // a silent `{}` fallback would mean match-EVERYTHING — the dangerous inverse of the intended\n // match-nothing — if a future json-rules emits a trailing non-where step or multi-step relation refs.\n const last = steps[steps.length - 1] as { operation?: string; where?: Row } | undefined;\n if (last?.operation !== 'where' || last.where === undefined)\n throw new Error('transition: expected a terminal WhereStep from toPrisma; got none');\n return last.where;\n};\n","import { isSerializableMerge } from './merge';\nimport type { Transition } from './types';\n\n/**\n * Can this transition be persisted (stored in the DB, edited in a UI, sent over the wire)?\n *\n * Predicates (json-rules) and permissions (ActionRule) are always plain JSON; the only\n * non-data escape hatch is a `to.merge` callback. So serializability reduces to the merge.\n */\nexport const isSerializable = (transition: Transition): boolean =>\n isSerializableMerge(transition.to.merge);\n","import {\n type Condition,\n checkRuleAgainstLens,\n type Lens,\n type LensNarrowing,\n validateRule,\n} from '@inixiative/json-rules';\nimport { isSerializableMerge } from './merge';\nimport type { ActionRule, Merge, Side, ToSide, Transition } from './types';\n\nexport type ValidationIssue = { path: string; message: string };\nexport type ValidationResult = { ok: boolean; errors: ValidationIssue[] };\n\nexport type ValidateOptions = {\n /** Optional field/relation allowlist; passed through to json-rules lens validation per predicate. */\n lens?: Lens | LensNarrowing;\n /** Reject callback merges (use when the transition must be persistable / tenant-configured). */\n requireSerializable?: boolean;\n};\n\nconst MERGE_KEYWORDS = new Set(['spread', 'deepMerge']);\nconst ARRAY_KINDS = new Set(['append', 'appendUnique']);\n\nconst validatePredicate = (\n predicate: Condition,\n errors: ValidationIssue[],\n path: string,\n lens?: Lens | LensNarrowing,\n): void => {\n const result = validateRule(predicate);\n for (const issue of result.errors)\n errors.push({ path: `${path}.${issue.path}`, message: issue.message });\n if (lens) {\n const lensCheck = checkRuleAgainstLens(predicate, lens);\n for (const violation of lensCheck.violations)\n errors.push({ path: `${path}.${violation.path}`, message: violation.reason });\n }\n};\n\nconst validatePermission = (\n rule: ActionRule | undefined,\n errors: ValidationIssue[],\n path: string,\n): void => {\n if (rule === undefined || rule === null || typeof rule === 'string') return;\n if ('rule' in rule) {\n const result = validateRule(rule.rule);\n for (const issue of result.errors)\n errors.push({ path: `${path}.rule.${issue.path}`, message: issue.message });\n return;\n }\n if ('rel' in rule) {\n if (!rule.rel || !rule.action)\n errors.push({ path, message: 'rel-rule requires non-empty `rel` and `action`' });\n return;\n }\n if ('self' in rule) {\n if (!rule.self) errors.push({ path, message: 'self-rule requires a non-empty field name' });\n return;\n }\n if ('any' in rule) {\n rule.any.forEach((sub, i) => {\n validatePermission(sub, errors, `${path}.any[${i}]`);\n });\n return;\n }\n if ('all' in rule) {\n rule.all.forEach((sub, i) => {\n validatePermission(sub, errors, `${path}.all[${i}]`);\n });\n return;\n }\n errors.push({ path, message: 'unrecognized ActionRule shape' });\n};\n\nconst validateMerge = (merge: Merge | undefined, errors: ValidationIssue[], path: string): void => {\n if (merge === undefined || typeof merge === 'function') return;\n if (typeof merge === 'string') {\n if (!MERGE_KEYWORDS.has(merge))\n errors.push({ path, message: `unknown merge strategy \"${merge}\"` });\n return;\n }\n if (!ARRAY_KINDS.has(merge.kind))\n errors.push({ path, message: `unknown merge kind \"${merge.kind}\"` });\n else if (!merge.path) errors.push({ path, message: `merge \"${merge.kind}\" requires a \\`path\\`` });\n};\n\nconst validateSide = (\n side: Side | ToSide,\n errors: ValidationIssue[],\n path: string,\n options: ValidateOptions,\n): void => {\n validatePredicate(side.predicate, errors, `${path}.predicate`, options.lens);\n validatePermission(side.permission, errors, `${path}.permission`);\n if (side.requires !== undefined && (typeof side.requires !== 'object' || side.requires === null))\n errors.push({\n path: `${path}.requires`,\n message: '`requires` must be a Prisma-include-shaped object',\n });\n if ('merge' in side) validateMerge(side.merge, errors, `${path}.merge`);\n};\n\n/**\n * Authoring validation for a single transition — run on save before persisting a tenant config.\n * Predicate validity delegates to json-rules (`validateRule`, plus `checkRuleAgainstLens` when a\n * `lens` is supplied for field/relation scoping); merge strategy and permission shape are checked here.\n */\nexport const validateTransition = (\n transition: Transition,\n options: ValidateOptions = {},\n): ValidationResult => {\n const errors: ValidationIssue[] = [];\n validateSide(transition.from, errors, 'from', options);\n validateSide(transition.to, errors, 'to', options);\n if (options.requireSerializable && !isSerializableMerge(transition.to.merge))\n errors.push({\n path: 'to.merge',\n message: 'callback merge is not serializable; use a keyword strategy',\n });\n return { ok: errors.length === 0, errors };\n};\n"]}
|
package/dist/index.d.cts
ADDED
|
@@ -0,0 +1,216 @@
|
|
|
1
|
+
import { Condition, Lens, LensNarrowing } from '@inixiative/json-rules';
|
|
2
|
+
|
|
3
|
+
type Row = Record<string, unknown>;
|
|
4
|
+
/**
|
|
5
|
+
* The serializable permission algebra.
|
|
6
|
+
*
|
|
7
|
+
* Re-declared here — deliberately NOT imported from any app's permissions package — so
|
|
8
|
+
* `@inixiative/transitions` stays a zero-app-dependency primitive. It is structurally
|
|
9
|
+
* identical to the rebac `ActionRule` used by `@template/permissions`, so a permission
|
|
10
|
+
* rule authored over there deserializes into a transition's `permission` field unchanged.
|
|
11
|
+
*
|
|
12
|
+
* The kernel never *interprets* an ActionRule; it hands the rule to an injected
|
|
13
|
+
* {@link Authorize} callback. Resolving `string` (delegate) and `{ rel, action }`
|
|
14
|
+
* (relation walk) requires a model + schema, which lives in the authorizer, not here.
|
|
15
|
+
*/
|
|
16
|
+
type ActionRule = string | {
|
|
17
|
+
rel: string;
|
|
18
|
+
action: string;
|
|
19
|
+
} | {
|
|
20
|
+
self: string;
|
|
21
|
+
} | {
|
|
22
|
+
rule: Condition;
|
|
23
|
+
} | {
|
|
24
|
+
any: ActionRule[];
|
|
25
|
+
} | {
|
|
26
|
+
all: ActionRule[];
|
|
27
|
+
} | null;
|
|
28
|
+
type Actor = ({
|
|
29
|
+
id?: string | null;
|
|
30
|
+
} & Row) | null | undefined;
|
|
31
|
+
/**
|
|
32
|
+
* Injected permission evaluator. Model-free by design: the kernel knows nothing about
|
|
33
|
+
* models or schemas, so the consumer closes over whatever its rebac needs (see
|
|
34
|
+
* {@link makeRebacAuthorize} for the reference implementation). Returns a bare boolean —
|
|
35
|
+
* authz is yes/no; the structured-reason machinery lives in the kernel.
|
|
36
|
+
*/
|
|
37
|
+
type Authorize = (rule: ActionRule, record: Row, actor: Actor) => boolean;
|
|
38
|
+
/** Serializable merge keywords (Mongo-flavored). Array strategies are field-scoped. */
|
|
39
|
+
type MergeStrategy = 'spread' | 'deepMerge' | {
|
|
40
|
+
kind: 'append';
|
|
41
|
+
path: string;
|
|
42
|
+
} | {
|
|
43
|
+
kind: 'appendUnique';
|
|
44
|
+
path: string;
|
|
45
|
+
};
|
|
46
|
+
/** A merge is a raw callback (full power, NOT serializable) or a serializable keyword strategy. */
|
|
47
|
+
type Merge<R extends Row = Row> = ((record: R, changes: Partial<R>) => R) | MergeStrategy;
|
|
48
|
+
/** Prisma-include-shaped metadata: the relations a side's predicate reads. Kernel ignores it. */
|
|
49
|
+
type Include = Record<string, unknown>;
|
|
50
|
+
/**
|
|
51
|
+
* One half of a transition. `predicate` (legality) and `permission` (authz) are evaluated
|
|
52
|
+
* against the SAME record — and which record is the load-bearing asymmetry:
|
|
53
|
+
* `from.*` reads the CURRENT record, `to.*` reads the RESULTING (merged) record.
|
|
54
|
+
*/
|
|
55
|
+
type Side = {
|
|
56
|
+
predicate: Condition;
|
|
57
|
+
permission?: ActionRule;
|
|
58
|
+
requires?: Include;
|
|
59
|
+
};
|
|
60
|
+
type ToSide<R extends Row = Row> = Side & {
|
|
61
|
+
merge?: Merge<R>;
|
|
62
|
+
};
|
|
63
|
+
/** An atomic edge: `from → to`. Disjunction lives at the action level, never here. */
|
|
64
|
+
type Transition<R extends Row = Row> = {
|
|
65
|
+
from: Side;
|
|
66
|
+
to: ToSide<R>;
|
|
67
|
+
};
|
|
68
|
+
/**
|
|
69
|
+
* A named verb: the OR of its edges. An object (not a bare `Transition[]`) because the
|
|
70
|
+
* action is the unit of authorization (`permission`, ANDed with each side) and affordance
|
|
71
|
+
* (`label`).
|
|
72
|
+
*/
|
|
73
|
+
type Action<R extends Row = Row> = {
|
|
74
|
+
paths: Transition<R>[];
|
|
75
|
+
permission?: ActionRule;
|
|
76
|
+
label?: string;
|
|
77
|
+
};
|
|
78
|
+
/** `model → verb → Action`. Mirrors the shape of a rebac schema. */
|
|
79
|
+
type TransitionMap = Record<string, Record<string, Action>>;
|
|
80
|
+
type FailureKind = 'no-from' | 'no-to' | 'unauthorized';
|
|
81
|
+
type AuthzLevel = 'action' | 'from' | 'to';
|
|
82
|
+
type PathFailure = {
|
|
83
|
+
from?: string;
|
|
84
|
+
to?: string;
|
|
85
|
+
authz?: AuthzLevel;
|
|
86
|
+
};
|
|
87
|
+
type Reason = PathFailure & {
|
|
88
|
+
kind: FailureKind;
|
|
89
|
+
paths?: PathFailure[];
|
|
90
|
+
};
|
|
91
|
+
type CheckResult<R extends Row = Row> = {
|
|
92
|
+
ok: true;
|
|
93
|
+
path: Transition<R>;
|
|
94
|
+
} | {
|
|
95
|
+
ok: false;
|
|
96
|
+
reason: Reason;
|
|
97
|
+
};
|
|
98
|
+
/** Options threaded into a check. Omit `authorize` to evaluate legality only. */
|
|
99
|
+
type CheckOptions = {
|
|
100
|
+
actor?: Actor;
|
|
101
|
+
authorize?: Authorize;
|
|
102
|
+
/** Action-level baseline permission, ANDed against the current record (supplied by the registry). */
|
|
103
|
+
basePermission?: ActionRule;
|
|
104
|
+
};
|
|
105
|
+
/** Options for affordance/check at the registry level. */
|
|
106
|
+
type AuthorizeOptions = {
|
|
107
|
+
actor?: Actor;
|
|
108
|
+
authorize?: Authorize;
|
|
109
|
+
};
|
|
110
|
+
|
|
111
|
+
/**
|
|
112
|
+
* The kernel: evaluate one atomic transition.
|
|
113
|
+
*
|
|
114
|
+
* Legality (json-rules) AND authz (injected, per side), with the load-bearing asymmetry —
|
|
115
|
+
* `from.*` reads the current `record`, `to.*` reads the merged `next` record. Authz order is
|
|
116
|
+
* action baseline → from → to, all ANDed. Returns a structured {@link CheckResult} whose
|
|
117
|
+
* `reason.kind` lets a caller map illegal → 409 vs unauthorized → 403.
|
|
118
|
+
*
|
|
119
|
+
* Omit `options.authorize` to check legality only.
|
|
120
|
+
*/
|
|
121
|
+
declare const checkTransition: <R extends Row>(transition: Transition<R>, record: R, changes?: Partial<R>, options?: CheckOptions) => CheckResult<R>;
|
|
122
|
+
|
|
123
|
+
/** Build a human-readable message from a structured {@link Reason} (logs / UI / error bodies). */
|
|
124
|
+
declare const describe: (reason: Reason) => string;
|
|
125
|
+
|
|
126
|
+
/** A transition is persistable iff its merge is absent or a keyword strategy (callbacks are not). */
|
|
127
|
+
declare const isSerializableMerge: (merge?: Merge) => boolean;
|
|
128
|
+
/**
|
|
129
|
+
* Produce the resulting record from a current record + proposed changes.
|
|
130
|
+
*
|
|
131
|
+
* - `spread` (default) — shallow overwrite (`{ ...record, ...changes }`)
|
|
132
|
+
* - `deepMerge` — recursive object merge, arrays replaced
|
|
133
|
+
* - `{ kind: 'append', path }` — concat `changes[path]` onto `record[path]`
|
|
134
|
+
* - `{ kind: 'appendUnique', path }` — append + dedupe (deep equality)
|
|
135
|
+
* - a callback — full power, not serializable
|
|
136
|
+
*/
|
|
137
|
+
declare const applyMerge: <R extends Row>(merge: Merge<R> | undefined, record: R, changes?: Partial<R>) => R;
|
|
138
|
+
|
|
139
|
+
type ModelPermission = {
|
|
140
|
+
actions: Record<string, ActionRule>;
|
|
141
|
+
};
|
|
142
|
+
/** `model → { actions: { actionName → ActionRule } }`. Mirrors `@template/permissions` RebacSchema. */
|
|
143
|
+
type RebacSchema = Record<string, ModelPermission>;
|
|
144
|
+
type RebacOptions = {
|
|
145
|
+
schema: RebacSchema;
|
|
146
|
+
/**
|
|
147
|
+
* Resolve the model a relation points at, given the source model + relation segment.
|
|
148
|
+
* Default: the relation segment name doubles as the target model key. Supply this when your
|
|
149
|
+
* relation field names differ from your model names (the template binds this via prismaMap).
|
|
150
|
+
*/
|
|
151
|
+
resolveModel?: (model: string, relationSegment: string) => string;
|
|
152
|
+
/** Optional superadmin bypass, checked before any rule. */
|
|
153
|
+
isSuperadmin?: (actor: Actor) => boolean;
|
|
154
|
+
};
|
|
155
|
+
|
|
156
|
+
/**
|
|
157
|
+
* A reference rebac evaluator — one implementation of the injected {@link Authorize} seam,
|
|
158
|
+
* bound to a single `model`. Faithful to `@template/permissions`' `rebac/check` (string-delegate,
|
|
159
|
+
* relation walk with cycle detection, self, json-rules `{ rule }`, any/all, per-row
|
|
160
|
+
* `permissionRules` override) but standalone. Swap it for a richer authorizer in production;
|
|
161
|
+
* this is slated to graduate into `@inixiative/permissions`.
|
|
162
|
+
*/
|
|
163
|
+
declare const makeRebacAuthorize: (options: RebacOptions & {
|
|
164
|
+
model: string;
|
|
165
|
+
}) => Authorize;
|
|
166
|
+
/** Curried form: `createRebac({ schema })(model)` → an {@link Authorize} for that model. */
|
|
167
|
+
declare const createRebac: (options: RebacOptions) => (model: string) => Authorize;
|
|
168
|
+
|
|
169
|
+
/**
|
|
170
|
+
* Authoritative check: the FIRST path whose `from` matches the current record, whose `to`
|
|
171
|
+
* matches the merged record, and whose permissions all pass, wins. If none pass, returns the
|
|
172
|
+
* aggregated structured failure (see {@link aggregate}).
|
|
173
|
+
*/
|
|
174
|
+
declare const check: (map: TransitionMap, model: string, verb: string, record: Row, changes?: Row, options?: AuthorizeOptions) => CheckResult;
|
|
175
|
+
/**
|
|
176
|
+
* Affordance hint: which verbs are offerable from `record` right now. Evaluates ONLY the
|
|
177
|
+
* `from` side (predicate + `action`/`from` permission against the current record) — `to` needs
|
|
178
|
+
* the merged record, which doesn't exist without proposed changes, so it defers to {@link check}.
|
|
179
|
+
*/
|
|
180
|
+
declare const available: (map: TransitionMap, model: string, record: Row, options?: AuthorizeOptions) => string[];
|
|
181
|
+
/**
|
|
182
|
+
* Set query: one OR'd Prisma `where` matching every record currently eligible for `verb`
|
|
183
|
+
* (the union of all its paths' `from` predicates). Empty action → match-nothing.
|
|
184
|
+
*/
|
|
185
|
+
declare const eligible: (map: TransitionMap, model: string, verb: string) => Row;
|
|
186
|
+
|
|
187
|
+
/**
|
|
188
|
+
* Can this transition be persisted (stored in the DB, edited in a UI, sent over the wire)?
|
|
189
|
+
*
|
|
190
|
+
* Predicates (json-rules) and permissions (ActionRule) are always plain JSON; the only
|
|
191
|
+
* non-data escape hatch is a `to.merge` callback. So serializability reduces to the merge.
|
|
192
|
+
*/
|
|
193
|
+
declare const isSerializable: (transition: Transition) => boolean;
|
|
194
|
+
|
|
195
|
+
type ValidationIssue = {
|
|
196
|
+
path: string;
|
|
197
|
+
message: string;
|
|
198
|
+
};
|
|
199
|
+
type ValidationResult = {
|
|
200
|
+
ok: boolean;
|
|
201
|
+
errors: ValidationIssue[];
|
|
202
|
+
};
|
|
203
|
+
type ValidateOptions = {
|
|
204
|
+
/** Optional field/relation allowlist; passed through to json-rules lens validation per predicate. */
|
|
205
|
+
lens?: Lens | LensNarrowing;
|
|
206
|
+
/** Reject callback merges (use when the transition must be persistable / tenant-configured). */
|
|
207
|
+
requireSerializable?: boolean;
|
|
208
|
+
};
|
|
209
|
+
/**
|
|
210
|
+
* Authoring validation for a single transition — run on save before persisting a tenant config.
|
|
211
|
+
* Predicate validity delegates to json-rules (`validateRule`, plus `checkRuleAgainstLens` when a
|
|
212
|
+
* `lens` is supplied for field/relation scoping); merge strategy and permission shape are checked here.
|
|
213
|
+
*/
|
|
214
|
+
declare const validateTransition: (transition: Transition, options?: ValidateOptions) => ValidationResult;
|
|
215
|
+
|
|
216
|
+
export { type Action, type ActionRule, type Actor, type Authorize, type AuthorizeOptions, type AuthzLevel, type CheckOptions, type CheckResult, type FailureKind, type Include, type Merge, type MergeStrategy, type ModelPermission, type PathFailure, type Reason, type RebacOptions, type RebacSchema, type Row, type Side, type ToSide, type Transition, type TransitionMap, type ValidateOptions, type ValidationIssue, type ValidationResult, applyMerge, available, check, checkTransition, createRebac, describe, eligible, isSerializable, isSerializableMerge, makeRebacAuthorize, validateTransition };
|
package/dist/index.d.ts
ADDED
|
@@ -0,0 +1,216 @@
|
|
|
1
|
+
import { Condition, Lens, LensNarrowing } from '@inixiative/json-rules';
|
|
2
|
+
|
|
3
|
+
type Row = Record<string, unknown>;
|
|
4
|
+
/**
|
|
5
|
+
* The serializable permission algebra.
|
|
6
|
+
*
|
|
7
|
+
* Re-declared here — deliberately NOT imported from any app's permissions package — so
|
|
8
|
+
* `@inixiative/transitions` stays a zero-app-dependency primitive. It is structurally
|
|
9
|
+
* identical to the rebac `ActionRule` used by `@template/permissions`, so a permission
|
|
10
|
+
* rule authored over there deserializes into a transition's `permission` field unchanged.
|
|
11
|
+
*
|
|
12
|
+
* The kernel never *interprets* an ActionRule; it hands the rule to an injected
|
|
13
|
+
* {@link Authorize} callback. Resolving `string` (delegate) and `{ rel, action }`
|
|
14
|
+
* (relation walk) requires a model + schema, which lives in the authorizer, not here.
|
|
15
|
+
*/
|
|
16
|
+
type ActionRule = string | {
|
|
17
|
+
rel: string;
|
|
18
|
+
action: string;
|
|
19
|
+
} | {
|
|
20
|
+
self: string;
|
|
21
|
+
} | {
|
|
22
|
+
rule: Condition;
|
|
23
|
+
} | {
|
|
24
|
+
any: ActionRule[];
|
|
25
|
+
} | {
|
|
26
|
+
all: ActionRule[];
|
|
27
|
+
} | null;
|
|
28
|
+
type Actor = ({
|
|
29
|
+
id?: string | null;
|
|
30
|
+
} & Row) | null | undefined;
|
|
31
|
+
/**
|
|
32
|
+
* Injected permission evaluator. Model-free by design: the kernel knows nothing about
|
|
33
|
+
* models or schemas, so the consumer closes over whatever its rebac needs (see
|
|
34
|
+
* {@link makeRebacAuthorize} for the reference implementation). Returns a bare boolean —
|
|
35
|
+
* authz is yes/no; the structured-reason machinery lives in the kernel.
|
|
36
|
+
*/
|
|
37
|
+
type Authorize = (rule: ActionRule, record: Row, actor: Actor) => boolean;
|
|
38
|
+
/** Serializable merge keywords (Mongo-flavored). Array strategies are field-scoped. */
|
|
39
|
+
type MergeStrategy = 'spread' | 'deepMerge' | {
|
|
40
|
+
kind: 'append';
|
|
41
|
+
path: string;
|
|
42
|
+
} | {
|
|
43
|
+
kind: 'appendUnique';
|
|
44
|
+
path: string;
|
|
45
|
+
};
|
|
46
|
+
/** A merge is a raw callback (full power, NOT serializable) or a serializable keyword strategy. */
|
|
47
|
+
type Merge<R extends Row = Row> = ((record: R, changes: Partial<R>) => R) | MergeStrategy;
|
|
48
|
+
/** Prisma-include-shaped metadata: the relations a side's predicate reads. Kernel ignores it. */
|
|
49
|
+
type Include = Record<string, unknown>;
|
|
50
|
+
/**
|
|
51
|
+
* One half of a transition. `predicate` (legality) and `permission` (authz) are evaluated
|
|
52
|
+
* against the SAME record — and which record is the load-bearing asymmetry:
|
|
53
|
+
* `from.*` reads the CURRENT record, `to.*` reads the RESULTING (merged) record.
|
|
54
|
+
*/
|
|
55
|
+
type Side = {
|
|
56
|
+
predicate: Condition;
|
|
57
|
+
permission?: ActionRule;
|
|
58
|
+
requires?: Include;
|
|
59
|
+
};
|
|
60
|
+
type ToSide<R extends Row = Row> = Side & {
|
|
61
|
+
merge?: Merge<R>;
|
|
62
|
+
};
|
|
63
|
+
/** An atomic edge: `from → to`. Disjunction lives at the action level, never here. */
|
|
64
|
+
type Transition<R extends Row = Row> = {
|
|
65
|
+
from: Side;
|
|
66
|
+
to: ToSide<R>;
|
|
67
|
+
};
|
|
68
|
+
/**
|
|
69
|
+
* A named verb: the OR of its edges. An object (not a bare `Transition[]`) because the
|
|
70
|
+
* action is the unit of authorization (`permission`, ANDed with each side) and affordance
|
|
71
|
+
* (`label`).
|
|
72
|
+
*/
|
|
73
|
+
type Action<R extends Row = Row> = {
|
|
74
|
+
paths: Transition<R>[];
|
|
75
|
+
permission?: ActionRule;
|
|
76
|
+
label?: string;
|
|
77
|
+
};
|
|
78
|
+
/** `model → verb → Action`. Mirrors the shape of a rebac schema. */
|
|
79
|
+
type TransitionMap = Record<string, Record<string, Action>>;
|
|
80
|
+
type FailureKind = 'no-from' | 'no-to' | 'unauthorized';
|
|
81
|
+
type AuthzLevel = 'action' | 'from' | 'to';
|
|
82
|
+
type PathFailure = {
|
|
83
|
+
from?: string;
|
|
84
|
+
to?: string;
|
|
85
|
+
authz?: AuthzLevel;
|
|
86
|
+
};
|
|
87
|
+
type Reason = PathFailure & {
|
|
88
|
+
kind: FailureKind;
|
|
89
|
+
paths?: PathFailure[];
|
|
90
|
+
};
|
|
91
|
+
type CheckResult<R extends Row = Row> = {
|
|
92
|
+
ok: true;
|
|
93
|
+
path: Transition<R>;
|
|
94
|
+
} | {
|
|
95
|
+
ok: false;
|
|
96
|
+
reason: Reason;
|
|
97
|
+
};
|
|
98
|
+
/** Options threaded into a check. Omit `authorize` to evaluate legality only. */
|
|
99
|
+
type CheckOptions = {
|
|
100
|
+
actor?: Actor;
|
|
101
|
+
authorize?: Authorize;
|
|
102
|
+
/** Action-level baseline permission, ANDed against the current record (supplied by the registry). */
|
|
103
|
+
basePermission?: ActionRule;
|
|
104
|
+
};
|
|
105
|
+
/** Options for affordance/check at the registry level. */
|
|
106
|
+
type AuthorizeOptions = {
|
|
107
|
+
actor?: Actor;
|
|
108
|
+
authorize?: Authorize;
|
|
109
|
+
};
|
|
110
|
+
|
|
111
|
+
/**
|
|
112
|
+
* The kernel: evaluate one atomic transition.
|
|
113
|
+
*
|
|
114
|
+
* Legality (json-rules) AND authz (injected, per side), with the load-bearing asymmetry —
|
|
115
|
+
* `from.*` reads the current `record`, `to.*` reads the merged `next` record. Authz order is
|
|
116
|
+
* action baseline → from → to, all ANDed. Returns a structured {@link CheckResult} whose
|
|
117
|
+
* `reason.kind` lets a caller map illegal → 409 vs unauthorized → 403.
|
|
118
|
+
*
|
|
119
|
+
* Omit `options.authorize` to check legality only.
|
|
120
|
+
*/
|
|
121
|
+
declare const checkTransition: <R extends Row>(transition: Transition<R>, record: R, changes?: Partial<R>, options?: CheckOptions) => CheckResult<R>;
|
|
122
|
+
|
|
123
|
+
/** Build a human-readable message from a structured {@link Reason} (logs / UI / error bodies). */
|
|
124
|
+
declare const describe: (reason: Reason) => string;
|
|
125
|
+
|
|
126
|
+
/** A transition is persistable iff its merge is absent or a keyword strategy (callbacks are not). */
|
|
127
|
+
declare const isSerializableMerge: (merge?: Merge) => boolean;
|
|
128
|
+
/**
|
|
129
|
+
* Produce the resulting record from a current record + proposed changes.
|
|
130
|
+
*
|
|
131
|
+
* - `spread` (default) — shallow overwrite (`{ ...record, ...changes }`)
|
|
132
|
+
* - `deepMerge` — recursive object merge, arrays replaced
|
|
133
|
+
* - `{ kind: 'append', path }` — concat `changes[path]` onto `record[path]`
|
|
134
|
+
* - `{ kind: 'appendUnique', path }` — append + dedupe (deep equality)
|
|
135
|
+
* - a callback — full power, not serializable
|
|
136
|
+
*/
|
|
137
|
+
declare const applyMerge: <R extends Row>(merge: Merge<R> | undefined, record: R, changes?: Partial<R>) => R;
|
|
138
|
+
|
|
139
|
+
type ModelPermission = {
|
|
140
|
+
actions: Record<string, ActionRule>;
|
|
141
|
+
};
|
|
142
|
+
/** `model → { actions: { actionName → ActionRule } }`. Mirrors `@template/permissions` RebacSchema. */
|
|
143
|
+
type RebacSchema = Record<string, ModelPermission>;
|
|
144
|
+
type RebacOptions = {
|
|
145
|
+
schema: RebacSchema;
|
|
146
|
+
/**
|
|
147
|
+
* Resolve the model a relation points at, given the source model + relation segment.
|
|
148
|
+
* Default: the relation segment name doubles as the target model key. Supply this when your
|
|
149
|
+
* relation field names differ from your model names (the template binds this via prismaMap).
|
|
150
|
+
*/
|
|
151
|
+
resolveModel?: (model: string, relationSegment: string) => string;
|
|
152
|
+
/** Optional superadmin bypass, checked before any rule. */
|
|
153
|
+
isSuperadmin?: (actor: Actor) => boolean;
|
|
154
|
+
};
|
|
155
|
+
|
|
156
|
+
/**
|
|
157
|
+
* A reference rebac evaluator — one implementation of the injected {@link Authorize} seam,
|
|
158
|
+
* bound to a single `model`. Faithful to `@template/permissions`' `rebac/check` (string-delegate,
|
|
159
|
+
* relation walk with cycle detection, self, json-rules `{ rule }`, any/all, per-row
|
|
160
|
+
* `permissionRules` override) but standalone. Swap it for a richer authorizer in production;
|
|
161
|
+
* this is slated to graduate into `@inixiative/permissions`.
|
|
162
|
+
*/
|
|
163
|
+
declare const makeRebacAuthorize: (options: RebacOptions & {
|
|
164
|
+
model: string;
|
|
165
|
+
}) => Authorize;
|
|
166
|
+
/** Curried form: `createRebac({ schema })(model)` → an {@link Authorize} for that model. */
|
|
167
|
+
declare const createRebac: (options: RebacOptions) => (model: string) => Authorize;
|
|
168
|
+
|
|
169
|
+
/**
|
|
170
|
+
* Authoritative check: the FIRST path whose `from` matches the current record, whose `to`
|
|
171
|
+
* matches the merged record, and whose permissions all pass, wins. If none pass, returns the
|
|
172
|
+
* aggregated structured failure (see {@link aggregate}).
|
|
173
|
+
*/
|
|
174
|
+
declare const check: (map: TransitionMap, model: string, verb: string, record: Row, changes?: Row, options?: AuthorizeOptions) => CheckResult;
|
|
175
|
+
/**
|
|
176
|
+
* Affordance hint: which verbs are offerable from `record` right now. Evaluates ONLY the
|
|
177
|
+
* `from` side (predicate + `action`/`from` permission against the current record) — `to` needs
|
|
178
|
+
* the merged record, which doesn't exist without proposed changes, so it defers to {@link check}.
|
|
179
|
+
*/
|
|
180
|
+
declare const available: (map: TransitionMap, model: string, record: Row, options?: AuthorizeOptions) => string[];
|
|
181
|
+
/**
|
|
182
|
+
* Set query: one OR'd Prisma `where` matching every record currently eligible for `verb`
|
|
183
|
+
* (the union of all its paths' `from` predicates). Empty action → match-nothing.
|
|
184
|
+
*/
|
|
185
|
+
declare const eligible: (map: TransitionMap, model: string, verb: string) => Row;
|
|
186
|
+
|
|
187
|
+
/**
|
|
188
|
+
* Can this transition be persisted (stored in the DB, edited in a UI, sent over the wire)?
|
|
189
|
+
*
|
|
190
|
+
* Predicates (json-rules) and permissions (ActionRule) are always plain JSON; the only
|
|
191
|
+
* non-data escape hatch is a `to.merge` callback. So serializability reduces to the merge.
|
|
192
|
+
*/
|
|
193
|
+
declare const isSerializable: (transition: Transition) => boolean;
|
|
194
|
+
|
|
195
|
+
type ValidationIssue = {
|
|
196
|
+
path: string;
|
|
197
|
+
message: string;
|
|
198
|
+
};
|
|
199
|
+
type ValidationResult = {
|
|
200
|
+
ok: boolean;
|
|
201
|
+
errors: ValidationIssue[];
|
|
202
|
+
};
|
|
203
|
+
type ValidateOptions = {
|
|
204
|
+
/** Optional field/relation allowlist; passed through to json-rules lens validation per predicate. */
|
|
205
|
+
lens?: Lens | LensNarrowing;
|
|
206
|
+
/** Reject callback merges (use when the transition must be persistable / tenant-configured). */
|
|
207
|
+
requireSerializable?: boolean;
|
|
208
|
+
};
|
|
209
|
+
/**
|
|
210
|
+
* Authoring validation for a single transition — run on save before persisting a tenant config.
|
|
211
|
+
* Predicate validity delegates to json-rules (`validateRule`, plus `checkRuleAgainstLens` when a
|
|
212
|
+
* `lens` is supplied for field/relation scoping); merge strategy and permission shape are checked here.
|
|
213
|
+
*/
|
|
214
|
+
declare const validateTransition: (transition: Transition, options?: ValidateOptions) => ValidationResult;
|
|
215
|
+
|
|
216
|
+
export { type Action, type ActionRule, type Actor, type Authorize, type AuthorizeOptions, type AuthzLevel, type CheckOptions, type CheckResult, type FailureKind, type Include, type Merge, type MergeStrategy, type ModelPermission, type PathFailure, type Reason, type RebacOptions, type RebacSchema, type Row, type Side, type ToSide, type Transition, type TransitionMap, type ValidateOptions, type ValidationIssue, type ValidationResult, applyMerge, available, check, checkTransition, createRebac, describe, eligible, isSerializable, isSerializableMerge, makeRebacAuthorize, validateTransition };
|
package/dist/index.js
ADDED
|
@@ -0,0 +1,2 @@
|
|
|
1
|
+
import {check,toPrisma,validateRule,checkRuleAgainstLens}from'@inixiative/json-rules';import {mergeWith,cloneDeep,get,set,uniqWith,isEqual}from'lodash-es';var y=e=>Array.isArray(e)?e:e===void 0?[]:[e],O=(e,t)=>Array.isArray(t)?t:void 0,l=e=>typeof e!="function",k=(e,t,n={})=>{if(typeof e=="function")return e(t,n);let i=e??"spread";if(i==="spread")return {...t,...n};if(i==="deepMerge")return mergeWith(cloneDeep(t),cloneDeep(n),O);let{kind:o,path:s}=i,r=cloneDeep({...t,...n}),p=[...y(get(t,s)),...y(get(n,s))];return set(r,s,o==="appendUnique"?uniqWith(p,isEqual):p),r};var A=e=>typeof e=="string"?e:"predicate not satisfied",d=(e,t,n,i)=>!e||t===void 0?false:!e(t,n,i),b=(e,t,n={},i={})=>{let{actor:o,authorize:s,basePermission:r}=i,p=k(e.to.merge,t,n),a=check(e.from.predicate,t);if(a!==true)return {ok:false,reason:{kind:"no-from",from:A(a)}};let u=check(e.to.predicate,p);return u!==true?{ok:false,reason:{kind:"no-to",to:A(u)}}:d(s,r,t,o)?{ok:false,reason:{kind:"unauthorized",authz:"action"}}:d(s,e.from.permission,t,o)?{ok:false,reason:{kind:"unauthorized",authz:"from"}}:d(s,e.to.permission,p,o)?{ok:false,reason:{kind:"unauthorized",authz:"to"}}:{ok:true,path:e}};var Y=e=>{switch(e.kind){case "no-from":return e.from??"transition is not available from the current state";case "no-to":return e.to??"the resulting state is not a valid target";case "unauthorized":return e.authz?`not authorized (${e.authz}-level permission denied)`:"not authorized";default:return e.kind}};var c=(e,t,n,i,o,s)=>{if(e.isSuperadmin?.(i))return true;if(o===null)return false;if(typeof o=="string"){let r=e.schema[t]?.actions[o]??null,a=n.permissionRules?.[o];return c(e,t,n,i,a!==void 0?{any:[r,a]}:r,s)}if("rel"in o&&"action"in o){let r=o.rel.split("."),p=n,a=t;for(let f of r){let g=p[f];if(!g)return false;a=e.resolveModel?e.resolveModel(a,f):f,p=g;}let u=`${a}:${String(p.id)}:${o.action}`;if(s.has(u))throw new Error(`Cycle detected in permission graph: ${u}`);return s.add(u),c(e,a,p,i,o.action,s)}if("self"in o){let r=i?.id??null;return r!==null&&n[o.self]===r}return "rule"in o?check(o.rule,n)===true:"any"in o?o.any.some(r=>c(e,t,n,i,r,new Set(s))):"all"in o?o.all.every(r=>c(e,t,n,i,r,new Set(s))):false},C=e=>{let{model:t,...n}=e;return (i,o,s)=>c(n,t,o,s,i,new Set)},H=e=>t=>C({...e,model:t});var z=(e,t,n)=>{let i=e[t]?.[n];if(!i)throw new Error(`transition: no action "${n}" registered on model "${t}"`);return i},E=e=>{let t=e.map(({kind:r,paths:p,...a})=>a),n=r=>e.find(p=>p.kind===r),i=n("unauthorized")??n("no-to")??n("no-from");if(!i)return {kind:"no-from",paths:t};let{paths:o,...s}=i;return {...s,paths:t}},te=(e,t,n,i,o={},s={})=>{let r=z(e,t,n),p={...s,basePermission:r.permission},a=[];for(let u of r.paths){let f=b(u,i,o,p);if(f.ok)return f;a.push(f.reason);}return {ok:false,reason:E(a)}},ne=(e,t,n,i={})=>{let o=e[t];if(!o)return [];let{actor:s,authorize:r}=i,p=(a,u)=>!r||a===void 0||r(a,u,s);return Object.entries(o).filter(([,a])=>a.paths.some(u=>check(u.from.predicate,n)===true&&p(a.permission,n)&&p(u.from.permission,n))).map(([a])=>a)},oe=(e,t,n)=>{let i=z(e,t,n),{steps:o}=toPrisma({any:i.paths.map(r=>r.from.predicate)}),s=o[o.length-1];if(s?.operation!=="where"||s.where===void 0)throw new Error("transition: expected a terminal WhereStep from toPrisma; got none");return s.where};var re=e=>l(e.to.merge);var _=new Set(["spread","deepMerge"]),L=new Set(["append","appendUnique"]),N=(e,t,n,i)=>{let o=validateRule(e);for(let s of o.errors)t.push({path:`${n}.${s.path}`,message:s.message});if(i){let s=checkRuleAgainstLens(e,i);for(let r of s.violations)t.push({path:`${n}.${r.path}`,message:r.reason});}},h=(e,t,n)=>{if(!(e==null||typeof e=="string")){if("rule"in e){let i=validateRule(e.rule);for(let o of i.errors)t.push({path:`${n}.rule.${o.path}`,message:o.message});return}if("rel"in e){(!e.rel||!e.action)&&t.push({path:n,message:"rel-rule requires non-empty `rel` and `action`"});return}if("self"in e){e.self||t.push({path:n,message:"self-rule requires a non-empty field name"});return}if("any"in e){e.any.forEach((i,o)=>{h(i,t,`${n}.any[${o}]`);});return}if("all"in e){e.all.forEach((i,o)=>{h(i,t,`${n}.all[${o}]`);});return}t.push({path:n,message:"unrecognized ActionRule shape"});}},W=(e,t,n)=>{if(!(e===void 0||typeof e=="function")){if(typeof e=="string"){_.has(e)||t.push({path:n,message:`unknown merge strategy "${e}"`});return}L.has(e.kind)?e.path||t.push({path:n,message:`merge "${e.kind}" requires a \`path\``}):t.push({path:n,message:`unknown merge kind "${e.kind}"`});}},S=(e,t,n,i)=>{N(e.predicate,t,`${n}.predicate`,i.lens),h(e.permission,t,`${n}.permission`),e.requires!==void 0&&(typeof e.requires!="object"||e.requires===null)&&t.push({path:`${n}.requires`,message:"`requires` must be a Prisma-include-shaped object"}),"merge"in e&&W(e.merge,t,`${n}.merge`);},fe=(e,t={})=>{let n=[];return S(e.from,n,"from",t),S(e.to,n,"to",t),t.requireSerializable&&!l(e.to.merge)&&n.push({path:"to.merge",message:"callback merge is not serializable; use a keyword strategy"}),{ok:n.length===0,errors:n}};export{k as applyMerge,ne as available,te as check,b as checkTransition,H as createRebac,Y as describe,oe as eligible,re as isSerializable,l as isSerializableMerge,C as makeRebacAuthorize,fe as validateTransition};//# sourceMappingURL=index.js.map
|
|
2
|
+
//# sourceMappingURL=index.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"sources":["../src/merge.ts","../src/check.ts","../src/describe.ts","../src/rebac/authorize.ts","../src/registry.ts","../src/serializable.ts","../src/validate.ts"],"names":["toArray","value","replaceArrays","_target","source","isSerializableMerge","merge","applyMerge","record","changes","strategy","mergeWith","cloneDeep","kind","path","base","merged","get","set","uniqWith","isEqual","reasonString","result","denies","authorize","rule","actor","checkTransition","transition","options","basePermission","next","fromResult","checkRule","toResult","describe","reason","evaluate","ctx","model","visited","schemaRule","rowRule","segments","current","currentModel","segment","related","key","actorId","sub","makeRebacAuthorize","rest","createRebac","getAction","map","verb","action","aggregate","failures","paths","_kind","_paths","pick","failure","chosen","_omit","representative","check","opts","available","actions","allows","rec","eligible","steps","toPrisma","last","isSerializable","MERGE_KEYWORDS","ARRAY_KINDS","validatePredicate","predicate","errors","lens","validateRule","issue","lensCheck","checkRuleAgainstLens","violation","validatePermission","i","validateMerge","validateSide","side","validateTransition"],"mappings":"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","file":"index.js","sourcesContent":["import { cloneDeep, get, isEqual, mergeWith, set, uniqWith } from 'lodash-es';\nimport type { Merge, MergeStrategy, Row } from './types';\n\nconst toArray = (value: unknown): unknown[] =>\n Array.isArray(value) ? value : value === undefined ? [] : [value];\n\n// deepMerge replaces arrays wholesale rather than index-merging them (the intuitive default).\nconst replaceArrays = (_target: unknown, source: unknown): unknown[] | undefined =>\n Array.isArray(source) ? source : undefined;\n\n/** A transition is persistable iff its merge is absent or a keyword strategy (callbacks are not). */\nexport const isSerializableMerge = (merge?: Merge): boolean => typeof merge !== 'function';\n\n/**\n * Produce the resulting record from a current record + proposed changes.\n *\n * - `spread` (default) — shallow overwrite (`{ ...record, ...changes }`)\n * - `deepMerge` — recursive object merge, arrays replaced\n * - `{ kind: 'append', path }` — concat `changes[path]` onto `record[path]`\n * - `{ kind: 'appendUnique', path }` — append + dedupe (deep equality)\n * - a callback — full power, not serializable\n */\nexport const applyMerge = <R extends Row>(\n merge: Merge<R> | undefined,\n record: R,\n changes: Partial<R> = {},\n): R => {\n if (typeof merge === 'function') return merge(record, changes);\n\n const strategy: MergeStrategy = merge ?? 'spread';\n\n if (strategy === 'spread') return { ...record, ...changes };\n // clone BOTH inputs: mergeWith assigns nested objects/arrays from `changes` by reference, which\n // would alias the caller's `changes` into the returned record (a mutation footgun for a pure guard).\n if (strategy === 'deepMerge')\n return mergeWith(cloneDeep(record), cloneDeep(changes), replaceArrays);\n\n // field-scoped array strategies: spread the rest of `changes`, then concat at `path`.\n const { kind, path } = strategy;\n const base = cloneDeep({ ...record, ...changes }) as R;\n const merged = [...toArray(get(record, path)), ...toArray(get(changes, path))];\n set(base as Row, path, kind === 'appendUnique' ? uniqWith(merged, isEqual) : merged);\n return base;\n};\n","import { check as checkRule } from '@inixiative/json-rules';\nimport { applyMerge } from './merge';\nimport type {\n ActionRule,\n Actor,\n Authorize,\n CheckOptions,\n CheckResult,\n Row,\n Transition,\n} from './types';\n\nconst reasonString = (result: boolean | string): string =>\n typeof result === 'string' ? result : 'predicate not satisfied';\n\n/**\n * Does this permission DENY?\n * - no authorizer injected → can't deny (legality-only mode)\n * - `undefined` rule → permission absent → open → can't deny\n * - any other rule (incl. `null` = terminal deny) → delegate to the authorizer\n */\nconst denies = (\n authorize: Authorize | undefined,\n rule: ActionRule | undefined,\n record: Row,\n actor: Actor,\n): boolean => {\n if (!authorize || rule === undefined) return false;\n return !authorize(rule, record, actor);\n};\n\n/**\n * The kernel: evaluate one atomic transition.\n *\n * Legality (json-rules) AND authz (injected, per side), with the load-bearing asymmetry —\n * `from.*` reads the current `record`, `to.*` reads the merged `next` record. Authz order is\n * action baseline → from → to, all ANDed. Returns a structured {@link CheckResult} whose\n * `reason.kind` lets a caller map illegal → 409 vs unauthorized → 403.\n *\n * Omit `options.authorize` to check legality only.\n */\nexport const checkTransition = <R extends Row>(\n transition: Transition<R>,\n record: R,\n changes: Partial<R> = {},\n options: CheckOptions = {},\n): CheckResult<R> => {\n const { actor, authorize, basePermission } = options;\n const next = applyMerge(transition.to.merge, record, changes);\n\n const fromResult = checkRule(transition.from.predicate, record as Row);\n if (fromResult !== true)\n return { ok: false, reason: { kind: 'no-from', from: reasonString(fromResult) } };\n\n const toResult = checkRule(transition.to.predicate, next as Row);\n if (toResult !== true)\n return { ok: false, reason: { kind: 'no-to', to: reasonString(toResult) } };\n\n if (denies(authorize, basePermission, record as Row, actor))\n return { ok: false, reason: { kind: 'unauthorized', authz: 'action' } };\n if (denies(authorize, transition.from.permission, record as Row, actor))\n return { ok: false, reason: { kind: 'unauthorized', authz: 'from' } };\n if (denies(authorize, transition.to.permission, next as Row, actor))\n return { ok: false, reason: { kind: 'unauthorized', authz: 'to' } };\n\n return { ok: true, path: transition };\n};\n","import type { Reason } from './types';\n\n/** Build a human-readable message from a structured {@link Reason} (logs / UI / error bodies). */\nexport const describe = (reason: Reason): string => {\n switch (reason.kind) {\n case 'no-from':\n return reason.from ?? 'transition is not available from the current state';\n case 'no-to':\n return reason.to ?? 'the resulting state is not a valid target';\n case 'unauthorized':\n return reason.authz\n ? `not authorized (${reason.authz}-level permission denied)`\n : 'not authorized';\n default: {\n // exhaustiveness guard: a new FailureKind must be handled here, not silently return undefined\n const _exhaustive: never = reason.kind;\n return _exhaustive;\n }\n }\n};\n","import { check as checkRule } from '@inixiative/json-rules';\nimport type { ActionRule, Actor, Authorize, Row } from '../types';\nimport type { RebacOptions, RebacSchema } from './types';\n\ntype Context = {\n schema: RebacSchema;\n resolveModel?: (model: string, relationSegment: string) => string;\n isSuperadmin?: (actor: Actor) => boolean;\n};\n\nconst evaluate = (\n ctx: Context,\n model: string,\n record: Row,\n actor: Actor,\n rule: ActionRule,\n visited: Set<string>,\n): boolean => {\n if (ctx.isSuperadmin?.(actor)) return true;\n if (rule === null) return false;\n\n // string → delegate to the named action on this model, additively merged with any per-row override.\n if (typeof rule === 'string') {\n const schemaRule = ctx.schema[model]?.actions[rule] ?? null;\n const rowRules = record.permissionRules as Record<string, ActionRule> | null | undefined;\n const rowRule = rowRules?.[rule];\n const merged: ActionRule = rowRule !== undefined ? { any: [schemaRule, rowRule] } : schemaRule;\n return evaluate(ctx, model, record, actor, merged, visited);\n }\n\n // { rel, action } → walk the relation (dot-paths supported), then check `action` on the target.\n if ('rel' in rule && 'action' in rule) {\n const segments = rule.rel.split('.');\n let current: Row = record;\n let currentModel = model;\n for (const segment of segments) {\n const related = current[segment] as Row | null | undefined;\n if (!related) return false;\n currentModel = ctx.resolveModel ? ctx.resolveModel(currentModel, segment) : segment;\n current = related;\n }\n const key = `${currentModel}:${String(current.id)}:${rule.action}`;\n if (visited.has(key)) throw new Error(`Cycle detected in permission graph: ${key}`);\n visited.add(key);\n return evaluate(ctx, currentModel, current, actor, rule.action, visited);\n }\n\n // { self } → record[field] matches the current actor.\n if ('self' in rule) {\n const actorId = actor?.id ?? null;\n return actorId !== null && record[rule.self] === actorId;\n }\n\n // { rule } → ABAC predicate (json-rules) over the record.\n if ('rule' in rule) return checkRule(rule.rule, record) === true;\n\n // Fork `visited` per branch — parallel paths through any/all aren't cycles.\n if ('any' in rule)\n return rule.any.some((sub) => evaluate(ctx, model, record, actor, sub, new Set(visited)));\n if ('all' in rule)\n return rule.all.every((sub) => evaluate(ctx, model, record, actor, sub, new Set(visited)));\n\n return false;\n};\n\n/**\n * A reference rebac evaluator — one implementation of the injected {@link Authorize} seam,\n * bound to a single `model`. Faithful to `@template/permissions`' `rebac/check` (string-delegate,\n * relation walk with cycle detection, self, json-rules `{ rule }`, any/all, per-row\n * `permissionRules` override) but standalone. Swap it for a richer authorizer in production;\n * this is slated to graduate into `@inixiative/permissions`.\n */\nexport const makeRebacAuthorize = (options: RebacOptions & { model: string }): Authorize => {\n const { model, ...rest } = options;\n return (rule, record, actor) => evaluate(rest, model, record, actor, rule, new Set());\n};\n\n/** Curried form: `createRebac({ schema })(model)` → an {@link Authorize} for that model. */\nexport const createRebac =\n (options: RebacOptions) =>\n (model: string): Authorize =>\n makeRebacAuthorize({ ...options, model });\n","import { check as checkRule, toPrisma } from '@inixiative/json-rules';\nimport { checkTransition } from './check';\nimport type {\n Action,\n AuthorizeOptions,\n CheckOptions,\n CheckResult,\n PathFailure,\n Reason,\n Row,\n TransitionMap,\n} from './types';\n\nconst getAction = (map: TransitionMap, model: string, verb: string): Action => {\n const action = map[model]?.[verb];\n if (!action) throw new Error(`transition: no action \"${verb}\" registered on model \"${model}\"`);\n return action;\n};\n\n// Pick the most-progressed failure across an action's paths:\n// unauthorized (a legal edge existed but authz denied) → 403\n// no-to (from matched, target invalid) → 409\n// no-from (no edge even starts here) → 409\nconst aggregate = (failures: Reason[]): Reason => {\n const paths: PathFailure[] = failures.map(({ kind: _kind, paths: _paths, ...rest }) => rest);\n const pick = (kind: Reason['kind']) => failures.find((failure) => failure.kind === kind);\n const chosen = pick('unauthorized') ?? pick('no-to') ?? pick('no-from');\n if (!chosen) return { kind: 'no-from', paths };\n const { paths: _omit, ...representative } = chosen;\n return { ...representative, paths };\n};\n\n/**\n * Authoritative check: the FIRST path whose `from` matches the current record, whose `to`\n * matches the merged record, and whose permissions all pass, wins. If none pass, returns the\n * aggregated structured failure (see {@link aggregate}).\n */\nexport const check = (\n map: TransitionMap,\n model: string,\n verb: string,\n record: Row,\n changes: Row = {},\n options: AuthorizeOptions = {},\n): CheckResult => {\n const action = getAction(map, model, verb);\n const opts: CheckOptions = { ...options, basePermission: action.permission };\n\n const failures: Reason[] = [];\n for (const path of action.paths) {\n const result = checkTransition(path, record, changes, opts);\n if (result.ok) return result;\n failures.push(result.reason);\n }\n return { ok: false, reason: aggregate(failures) };\n};\n\n/**\n * Affordance hint: which verbs are offerable from `record` right now. Evaluates ONLY the\n * `from` side (predicate + `action`/`from` permission against the current record) — `to` needs\n * the merged record, which doesn't exist without proposed changes, so it defers to {@link check}.\n */\nexport const available = (\n map: TransitionMap,\n model: string,\n record: Row,\n options: AuthorizeOptions = {},\n): string[] => {\n const actions = map[model];\n if (!actions) return [];\n const { actor, authorize } = options;\n\n const allows = (rule: Action['permission'], rec: Row): boolean =>\n !authorize || rule === undefined || authorize(rule, rec, actor);\n\n return Object.entries(actions)\n .filter(([, action]) =>\n action.paths.some(\n (path) =>\n checkRule(path.from.predicate, record) === true &&\n allows(action.permission, record) &&\n allows(path.from.permission, record),\n ),\n )\n .map(([verb]) => verb);\n};\n\n/**\n * Set query: one OR'd Prisma `where` matching every record currently eligible for `verb`\n * (the union of all its paths' `from` predicates). Empty action → match-nothing.\n */\nexport const eligible = (map: TransitionMap, model: string, verb: string): Row => {\n const action = getAction(map, model, verb);\n const { steps } = toPrisma({ any: action.paths.map((path) => path.from.predicate) });\n // json-rules guarantees the last step is the WhereStep. Assert it loudly rather than cast-and-swallow:\n // a silent `{}` fallback would mean match-EVERYTHING — the dangerous inverse of the intended\n // match-nothing — if a future json-rules emits a trailing non-where step or multi-step relation refs.\n const last = steps[steps.length - 1] as { operation?: string; where?: Row } | undefined;\n if (last?.operation !== 'where' || last.where === undefined)\n throw new Error('transition: expected a terminal WhereStep from toPrisma; got none');\n return last.where;\n};\n","import { isSerializableMerge } from './merge';\nimport type { Transition } from './types';\n\n/**\n * Can this transition be persisted (stored in the DB, edited in a UI, sent over the wire)?\n *\n * Predicates (json-rules) and permissions (ActionRule) are always plain JSON; the only\n * non-data escape hatch is a `to.merge` callback. So serializability reduces to the merge.\n */\nexport const isSerializable = (transition: Transition): boolean =>\n isSerializableMerge(transition.to.merge);\n","import {\n type Condition,\n checkRuleAgainstLens,\n type Lens,\n type LensNarrowing,\n validateRule,\n} from '@inixiative/json-rules';\nimport { isSerializableMerge } from './merge';\nimport type { ActionRule, Merge, Side, ToSide, Transition } from './types';\n\nexport type ValidationIssue = { path: string; message: string };\nexport type ValidationResult = { ok: boolean; errors: ValidationIssue[] };\n\nexport type ValidateOptions = {\n /** Optional field/relation allowlist; passed through to json-rules lens validation per predicate. */\n lens?: Lens | LensNarrowing;\n /** Reject callback merges (use when the transition must be persistable / tenant-configured). */\n requireSerializable?: boolean;\n};\n\nconst MERGE_KEYWORDS = new Set(['spread', 'deepMerge']);\nconst ARRAY_KINDS = new Set(['append', 'appendUnique']);\n\nconst validatePredicate = (\n predicate: Condition,\n errors: ValidationIssue[],\n path: string,\n lens?: Lens | LensNarrowing,\n): void => {\n const result = validateRule(predicate);\n for (const issue of result.errors)\n errors.push({ path: `${path}.${issue.path}`, message: issue.message });\n if (lens) {\n const lensCheck = checkRuleAgainstLens(predicate, lens);\n for (const violation of lensCheck.violations)\n errors.push({ path: `${path}.${violation.path}`, message: violation.reason });\n }\n};\n\nconst validatePermission = (\n rule: ActionRule | undefined,\n errors: ValidationIssue[],\n path: string,\n): void => {\n if (rule === undefined || rule === null || typeof rule === 'string') return;\n if ('rule' in rule) {\n const result = validateRule(rule.rule);\n for (const issue of result.errors)\n errors.push({ path: `${path}.rule.${issue.path}`, message: issue.message });\n return;\n }\n if ('rel' in rule) {\n if (!rule.rel || !rule.action)\n errors.push({ path, message: 'rel-rule requires non-empty `rel` and `action`' });\n return;\n }\n if ('self' in rule) {\n if (!rule.self) errors.push({ path, message: 'self-rule requires a non-empty field name' });\n return;\n }\n if ('any' in rule) {\n rule.any.forEach((sub, i) => {\n validatePermission(sub, errors, `${path}.any[${i}]`);\n });\n return;\n }\n if ('all' in rule) {\n rule.all.forEach((sub, i) => {\n validatePermission(sub, errors, `${path}.all[${i}]`);\n });\n return;\n }\n errors.push({ path, message: 'unrecognized ActionRule shape' });\n};\n\nconst validateMerge = (merge: Merge | undefined, errors: ValidationIssue[], path: string): void => {\n if (merge === undefined || typeof merge === 'function') return;\n if (typeof merge === 'string') {\n if (!MERGE_KEYWORDS.has(merge))\n errors.push({ path, message: `unknown merge strategy \"${merge}\"` });\n return;\n }\n if (!ARRAY_KINDS.has(merge.kind))\n errors.push({ path, message: `unknown merge kind \"${merge.kind}\"` });\n else if (!merge.path) errors.push({ path, message: `merge \"${merge.kind}\" requires a \\`path\\`` });\n};\n\nconst validateSide = (\n side: Side | ToSide,\n errors: ValidationIssue[],\n path: string,\n options: ValidateOptions,\n): void => {\n validatePredicate(side.predicate, errors, `${path}.predicate`, options.lens);\n validatePermission(side.permission, errors, `${path}.permission`);\n if (side.requires !== undefined && (typeof side.requires !== 'object' || side.requires === null))\n errors.push({\n path: `${path}.requires`,\n message: '`requires` must be a Prisma-include-shaped object',\n });\n if ('merge' in side) validateMerge(side.merge, errors, `${path}.merge`);\n};\n\n/**\n * Authoring validation for a single transition — run on save before persisting a tenant config.\n * Predicate validity delegates to json-rules (`validateRule`, plus `checkRuleAgainstLens` when a\n * `lens` is supplied for field/relation scoping); merge strategy and permission shape are checked here.\n */\nexport const validateTransition = (\n transition: Transition,\n options: ValidateOptions = {},\n): ValidationResult => {\n const errors: ValidationIssue[] = [];\n validateSide(transition.from, errors, 'from', options);\n validateSide(transition.to, errors, 'to', options);\n if (options.requireSerializable && !isSerializableMerge(transition.to.merge))\n errors.push({\n path: 'to.merge',\n message: 'callback merge is not serializable; use a keyword strategy',\n });\n return { ok: errors.length === 0, errors };\n};\n"]}
|
package/package.json
ADDED
|
@@ -0,0 +1,69 @@
|
|
|
1
|
+
{
|
|
2
|
+
"name": "@inixiative/transitions",
|
|
3
|
+
"version": "0.0.1",
|
|
4
|
+
"description": "Declarative, serializable transition guard + affordance layer on top of @inixiative/json-rules",
|
|
5
|
+
"main": "./dist/index.cjs",
|
|
6
|
+
"module": "./dist/index.js",
|
|
7
|
+
"types": "./dist/index.d.ts",
|
|
8
|
+
"type": "module",
|
|
9
|
+
"files": [
|
|
10
|
+
"dist",
|
|
11
|
+
"README.md",
|
|
12
|
+
"LICENSE"
|
|
13
|
+
],
|
|
14
|
+
"scripts": {
|
|
15
|
+
"build": "tsup",
|
|
16
|
+
"test": "bun test",
|
|
17
|
+
"typecheck": "tsc --noEmit",
|
|
18
|
+
"lint": "biome check .",
|
|
19
|
+
"format": "biome format --write .",
|
|
20
|
+
"check": "bun run typecheck && bun run lint",
|
|
21
|
+
"prepare": "lefthook install",
|
|
22
|
+
"prepublishOnly": "bun run check && bun run test && bun run build"
|
|
23
|
+
},
|
|
24
|
+
"keywords": [
|
|
25
|
+
"transition",
|
|
26
|
+
"state",
|
|
27
|
+
"lifecycle",
|
|
28
|
+
"guard",
|
|
29
|
+
"json-rules",
|
|
30
|
+
"rebac",
|
|
31
|
+
"typescript"
|
|
32
|
+
],
|
|
33
|
+
"author": "Aron Greenspan",
|
|
34
|
+
"license": "MIT",
|
|
35
|
+
"repository": {
|
|
36
|
+
"type": "git",
|
|
37
|
+
"url": "git+https://github.com/inixiative/transitions.git"
|
|
38
|
+
},
|
|
39
|
+
"publishConfig": {
|
|
40
|
+
"access": "public"
|
|
41
|
+
},
|
|
42
|
+
"devDependencies": {
|
|
43
|
+
"@biomejs/biome": "^2.4.6",
|
|
44
|
+
"@types/bun": "^1.3.10",
|
|
45
|
+
"@types/lodash-es": "^4.17.12",
|
|
46
|
+
"lefthook": "^2.1.2",
|
|
47
|
+
"tsup": "^8.5.0",
|
|
48
|
+
"typescript": "^5.0.0"
|
|
49
|
+
},
|
|
50
|
+
"peerDependencies": {
|
|
51
|
+
"typescript": "^5.0.0"
|
|
52
|
+
},
|
|
53
|
+
"peerDependenciesMeta": {
|
|
54
|
+
"typescript": {
|
|
55
|
+
"optional": true
|
|
56
|
+
}
|
|
57
|
+
},
|
|
58
|
+
"dependencies": {
|
|
59
|
+
"@inixiative/json-rules": "^2.6.0",
|
|
60
|
+
"lodash-es": "^4.17.21"
|
|
61
|
+
},
|
|
62
|
+
"exports": {
|
|
63
|
+
".": {
|
|
64
|
+
"types": "./dist/index.d.ts",
|
|
65
|
+
"import": "./dist/index.js",
|
|
66
|
+
"require": "./dist/index.cjs"
|
|
67
|
+
}
|
|
68
|
+
}
|
|
69
|
+
}
|