suaveplan/openspec/changes/permissions-completion/proposal.md

Permissions completion — default-preset factory, event singleton, deep-path utils, pattern-match utils

Package: @suaveplan/permissions Status: PROPOSED Type: feature

Why

The 2026-05-02 audit of packages/auth/permissions/src against ../suaveplan/packages/universal/permissions/src identified four confirmed feature gaps. The genesis permissions package has the heavy machinery (managers, cache, middleware, policy engine, role/ability builders, condition / field / subject matchers) but is missing four small ergonomic helpers that upstream callers rely on: a createPermissions() factory that wires the defaults together, a singleton permissionEvents event bus, deepGet / deepHas for condition-matching against nested input shapes, and matchPattern / patternToRegex for wildcard-style action matching.

Without these helpers, every consumer of @suaveplan/permissions has to hand-roll the same boilerplate (instantiate MemoryAdapter, AbilityBuilder, DefaultConditionMatcher, DefaultFieldMatcher, DefaultSubjectDetector; wire the matchers into builder.build; then track and bind the result). Worse, every consumer that wants to listen for permission:granted / permission:denied events has to create its own EventEmitter and pass it through the manager constructor, which leads to two un-shared event buses on every realistic deployment. Both gaps are small but high-friction; closing them in one change avoids four sequential micro-changes and lets the upstream test fixtures port verbatim.

The four gaps:

1. createPermissions() factory + PermissionsInstance interface (97 L upstream presets/default-preset/default-preset.ts) — returns a single bag of { ability, builder, adapter, conditionMatcher, fieldMatcher, subjectDetector } so consumers can destructure rather than instantiating six classes by hand. Every default is overridable through a single PresetOptions arg.
2. permissionEvents singleton event bus (57 L upstream permission-events.ts) — a process-wide EventBusLike from @suaveplan/events keyed by "permission:checked" | "permission:granted" | "permission:denied" | "role:assigned" | "role:revoked". Genesis already exports the PermissionEventMap type but never wires a singleton — managers either accept an optional event bus (which most callers leave undefined) or emit nothing.
3. deepGet(obj, path) and deepHas(obj, path) utilities (47 L upstream utils/deep-get.ts) — typed dot-path getters used by DefaultConditionMatcher to read user.profile.role or similar nested context fields. The genesis condition matcher currently only accepts top-level keys, blocking realistic conditions.
4. matchPattern(input, pattern) and patternToRegex(pattern) utilities (54 L upstream utils/pattern-matching.ts) — glob-style matching (*, manage, prefix foo*, suffix *foo) compiled to RegExp. Used by DefaultFieldMatcher and by Ability.can(action, subject) for wildcard action / subject matching, which the genesis WILDCARD_ACTION constant already presupposes but does not implement.

What changes

