@ory/argus 0.14.0 → 1.0.0

package/dist/permissions.d.ts

@@ -8,7 +8,7 @@
  *
  *   1. Runs the check.
  *   2. On a Keto deny (`result.allowed === false`), applies the mode:
- *        - `observe` — record a `permission.observe_deny` audit span,
+ *        - `observe` — record a `permission.observe_deny` audit event,
  *          return `{ kind: "observe", … }` so the caller allows the
  *          tool through.
  *        - `enforce` — return `{ kind: "deny", … }` so the caller blocks.
@@ -30,14 +30,38 @@
 import type { OryAgentClient } from "./client.js";
 import { type PermissionMode } from "./config.js";
 import type { OryError, OryErrorCode, PermissionCheck, PermissionResult } from "./types.js";
+/**
+ * Why a permission check came back denied, once the block-aware OPL schema is
+ * in play:
+ *
+ *   - `not_granted` — the subject simply has no `use` grant on the object
+ *     (the legacy "deny by absence" case).
+ *   - `explicit_block` — a `blocked` relation matched the subject, so the
+ *     `access` permit's deny-override fired even if a `use` grant exists.
+ *
+ * Threaded onto the decision's activity attributes and into the observe-mode
+ * audit event so "explicitly blocked" is distinguishable from "never granted"
+ * in activity logs, mirroring how `checkRejected` distinguishes an auth-rejected
+ * deny.
+ */
+export type BlockReason = "not_granted" | "explicit_block";
+/**
+ * Map the logical grant relation a caller passes (`use`) onto the relation or
+ * permit Argus actually checks. A `use` check always routes through the
+ * block-aware `access` permit (`use && !blocked`), so an explicit block is
+ * always respected — the permission model must therefore be applied to the
+ * project (done in the Ory Console, Agent Security) for checks to resolve. Any
+ * other relation passes through unchanged.
+ */
+export declare function resolveCheckRelation(relation: string): string;
 /**
  * Attributes describing *what was checked* and *under which posture*.
- * Plugins spread this onto their `tool.invoke` / `tool.block` spans so
+ * Plugins spread this onto their `tool.invoke` / `tool.block` activity events so
  * the audit trail makes the observe-vs-enforce posture and the checked
- * subject visible at a glance — without that, a span with `allowed=false`
+ * subject visible at a glance — without that, an event with `allowed=false`
  * status=ok is ambiguous (observe pass-through? fail-open? bug?).
  */
