@ory/argus 0.2.1 → 0.3.0

package/dist/client.js

@@ -38,6 +38,11 @@ class OryAgentClient {
             traceFile: config.traceFile,
             ...(config.exporter ? { exporter: config.exporter } : {}),
         });
+        // Every span — including direct `tracer.record(...)` calls from
+        // plugin handlers — gets userSubject / agentSubject merged in, so
+        // tool.invoke / tool.block / permission.observe_deny spans carry
+        // the same principal attribution as the API-call spans.
+        this.tracer.setAttributeEnricher(() => this.principalSpanAttributes());
         // Seed agent principal from the constructor `apiKey` so existing
         // call sites keep working until they migrate to ensureAgentIdentity.
         if (config.apiKey)

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 export { OryAgentClient, type OryAgentConfig, type PrincipalIdentity, } from "./client.js";
 export { DebugLogger, redactLogData, type LogEntry, type LogLevel, } from "./logger.js";
-export { Tracer, ActiveSpan, deriveTraceId, formatSpan, watchTraceFile, type TraceEvent, type SpanStatus, type TraceSpan, type SpanOptions, type TracerOptions, type TracerContext, } from "./tracer.js";
+export { Tracer, ActiveSpan, deriveTraceId, formatSpan, watchTraceFile, type TraceEvent, type SpanStatus, type TraceSpan, type SpanOptions, type TracerOptions, type TracerContext, type SpanAttributeEnricher, } from "./tracer.js";
 export { loadConfig, saveConfig, resolveConfig, mutateConfig, getConfigPath, getDataDir, getHarnessDataDir, type OryPluginConfig, type OryOAuth2Tokens, type OryUserCredentials, type OryAgentCredentialsBlock, type OryAgentDynamicCredentials, type PermissionMode, } from "./config.js";
 export { pkceLogin, refreshAccessToken, detectHeadless, generateCodeVerifier, sha256Base64Url, buildAuthorizeUrl, LOOPBACK_PORTS, DEFAULT_LOGIN_TIMEOUT_MS, type PkceLoginOptions, type PkceLoginOutcome, type PkceDeclineReason, } from "./auth.js";
 export { loadTokens, saveTokens, clearTokens, isExpired, refreshAndSave, tryAcquirePkceFlightLock, clearPkceFlightLock, waitForPeerTokens, waitForPeerTokensSync, TOKEN_EXPIRY_SKEW_SEC, type PkceFlightLock, } from "./auth-store.js";
@@ -14,7 +14,7 @@ export { runDevLauncher, type DevLauncherConfig, type InstallContext, } from "./
 export { renderOrySkills, renderOryCommands, commandToSkill, commandToToml, commandToFrontmatterMarkdown, commandToPlainMarkdown, toSkillMarkdown, writeSkillTree, removeSkillDirs, ORY_SKILL_NAMES, ORY_COMMAND_SKILL_NAMES, ORY_COMMAND_SLUGS, type RenderedSkill, type RenderedCommand, type RenderProfileOptions, } from "./skills.js";
 export { runLocalCommand, ensureDevJaeger, stopDevJaeger, DEV_JAEGER_CONTAINER, type EnsureDevJaegerResult, type StopDevJaegerResult, } from "./local/index.js";
 export { runRegistryCommand } from "./registry/index.js";
-export { checkAndDecide, applyPermissionMode, type PermissionDecision, type ModeDecision, type CheckAndDecideOptions, type ApplyPermissionModeContext, } from "./permissions.js";
+export { checkAndDecide, applyPermissionMode, type PermissionDecision, type ModeDecision, type DecisionSpanAttributes, type CheckAndDecideOptions, type ApplyPermissionModeContext, } from "./permissions.js";
 export { HARNESS_TOOL_CATALOG, KNOWN_HARNESSES, ALL_TOOLS, getToolCatalog, type KnownHarness, } from "./tool-catalog.js";
 export { parseClaudeCodeMcpTool, parseGeminiMcpTool, parseMcpToolGeneric, checkMcpPermission, type McpToolIdentifier, type McpPermissionCheckOptions, type McpPermissionResult, } from "./mcp.js";
 export { resolveUserSubject, subjectLabel, type UserSubjectRef, } from "./subject.js";

package/dist/permissions.d.ts

@@ -23,22 +23,40 @@
 import type { OryAgentClient } from "./client.js";
 import { type PermissionMode } from "./config.js";
 import type { OryError, PermissionCheck, PermissionResult } from "./types.js";
