@nzelajs/adapter-expr-cel

English below - Version francaise plus bas.

The CEL GuardRunner for the Nzela engine. It makes inline cel: transition guards REAL: an expression is evaluated against the instance's data with @marcbachmann/cel-js, sandboxed and fail-closed. It also carries a named predicate registry for guards referenced by name.

English

Install

npm add @nzelajs/adapter-expr-cel

What it provides

• CelGuardRunner (implements GuardRunner): for each guard ref of a transition,
  • cel:EXPR evaluates EXPR against the ExpressionContext (form, case, beneficiary, requester, policy, tenant) using CEL. The result MUST be a strict boolean. Any parse or evaluation error (unknown variable, missing field, type mismatch) and any non-boolean result FAIL CLOSED (the guard fails, never a silent pass). Compiled expressions are cached.
  • ref:name or a bare name delegates to an injected predicate registry; an unknown name FAILS CLOSED, and a predicate that throws FAILS CLOSED.
  • check returns the first GuardFailure (or null); assert throws GuardFailedError on the first. Empty or undefined guard list passes.
• The CEL matches function (unbounded regex) is FORBIDDEN, fail-closed: it compiles to an unbounded RegExp and is a ReDoS vector. Express conditions with ==, in, startsWith, contains.
• validateCelExpression(expr): a pure publish-time compile check (no evaluation). It throws on invalid CEL syntax and on the forbidden matches(. Wire it as parseBlueprint's validateExpression (directly, or through the studio's validateGraph/publishGraph) so a broken cel: guard is rejected when the client publishes instead of failing closed later at runtime - keeping @nzelajs/blueprint vendor-free (it never imports CEL; the app injects this callback).

Inject named predicates via the constructor ({ predicates }) or register(name, predicate). A predicate reads the same GuardContext and ExpressionContext as the CEL path, so app-specific logic (a database check) and declarative CEL guards live behind one runner.

Francais

Installation

npm add @nzelajs/adapter-expr-cel

Ce que ca fournit

• CelGuardRunner (implemente GuardRunner) : pour chaque ref de garde d'une transition,
  • cel:EXPR evalue EXPR contre l'ExpressionContext (form, case, beneficiary, requester, policy, tenant) avec CEL. Le resultat DOIT etre un booleen strict. Toute erreur de compilation ou d'evaluation (variable inconnue, champ absent, type incompatible) et tout resultat non booleen ECHOUENT FERMES (la garde echoue, jamais de pass silencieux). Les expressions compilees sont mises en cache.
  • ref:name ou un simple name delegue a un registre de predicats injecte ; un nom inconnu ECHOUE FERME, et un predicat qui leve une erreur ECHOUE FERME.
  • check renvoie la premiere GuardFailure (ou null) ; assert leve GuardFailedError a la premiere. Liste vide ou absente : pass.
• La fonction CEL matches (regex non bornee) est INTERDITE, fail-closed : elle compile vers une RegExp non bornee, vecteur de ReDoS. Exprimez les conditions avec ==, in, startsWith, contains.
• validateCelExpression(expr) : un controle pur a la publication (compilation sans evaluation). Il leve sur une syntaxe CEL invalide et sur le matches( interdit. Branchez-le comme validateExpression de parseBlueprint (directement, ou via validateGraph/publishGraph du studio) pour rejeter une garde cel: cassee des la publication au lieu d'un echec ferme plus tard au runtime - en gardant @nzelajs/blueprint sans vendor (il n'importe jamais CEL ; l'app injecte ce callback).

Injectez des predicats nommes via le constructeur ({ predicates }) ou register(name, predicate). Un predicat lit le meme GuardContext et ExpressionContext que la voie CEL : la logique propre a l'app (un controle en base) et les gardes CEL declaratives cohabitent derriere un seul runner.

License

Apache-2.0