-export interface DecisionSpanAttributes {
+export interface DecisionActivityAttributes {
     permissionMode: PermissionMode;
     /** Direct subject ID when the check used `subjectId`. */
     subjectId?: string;
@@ -50,27 +74,62 @@ export interface DecisionSpanAttributes {
      * distinguishable from a normal Keto deny in the audit trail.
      */
     checkRejected?: OryErrorCode;
+    /**
+     * Shell decomposition (issue #76): the specific denied command word that
+     * caused a `Bash` deny (`curl`), so denial text and `tool.block` events name
+     * it. {@link shellDeniedWords} carries the full set when more than one.
+     */
+    shellWord?: string;
+    shellDeniedWords?: string[];
+    /**
+     * The parsed decomposition, attached to activity so the shell breakdown is
+     * observable in real time: every command word extracted, and how many. These
+     * are binary/builtin *names* only — the **raw** command is NEVER placed in a
+     * activity event; it goes only to the local debug log, gated by
+     * `ORY_AGENT_DEBUG`.
+     */
+    shellWords?: string[];
+    shellCommandCount?: number;
+    /**
+     * Set when a shell command could not be safely parsed (dynamic name /
+     * unparseable) and enforce mode denied it, or observe logged it.
+     */
+    shellTooComplex?: true;
+    /**
+     * Set on a deny: whether the deny was an explicit block or a plain missing
+     * grant. See {@link BlockReason}.
+     */
+    blockReason?: BlockReason;
+    /**
+     * The machine principal an explicit block matched — the exact subject string
+     * (`Agent:<clientId>|<session>`, …), so the audit trail names the relation an
+     * admin would go edit. Set whenever a principal block fired, including on a
+     * deny the user's own check had already produced.
+     */
+    blockedPrincipal?: string;
+    /** Which level of the identity model the block was written at. */
+    blockedPrincipalLevel?: string;
 }
 export type PermissionDecision = {
     kind: "allow";
     result: PermissionResult;
     mode: PermissionMode;
-    spanAttributes: DecisionSpanAttributes;
+    activityAttributes: DecisionActivityAttributes;
 } | {
     kind: "deny";
     result: PermissionResult;
     mode: "enforce";
-    spanAttributes: DecisionSpanAttributes;
+    activityAttributes: DecisionActivityAttributes;
 } | {
     kind: "observe";
     result: PermissionResult;
     mode: "observe";
-    spanAttributes: DecisionSpanAttributes;
+    activityAttributes: DecisionActivityAttributes;
 } | {
     kind: "fail_open";
     error: OryError;
     mode: PermissionMode;
-    spanAttributes: DecisionSpanAttributes;
+    activityAttributes: DecisionActivityAttributes;
 };
 /**
  * The "what should the caller do?" half of a decision, independent of
@@ -81,23 +140,23 @@ export type PermissionDecision = {
 export type ModeDecision = {
     kind: "allow";
     mode: PermissionMode;
-    spanAttributes: DecisionSpanAttributes;
+    activityAttributes: DecisionActivityAttributes;
 } | {
     kind: "deny";
     mode: "enforce";
-    spanAttributes: DecisionSpanAttributes;
+    activityAttributes: DecisionActivityAttributes;
 } | {
     kind: "observe";
     mode: "observe";
-    spanAttributes: DecisionSpanAttributes;
+    activityAttributes: DecisionActivityAttributes;
 };
 export interface CheckAndDecideOptions {
     /**
-     * Span attributes merged into the underlying `permission.check` span
-     * and into the synthetic `permission.observe_deny` span when emitted.
+     * Activity attributes merged into the underlying `permission.check` event
+     * and into the synthetic `permission.observe_deny` event when emitted.
      * Same shape and semantics as `client.checkPermission`'s option.
      */
-    spanAttributes?: Record<string, unknown>;
+    activityAttributes?: Record<string, unknown>;
     /**
      * Override the resolved {@link PermissionMode}. Tests use this to
      * exercise both branches without mutating env or config state.
@@ -107,7 +166,7 @@ export interface CheckAndDecideOptions {
 export interface ApplyPermissionModeContext {
     /**
      * Namespace / object / relation that produced the `allowed` boolean.
-     * Logged on observe-deny and attached to the audit span. All optional
+     * Logged on observe-deny and attached to the audit event. All optional
      * — the helper still works without them, but populated values make
      * the audit trail searchable.
      */
@@ -118,37 +177,44 @@ export interface ApplyPermissionModeContext {
     subjectId?: string;
     /** SubjectSet for the observe-deny log line, if available. */
     subjectSet?: PermissionCheck["subjectSet"];
-    /** Attributes merged into the `permission.observe_deny` span. */
-    spanAttributes?: Record<string, unknown>;
+    /** Attributes merged into the `permission.observe_deny` activity event. */
+    activityAttributes?: Record<string, unknown>;
     /** Override the resolved mode (tests). */
     modeOverride?: PermissionMode;
+    /**
+     * Why the check denied, when known (block-aware schema path). When
+     * `explicit_block`, observe mode records a distinct `permission.block_observed`
+     * audit event instead of the generic `permission.observe_deny`, and the
+     * reason is attached to the decision activity attributes in every mode.
+     */
+    blockReason?: BlockReason;
 }
 /**
  * Map an `allowed` boolean from any permission check (plain or MCP)
  * onto a {@link ModeDecision}. When `allowed === false` and the mode
- * is `observe`, emits the `permission.observe_deny` audit span and
+ * is `observe`, emits the `permission.observe_deny` audit event and
  * returns `{ kind: "observe" }` so the caller knows to let the action
  * proceed despite the deny.
  */
 export declare function applyPermissionMode(client: OryAgentClient, allowed: boolean, context?: ApplyPermissionModeContext): ModeDecision;
 /**
- * Outcome of {@link gateToolCall}. Either Ory is disabled entirely
- * (`config.auditOnly` kill switch), the tool is a user-interaction
- * primitive (`AskUserQuestion`, `ExitPlanMode`, `TodoWrite`, …) and we
- * pass through with a single audit span, or it's a real tool execution
- * and the caller gets the standard {@link PermissionDecision}.
+ * Outcome of {@link gateToolCall}. Either Agent Security isn't connected so no
+ * check runs, the tool is a user-interaction primitive (`AskUserQuestion`,
+ * `ExitPlanMode`, `TodoWrite`, …) and we pass through with one audit event,
+ * or it's a real tool execution and the caller gets the standard
+ * {@link PermissionDecision}.
  */
 export type ToolGateOutcome = {
-    kind: "audit_only";
-    /** Attributes to attach to the caller's pass-through trace, if any. */
-    spanAttributes: {
-        auditOnly: true;
+    kind: "not_connected";
+    /** Attributes to attach to the caller's pass-through activity, if any. */
+    activityAttributes: {
+        securityConnected: false;
         toolName: string;
     };
 } | {
     kind: "interactive";
-    /** Attributes to attach to the caller's pass-through trace, if any. */
-    spanAttributes: {
+    /** Attributes to attach to the caller's pass-through activity, if any. */
+    activityAttributes: {
         interactive: true;
         toolName: string;
     };
@@ -161,18 +227,33 @@ export interface GateToolCallArgs {
     /** Permission check to run when the tool is a real execution. */
     check: PermissionCheck;
     /**
-     * Attributes merged into the permission span (real path) and the
-     * `user.interaction` span (interactive path).
+     * Attributes merged into permission activity (real path) and the
+     * `user.interaction` event (interactive path).
      */
-    spanAttributes?: Record<string, unknown>;
+    activityAttributes?: Record<string, unknown>;
     /** Override the resolved {@link PermissionMode}. Tests use this. */
     modeOverride?: PermissionMode;
+    /**
+     * Raw shell command string when {@link toolName} is the harness's shell tool
+     * (issue #76). When present and the tool is a shell tool, the gate decomposes
+     * the command into `ShellTool:<word>#use` sub-checks in addition to the
+     * top-level tool check. Absent / undefined ⇒ decomposition is skipped and the
+     * gate behaves exactly as before.
+     */
+    shellCommand?: string;
+    /**
+     * The acting machine principals, so an explicit block on the agent install,
+     * this session, the sub-agent kind, or this spawn can deny the call. Omitted ⇒
+     * only the agent principal already on the client is considered (there is no
+     * sub-agent context to check).
+     */
+    principals?: PrincipalBlockSubjects;
 }
 /**
- * Single entry point for the pre-tool-use gate. Applies the
- * `config.auditOnly` kill switch first — when set, Ory is disabled
- * entirely and the caller gets `{ kind: "audit_only" }` back without any
- * permission check (record the invocation as an audit span and proceed).
+ * Single entry point for the pre-tool-use gate. Checks whether Agent Security
+ * is connected first — with no project URL there is
+ * nothing to check against, so the caller gets `{ kind: "not_connected" }`
+ * back and should record the invocation as an audit event and proceed.
  * Otherwise splits the harness's incoming "tool" into two semantic
  * categories:
  *
@@ -182,7 +263,7 @@ export interface GateToolCallArgs {
  *     through Ory: the user is the decision-maker, and blocking them in
  *     enforce mode (or logging a misleading observe-deny) hides the very
  *     prompt the user needs to see. We record one `user.interaction`
- *     audit span and return — no permission check, no `tool.invoke`,
+ *     audit event and return — no permission check, no `tool.invoke`,
  *     no `tool.block`.
  *
  *   - **Execution** — every other tool. Delegates to
@@ -194,11 +275,40 @@ export interface GateToolCallArgs {
  * semantics; the new `interactive` kind means "do nothing else."
  */
 export declare function gateToolCall(client: OryAgentClient, args: GateToolCallArgs): Promise<ToolGateOutcome>;
+/**
+ * Gate a shell tool by decomposing its command into the program/builtin words
+ * that will run and checking each as `ShellTool:<word>#use`, on top of the
+ * existing top-level tool check.
+ *
+ * Aggregation: **any deny → deny** (naming the offending word); else any observe
+ * → observe (pass through, per-word `permission.observe_deny` events recorded);
+ * else allow. A too-complex / unparseable command is **fail-closed** in enforce
+ * (deny + alert) and logged-then-passed in observe. A parser-unavailable or
+ * infrastructure error is **fail-open** (top-level decision only) — availability
+ * must not hinge on the parser.
+ */
+export declare function decomposeAndCheck(client: OryAgentClient, args: GateToolCallArgs): Promise<PermissionDecision>;
 /**
  * Run a permission check and resolve the configured mode against the
  * result. Never throws — infrastructure errors surface as a typed
  * `{ kind: "fail_open" }` decision, and auth-rejected check calls in
  * enforce mode as `{ kind: "deny" }` (see
- * {@link CHECK_AUTH_REJECTED_CODES}).
+ * {@link CHECK_UNTRUSTED_CODES}).
  */
 export declare function checkAndDecide(client: OryAgentClient, check: PermissionCheck, opts?: CheckAndDecideOptions): Promise<PermissionDecision>;
+/**
+ * The acting machine principals for a tool call, as the subjects a `blocked`
+ * relation can name. Built by the caller (a harness handler knows whether it is
+ * in a sub-agent and what its type/spawn id are) and threaded into
+ * {@link gateToolCall}.
+ */
+export interface PrincipalBlockSubjects {
+    /** Sub-agent client id, when this call runs inside a sub-agent. */
+    subAgentClientId?: string;
+    /** Sub-agent type, required for the spawn-level subject to be built. */
+    subAgentType?: string;
+    /** Per-spawn id, on the harnesses that expose one. */
+    perSpawnId?: string;
+    /** Override the session; defaults to the client's ambient session. */
+    sessionId?: string;
+}