• ADDED: presets/default-preset/default-preset.ts exporting createPermissions<TAction, TSubject, TConditions>(options?: PresetOptions<...>): PermissionsInstance<TAction, TSubject, TConditions>. The factory wires MemoryAdapter, AbilityBuilder, DefaultConditionMatcher, DefaultFieldMatcher, DefaultSubjectDetector, builds the Ability, and returns all six instances in a frozen result object. Every default is overridable via PresetOptions.
• ADDED: presets/default-preset/default-preset.types.ts exporting PresetOptions<TAction, TSubject, TConditions> (overrides for each of the six injected dependencies) and PermissionsInstance<TAction, TSubject, TConditions> (the result shape).
• ADDED: events/permission-events.ts permissionEvents exported singleton — a module-scope EventBusLike instance keyed by the existing PermissionEventMap. Managers and the ability builder SHALL emit through it when no caller-supplied bus is passed. The existing PermissionEventMap type stays exported as before.
• ADDED: utils/deep-get/deep-get.ts exporting deepGet(obj: unknown, path: string): unknown and deepHas(obj: unknown, path: string): boolean. Supports dot-notation (user.profile.role) and array-index segments (tags.0 resolves obj.tags[0]). Returns undefined from deepGet (and false from deepHas) when any segment is missing rather than throwing.
• ADDED: utils/pattern-match/pattern-match.ts exporting matchPattern(input: string, pattern: string): boolean and patternToRegex(pattern: string): RegExp. Patterns: * and "manage" match everything, foo* matches by prefix, *foo matches by suffix, otherwise exact-equality. The compiled RegExp is cached by pattern string in a module-scope Map<string, RegExp> so repeated lookups (the hot path inside Ability.can) do not re-compile.
• MODIFIED: conditions/condition-matcher/condition-matcher.ts — DefaultConditionMatcher.match(conditions, context) SHALL use deepGet(context, key) to resolve dot-notation keys (currently it only resolves top-level keys via context[key]).
• MODIFIED: conditions/field-matcher/field-matcher.ts — DefaultFieldMatcher.match(pattern, field) SHALL delegate to matchPattern(field, pattern) (currently it only supports exact equality and a hard-coded * wildcard).
• MODIFIED: core/ability/ability.ts — Ability.can(action, subject?, field?) action / subject lookup SHALL delegate to matchPattern(input, ruleAction) so registered wildcard actions (e.g. read*, *:archive) match. Currently the WILDCARD_ACTION constant exists but Ability.can does not honor it.
• MODIFIED: package.json adds subpath exports ./presets/default-preset/default-preset, ./events/permission-events, ./utils/deep-get/deep-get, ./utils/pattern-match/pattern-match.
• MODIFIED: index.ts re-exports the four new public symbols (createPermissions, permissionEvents, deepGet, deepHas, matchPattern, patternToRegex, PermissionsInstance, PresetOptions).

Out of scope

• GraphQL field-level permissions middleware — separate change. Upstream has a middleware/graphql-permissions.ts (~180 L) that intercepts GraphQLResolveInfo. Genesis permissions is universal-tier and cannot depend on graphql; if we want this it belongs in a new @suaveplan/permissions-graphql browser-tier package.
• CASL pure-class subject system — upstream supports passing a class constructor as a subject (subject: ArticleClass) and resolves the subject string via subject.modelName. Genesis intentionally chose typed-pattern matching (string subjects only) to avoid pulling reflection at runtime; documented in the genesis permissions README. Out of scope here.
• Async condition matchers — upstream's DefaultConditionMatcher.match is synchronous; some downstream callers want an async variant for "is the user a member of this org?" lookups. That requires an AsyncConditionMatcher interface and an Ability.canAsync companion — meaningfully larger surface change, out of scope.
• Reactive bindings — React hooks (usePermission, usePermissionRule) live in the browser-tier @suaveplan/react-permissions package (which already exists as a separate "enterprise-react-permissions" change). Not a permissions core concern.
• Pattern-match anchor configurability — upstream's patternToRegex always anchors with ^ and $. Some callers want unanchored "contains" semantics for log-style matching. We keep the upstream anchored semantics; unanchored variants belong in a permissions-search follow-up.

Source mapping

Genesis enterprise/permissions.md is a generic enterprise-quality template (no per-feature requirements), so source mapping cites the upstream package source directly.

Requirement	Source file	Source lines	Notes
createPermissions factory	packages/universal/permissions/src/presets/default-preset/default-preset.ts	L60-L97	Verbatim port
PermissionsInstance interface	packages/universal/permissions/src/presets/default-preset/default-preset.ts	L23-L40	Verbatim
PresetOptions interface	packages/universal/permissions/src/presets/default-preset/default-preset.types.ts	L1-L26	Verbatim
permissionEvents singleton	packages/universal/permissions/src/permission-events.ts	L11-L57	Verbatim port; replace upstream EventEmitter (custom class) with EventBusLike from @suaveplan/events to match genesis-wide bus contract
deepGet	packages/universal/permissions/src/utils/deep-get.ts	L21-L36	Verbatim
deepHas	packages/universal/permissions/src/utils/deep-get.ts	L45-L47	Verbatim
matchPattern	packages/universal/permissions/src/utils/pattern-matching.ts	L20-L30	Verbatim
patternToRegex	packages/universal/permissions/src/utils/pattern-matching.ts	L41-L44	Verbatim port; ADD module-scope Map<string, RegExp> cache (genesis-only optimisation; upstream re-compiles every call)

