Pure scoped approval and access policy. No temporal counters or rate enforcement.
pnpm add @kehto/firewall
| Package | Range |
|---|---|
@napplet/core |
>=0.32.0 <0.46.0 |
The pure approval API evaluates NAP interface access, resource scopes, network
origins, and explicitly registered extension categories. evaluatePermissions
automatically requires interface access for every requested domain. A resource or
network grant cannot supply interface access, and interface access cannot supply
resource or network authority. Matching explicit denials take precedence.
One request carries at most maxRequirements requirements, counting the
interface requirement (default MAX_PERMISSION_REQUIREMENTS, 128); a larger
request is invalid. The grant table holds at most maxGrants grants (default
MAX_PERMISSION_GRANTS, 2048), and one napplet holds at most
maxGrantsPerPrincipal of them (default MAX_PERMISSION_GRANTS_PER_PRINCIPAL,
512, clamped to maxGrants). admitPermissionGrants adds a decision's grants
and makes room by evicting only session grants, oldest first: the napplet's
own, then those of the napplet holding the most. Persistent and once grants
are never evicted; with nothing left to evict it throws the limit RangeError.
All three are PermissionPolicyOptions and host
policy, not protocol: permissionLimits(options) resolves them and throws a
RangeError outside 1 to MAX_PERMISSION_REQUIREMENTS_CEILING (1024) or
MAX_PERMISSION_GRANTS_CEILING (16384), because evaluation costs requirements ×
grants. Callers plan within the bound, for example by naming each network
origin once and bounding relay plans.
A verified principal uses the catalog ID from a signature-verified manifest plus its verified artifact hash. Named/root IDs include the publisher; snapshot IDs use the signed event ID. Shape validation does not verify signatures: the host must supply these facts from its resolver. Development targets use a separate principal kind and can receive only session or once grants.
import {
createPermissionState,
evaluatePermissions,
putPermissionGrant,
} from '@kehto/firewall';
const permission = {
category: 'interface' as const,
domain: 'link',
operation: 'access',
scope: { kind: 'exact' as const, value: 'link' },
};
const principal = {
kind: 'verified' as const,
manifestKey: verifiedManifest.catalogId,
artifactHash: verifiedManifest.artifactHash,
};
let state = createPermissionState();
state = putPermissionGrant(state, {
id: 'host-generated-grant-id', principal, permission,
effect: 'allow', lifetime: 'persistent',
});
const decision = evaluatePermissions(state, {
principal, sessionId: 'endpoint-generation-1', requestId: 'host-request-1',
requirements: [permission],
});
// decision.decision is 'allow'; link destination authority is a separate requirement.
Scopes are exact by default. Network origins normalize scheme/host/default ports and reject credentials, wildcards and path/query/fragment constraints. Virtual directory grants match path segment boundaries; paths with traversal, backslashes, percent encoding or empty segments are rejected. This does not replace NAP-FS mount/symlink checks or per-entry authorization for recursive operations. Exact resource strings preserve their bytes and do not alter NAP-RESOURCE cache keys. Hosts must use opaque keys for secret-bearing resources rather than persist or show secrets in permission descriptions.
A session grant matches one endpoint generation. A once grant additionally matches
a host-generated request token. consumePermissionGrants rechecks all requirements
and consumes the one-use grants only on allow; the runtime must store its returned
state atomically before executing the operation. Reusing a wire request ID must
never reuse a host authorization token. revokePermissionGrant removes policy;
the runtime remains responsible for cancelling affected pending and live work.
serializePermissions writes only persistent grants. deserializePermissions
validates the version and every grant and reports an explicit failure for malformed,
duplicate, ephemeral or unknown-category records. It never converts the old
Firewall's broad allow policy into new authority. Storage I/O, failure reporting,
approval UI, request cancellation, protocol responses belong to
host/runtime integration. Extension categories must be explicitly registered via
PermissionPolicyOptions.extensions and use exact scope keys.
PermissionRules describe what a host does with a request no stored decision
covers: one default action (allow, ask or deny) plus exceptions per
interface or per operation, each overridable per napplet.
createPermissionRules() with no argument asks for everything.
resolvePermissionRule(rules, principal, requirement) returns the most specific
match, setPermissionRule returns changed rules, and
serializePermissionRules / deserializePermissionRules store them; a damaged
document is refused whole rather than partly applied. Rules never create
authority themselves: the runtime turns an allow into a session grant through
PermissionAdapter.defaultDecision. See Scoped Firewall approvals.
Approval grants cannot bypass a host-installed limiter. Runtime does not install
one automatically. Temporal controls and the previous behavioral API live in
@kehto/rate-limit and its explicit /legacy migration entry point.
Network requirements accept scope: { kind: "ice", value: "turn:relay.example:3478?transport=udp" }.
STUN/TURN scopes match exact scheme, host, port, and optional transport; web-origin
grants never cover them. The normalizer rejects credentials, paths and fragments,
normalizes host case, and supplies the standard 3478/5349 port when omitted.
Credentials remain host-private. See RFC 7064 and RFC 7065 for the URI formats.