# @kehto/firewall

Pure scoped approval and access policy. No temporal counters or rate enforcement.

## Install

```sh
pnpm add @kehto/firewall
```

## Manifest Facts

| Field | Value |
|-------|-------|
| Source | `packages/firewall/package.json`, `packages/firewall/src/index.ts` |
| Version | `0.11.0` |
| Runtime entry | `./dist/index.js` |
| Types entry | `./dist/index.d.ts` |
| Side effects | `false` |

## Peer Dependencies

| Package | Range |
|---------|-------|
| `@napplet/core` | `>=0.32.0 <0.46.0` |

## Approval policy

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.

```ts
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.

## Default rules

`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](/firewall-approvals#default-rules).

## Scope Boundaries

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.

## API Reference

<a href="../api/modules/_kehto_firewall.html" target="_self">Generated API reference</a>.

### ICE endpoint scopes

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.
