failproofai 1.0.1 → 1.0.2-beta.0

package/.next/standalone/fp-cloud-cli/fp_cli/permissions.py

@@ -0,0 +1,208 @@
+"""Permission catalogue (mirrors the server ``Permission`` enum + dashboard presets).
+
+Used to validate ``--permission`` / ``--add`` / ``--remove`` / ``--preset`` values
+client-side so a typo is a clean usage error instead of a server 422. Kept in sync
+with ``server/src/auth.rs`` (``Permission::all``) and
+``dashboard/lib/permissionGroups.ts`` (presets).
+"""
+
+from __future__ import annotations
+
+import re
+from typing import List
+
+# The full assignable permission set, in the server's declared order.
+ALL_PERMISSIONS: List[str] = [
+    "events:add",
+    "events:read",
+    "keys:create",
+    "keys:read",
+    "keys:disable",
+    "keys:regenerate",
+    "keys:update",
+    "users:create",
+    "users:read",
+    "users:update",
+    "users:delete",
+    "evaluations:read",
+    "evaluations:trigger",
+    "dashboards:read",
+    "dashboards:write",
+    "dashboards:delete",
+    "queries:read",
+    "queries:write",
+    "queries:delete",
+    "queries:run",
+    "agent:use",
+    "settings:read",
+    "settings:write",
+    "alerts:read",
+    "alerts:write",
+    "issues:read",
+    "issues:create",
+    "issues:close",
+    "audits:read",
+    "audits:write",
+    "policies:read",
+    "policies:write",
+    "policies:pull",
+    "usage:read",
+    "orgs:admin",
+]
+
+# Retired spellings. `incidents:*` was renamed to `issues:*`; the server still
+# PARSES the old tokens forever (see Permission::from_str) so keys minted before
+# the rename keep working. Accept them here too and normalize, or a script that
+# has passed `--add incidents:read` for a year would start exiting 2 against a
+# server that would happily have honoured it.
+#
+# `incidents:ack` gated ack + comment + assign + subscribe + resolve, which now
+# span all three issues permissions — so it expands to all three rather than
+# mapping to any one, matching expand_implied() on the server.
+RETIRED_PERMISSION_ALIASES = {
+    "incidents:read": ["issues:read"],
+    "incidents:write": ["issues:create"],
+    "incidents:ack": ["issues:read", "issues:create", "issues:close"],
+    "alerts:ack": ["issues:read", "issues:create", "issues:close"],
+}
+
+
+def normalize_permissions(perms: List[str]) -> List[str]:
+    """Expand retired spellings to their current equivalents, order-preserving."""
+    out: List[str] = []
+    for p in perms:
+        for mapped in RETIRED_PERMISSION_ALIASES.get(p, [p]):
+            if mapped not in out:
+                out.append(mapped)
+    return out
+
+# orgs:admin is an instance-level grant, not assignable to an org API key or member
+# through these commands; exclude it from what the CLI lets you grant.
+ASSIGNABLE_PERMISSIONS: List[str] = [p for p in ALL_PERMISSIONS if p != "orgs:admin"]
+
+_READ_ONLY = [p for p in ALL_PERMISSIONS if p.endswith(":read")]
+# Must match BUILTIN_PERMISSION_SETS["standard"] in server/src/ch_tenancy.rs and
+# STANDARD_PERMS in dashboard/lib/permissionGroups.ts. `issues:read` arrives via
+# _READ_ONLY (it ends in ":read"); create + close are added explicitly. Close is
+# included because the retired `incidents:ack` this replaces already granted
+# resolve — see migration 20260721000000.
+_STANDARD = _READ_ONLY + [
+    "evaluations:trigger",
+    "queries:run",
+    "issues:create",
+    "issues:close",
+    "agent:use",
+]
+
+# Builtin permission-set presets (dashboard/lib/permissionGroups.ts).
+PRESETS = {
+    "read-only": list(_READ_ONLY),
+    "standard": list(_STANDARD),
+    "admin": list(ASSIGNABLE_PERMISSIONS),
+    "clear": [],
+}
+
+_ASSIGNABLE_SET = frozenset(ASSIGNABLE_PERMISSIONS)
+
+# Permissions that parse + are user-assignable but must NEVER sit on an API key — the server's
+# `Permission::key_assignable` rejects them (422). `orgs:admin` is already excluded above;
+# `keys:update` is human-only (a bearer key can create keys but never edit them). The key flows
+# strip these from a permission-set seed (silently, like the dashboard's keyAssignableOnly-strip)
+# and reject them from an explicit `--add` (so the user gets a clean message, not a server 422).
+KEY_NON_ASSIGNABLE = frozenset({"orgs:admin", "keys:update"})
+KEY_ASSIGNABLE_PERMISSIONS: List[str] = [p for p in ASSIGNABLE_PERMISSIONS if p not in KEY_NON_ASSIGNABLE]
+
+
+def unknown_permissions(perms: List[str]) -> List[str]:
+    """Return any tokens that are not assignable permissions (empty if all valid).
+
+    Retired spellings count as VALID. The server parses them (aliasing to the
+    current names), so rejecting them here would make the CLI stricter than the
+    API it fronts — a script that has passed `--add incidents:read` for a year
+    would start failing with exit 2 against a server that would have accepted it.
+    The returned values are already normalized — `parse_permission_tokens` and
+    `parse_key_permission_tokens` apply `normalize_permissions` themselves.
+    """
+    return [
+        p
+        for p in perms
+        if p not in _ASSIGNABLE_SET and p not in RETIRED_PERMISSION_ALIASES
+    ]
+
+
+def key_assignable_only(perms) -> List[str]:
+    """Drop the human-only permissions (`keys:update` / `orgs:admin`) from a permission list —
+    used when SEEDING a key from a permission set, mirroring the dashboard's keyAssignableOnly
+    strip. Order-preserving."""
+    return [p for p in perms if p not in KEY_NON_ASSIGNABLE]
+
+
+def parse_key_permission_tokens(tokens, *, require_nonempty: bool = True) -> List[str]:
+    """Like :func:`parse_permission_tokens`, but for an API KEY — additionally rejects the
+    human-only permissions (`keys:update` / `orgs:admin`) with a clear message, so an explicit
+    `--add keys:update` fails client-side (exit 2) instead of hitting a server 422."""
+    flat = parse_permission_tokens(tokens, require_nonempty=require_nonempty)
+    forbidden = [p for p in flat if p in KEY_NON_ASSIGNABLE]
+    if forbidden:
+        raise PermissionTokenError(
+            f'{", ".join(sorted(set(forbidden)))} can\'t be granted to an API key — it\'s human-only'
+        )
+    return flat
+
+
+def expand_preset(name: str) -> List[str]:
+    """Return the permissions for a builtin preset, or raise KeyError."""
+    return list(PRESETS[name])
+
+
+class PermissionTokenError(Exception):
+    """A malformed or unknown compact ``slug:act.act`` permission token (carries a
+    user-facing message). Shared by ``keys`` and ``users`` so both surfaces parse the
+    compact token format identically."""
+
+
+def parse_permission_tokens(tokens, *, require_nonempty: bool = True) -> List[str]:
+    """Expand the compact ``slug:act1.act2`` permission tokens into a de-duplicated flat
+    assignable permission list (``events:read.add`` → ``events:read``, ``events:add``). Tokens
+    separated by **whitespace or commas** within one value AND repeated flags all compose — so
+    ``-p "a b"``, ``--add a,b``, and ``--add a --add b`` are equivalent. Raises
+    :class:`PermissionTokenError` on a malformed token or an unknown permission, and — when
+    ``require_nonempty`` — on an empty set (``users`` ``--add``/``--remove`` may be empty, so
+    they call the helper only when a value is supplied)."""
+    flat: List[str] = []
+    seen: set = set()
+    for raw in tokens or []:
+        for tok in re.split(r"[\s,]+", str(raw).strip()):  # whitespace- or comma-separated
+            if not tok:
+                continue  # stray empties from `a,,b` / whitespace-only input
+            if ":" not in tok:
+                raise PermissionTokenError(f'bad permission "{tok}" — expected slug:action (e.g. events:read.add)')
+            slug, _, actions_str = tok.partition(":")
+            slug = slug.strip()
+            actions = [a.strip() for a in actions_str.split(".")]
+            if not slug or not actions_str.strip() or any(not a for a in actions):
+                raise PermissionTokenError(f'bad permission "{tok}" — no action after \':\' (e.g. {slug or "events"}:read.add)')
+            for a in actions:
+                perm = f"{slug}:{a}"
+                if perm not in seen:
+                    seen.add(perm)
+                    flat.append(perm)
+    if not flat:
+        if require_nonempty:
+            raise PermissionTokenError("at least one permission is required (e.g. events:read.add)")
+        return flat
+    unknown = unknown_permissions(flat)
+    if unknown:
+        raise PermissionTokenError(f'unknown permission(s): {", ".join(unknown)}')
+    # Expand the retired spellings HERE, at the one boundary every caller goes
+    # through. `unknown_permissions` deliberately accepts `incidents:*` and
+    # `alerts:ack` so a script that has passed them for a year keeps working —
+    # but `normalize_permissions`, the function that turns them into current
+    # names, had ZERO call sites in the package. So the raw token was carried
+    # all the way into `users update`'s diff, where `predicted_after =
+    # (before | add) - remove` subtracted a string that is not in the server's
+    # set: `--remove incidents:ack` computed no change at all, took the no-op
+    # branch, and exited 0 reporting `{"removed": []}` without ever calling the
+    # server — while the member kept every issues permission. The command's own
+    # help gives `--remove alerts:read,incidents:ack` as a worked example.
+    return normalize_permissions(flat)

