Plugin Capability Reference

3 min readPlugin author · Security reviewerv0.9.0a1 stable

What this page covers

Stigmem plugins declare capabilities in PluginManifest.capabilities. The registry passes each handler a PluginContext scoped to the declaring plugin. A handler can only retrieve a core API handle when the manifest declares the matching capability.

Audience: Plugin authors, operators, and security reviewers evaluating plugin access.

The v0.9.0a1 capability model is intentionally fail closed.

Unknown names rejected

During manifest validation.

Missing declared capabilities raise

CapabilityError when a handler calls the gated accessor.

Declaring ≠ guarantee

Declaring a capability permits access, but the exposed handle may still be None if the node did not provide that core API to plugins.

Not a replacement

Treat capabilities as security review inputs, not as a replacement for plugin signing, trusted-publisher policy, or code review.

For a working example, see the Plugin Author Guide. For hook dispatch behavior, see the Plugin Hook Reference.

Capability table

Capability

Accessor

Access · review guidance

facts.read

get_facts_reader()

Read-oriented fact access. Verify the plugin has a need to inspect facts in the scopes it will operate on.

facts.write

get_facts_writer()

Write-oriented fact access. High impact. Confirm writes are namespaced, auditable, and bounded by operator policy.

recall.read

get_recall_reader()

Read-oriented recall access. Review data exposure risk because recall may combine multiple facts into richer context.

recall.write

get_recall_writer()

Write or mutation access for recall state. High impact. Confirm the plugin cannot poison ranking or recall state outside its intended scope.

audit.emit

get_audit_emitter()

Emit audit events. Does not grant read access to audit history.

audit.read

get_audit_reader()

Read audit data. Sensitive. Audit trails can reveal actors, target entities, tenant identifiers, and operational metadata.

federation.read

get_federation_reader()

Read federation state. Review peer metadata exposure and whether the plugin can infer trust relationships.

federation.write

get_federation_writer()

Write or mutation access. High impact. Federation mutation can affect peer behavior and propagation.

identity.read

get_identity_reader()

Read identity state. Sensitive. Identity metadata can affect authorization, attribution, and audit review.

tenant.read

get_tenant_reader()

Read tenant context. Review multi-tenant boundary impact.

tenant.write

get_tenant_writer()

Write or mutation access. High impact. Tenant mutation can affect isolation and routing.

config.read

get_config_reader()

Read node or plugin configuration. Review whether configuration contains secrets, trusted publisher identities, or topology.

network.outbound

get_network_outbound()

Outbound network access. High impact. Review destination allowlists, data exfiltration risk, and timeout behavior.

Denial behavior

Capability denial is enforced when the handler asks for a core API handle:

from stigmem_node.plugins import PluginContext


def handler(ctx: PluginContext, **_: object) -> None:
    ctx.get_facts_reader()

If the plugin manifest does not declare facts.read, the accessor raises CapabilityError:

plugin 'example-plugin' cannot call get_facts_reader: capability 'facts.read' not declared

The registry treats that like any other handler failure for the hook semantic:

Voting / filter / score-delta

Failures surface as plugin execution errors.

Non-strict fire-and-forget

Logged and audited without stopping the hook site.

Strict audit (incl. audit_emit)

Failures are surfaced.

Operator review checklist

1. Confirm the package is signed by an accepted trusted publisher or an explicit operator override.
2. Compare the manifest capability list to the plugin's documented behavior.
3. Reject broad write, tenant, federation, identity, or outbound-network access unless the use case requires it.
4. Prefer plugins that emit audit events for meaningful side effects.
5. Re-review capabilities when upgrading a plugin package, even if the signing identity has not changed.