agentlock-shared 0.2.0 → 0.3.0

package/dist/policy.d.ts

@@ -1,10 +1,180 @@
-import type { PolicyRules, AgentActionRequest, PolicyEvaluationResult } from './types.js';
+import type { PolicyRules, AgentActionRequest, PolicyEvaluationResult, PolicyDecision, ActionType } from './types.js';
+/** Returns the more restrictive of two categories. */
+export declare function maxCategory(a: ActionType, b: ActionType): ActionType;
+/**
+ * Derive the minimum (floor) category for a given tool + payload, independent
+ * of what the agent declared. See comment above for rationale.
+ *
+ * Returns `undefined` when no opinion — caller treats that as "trust declared".
+ */
+export declare function getCategoryFloor(tool: string, payload: Record<string, unknown>): ActionType;
 export declare const DEFAULT_POLICY_RULES: PolicyRules;
-export declare function evaluatePolicy(action: AgentActionRequest, rules: PolicyRules): PolicyEvaluationResult;
-export declare function buildActionPreview(action: AgentActionRequest): {
+export declare function compileSshPattern(raw: string): RegExp;
+/**
+ * Compile a user-supplied Claude Code Bash pattern into a RegExp.
+ *
+ * Same semantics as the SSH `commandRules` evaluator (single source of
+ * truth — `compileSshPattern`), so admins only learn one pattern dialect.
+ * Default: full-string match with `*` and `?` as glob wildcards.
+ *
+ *  - `grep`        → exact match only ("grep" with no args)
+ *  - `grep *`      → grep followed by a space and any args
+ *  - `grep /home/*`→ grep with args starting with `/home/`
+ *  - `^git push`   → starts-with-regex (regex hint chars trigger raw mode)
+ *  - `/.../`       → fully raw regex (escape hatch for advanced cases)
+ *
+ * The exact-by-default behaviour is the safer choice: forgetting the `*`
+ * means your rule is narrower than expected, not wider.
+ */
+export declare const compileClaudeBashPattern: typeof compileSshPattern;
+export interface ClaudeBashEvalOutcome {
+    decision: PolicyDecision;
+    reason: string;
+    matchedPattern: string;
+    /**
+     * Per-rule two-person approval flag, copied from the matched rule. The
+     * routing endpoint forwards this to the gateway so the resulting
+     * approval_request inherits it instead of falling back to the
+     * surrounding `permission.claude_code` rule's flag. `undefined` means
+     * the rule didn't set it — caller falls back to the matched_rule's
+     * own value.
+     */
+    require_two_approvals?: boolean;
+    /**
+     * Per-rule approver allowlist, copied from the matched rule. Same
+     * fallback semantics as `require_two_approvals`. Empty/undefined ⇒ no
+     * per-rule restriction.
+     */
+    allowed_approvers?: string[];
+}
+/**
+ * Optional context the routing endpoint passes to
+ * {@link evaluateClaudeBashRules}. Currently only used to surface the
+ * shell-metachar safety gate's classification context in audit/log output;
+ * no admin-class auto-escalation is performed because the editor's linter
+ * already warns admins about high-risk ALLOWs and an explicit ALLOW must
+ * be honoured.
+ */
+export interface ClaudeBashEvalOptions {
+    /**
+     * What the hardcoded pattern classifier (the one in the routing endpoint)
+     * thinks this command is. Currently informational — kept on the option
+     * type so the gateway can pass it without conditional plumbing and so a
+     * future auditing/logging change can surface it without another schema
+     * bump.
+     */
+    hardcodedActionType?: ActionType;
+    /**
+     * Workspace's high-risk auto-approval opt-in. Retained on the type for
+     * compatibility with existing callers; no longer consulted by the Bash
+     * rule evaluator (admin-class auto-escalation has been removed — see the
+     * docstring on {@link evaluateClaudeBashRules}).
+     */
+    allowHighRiskAutoApproval?: {
+        admin?: boolean;
+        financial?: boolean;
+    };
+}
+/**
+ * Evaluate a Bash command against the workspace's user-defined Claude Code
+ * rules. Returns the first matching rule's outcome, or — when no rule
+ * matches — the policy's `defaultDecision`. Returns `null` to signal "no
+ * opinion" (caller should fall back to the hardcoded classifier) when the
+ * rules block is undefined or the rules array is empty AND no
+ * `defaultDecision` is set.
+ *
+ * Rules are evaluated in order; the FIRST match wins. ReDoS-suspect
+ * patterns and patterns that fail to compile are silently skipped (the
+ * Zod schema rejects them at save time, but we re-check at evaluation
+ * to stay safe against rules that pre-date the validation).
+ *
+ * Safety gates (only applied to ALLOW outcomes — BLOCK and
+ * REQUIRE_APPROVAL are always honoured as written so admins keep the
+ * ability to stop a command unconditionally):
+ *
+ * 1. **Shell-meta escalation** — if the command contains shell-control
+ *    chars (`;`, `&&`, `||`, `|`, `` ` ``, `$()`, `>`, `<`) and the
+ *    matched pattern is a literal prefix (not `/.../`), the rule is
+ *    escalated to `REQUIRE_APPROVAL`. Keeps `ALLOW: git status` from
+ *    silently approving `git status; rm -rf /` — the admin almost
+ *    certainly didn't mean to grant an arbitrary suffix.
+ *
+ * Admin-class commands (`rm -rf`, `git push`, `kubectl apply`, …) are
+ * NOT auto-escalated. If an admin writes `ALLOW: git push *`, the rule
+ * fires as written. The policy editor's linter still flags such ALLOWs
+ * as a recommendation to double-check, but runtime respects the explicit
+ * intent — silent escalation surprised users more than it protected them.
+ */
+export declare function evaluateClaudeBashRules(command: string, rules: NonNullable<PolicyRules['claudeBash']> | undefined | null, options?: ClaudeBashEvalOptions): ClaudeBashEvalOutcome | null;
+/**
+ * Options for {@link evaluatePolicy}. Kept narrow — most callers pass none.
+ */
+export interface EvaluatePolicyOptions {
+    /**
+     * When true, skip the server-side category floor and use the agent's
+     * self-declared `action_type` as-is. Set by the gateway when the agent
+     * record has `trust_declared_action_type = true`.
+     *
+     * DANGER: Only enable for fully trusted agents with a narrow allowed_tools
+     * list. A compromised agent with this flag set can downgrade any request
+     * (including stripe.charge, admin.delete_user) to `read` and bypass the
+     * financial/admin safety rails.
+     */
+    skipCategoryFloor?: boolean;
+    /**
+     * When true, signals that the caller has already verified an active
+     * `browser_sessions` row matching the request's `session_id`. The blanket
+     * "Browser actions require an active session" BLOCK for `browser.*`
+     * (non-`browser.open`) is then skipped so the request falls through to
+     * per-tool rule matching — allowing admins to BLOCK specific browser tools
+     * (e.g. `browser.fill_credentials`) from a policy without those rules being
+     * shadowed by the catch-all.
+     *
+     * Only set this when the session has been validated against the DB by a
+     * trusted caller (the gateway), not from unverified client input.
+     */
+    hasActiveSession?: boolean;
+}
+export declare function evaluatePolicy(action: AgentActionRequest, rules: PolicyRules, options?: EvaluatePolicyOptions): PolicyEvaluationResult;
+export declare function buildActionPreview(action: AgentActionRequest, effectiveActionType?: ActionType): {
     summary: string;
     target?: string;
     impact?: string;
     cost_estimate?: number;
+    declared_action_type?: ActionType;
+    effective_action_type?: ActionType;
+    command?: string;
+    claude_tool?: string;
 };
+/**
+ * Suggest a Claude Code Bash policy pattern from a raw command string. Used
+ * by the "Approve and remember" affordance in the approval UI to pre-fill
+ * the rule-creation form with a sensible default; admins can edit the
+ * suggestion before submitting.
+ *
+ * Heuristic (in order):
+ *  - Empty / whitespace-only → empty string (UI handles this).
+ *  - Quoted segments (`"..."`, `'...'`) are removed before tokenising so
+ *    `git commit -m "fix bug"` → tokens `[git, commit, -m]`, not five
+ *    fragmented strings.
+ *  - Single token → `<token>` (exact match for that bare command).
+ *  - Two tokens, second is a flag (`-x`, `--long`) → `<first> *`.
+ *  - Two tokens, second looks like a path (starts with `/`, `.`, `~`, `\\`)
+ *    → `<first> *`. Pinning the path makes the rule too narrow; dropping
+ *    it makes nothing match. Falling back to `<first> *` is the safest
+ *    middle ground; the admin can tighten further if they want.
+ *  - Two+ tokens, second is non-flag → `<first> <second> *` (typical
+ *    subcommand form: `git push *`, `kubectl apply *`).
+ *
+ * The output is always a glob the routing endpoint understands. Admins
+ * can switch to a regex via `/.../` if they need finer control.
+ */
+export declare function suggestClaudeBashPattern(command: string): string;
+/** Return the vpnCredentialId matching `host`, or `undefined` if no route
+ *  matches (or `host`/`routes` is missing/empty). */
+export declare function resolveVpnRoute(host: string | undefined | null, routes: PolicyRules['vpnRoutes']): string | undefined;
+/** Parse a URL string and return its hostname in lowercase, or `undefined`
+ *  if the input isn't a parseable URL. Used by the runner to extract the
+ *  routing key for http.request / browser.open actions. */
+export declare function hostnameFromUrl(url: string | undefined | null): string | undefined;
 //# sourceMappingURL=policy.d.ts.map

package/dist/policy.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"policy.d.ts","sourceRoot":"","sources":["../src/policy.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,WAAW,EACX,kBAAkB,EAClB,sBAAsB,EAGvB,MAAM,YAAY,CAAC;AAUpB,eAAO,MAAM,oBAAoB,EAAE,WAiBlC,CAAC;AASF,wBAAgB,cAAc,CAC5B,MAAM,EAAE,kBAAkB,EAC1B,KAAK,EAAE,WAAW,GACjB,sBAAsB,CAsHxB;AAED,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,kBAAkB,GAAG;IAC9D,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB,CA6CA"}
+{"version":3,"file":"policy.d.ts","sourceRoot":"","sources":["../src/policy.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,WAAW,EACX,kBAAkB,EAClB,sBAAsB,EAEtB,cAAc,EACd,UAAU,EACX,MAAM,YAAY,CAAC;AA+BpB,sDAAsD;AACtD,wBAAgB,WAAW,CAAC,CAAC,EAAE,UAAU,EAAE,CAAC,EAAE,UAAU,GAAG,UAAU,CAEpE;AAuED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC/B,UAAU,CAqDZ;AAED,eAAO,MAAM,oBAAoB,EAAE,WA2ClC,CAAC;AAqBF,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAarD;AAQD;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,wBAAwB,0BAAoB,CAAC;AAE1D,MAAM,WAAW,qBAAqB;IACpC,QAAQ,EAAE,cAAc,CAAC;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,cAAc,EAAE,MAAM,CAAC;IACvB;;;;;;;OAOG;IACH,qBAAqB,CAAC,EAAE,OAAO,CAAC;IAChC;;;;OAIG;IACH,iBAAiB,CAAC,EAAE,MAAM,EAAE,CAAC;CAC9B;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,qBAAqB;IACpC;;;;;;OAMG;IACH,mBAAmB,CAAC,EAAE,UAAU,CAAC;IACjC;;;;;OAKG;IACH,yBAAyB,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAC;QAAC,SAAS,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC;CACtE;AAiCD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,WAAW,CAAC,WAAW,CAAC,YAAY,CAAC,CAAC,GAAG,SAAS,GAAG,IAAI,EAChE,OAAO,GAAE,qBAA0B,GAClC,qBAAqB,GAAG,IAAI,CA6G9B;AA2CD;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC;;;;;;;;;OASG;IACH,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B;;;;;;;;;;;OAWG;IACH,gBAAgB,CAAC,EAAE,OAAO,CAAC;CAC5B;AAED,wBAAgB,cAAc,CAC5B,MAAM,EAAE,kBAAkB,EAC1B,KAAK,EAAE,WAAW,EAClB,OAAO,GAAE,qBAA0B,GAClC,sBAAsB,CAmXxB;AAED,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,kBAAkB,EAC1B,mBAAmB,CAAC,EAAE,UAAU,GAC/B;IACD,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,oBAAoB,CAAC,EAAE,UAAU,CAAC;IAClC,qBAAqB,CAAC,EAAE,UAAU,CAAC;IACnC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB,CAwIA;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAkBhE;AAqBD;qDACqD;AACrD,wBAAgB,eAAe,CAC7B,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,EAC/B,MAAM,EAAE,WAAW,CAAC,WAAW,CAAC,GAC/B,MAAM,GAAG,SAAS,CAqBpB;AAED;;2DAE2D;AAC3D,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,GAAG,MAAM,GAAG,SAAS,CAOlF"}