package/.next/standalone/fp-cloud-cli/fp_cli/policy_check.py

@@ -0,0 +1,290 @@
+"""Check a policy before it reaches a fleet.
+
+Nothing between an author and a machine validates policy source today. The CLI
+rejects a NUL byte, the server checks the id charset and a 1 MiB ceiling — and
+neither looks at whether the file is parseable JavaScript at all. So this
+publishes, deploys, and reaches every machine in the fleet:
+
+    echo 'this is not javascript {{{' | fp policies publish broken
+
+It then fails at enforcement time, on the machine, where nobody is watching.
+That is the worst available place for a syntax error to surface, which is what
+these two checks exist to move.
+
+``check_syntax`` is the cheap one and runs before every publish. ``run_policy``
+is the deliberate one behind ``fp policies test``: it actually executes the
+policy against a context you describe, so an author — human or agent — can see
+allow/deny/instruct before anyone's machine does.
+
+Both shell out to ``node``. Neither makes it a hard dependency: a machine
+without node still publishes, with a stated reason rather than a silent skip.
+"""
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import subprocess
+import re
+import tempfile
+from dataclasses import dataclass
+from typing import Any, Dict, List, Optional
+
+#: Budget for EXECUTING a policy. Short on purpose: a policy with an accidental
+#: infinite loop must fail the command instead of hanging it, and a policy that
+#: cannot decide in five seconds cannot sit on a hook either. This is a product
+#: statement about hook latency, so it stays tight.
+_TIMEOUT_SECS = 5
+
+#: Budget for PARSING one — `node --check`, which runs no user code at all.
+#:
+#: Separate from the number above because the reasoning above does not apply to
+#: it: parsing is bounded work whose only real variable is how long a cold node
+#: process takes to start, and that is a property of the machine, not of the
+#: policy. Sharing the execution budget made the syntax check fail on a busy
+#: runner and report `the syntax check timed out` — which reads as "your policy
+#: is bad" for what is actually "this box was loaded". Seen on CI once the
+#: fp-cloud-cli matrix widened to four concurrent interpreters: three legs passed and
+#: the fourth timed out on the same source.
+#:
+#: Generous rather than tight, because nothing here can loop: if `node --check`
+#: has not answered in thirty seconds, node is wedged and saying so is right.
+_SYNTAX_TIMEOUT_SECS = 30
+
+#: SGR escapes node emits around its stack frames.
+_ANSI = re.compile(r"\x1b\[[0-9;]*m")
+
+
+def node_available() -> bool:
+    return shutil.which("node") is not None
+
+
+@dataclass
+class SyntaxResult:
+    ok: bool
+    #: None when the check could not run at all (no node). Distinct from `ok`,
+    #: because "we did not look" must never render as "we looked and it passed".
+    checked: bool
+    message: str = ""
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {"ok": self.ok, "checked": self.checked, "message": self.message}
+
+
+def check_syntax(source: str) -> SyntaxResult:
+    """Parse-check policy source with ``node --check``.
+
+    Written to a ``.mjs`` file so node parses it as a module: policies are ESM
+    (`import { deny } from "failproofai"`), and checking that as a script would
+    reject every real policy for using `import`.
+    """
+    if not node_available():
+        return SyntaxResult(
+            ok=True, checked=False,
+            message="node was not found on PATH, so the policy was not syntax-checked",
+        )
+    with tempfile.TemporaryDirectory() as tmp:
+        path = os.path.join(tmp, "policy.mjs")
+        with open(path, "w", encoding="utf-8") as fh:
+            fh.write(source)
+        try:
+            proc = subprocess.run(
+                ["node", "--check", path],
+                capture_output=True, text=True, timeout=_SYNTAX_TIMEOUT_SECS,
+            )
+        except subprocess.TimeoutExpired:
+            # `checked=False`, not `ok=False`. A timeout here says nothing about
+            # the SOURCE — `node --check` runs none of it — so reporting a syntax
+            # failure blamed the user's policy for the machine being busy, and
+            # `fp policies publish` refused a perfectly good file. "We could not
+            # look" is the honest verdict, and it is the one `SyntaxResult`
+            # already models: the same shape as node being absent entirely.
+            return SyntaxResult(
+                ok=True, checked=False,
+                message=(
+                    f"the syntax check did not finish within {_SYNTAX_TIMEOUT_SECS}s, "
+                    "so the source was not checked"
+                ),
+            )
+        except OSError as exc:
+            return SyntaxResult(ok=True, checked=False,
+                                message=f"could not run node ({exc}); source not checked")
+    if proc.returncode == 0:
+        return SyntaxResult(ok=True, checked=True)
+    # node prints the offending line, a caret, the SyntaxError — and then its own
+    # internal stack and version banner. The first three are the whole value of
+    # the check; the rest is node talking about itself inside an error box about
+    # the user's policy.
+    raw = (proc.stderr or proc.stdout or "").strip().replace(path, "<policy>")
+    # node colourises its stack frames, so the marker lines arrive with ANSI
+    # prefixes and a plain startswith() sails straight past them. Strip escapes
+    # before matching, and from the kept text too — this is going inside a box
+    # the CLI is already styling.
+    raw = _ANSI.sub("", raw)
+    keep = []
+    for line in raw.splitlines():
+        stripped = line.strip()
+        if stripped.startswith("at ") or stripped.startswith("Node.js v"):
+            break
+        keep.append(line)
+    detail = "\n".join(keep).strip() or raw
+    return SyntaxResult(ok=False, checked=True, message=detail)
+
+
+#: A stand-in for the `failproofai` package a policy imports. Policies are
+#: authored against the real one; this provides the same three helpers and
+#: collects what `customPolicies.add` registers, so a policy can be executed
+#: without installing anything.
+_SHIM = """\
+export const allow = (reason) => reason ? { decision: "allow", reason } : { decision: "allow" };
+export const deny = (reason) => ({ decision: "deny", reason });
+export const instruct = (reason) => ({ decision: "instruct", reason });
+export const registered = [];
+export const customPolicies = { add: (p) => { registered.push(p); } };
+export default { allow, deny, instruct, customPolicies };
+"""
+
+_RUNNER = """\
+import { registered } from "failproofai";
+import "./policy.mjs";
+
+const ctx = JSON.parse(process.argv[2]);
+const out = [];
+for (const p of registered) {
+  // The SAME filter the engine applies before it ever calls `fn`
+  // (`src/hooks/policy-registry.ts`): a policy whose `match` does not cover this
+  // event or this tool is never RUN on a real machine, so running it here and
+  // folding its verdict into the overall decision reported a DENY the daemon
+  // would never have produced. `--event`/`--tool` only shaped the synthetic ctx;
+  // they did not gate registration. A `match: { events: ["PostToolUse"],
+  // toolNames: ["Write"] }` policy printed a red DENY under the default
+  // `--event PreToolUse`, and `--expect deny` passed in CI, while the machine
+  // allowed the command.
+  const m = p.match ?? {};
+  const evs = m.events ?? [];
+  const tools = m.toolNames ?? [];
+  if (evs.length > 0 && !evs.includes(ctx.eventType)) {
+    out.push({ name: p.name ?? "(unnamed)", description: p.description ?? null,
+               decision: "skipped", reason: `match.events does not include ${ctx.eventType}` });
+    continue;
+  }
+  if (tools.length > 0 && (!ctx.toolName || !tools.includes(ctx.toolName))) {
+    out.push({ name: p.name ?? "(unnamed)", description: p.description ?? null,
+               decision: "skipped", reason: `match.toolNames does not include ${ctx.toolName ?? "(none)"}` });
+    continue;
+  }
+  try {
+    const r = await p.fn(ctx);
+    out.push({ name: p.name ?? "(unnamed)", description: p.description ?? null,
+               decision: r?.decision ?? "allow", reason: r?.reason ?? null });
+  } catch (e) {
+    out.push({ name: p.name ?? "(unnamed)", error: String(e && e.message || e) });
+  }
+}
+process.stdout.write(JSON.stringify({ policies: out }));
+"""
+
+
+@dataclass
+class PolicyRun:
+    ok: bool
+    results: List[Dict[str, Any]]
+    error: str = ""
+
+    @property
+    def decision(self) -> str:
+        """The strictest decision any policy returned.
+
+        deny beats instruct beats allow, because that is how a fleet of policies
+        composes: one refusal is a refusal regardless of what the others said.
+        """
+        decisions = [r.get("decision") for r in self.results if "decision" in r]
+        for level in ("deny", "instruct"):
+            if level in decisions:
+                return level
+        return "allow"
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {"ok": self.ok, "decision": self.decision,
+                "policies": self.results, "error": self.error}
+
+
+def run_policy(
+    source: str,
+    *,
+    tool: str = "Bash",
+    command: Optional[str] = None,
+    file_path: Optional[str] = None,
+    event: str = "PreToolUse",
+    tool_input: Optional[Dict[str, Any]] = None,
+) -> PolicyRun:
+    """Execute a policy against one synthetic context and report each verdict.
+
+    Runs in a temp directory with the shim beside it, so the policy's
+    `import ... from "failproofai"` resolves without a node_modules anywhere.
+    Nothing is installed and nothing outside the temp directory is written.
+
+    This is a DRY RUN, not the enforcement path: it proves the policy parses,
+    registers, and returns a decision for the input described. It cannot prove
+    the daemon will feed it the same context.
+    """
+    if not node_available():
+        return PolicyRun(ok=False, results=[],
+                         error="node was not found on PATH, so the policy could not be run")
+
+    payload: Dict[str, Any] = dict(tool_input or {})
+    if command is not None:
+        payload.setdefault("command", command)
+    if file_path is not None:
+        payload.setdefault("file_path", file_path)
+    ctx = {"eventType": event, "toolName": tool, "toolInput": payload, "payload": payload}
+
+    with tempfile.TemporaryDirectory() as tmp:
+        # The shim goes in `node_modules/failproofai/` rather than beside the
+        # policy, so the bare specifier a real policy writes —
+        # `import { deny } from "failproofai"` — resolves by node's ordinary
+        # lookup. The policy under test is then byte-identical to the one that
+        # gets published; an import map would have meant testing a rewritten
+        # file, and import-map support also varies by node version.
+        pkg = os.path.join(tmp, "node_modules", "failproofai")
+        os.makedirs(pkg)
+        with open(os.path.join(pkg, "package.json"), "w", encoding="utf-8") as fh:
+            fh.write(json.dumps({"name": "failproofai", "version": "0.0.0",
+                                 "type": "module", "main": "index.mjs",
+                                 "exports": "./index.mjs"}))
+        with open(os.path.join(pkg, "index.mjs"), "w", encoding="utf-8") as fh:
+            fh.write(_SHIM)
+        for name, body in (("policy.mjs", source), ("run.mjs", _RUNNER)):
+            with open(os.path.join(tmp, name), "w", encoding="utf-8") as fh:
+                fh.write(body)
+        with open(os.path.join(tmp, "package.json"), "w", encoding="utf-8") as fh:
+            fh.write(json.dumps({"type": "module"}))
+        try:
+            proc = subprocess.run(
+                ["node", "run.mjs", json.dumps(ctx)],
+                cwd=tmp, capture_output=True, text=True, timeout=_TIMEOUT_SECS,
+            )
+        except subprocess.TimeoutExpired:
+            return PolicyRun(ok=False, results=[],
+                             error=f"the policy did not finish within {_TIMEOUT_SECS}s")
+        except OSError as exc:
+            return PolicyRun(ok=False, results=[], error=f"could not run node: {exc}")
+
+    if proc.returncode != 0:
+        detail = (proc.stderr or proc.stdout or "").strip().splitlines()
+        return PolicyRun(ok=False, results=[],
+                         error="\n".join(detail[:6]) or "the policy failed to run")
+    try:
+        data = json.loads(proc.stdout or "{}")
+    except json.JSONDecodeError:
+        return PolicyRun(ok=False, results=[], error="the policy produced no readable result")
+
+    results = data.get("policies") or []
+    if not results:
+        return PolicyRun(
+            ok=False, results=[],
+            error=("the file registered no policies — a policy calls "
+                   "`customPolicies.add({...})`; check it does, and that the call runs "
+                   "at import time"),
+        )
+    return PolicyRun(ok=True, results=results)