agentfootprint
Version:
The explainable agent framework — backtrack a wrong answer to the exact context that caused it (evidence, not guesses). Built on footprintjs.
225 lines • 11.1 kB
TypeScript
/**
* PermissionPolicy — data-driven role-based authorization for tool dispatch.
*
* Closes host-app gap #2 (of 8). Permissions are CROSS-CUTTING — they're not
* context engineering, they're a guard ON context-engineering operations
* (tool dispatch, skill activation, memory writes, output emission).
* That's why this lives in `agentfootprint/security`, parallel to the
* provider subpaths.
*
* Two surfaces, one primitive:
* 1. `PermissionPolicy.fromRoles({...}, activeRole)` — declarative,
* data-driven, auditable. Production governance.
* 2. The PermissionPolicy instance satisfies BOTH:
* - `PermissionChecker` interface (async check; consumed by Agent
* constructor's `permissionChecker` field)
* - sync `isAllowed(toolId)` method (consumed by `gatedTools(...)`
* from `agentfootprint/providers`)
*
* **Status: contract-shaped and tested — independently reproduced against a
* local harness, 2026-08-13.** A tool declaring `memory_write` and `user_data`
* was put in front of two roles: the read-only role passed the tool-NAME
* allowlist, failed the `memory_write` capability check, and the tool executed
* ZERO times; the admin role cleared `tool_call`, `memory_write` and
* `user_data` and executed once. A separate checker that threw `simulated
* authorizer outage` failed CLOSED — a denial carrying the operator's error in
* its rationale, the model free to continue without the tool, zero executions
* again. The reviewer's own wording: *"the permission checker is a real
* execution guard, not merely tool hiding"*, which holds exactly as far as the
* policy inputs and the role binding are trustworthy — a fact about a
* deployment, not about this class.
*
* What was exercised: the guard, end to end, by somebody who is not this
* library's author — on a DETERMINISTIC LOCAL run whose model was a mock and
* whose "authorizer outage" was a thrown `Error` (those tests *"were local and
* deterministic, so they consumed no GCP credit"*). What was NOT: **no external
* authorization service has answered a `check()` from this repository**, so
* this is not the field-validated rung — a real IAM/OPA/entitlements backend,
* with its own latency, partial outages and stale caches, remains unexercised.
* Runnable: `examples/features/03-permissions.ts` (all four shapes).
*
* Pattern: Strategy (GoF) for the role-allowlist policy + Adapter
* (matches `PermissionChecker` interface so it composes with
* existing v2.4 Agent constructor).
*
* Role: Layer-3 cross-cutting guard. Not Injection. Not provider.
* Lives in its own subpath (`agentfootprint/security`).
*
* @example Read-only role for a support agent
* const policy = PermissionPolicy.fromRoles(
* {
* readonly: ['lookup_order', 'get_status', 'list_skills', 'read_skill'],
* support: ['lookup_order', 'get_status', 'process_refund', 'list_skills', 'read_skill'],
* },
* 'readonly',
* );
*
* policy.isAllowed('lookup_order'); // → true
* policy.isAllowed('process_refund'); // → false (not in readonly role)
*
* // As a tool-dispatch gate (composes with gatedTools)
* const provider = gatedTools(staticTools(allTools), (name) => policy.isAllowed(name));
*
* // As an Agent permissionChecker (the v2.4 surface)
* const agent = Agent.create({ provider, model, permissionChecker: policy }).build();
*
* @example Per-identity role switching at runtime
* const policy = PermissionPolicy.fromRoles({
* readonly: [...],
* admin: [...],
* }, 'readonly');
*
* const adminPolicy = policy.withActiveRole('admin');
* // Same allowlist data; different active role.
*/
import type { PermissionCapability, PermissionChecker, PermissionRequest, PermissionDecision, ToolCapability } from '../provider-contract/types.js';
/**
* Map of role name → list of tool ids that role is allowed to invoke.
* The shape consumers extend over time as new tools / roles arrive.
*/
export type RoleAllowlist = Readonly<Record<string, readonly string[]>>;
/**
* Map of role name → the ids that role may reach, for a rule map beside the
* tool allowlist (9.11.0). A role ABSENT from the map has no rule of that kind,
* which means the rule does not apply to it — see {@link PermissionPolicyRules}.
*/
export type RoleIdRules = Readonly<Record<string, readonly string[]>>;
/**
* The optional rules that sit BESIDE the tool allowlist (9.11.0).
*
* Both are opt-in and both are enforced only where they are configured, because
* every one of them would otherwise change what an existing deployment permits.
* A `PermissionPolicy.fromRoles(roles, role)` built without this bag behaves
* exactly as it did in every earlier release — and reports `governs` as absent,
* so the framework never asks it anything new either.
*/
export interface PermissionPolicyRules {
/**
* role → the {@link ToolCapability} values that role may exercise.
*
* Configured (for ANY role) ⇒ the policy declares it governs all four
* capabilities, and the framework starts asking about a tool that declared
* them. For a role with a rule, a capability the rule does not list is
* DENIED. For a role WITHOUT one, capability checks fall through to the tool
* allowlist — the tool already passed it, so nothing changes for that role.
*
* @example a support role that may read but never write
* PermissionPolicy.fromRoles(roles, 'support', {
* capabilities: { support: ['memory_read', 'external_net'], admin: [...] },
* })
*/
readonly capabilities?: Readonly<Record<string, readonly ToolCapability[]>>;
/**
* role → the SKILL ids that role may activate with `read_skill`.
*
* Configured (for ANY role) ⇒ the policy declares it governs `'skill_read'`,
* and the agent starts asking per skill: a refused skill's row disappears
* from the `read_skill` menu the model reads, and an activation of it is
* refused with this policy's own rationale. For a role WITHOUT a rule, every
* skill stays visible — silence is not a denial.
*
* Ids are the bare skill ids (`'refunds'`), not the `skill:` targets: the
* prefix is the wire convention that keeps a skill and a tool of the same
* name apart, and it is this policy's job to know that, not yours.
*/
readonly skills?: RoleIdRules;
}
export interface PermissionPolicyOptions {
/**
* The role allowlist. Each role maps to the tool ids it can invoke.
* Tool ids match the `name` field of `Tool.schema.name` exactly.
*/
readonly roles: RoleAllowlist;
/**
* Which role is active for this policy instance. Calls to
* `.isAllowed(toolId)` check against this role's allowlist.
* Use `.withActiveRole(name)` to derive a sibling policy with a
* different active role.
*/
readonly activeRole: string;
/** Optional capability + skill rules (9.11.0). See {@link PermissionPolicyRules}. */
readonly rules?: PermissionPolicyRules;
}
/**
* Data-driven role-based permission policy. Satisfies the v2.4
* `PermissionChecker` interface AND exposes a sync `isAllowed` method
* for use with `gatedTools` from `agentfootprint/providers`.
*/
export declare class PermissionPolicy implements PermissionChecker {
private readonly opts;
readonly name = "PermissionPolicy";
/**
* Which capabilities this policy asks to be consulted about beyond
* `'tool_call'` (9.11.0) — DERIVED from what was configured, never a
* separate switch that could disagree with the rules.
*
* Absent when no rules were given, which is what makes every policy built
* the old way byte-identical: the framework asks it nothing new.
*/
readonly governs?: readonly PermissionCapability[];
private constructor();
/**
* Factory: build a role-based policy from a role → tool-ids map and
* the role active for this instance.
*
* Throws if `activeRole` isn't a key in `roles` — fail loud at
* config time, not at first denied call.
*/
static fromRoles(roles: RoleAllowlist, activeRole: string, rules?: PermissionPolicyRules): PermissionPolicy;
/**
* Sync allowlist check. Use as a predicate with `gatedTools`:
*
* gatedTools(staticTools(allTools), (toolId) => policy.isAllowed(toolId))
*
* Returns true iff `toolId` is in the active role's allowlist.
* Closes-fail by design: missing role membership = denied.
*/
isAllowed(toolId: string): boolean;
/**
* Async check matching the `PermissionChecker` interface — consumed
* by `Agent.create({ permissionChecker })`. Wraps `isAllowed` with
* the structured `PermissionDecision` envelope (allow / deny + a
* `policyRuleId` so observability can trace which role decided).
*
* ## What each capability is judged by (9.11.0)
*
* - `'tool_call'` — the tool allowlist. Unchanged since v2.4.
* - `'skill_read'` — the active role's `rules.skills` list, when it has one.
* Without one, allowed: a policy that never mentioned skills has not
* denied any, and silence is not a refusal.
* - a {@link ToolCapability} — the active role's `rules.capabilities` list,
* when it has one. Without one, it falls through to the tool allowlist
* below, which the tool already passed on its `'tool_call'` check — so a
* role with no capability rule behaves exactly as it did before.
*
* The framework only ever sends the last two to a policy that declared
* {@link PermissionPolicy.governs}, which this class derives from the rules
* themselves — so "unconfigured" and "never asked" cannot drift apart.
*/
check(request: PermissionRequest): Promise<PermissionDecision>;
/**
* Skill activation, judged on its own map (9.11.0).
*
* Deliberately NOT routed through the tool allowlist: a `skill:<id>` target
* is not a tool name, so `isAllowed` would deny every skill for every role
* the moment a policy was attached — hiding a whole catalogue nobody asked
* to hide. A role with no skill rule sees every skill; a role WITH one sees
* exactly what it lists.
*/
private checkSkill;
/**
* Derive a sibling policy with a different active role. Same role
* map; different active role. Useful for per-identity routing
* (one policy instance per request, varying active role per caller).
*
* Returns a NEW PermissionPolicy — original is unchanged.
*/
withActiveRole(activeRole: string): PermissionPolicy;
/** The role name currently active. Useful for observability. */
get activeRole(): string;
/** All defined role names. Stable order = registration order. */
get roles(): readonly string[];
/** All tool ids allowed under the current active role. */
allowedToolIds(): readonly string[];
}
//# sourceMappingURL=PermissionPolicy.d.ts.map