@package-system

Features and access

Feature grants, role defaults, and the deny-by-default visibility predicate.

Features are the access currency of the package system. A package declares the capability classes it provides, project roles receive grants of those ids, and every surface a caller can see or invoke — tools, skills, routes, widgets, dock entries, commands, workflow templates — is checked against the caller's grants through one shared predicate. There is no second authorization vocabulary.

Declaring features

Features live in the manifest's requires block:

"requires": {
  "providesFeatures": [
    "my-pkg.read",
    { "id": "my-pkg.admin", "title": "Administration", "description": "Manage package settings." }
  ],
  "defaultRoleGrants": {
    "owner":  ["my-pkg.read", "my-pkg.admin"],
    "admin":  ["my-pkg.read", "my-pkg.admin"],
    "member": ["my-pkg.read"],
    "viewer": []
  }
}
  • providesFeatures entries are a bare id or a { id, title?, description? } object, whose metadata the admin roles UI shows without changing the id. Duplicate ids fail manifest validation.
  • The id prefix is the tier, so the boundary can never drift from a hand-kept list. platform.* marks a decision that crosses the project boundary — another tenant, a platform-global file, cross-user records, the global credential scope. Every other id, project.* included, acts inside the caller's own session.projectId. The tier is a label, never a gate: hasFeature stays the one predicate, with no tier branch. The label governs defaults — a platform.* id carries no default role grant and reaches nobody until an operator grants it. Use platform.* only for a capability that genuinely reaches outside the project.
  • defaultRoleGrants maps role names to the ids each role receives at install; admins adjust grants per project afterwards. It cannot reach the strongest roles: for any non-builtin package the merge skips every '*' holder and every role at or stronger than the admin priority anchor, so an owner or admin entry in a project-dropped or third-party manifest is silently ignored and those ids are grantable only by hand in Admin → Roles. Declare grants for manager, member, viewer and custom roles; owner holds the wildcard already.
  • The consumers — which tools, skills, commands and App surfaces a feature gates — are never stored on the manifest; they are derived from the loaded definitions at boot, so they cannot drift from the code.

The one visibility predicate

Every requires: { features: [...] } declaration is evaluated by one shared function, meetsRequires(session, requires), built on hasFeature; surfaces never inline a copy.

DeclarationResult
No requires / empty featuresVisible to everyone (ungated)
Caller's grantedFeatures contains '*'Passes every check (the '*' wildcard; the seeded owner role holds it, admin does not)
Multiple features listedEvery listed feature must be granted (AND semantics)
Feature id that no package providesNever granted to any role except '*' holders. It cannot appear in a derived grant list either, so it is wildcard-holder-only by construction
Caller has no grantedFeatures at allDenied

A failing check hides the surface entirely: a gated skill is not injected, not in the packages overview or any catalog, never shown locked or disabled — a caller lacking the feature cannot infer it exists. The same holds for gated tools (catalog and dispatch), commands, widgets and dock entries.

Visibility and execution are gated independently. Hiding happens at the advertisement boundary; execution is enforced server-side too — the dispatcher checks a route's feature before the handler runs (Routes), tool dispatch rejects callers failing requires.features, and filesystem access goes through URI policies.

Where requires appears

SurfaceFieldNotes
Markdown contributions (PackageFile)requires.featuresAuthored via the flat requiredFeatures: [a, b] frontmatter key — see Instructions
Tools (PackageTool)requires.features, requires.escalationsfeatures gates catalog visibility and dispatch; escalations is catalog metadata for input-dependent checks the handler makes itself
Commands (PackageCommand)requires.featuresSame semantics
Workflow templates (PackageWorkflow)requires.featuresGates every template-listing surface — see Workflows
Widgets and dock entriesrequires.featuresGated surfaces are omitted from the workspace snapshot (App surfaces); a widget's requires.tools is catalog metadata, not a gate
Routesexport const feature = '...'One feature per route file, enforced by the dispatcher before the handler runs
Whole packagerequires.accessFeatureA single feature id that gates the ENTIRE package — see below

For imperative checks inside a handler, the same building blocks are exported from @neuralis/package-system/access:

import { hasFeature, requireFeature, meetsRequires } from '@neuralis/package-system/access';

hasFeature(session, 'my-pkg.read');        // boolean
requireFeature(session, 'my-pkg.admin');   // throws a 403-status error when missing
meetsRequires(session, { features: ['a', 'b'] }); // AND over the list

Base-access feature — gating a whole package

Beyond per-tool, -skill and -widget features, a package can gate its entire surface with one declaration:

"requires": { "accessFeature": "labs.access" }

A caller lacking labs.access sees none of the package — no tools, skills, widgets or <packages> overview entry; hidden, not locked, so its existence can't be inferred. Without accessFeature the package is visible to everyone, so packages imported from other ecosystems load unchanged.

This is the clean way to build and test a package in isolation: declare an access feature with no default role grant, and until you grant it only a '*' holder (owner-strength) sees the package — a project admin does not, because the seeded admin role holds an enumerated list rather than the wildcard. The feature is grantable in Admin → Roles. An administrator can also attach a required feature to an installed package in Admin → Packages (or neuralis package access <package> <feature>), picking from the project's existing features: a restrict-only override that tightens visibility, never grants access, and is grantable in Admin → Roles too.

Scope — who a loaded package reaches

Package consumption is governed by three orthogonal axes:

AxisQuestionMechanism
uri-policyWhich paths may the package touch?URI policies
featureWhich roles may use a capability?requires (above)
scopeWhich user/agent is a loaded package advertised to?source scope + canAccessScope

A package contributed by a user-scoped or agent-scoped source loads for the project but is advertised only to that user or agent — its tools, skills and widgets never reach another member's stream, MCP catalog or workspace. One predicate, canAccessScope, decides both file access and package visibility at every advertise boundary; that is what makes per-person and per-agent capabilities possible on a shared, multi-tenant project.

Role priority

Feature grants answer "what can this caller do"; role priority answers "what strength of role may this caller hand out". Priority is one ordinal per role, lower = stronger; the five built-in roles anchor the scale and custom roles declare their own (anchors and range: roles). The name is cosmetic, the number is enforced, and an unknown label with no declared priority resolves to the weakest value, so it can never escalate.

The assignment rule, implemented once in canAssignRole / validateRoleAssignment: a caller may assign a role only when the target's priority is equal to or weaker than their own (targetPriority >= callerPriority). An undefined caller priority means a system session with no membership identity, which bypasses the check. The caller's priority travels as SessionContext.priority (sessions). It is enforced at every role-handling boundary: invitations, member role changes, role definition edits, and agent provisioning from package team members. The same priority decides a uri-policy rule's priority subject (URI policies).

Deny by default

One posture: undeclared means ungated, ungranted means invisible, unknown means denied. Referencing a feature id nothing provides is a legitimate technique — it makes a contribution reachable only by a '*' holder. Administering roles and grants across projects: Roles and features.

On this page