+/**
+ * Attributes describing *what was checked* and *under which posture*.
+ * Plugins spread this onto their `tool.invoke` / `tool.block` spans 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`
+ * status=ok is ambiguous (observe pass-through? fail-open? bug?).
+ */
+export interface DecisionSpanAttributes {
+    permissionMode: PermissionMode;
+    /** Direct subject ID when the check used `subjectId`. */
+    subjectId?: string;
+    /** SubjectSet rendered as `<namespace>:<object>#<relation>` when used. */
+    subjectSet?: string;
+}
 export type PermissionDecision = {
     kind: "allow";
     result: PermissionResult;
     mode: PermissionMode;
+    spanAttributes: DecisionSpanAttributes;
 } | {
     kind: "deny";
     result: PermissionResult;
     mode: "enforce";
+    spanAttributes: DecisionSpanAttributes;
 } | {
     kind: "observe";
     result: PermissionResult;
     mode: "observe";
+    spanAttributes: DecisionSpanAttributes;
 } | {
     kind: "fail_open";
     error: OryError;
     mode: PermissionMode;
+    spanAttributes: DecisionSpanAttributes;
 };
 /**
  * The "what should the caller do?" half of a decision, independent of
@@ -49,12 +67,15 @@ export type PermissionDecision = {
 export type ModeDecision = {
     kind: "allow";
     mode: PermissionMode;
+    spanAttributes: DecisionSpanAttributes;
 } | {
     kind: "deny";
     mode: "enforce";
+    spanAttributes: DecisionSpanAttributes;
 } | {
     kind: "observe";
     mode: "observe";
+    spanAttributes: DecisionSpanAttributes;
 };
 export interface CheckAndDecideOptions {
     /**
@@ -81,6 +102,8 @@ export interface ApplyPermissionModeContext {
     relation?: string;
     /** Subject ID for the observe-deny log line, if available. */
     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>;
     /** Override the resolved mode (tests). */

package/dist/permissions.js

@@ -25,6 +25,22 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.applyPermissionMode = applyPermissionMode;
 exports.checkAndDecide = checkAndDecide;
 const config_js_1 = require("./config.js");
