@cloudhal/agent-runtime 0.0.0-stage → 0.1.0

package/dist/src/policy.js

@@ -0,0 +1,508 @@
+                                                      
+                                            
+                                       
+
+/**
+ * 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`).
+ */
+                   
+               
+                
+                  
+                   
+                       
+                       
+                     
+                    
+                  
+                      
+                   
+                  
+                  
+                    
+                   
+                       
+                           
+                    
+                        
+                     
+                
+                   
+                    
+                    
+                   
+                                                                                
+                 
+                                                                                     
+                    
+                     
+                         
+                      
+                          
+                        
+                                                                                 
+               
+        
+
+/**
+ * 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 const KEY_SCOPES                   = [
+  "site:read",
+  "site:write",
+  "content:read",
+  "content:write",
+  "content:write:own",
+  "content:draft:own",
+  // RFC-0014 §5 (ADR-0028): file body proposals a person accepts or rejects; changes no content,
+  // so `plan` keys hold it. Every write variant implies it.
+  "content:propose",
+  "preview:create",
+  "site:publish",
+  "site:publish:own",
+  "site:rollback",
+  "asset:upload",
+  "asset:manage",
+  // RFC-0006 §9.1: read-only site analytics (aggregates, no personal data). Implies nothing and
+  // nothing implies it except `*`.
+  "analytics:read",
+  // RFC-0007 §10.1: reader comments. Reading carries no email or IP hash (the contract has no
+  // field for them); moderating and replying have own variants for Authors' entries.
+  "comments:read",
+  "comments:moderate",
+  "comments:moderate:own",
+  "comments:reply",
+  "comments:reply:own",
+  // RFC-0008 §10.1: read the schedule; create and change releases and gates (`own`: only one's
+  // own nodes); approve releases and let `auto`-mode releases run without a person (`own`: every
+  // item is one's own). `releases:publish` is implied by `site:publish`; it exists on its own so
+  // an owner can give a key "schedule, never publish now".
+  "schedules:read",
+  "schedules:write",
+  "schedules:write:own",
+  "releases:publish",
+  "releases:publish:own",
+];
+
+/** Scopes only a person holds (through their role): never stored on a key, never satisfy a tool. */
+export const PERSON_SCOPES                   = [
+  "audit:read",
+  "site:settings",
+  "members:invite",
+  "members:manage",
+  "agents:manage",
+  // RFC-0034 §3: new sites belong to people who run the installation.
+  "site:create",
+  // RFC-0007 §10.1: commenter emails, a commenter's export and erasure — people only.
+  "commenters:data",
+  // RFC-0008 §10.1 (D7): creating, editing, resuming, running and deleting automations — standing
+  // rules of autonomy stay with people.
+  "automations:manage",
+  // RFC-0016 (D6): in-editor AI commands; agents bring their own model.
+  "ai:invoke",
+];
+
+/** @deprecated use `KEY_SCOPES` (what a key may carry). */
+export const ALL_SCOPES          = [...KEY_SCOPES];
+
+/** Every scope except `*`. */
+export const SCOPES                   = [...KEY_SCOPES, ...PERSON_SCOPES];
+
+export function isScope(value         )                 {
+  return value === "*" || (typeof value === "string" && (SCOPES            ).includes(value));
+}
+
+export function isKeyScope(value         )                 {
+  return typeof value === "string" && (KEY_SCOPES            ).includes(value);
+}
+
+/** Direct implications (the lattice of RFC-0005 §1); `implies` follows them transitively. */
+const IMPLIES                                           = {
+  "content:write": ["content:write:own"],
+  "content:write:own": ["content:draft:own"],
+  "content:draft:own": ["content:propose"],
+  // RFC-0008 §10.1: publishing later is no more power than publishing now.
+  "site:publish": ["site:publish:own", "releases:publish"],
+  "site:publish:own": ["releases:publish:own"],
+  "releases:publish": ["releases:publish:own"],
+  "schedules:write": ["schedules:write:own"],
+  "asset:manage": ["asset:upload"],
+  "members:manage": ["members:invite"],
+  "comments:moderate": ["comments:moderate:own"],
+  "comments:reply": ["comments:reply:own"],
+};
+
+/** `a` grants at least what `b` grants. */
+export function implies(a       , b       )          {
+  if (a === "*" || a === b) return true;
+  return (IMPLIES[a] ?? []).some((x) => implies(x, b));
+}
+
+/** The scopes `scope` implies, strongest first (not including itself). */
+export function weakerScopes(scope       )          {
+  const out          = [];
+  const walk = (s       ) => {
+    for (const x of IMPLIES[s] ?? []) {
+      if (!out.includes(x)) out.push(x);
+      walk(x);
+    }
+  };
+  walk(scope);
+  return out;
+}
+
+/** Does a set of scopes grant `scope` (directly, through `*`, or through a stronger scope)? */
+export function holds(scopes                   , scope       )          {
+  return scopes.some((s) => isScope(s) && implies(s, scope));
+}
+
+/**
+ * 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.
+ */
+                      
+                                               
+                                         
+                                                                                                    
+                                       
+     
+                                                                                                 
+                                                                                   
+     
+                                        
+
+/** Own variants that satisfy a tool scope with a limit, strongest first. */
+const OWN_VARIANTS                                                                              = {
+  "content:write": [
+    { scope: "content:write:own", level: "own" },
+    { scope: "content:draft:own", level: "draft" },
+  ],
+  "site:publish": [{ scope: "site:publish:own", level: "own" }],
+  "comments:moderate": [{ scope: "comments:moderate:own", level: "own" }],
+  "comments:reply": [{ scope: "comments:reply:own", level: "own" }],
+  "schedules:write": [{ scope: "schedules:write:own", level: "own" }],
+  "releases:publish": [{ scope: "releases:publish:own", level: "own" }],
+};
+
+/**
+ * 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.
+ */
+                                                                                          
+
+                                  
+                         
+                            
+                           
+                          
+ 
+
+                             
+                                       
+               
+                                                         
+                  
+                               
+                                                                        
+                             
+     
+                                                                                              
+                                                                               
+     
+                                                      
+                                                                                        
+                                                                      
+     
+                                                                                                  
+                                                        
+     
+                          
+ 
+
+                            
+               
+                  
+                                                                                          
+                                                                             
+                                                                                                
+                               
+                                                                                         
+                              
+                                                                                                       
+                                                             
+                                                                                            
+                             
+     
+                                                                                                 
+                                                                                         
+     
+                                    
+     
+                                                                                                    
+                                                                                              
+                                   
+     
+                                 
+                                                                                                   
+                                            
+ 
+
+/** A staff member as the policy layer sees them. */
+                            
+                                                                   
+             
+                             
+                 
+             
+                            
+     
+                                                                                               
+                                                                  
+     
+                                                     
+ 
+
+/** The mode that actually applies: `bypass` only counts locally, remote keys fall back to `edits`. */
+export function effectiveMode(principal           )                        {
+  if (principal.actor.kind !== "agent") return undefined;
+  const mode = principal.mode ?? "edits";
+  return mode === "bypass" && !principal.local ? "edits" : mode;
+}
+
+/**
+ * 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).
+ */
+                                                                                      
+
+                      
+                                       
+                                                                               
+     
+                                
+                     
+                                                                                                               
+                           
+         
+                                                                                                
+                                                                                                 
+                         
+         
+                                                            
+                                                             
+                       
+      
+
+/**
+ * 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 class PolicyEngine {
+           #tools = new Map                    ();
+
+  constructor(tools              ) {
+    for (const t of tools) this.#tools.set(t.name, t);
+  }
+
+  tool(name        )                         {
+    return this.#tools.get(name);
+  }
+
+  /** Every tool, in registration order (a run envelope lists the ones a run may call). */
+  tools()               {
+    return [...this.#tools.values()];
+  }
+
+  evaluate(
+    principal           ,
+    toolName        ,
+    options                                                                      = {},
+  )           {
+    const tool = this.#tools.get(toolName);
+    if (!tool) return { kind: "deny", reason: `unknown tool ${toolName}` };
+    const cls = tool.classify?.(options.args ?? {});
+    const required = cls === "propose" && tool.proposeScopes ? tool.proposeScopes : tool.scopes;
+    let limit                      ;
+    const missing          = [];
+    for (const s of required) {
+      // Person-only scopes never satisfy a tool (I7), not even through `*`.
+      if (PERSON_SCOPES.includes(s)) {
+        missing.push(s);
+        continue;
+      }
+      if (holds(principal.scopes, s)) continue;
+      const variant = tool.own
+        ? OWN_VARIANTS[s]?.find((v) => holds(principal.scopes, v.scope))
+        : undefined;
+      if (variant && !limit) {
+        limit =
+          tool.own === "changeset"
+            ? { level: "own", target: "changeset" }
+            : tool.own === "comment"
+              ? { level: "own", target: "comment" }
+              : tool.own === "release"
+                ? { level: "own", target: "release" }
+                : { level: variant.level, target: "entry" };
+        continue;
+      }
+      missing.push(s);
+    }
+    if (missing.length > 0)
+      return { kind: "deny", reason: `missing scope ${missing.join(", ")}`, code: "missing_scope" };
+    if (principal.skill) {
+      // A skill may only call tools inside the scopes it declared (own variants count).
+      const declared = principal.skill.scopes;
+      const covered = (s       ) =>
+        holds(declared, s) ||
+        (tool.own !== undefined && (OWN_VARIANTS[s] ?? []).some((v) => holds(declared, v.scope)));
+      const outside = required.filter((s) => !covered(s));
+      if (outside.length > 0)
+        return {
+          kind: "deny",
+          reason: `skill ${principal.skill.name} did not declare ${outside.join(", ")}`,
+          code: "skill",
+        };
+    }
+    const mode = effectiveMode(principal);
+    const limited = limit ? { limit } : {};
+    if (cls)
+      return classified(tool, cls, principal, mode, {
+        confirmed: options.confirmed === true,
+        limited,
+      });
+    const writes = tool.annotations.readOnlyHint !== true;
+    if (mode === "plan" && writes)
+      return {
+        kind: "deny",
+        reason: "plan mode is read-only: propose the change instead",
+        code: "mode",
+      };
+    const needsApproval =
+      tool.requiresApproval ||
+      tool.annotations.destructiveHint === true ||
+      (principal.skill?.approval ?? []).includes(toolName) ||
+      (mode === "manual" && writes);
+    if (needsApproval && !options.confirmed && mode !== "bypass") {
+      // A tool that always asks (publish, rollback) says so first; then plain destructive ones.
+      const cause                = tool.requiresApproval
+        ? "tool"
+        : tool.annotations.destructiveHint
+          ? "destructive"
+          : (principal.skill?.approval ?? []).includes(toolName)
+            ? "skill"
+            : "manual-mode";
+      const reason = {
+        "manual-mode": `manual mode: ${toolName} needs a person's approval`,
+        destructive: `${toolName} is destructive`,
+        tool: `${toolName} requires approval`,
+        skill: `${toolName} requires approval`,
+        role: `${toolName} needs someone whose role allows it`,
+      }[cause];
+      // `auto` lets a low-risk publish through; rollback and deletions always wait for a person.
+      const auto = mode === "auto" && toolName === "publish";
+      return {
+        kind: "approval-required",
+        reason,
+        cause,
+        ...(auto ? { autoApprove: "low-risk-publish"          } : {}),
+        ...limited,
+      };
+    }
+    return { kind: "allow", ...limited };
+  }
+}
+
+/** The decision for a classified call (RFC-0007 §10.2), after the scope and skill checks. */
+function classified(
+  tool            ,
+  cls           ,
+  principal           ,
+  mode                       ,
+  o                                                       ,
+)           {
+  // Reading changes nothing; a proposal changes nothing until a person accepts it, so `plan`
+  // mode may propose (ADR-0015's follow-up, ADR-0028).
+  if (cls === "read" || cls === "propose") return { kind: "allow", ...o.limited };
+  if (mode === "plan")
+    return {
+      kind: "deny",
+      reason: "plan mode is read-only: propose the change instead",
+      code: "mode",
+    };
+  if (o.confirmed) return { kind: "allow", ...o.limited };
+  const wait = (cause               , reason        )           => ({
+    kind: "approval-required",
+    reason,
+    cause,
+    ...o.limited,
+  });
+  // A person makes something public, in every mode — `bypass` included — and people over MCP
+  // are asked in their own client.
+  if (cls === "person")
+    return wait("tool", `${tool.name} makes something public: a person decides`);
+  if ((principal.skill?.approval ?? []).includes(tool.name))
+    return wait("skill", `${tool.name} requires approval`);
+  // RFC-0008 §10.3: scheduled publishing follows ADR-0015's publish rules. `bypass` (local only)
+  // lets it through; `auto` may skip the person for a low-risk release inside the window, which
+  // the server decides from the release; every other mode, and people over MCP, wait.
+  if (cls === "publish") {
+    if (mode === "bypass") return { kind: "allow", ...o.limited };
+    return {
+      kind: "approval-required",
+      reason: `${tool.name} makes content public or removes it at a time: a person approves it`,
+      cause: mode === "manual" ? "manual-mode" : "tool",
+      ...(mode === "auto" ? { autoApprove: "low-risk-release"          } : {}),
+      ...o.limited,
+    };
+  }
+  // Labels are notes people read before deciding: free in `manual` (a waiting label would be the
+  // person's own work); reductions wait there.
+  if (cls === "reduce" && mode === "manual")
+    return wait("manual-mode", `manual mode: ${tool.name} needs a person's approval`);
+  return { kind: "allow", ...o.limited };
+}
+
+/**
+ * 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 function defaultScopes(actor       )          {
+  switch (actor.kind) {
+    case "human":
+    case "system":
+      return ["*"];
+    case "agent":
+      return [
+        "site:read",
+        "content:read",
+        "content:write",
+        "preview:create",
+        "asset:upload",
+        "analytics:read",
+        // RFC-0007 D2: agents read comments (never an email or IP hash).
+        "comments:read",
+        // RFC-0008 §10.1: agents read the schedule.
+        "schedules:read",
+      ];
+  }
+}

package/dist/src/roles.d.ts

@@ -0,0 +1,110 @@
+/**
+ * Staff roles (RFC-0005 §2, ADR-0018): named sets of the policy engine's scopes, so people and
+ * agents stay one kind of actor and an agent key never does more than the person who created it.
+ * This module is the single source for the policy engine, REST, MCP and Studio (via `/api/instance`).
+ */
+import { type AgentMode } from "./modes.js";
+import { type Scope } from "./policy.js";
+export type Role = "owner" | "administrator" | "editor" | "author" | "contributor";
+/** Highest rank first: Owner > Administrator > Editor > Author > Contributor. */
+export declare const ROLES: readonly Role[];
+export declare function isRole(value: unknown): value is Role;
+/** Higher is more senior. */
+export declare function rank(role: Role): number;
+/**
+ * Role → scopes (RFC-0005 §2.1). Implied scopes are not repeated. The Owner holds `*`, so a future
+ * scope reaches the Owner without a migration; Administrator holds every non-wildcard scope.
+ */
+export declare const ROLE_SCOPES: Readonly<Record<Role, readonly Scope[]>>;
+export declare function roleScopes(role: Role): Scope[];
+/**
+ * The most autonomous mode a key created by this role may hold (RFC-0005 §5.2): a Contributor has
+ * no publish power, so `auto` would be meaningless. `bypass` stays local only.
+ */
+export declare function modeCap(role: Role): AgentMode;
+export declare const MODE_CAPS: Readonly<Record<Role, AgentMode>>;
+/** `mode`, lowered to `cap` when it is more autonomous. */
+export declare function clampMode(mode: AgentMode, cap: AgentMode): AgentMode;
+/** Remote modes a role's keys may hold, least autonomous first. */
+export declare function modesFor(role: Role): AgentMode[];
+/**
+ * Narrows a key's scopes to a role (RFC-0005 §5.1): keeps each key scope the role holds; else the
+ * strongest weaker variant the role holds; else drops it. Person-only scopes and `*` never survive
+ * on a key (I7).
+ *
+ * `narrow(["content:write","site:publish"], author)` → `["content:write:own","site:publish:own"]`.
+ */
+export declare function narrow(keyScopes: readonly string[], roleScopeSet: readonly Scope[]): Scope[];
+/** Scopes a key requested that the role cannot give it (after narrowing nothing is dropped). */
+export declare function scopesAboveRole(requested: readonly Scope[], role: Role): Scope[];
+/** Why a member action breaks the rank rule (RFC-0005 §3, I4, I12), as data. */
+export type RankProblem = "self" | "owner_role" | "target_is_owner" | "role_too_high" | "not_allowed";
+export declare function describeRankProblem(problem: RankProblem): string;
+/** May `inviter` invite someone as `role`? Editors invite Contributors and Authors only (†). */
+export declare function inviteProblem(inviter: Role, role: Role): RankProblem | undefined;
+export declare function canInvite(inviter: Role, role: Role): boolean;
+/** Roles `inviter` may invite, highest first. */
+export declare function invitableRoles(inviter: Role): Role[];
+export interface MemberRef {
+    userId: string;
+    role: Role;
+}
+/** May `actor` change `target`'s role to `to`? */
+export declare function roleChangeProblem(actor: MemberRef, target: MemberRef, to: Role): RankProblem | undefined;
+/** May `actor` remove `target`? */
+export declare function removalProblem(actor: MemberRef, target: MemberRef): RankProblem | undefined;
+/**
+ * What a person can do, for UI gating (RFC-0005 I16: cosmetic; the server decides). Each ability
+ * is a scope check except `ownership.transfer` (Owner only).
+ */
+export declare const ABILITIES: {
+    readonly "entries.create": "content:draft:own";
+    readonly "entries.editOwnPublished": "content:write:own";
+    readonly "entries.editAny": "content:write";
+    readonly "pages.write": "content:write";
+    readonly "publish.own": "site:publish:own";
+    readonly "publish.any": "site:publish";
+    readonly rollback: "site:rollback";
+    readonly "structure.write": "site:write";
+    readonly "assets.upload": "asset:upload";
+    readonly "assets.manage": "asset:manage";
+    readonly "activity.all": "audit:read";
+    readonly "settings.write": "site:settings";
+    readonly "members.invite": "members:invite";
+    readonly "members.manage": "members:manage";
+    readonly "agents.manage": "agents:manage";
+    readonly "sites.create": "site:create";
+    readonly "analytics.read": "analytics:read";
+    readonly "analytics.settings": "site:settings";
+    readonly "comments.read": "comments:read";
+    readonly "comments.moderate": "comments:moderate:own";
+    readonly "comments.moderateAny": "comments:moderate";
+    readonly "comments.reply": "comments:reply:own";
+    readonly "comments.replyAny": "comments:reply";
+    readonly "commenters.data": "commenters:data";
+    readonly "comments.settings": "site:settings";
+    readonly "schedules.read": "schedules:read";
+    readonly "schedules.write": "schedules:write:own";
+    readonly "schedules.writeAny": "schedules:write";
+    readonly "releases.approve": "releases:publish:own";
+    readonly "releases.approveAny": "releases:publish";
+    readonly "automations.manage": "automations:manage";
+    readonly "schedules.settings": "site:settings";
+    readonly "ai.invoke": "ai:invoke";
+    readonly "ai.settings": "site:settings";
+    readonly "ownership.transfer": "owner";
+};
+export type Ability = keyof typeof ABILITIES;
+/** The ability map for a person (`role` undefined: no membership source, everything allowed). */
+export declare function abilities(role: Role | undefined, scopes: readonly Scope[]): Record<Ability, boolean>;
+/** Invite expiry (RFC-0005 §7.1): 7 days by default, 1 hour to 14 days, Administrator ≤ 72 h. */
+export declare const INVITE_DEFAULT_HOURS: number;
+export declare const INVITE_MIN_HOURS = 1;
+export declare const INVITE_MAX_HOURS: number;
+export declare const INVITE_ADMIN_MAX_HOURS = 72;
+/** The longest an invite for `role` may last. */
+export declare function inviteMaxHours(role: Role): number;
+/** Why an expiry is refused for an invite as `role`, or undefined. */
+export declare function inviteExpiryProblem(role: Role, hours: number): string | undefined;
+/** The default expiry for an invite as `role` (Administrator invites are capped). */
+export declare function inviteDefaultHours(role: Role): number;