@cloudhal/agent-runtime 0.0.0-stage → 0.1.0

package/dist/src/policy.d.ts

@@ -0,0 +1,197 @@
+import type { Actor } from "@cloudhal/core-contracts";
+import type { AgentMode } from "./modes.js";
+import type { Role } from "./roles.js";
+/**
+ * Scopes follow `area:verb`; `*` grants everything (the Owner, local stdio, auth-less servers).
+ * RFC-0005 §1 adds own-limited variants (`…:own`) and person-only scopes. A stronger scope implies
+ * the weaker ones (`implies`).
+ */
+export type Scope = "site:read" | "site:write" | "content:read" | "content:write" | "content:write:own" | "content:draft:own" | "content:propose" | "preview:create" | "site:publish" | "site:publish:own" | "site:rollback" | "asset:upload" | "asset:manage" | "analytics:read" | "comments:read" | "comments:moderate" | "comments:moderate:own" | "comments:reply" | "comments:reply:own" | "commenters:data" | "audit:read" | "site:settings" | "members:invite" | "members:manage" | "agents:manage" | "site:create" | "schedules:read" | "schedules:write" | "schedules:write:own" | "releases:publish" | "releases:publish:own" | "automations:manage" | "ai:invoke" | "*";
+/**
+ * Tool scopes: what agent keys may hold and what MCP tools require (I7). `*`, and the person-only
+ * scopes, are never grantable to a key.
+ */
+export declare const KEY_SCOPES: readonly Scope[];
+/** Scopes only a person holds (through their role): never stored on a key, never satisfy a tool. */
+export declare const PERSON_SCOPES: readonly Scope[];
+/** @deprecated use `KEY_SCOPES` (what a key may carry). */
+export declare const ALL_SCOPES: Scope[];
+/** Every scope except `*`. */
+export declare const SCOPES: readonly Scope[];
+export declare function isScope(value: unknown): value is Scope;
+export declare function isKeyScope(value: unknown): value is Scope;
+/** `a` grants at least what `b` grants. */
+export declare function implies(a: Scope, b: Scope): boolean;
+/** The scopes `scope` implies, strongest first (not including itself). */
+export declare function weakerScopes(scope: Scope): Scope[];
+/** Does a set of scopes grant `scope` (directly, through `*`, or through a stronger scope)? */
+export declare function holds(scopes: readonly string[], scope: Scope): boolean;
+/**
+ * The own limit an allowed call carries (RFC-0005 §9): the caller holds only an own variant of the
+ * tool's scope, so the handler must check the target. `draft` = never-published entries, status
+ * draft/review only.
+ */
+export type OwnLimit = {
+    level: "own" | "draft";
+    target: "entry";
+} | {
+    level: "own";
+    target: "changeset";
+}
+/** RFC-0007 §10.1: each comment's entry must be the person's own (its author, or their agent). */
+ | {
+    level: "own";
+    target: "comment";
+}
+/**
+ * RFC-0008 §10.1: every node a release (or a gate) touches must be the person's own — an entry
+ * whose author is the person or one of their agents (`ownOnlyChangeSet`'s rule).
+ */
+ | {
+    level: "own";
+    target: "release";
+};
+/**
+ * What a call does, decided from its arguments (RFC-0007 §10.2), for tools whose policy depends
+ * on them (`moderate_comments` may hide in `edits` mode but never approve):
+ *
+ * | Class | Meaning | plan | manual | edits | auto | bypass (local) |
+ * |---|---|---|---|---|---|---|
+ * | `read` | changes nothing | ✓ | ✓ | ✓ | ✓ | ✓ |
+ * | `advisory` | changes only notes people read before deciding (labels) | ✗ | ✓ | ✓ | ✓ | ✓ |
+ * | `reduce` | reversible, can only make something less visible | ✗ | waits | ✓ | ✓ | ✓ |
+ * | `publish` | makes content public, or removes it, at a time | ✗ | waits | waits | low-risk in window ✓, else waits | ✓ |
+ * | `person` | makes something public | ✗ | waits | waits | waits | **waits** |
+ * | `propose` | files a proposal a person accepts or rejects; changes no content (ADR-0028) | ✓ | ✓ | ✓ | ✓ | ✓ |
+ *
+ * `person` calls wait with cause `tool` in every mode, `bypass` included, and for people calling
+ * over MCP too (they are asked in their own client). `publish` (RFC-0008 §10.3) follows ADR-0015's
+ * publish rules instead: in `auto` mode the decision carries `autoApprove: "low-risk-release"` and
+ * the server applies the low-risk check and the window rule (§10.7) to the release itself.
+ * Tools without `classify`, or whose `classify` returns nothing for a call, behave as before.
+ */
+export type CallClass = "read" | "advisory" | "reduce" | "publish" | "person" | "propose";
+export interface ToolAnnotations {
+    readOnlyHint?: boolean;
+    destructiveHint?: boolean;
+    idempotentHint?: boolean;
+    openWorldHint?: boolean;
+}
+export interface ToolPolicy {
+    /** Tool name as exposed over MCP. */
+    name: string;
+    /** Scopes the caller must hold (any `*` satisfies). */
+    scopes: Scope[];
+    annotations: ToolAnnotations;
+    /** Tools that always need a human decision, independent of scopes. */
+    requiresApproval?: boolean;
+    /**
+     * The own variants of the tool's scope satisfy it with a limit (RFC-0005 §9): `entry` — the
+     * handler checks the target entry; `changeset` — a publish must be own-only.
+     */
+    own?: "entry" | "changeset" | "comment" | "release";
+    /** Per-argument policy (RFC-0007 §10.2); `evaluate` receives the call's arguments. */
+    classify?: (args: Record<string, unknown>) => CallClass | undefined;
+    /**
+     * The scopes a `propose` call needs instead of `scopes` (ADR-0028): proposing an edit to a body
+     * needs `content:propose`, not the write it proposes.
+     */
+    proposeScopes?: Scope[];
+}
+export interface Principal {
+    actor: Actor;
+    scopes: Scope[];
+    /** Skill the agent declared it is running (its frontmatter decides extra approvals). */
+    skill?: {
+        name: string;
+        scopes: string[];
+        approval: string[];
+    } | undefined;
+    /** Agents only: how independently it works (ADR-0015). Absent = `edits`; people have none. */
+    mode?: AgentMode | undefined;
+    /** True for the local stdio server (the developer's own machine); enables `bypass`. */
+    local?: boolean | undefined;
+    /** Set while `mode` comes from a time-boxed elevation (ADR-0016): the key's own mode and the end. */
+    elevation?: {
+        from: AgentMode;
+        until: string;
+    } | undefined;
+    /** The API key an agent authenticated with (lets it ask for an elevation of that key). */
+    keyId?: string | undefined;
+    /**
+     * RFC-0008 §11.2: the key is an automation's key (`purpose: "automation"` in its metadata). It
+     * works only inside an open run of that automation, except `begin_run` and `get_mode`.
+     */
+    automationId?: string | undefined;
+    /**
+     * The person behind the call (RFC-0005): for people themselves, for agents the person who created
+     * the key. Absent when there is no membership source (auth-less servers, local stdio): such
+     * principals are not role-bound.
+     */
+    person?: PersonRef | undefined;
+    /** Agents only: the key's own scopes before narrowing, so `forSite` can narrow them per site. */
+    keyScopes?: readonly string[] | undefined;
+}
+/** A staff member as the policy layer sees them. */
+export interface PersonRef {
+    /** Actor id (`user_…`), the form `author` and audit rows use. */
+    id: string;
+    /** Better Auth user id. */
+    userId: string;
+    role: Role;
+    name?: string | undefined;
+    /**
+     * RFC-0034 A2: the sites an Editor, Author or Contributor is limited to, each with its role.
+     * Absent: the role applies to every site. `forSite` applies it.
+     */
+    sites?: Readonly<Record<string, Role>> | undefined;
+}
+/** The mode that actually applies: `bypass` only counts locally, remote keys fall back to `edits`. */
+export declare function effectiveMode(principal: Principal): AgentMode | undefined;
+/**
+ * Why a call waits for a person (stored on approvals and audit rows). `role`: the caller's role
+ * allows less than the call (an Author's publish that is not own-only, RFC-0005 §6).
+ */
+export type ApprovalCause = "tool" | "destructive" | "skill" | "manual-mode" | "role";
+export type Decision = {
+    kind: "allow";
+    limit?: OwnLimit;
+} | {
+    kind: "deny";
+    reason: string;
+    code?: "missing_scope" | "mode" | "skill";
+} | {
+    kind: "approval-required";
+    reason: string;
+    /** Why a person must decide: the tool always asks, it is destructive, the skill asks, or manual mode. */
+    cause: ApprovalCause;
+    /**
+     * `auto` mode: the caller may skip the person when the change is low risk — a publish now
+     * (`low-risk-publish`, ADR-0015) or a release inside the key's window (`low-risk-release`,
+     * RFC-0008 §10.7).
+     */
+    autoApprove?: "low-risk-publish" | "low-risk-release";
+    /** The own limit the call runs under once approved. */
+    limit?: OwnLimit;
+};
+/**
+ * The single place that decides whether a tool call may run (ADR-0004). Humans and agents share
+ * the same model: scopes come from the role or API key, approvals from annotations and the
+ * declared skill. Skills never grant permission — they can only ask for more approval.
+ */
+export declare class PolicyEngine {
+    #private;
+    constructor(tools: ToolPolicy[]);
+    tool(name: string): ToolPolicy | undefined;
+    /** Every tool, in registration order (a run envelope lists the ones a run may call). */
+    tools(): ToolPolicy[];
+    evaluate(principal: Principal, toolName: string, options?: {
+        confirmed?: boolean;
+        args?: Record<string, unknown> | undefined;
+    }): Decision;
+}
+/**
+ * Default scope sets per actor kind, for principals without a membership source (auth-less
+ * servers, tests, local scripts). With auth, a person's scopes come from their role (RFC-0005 I1).
+ */
+export declare function defaultScopes(actor: Actor): Scope[];