+function formatSubjectSet(set) {
+    if (!set)
+        return undefined;
+    return `${set.namespace}:${set.object}#${set.relation}`;
+}
+function buildDecisionAttributes(mode, subjectId, subjectSet) {
+    const set = formatSubjectSet(subjectSet);
+    // SubjectSet supersedes subjectId in the span (the printable label is
+    // derivable from it); avoid emitting both so consumers don't need to
+    // dedupe.
+    if (set)
+        return { permissionMode: mode, subjectSet: set };
+    if (subjectId)
+        return { permissionMode: mode, subjectId };
+    return { permissionMode: mode };
+}
 /**
  * Map an `allowed` boolean from any permission check (plain or MCP)
  * onto a {@link ModeDecision}. When `allowed === false` and the mode
@@ -34,14 +50,16 @@ const config_js_1 = require("./config.js");
  */
 function applyPermissionMode(client, allowed, context = {}) {
     const mode = context.modeOverride ?? (0, config_js_1.resolveConfig)().permissionMode;
+    const spanAttributes = buildDecisionAttributes(mode, context.subjectId, context.subjectSet);
     if (allowed)
-        return { kind: "allow", mode };
+        return { kind: "allow", mode, spanAttributes };
     if (mode === "observe") {
         client.logger.warn("permission.observe_deny", {
             namespace: context.namespace,
             object: context.object,
             relation: context.relation,
             subjectId: context.subjectId,
+            subjectSet: spanAttributes.subjectSet,
             note: "denied by Ory; allowed by plugin in observe mode",
         });
         client.tracer.record("permission.observe_deny", "denied", {
@@ -49,13 +67,13 @@ function applyPermissionMode(client, allowed, context = {}) {
                 namespace: context.namespace,
                 object: context.object,
                 relation: context.relation,
-                mode,
+                ...spanAttributes,
                 ...context.spanAttributes,
             },
         });
-        return { kind: "observe", mode: "observe" };
+        return { kind: "observe", mode: "observe", spanAttributes };
     }
-    return { kind: "deny", mode: "enforce" };
+    return { kind: "deny", mode: "enforce", spanAttributes };
 }
 /**
  * Run a permission check and resolve the configured mode against the
@@ -64,6 +82,7 @@ function applyPermissionMode(client, allowed, context = {}) {
  */
 async function checkAndDecide(client, check, opts = {}) {
     const mode = opts.modeOverride ?? (0, config_js_1.resolveConfig)().permissionMode;
+    const spanAttributes = buildDecisionAttributes(mode, check.subjectId, check.subjectSet);
     let result;
     try {
         result = await client.checkPermission(check, {
@@ -71,19 +90,20 @@ async function checkAndDecide(client, check, opts = {}) {
         });
     }
     catch (err) {
-        return { kind: "fail_open", error: err, mode };
+        return { kind: "fail_open", error: err, mode, spanAttributes };
     }
     const inner = applyPermissionMode(client, result.allowed, {
         namespace: check.namespace,
         object: check.object,
         relation: check.relation,
         subjectId: check.subjectId,
+        subjectSet: check.subjectSet,
         spanAttributes: opts.spanAttributes,
         modeOverride: opts.modeOverride,
     });
     if (inner.kind === "allow")
-        return { kind: "allow", result, mode: inner.mode };
+        return { kind: "allow", result, mode: inner.mode, spanAttributes: inner.spanAttributes };
     if (inner.kind === "observe")
-        return { kind: "observe", result, mode: "observe" };
-    return { kind: "deny", result, mode: "enforce" };
+        return { kind: "observe", result, mode: "observe", spanAttributes: inner.spanAttributes };
+    return { kind: "deny", result, mode: "enforce", spanAttributes: inner.spanAttributes };
 }

package/dist/tracer.d.ts

@@ -99,6 +99,14 @@ export interface ProcessMetadata {
     gitBranch?: string;
     gitCommit?: string;
 }
+/**
+ * Returns a record of attributes to merge into every span's attribute
+ * bag at span-end. Used by `OryAgentClient` to inject the current
+ * `userSubject` / `agentSubject` onto every span without each handler
+ * having to remember to attach them. Must not throw and should be cheap;
+ * it is invoked on every span.
+ */
+export type SpanAttributeEnricher = () => Record<string, unknown> | undefined;
 export declare class Tracer extends EventEmitter {
     readonly harness: string;
     readonly processMetadata: ProcessMetadata;
@@ -106,6 +114,7 @@ export declare class Tracer extends EventEmitter {
     private readonly _spans;
     private _context;
     private _exporter;
+    private _enricher;
     constructor(opts: TracerOptions);
     /** Backwards-compatible accessors for the most common metadata fields. */
     get hostname(): string;
@@ -135,6 +144,15 @@ export declare class Tracer extends EventEmitter {
      */
     setExporter(exporter: SpanExporter | null): void;
     get exporter(): SpanExporter | null;
+    /**
+     * Install (or replace) an attribute enricher. The enricher is invoked
+     * on every span at end-time and its return value is merged into the
+     * span's attributes (with caller-supplied attributes taking precedence).
+     * Pass `null` to clear.
+     */
+    setAttributeEnricher(enricher: SpanAttributeEnricher | null): void;
+    /** @internal — invoked by `ActiveSpan.end()`. Never throws. */
+    _callEnricher(): Record<string, unknown> | undefined;
     /**
      * Flush any pending exports. Call before the host process exits so
      * the OTLP HTTP request has a chance to complete.

package/dist/tracer.js

@@ -98,8 +98,12 @@ class ActiveSpan {
         }
         this._ended = true;
         const durationMs = Math.round(performance.now() - this.startMs);
-        const merged = this.baseAttributes || attributes
-            ? { ...this.baseAttributes, ...attributes }
+        // Pull enricher attributes (e.g. userSubject / agentSubject from the
+        // client's principals) at span-end so every span gets them, including
+        // direct `tracer.record(...)` calls from plugin handlers.
+        const enriched = this.tracer._callEnricher();
+        const merged = enriched || this.baseAttributes || attributes
+            ? { ...enriched, ...this.baseAttributes, ...attributes }
             : undefined;
         const meta = this.tracer.processMetadata;
         const span = {
@@ -137,6 +141,7 @@ class Tracer extends node_events_1.EventEmitter {
     _spans = [];
     _context = {};
     _exporter;
+    _enricher = null;
     constructor(opts) {
         super();
         this.harness = opts.harness;
@@ -212,6 +217,30 @@ class Tracer extends node_events_1.EventEmitter {
     get exporter() {
         return this._exporter;
     }
+    /**
+     * Install (or replace) an attribute enricher. The enricher is invoked
+     * on every span at end-time and its return value is merged into the
+     * span's attributes (with caller-supplied attributes taking precedence).
+     * Pass `null` to clear.
+     */
+    setAttributeEnricher(enricher) {
+        this._enricher = enricher;
+    }
+    /** @internal — invoked by `ActiveSpan.end()`. Never throws. */
+    _callEnricher() {
+        if (!this._enricher)
+            return undefined;
+        try {
+            const out = this._enricher();
+            if (!out || Object.keys(out).length === 0)
+                return undefined;
+            return out;
+        }
+        catch {
+            // Enricher contract: never throw. Swallow defensively.
+            return undefined;
+        }
+    }
     /**
      * Flush any pending exports. Call before the host process exits so
      * the OTLP HTTP request has a chance to complete.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ory/argus",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "Ory Argus: the core API for building authentication, authorization, and audit into AI agent harness plugins, extensions, and custom integrations",
   "license": "Apache-2.0",
   "homepage": "https://ory.com",