Requirements with no source line

Requirement	Justification
permissionEvents typed against @suaveplan/types::EventBusLike (rather than upstream's custom EventEmitter class)	Genesis-wide event-bus contract policy: every cross-cutting bus uses EventBusLike so callers can swap in their own bus. Upstream uses a self-defined EventEmitter; that breaks consumer composition.
RegExp cache in patternToRegex	Genesis-wide hot-path optimisation policy. Ability.can is called on every check; pattern RegExp compilation is the hottest unbounded allocation. Bounding the cache (LRU at 1024 entries, eviction on insertion) is genesis-original.
deepGet array-index support (tags.0)	Upstream supports only object-key segments; conditions like firstTag === user.tags[0] could not be written. Adding numeric segments is a small extension that opens the realistic use case without breaking existing callers.
Ability.can action wildcard via matchPattern	Upstream Ability.can does honor manage and * wildcards via inline checks. Genesis Ability.can already imports WILDCARD_ACTION but does not actually use it; this change makes the wildcard resolution match the upstream behavior — wired through the new matchPattern util.

Verification approach

Each spec delta requirement carries a **Verified by:** line pointing at concrete it(...) titles. The test files that will exist after this change ships:

• packages/auth/permissions/src/presets/default-preset/default-preset.test.ts — destructure-and-use, matcher overrides, adapter override, multiple instances are independent
• packages/auth/permissions/src/presets/default-preset/default-preset.spec-conformance.test.ts — generics flow through (expectTypeOf), result is frozen, options validated
• packages/auth/permissions/src/events/permission-events.test.ts — listener registration, event payload shapes, manager auto-emits when no bus is passed
• packages/auth/permissions/src/events/permission-events.spec-conformance.test.ts — singleton invariant (multiple imports return the same instance), EventBusLike contract pinned
• packages/auth/permissions/src/utils/deep-get/deep-get.test.ts — dot-path resolution, array-index resolution, missing-segment returns undefined, null-safe traversal
• packages/auth/permissions/src/utils/deep-get/deep-get.spec-conformance.test.ts — deepHas agrees with deepGet !== undefined for every fixture
• packages/auth/permissions/src/utils/pattern-match/pattern-match.test.ts — exact match, * wildcard, manage wildcard, prefix, suffix, both-side wildcard, escaped special characters
• packages/auth/permissions/src/utils/pattern-match/pattern-match.spec-conformance.test.ts — RegExp cache reuse for repeated patterns; cache eviction at 1024 entries
• packages/auth/permissions/src/conditions/condition-matcher/condition-matcher.test.ts — extended with dot-path keys (user.profile.role)
• packages/auth/permissions/src/conditions/field-matcher/field-matcher.test.ts — extended with wildcard-pattern matching (field*, *field)
• packages/auth/permissions/src/core/ability/ability.test.ts — extended with wildcard-action matching (read* matches read:article)

Migration impact

This change is mostly additive — it adds four new public symbols and three small behavior changes inside existing implementations.

The three MODIFIED items (in condition-matcher, field-matcher, ability) are behavior-compatible extensions: every existing test continues to pass because the new behaviors only activate when the input contains a . (dot-path) or * (wildcard pattern) — neither of which existing tests exercise as a string literal. The full sweep is part of §9 of tasks.md.

Affected packages:

• None outside @suaveplan/permissions — bunx turbo ls --filter=...@suaveplan/permissions returns only @suaveplan/permissions itself. No internal consumer exists today (verified by grep -rl "@suaveplan/permissions" /home/ubuntu/web/genesis/packages/ --include="package.json" | grep -v node_modules returning only the package itself).

Impact

Affected dependents

Run bunx turbo ls --filter=...@suaveplan/permissions to enumerate. For each dependent, check one box:

• (No dependents in genesis today — verified by grep -rl "@suaveplan/permissions" /home/ubuntu/web/genesis/packages/ --include="package.json" | grep -v node_modules returning only packages/auth/permissions/package.json.)

When the upstream @suaveplan/auth migrates into genesis, it will consume createPermissions and permissionEvents. The four exports are stable from day one of this change so auth's migration is a non-issue.