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": []
}
}providesFeaturesentries 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 ownsession.projectId. The tier is a label, never a gate:hasFeaturestays the one predicate, with no tier branch. The label governs defaults — aplatform.*id carries no default role grant and reaches nobody until an operator grants it. Useplatform.*only for a capability that genuinely reaches outside the project. defaultRoleGrantsmaps 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 theadminpriority anchor, so anowneroradminentry in a project-dropped or third-party manifest is silently ignored and those ids are grantable only by hand in Admin → Roles. Declare grants formanager,member,viewerand custom roles;ownerholds 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.
| Declaration | Result |
|---|---|
No requires / empty features | Visible to everyone (ungated) |
Caller's grantedFeatures contains '*' | Passes every check (the '*' wildcard; the seeded owner role holds it, admin does not) |
| Multiple features listed | Every listed feature must be granted (AND semantics) |
| Feature id that no package provides | Never 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 all | Denied |
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
| Surface | Field | Notes |
|---|---|---|
Markdown contributions (PackageFile) | requires.features | Authored via the flat requiredFeatures: [a, b] frontmatter key — see Instructions |
Tools (PackageTool) | requires.features, requires.escalations | features gates catalog visibility and dispatch; escalations is catalog metadata for input-dependent checks the handler makes itself |
Commands (PackageCommand) | requires.features | Same semantics |
Workflow templates (PackageWorkflow) | requires.features | Gates every template-listing surface — see Workflows |
| Widgets and dock entries | requires.features | Gated surfaces are omitted from the workspace snapshot (App surfaces); a widget's requires.tools is catalog metadata, not a gate |
| Routes | export const feature = '...' | One feature per route file, enforced by the dispatcher before the handler runs |
| Whole package | requires.accessFeature | A 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 listBase-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:
| Axis | Question | Mechanism |
|---|---|---|
| uri-policy | Which paths may the package touch? | URI policies |
| feature | Which roles may use a capability? | requires (above) |
| scope | Which 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.