@ory/argus 0.14.0 → 1.0.1

package/dist/status-data.js

@@ -34,6 +34,7 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.probePermissionsCoverage = probePermissionsCoverage;
+exports.resolveDynamicName = resolveDynamicName;
 exports.collectStatusReport = collectStatusReport;
 /**
  * Structured status data — the data-gathering half of the `status` command,
@@ -48,23 +49,34 @@ exports.collectStatusReport = collectStatusReport;
  * implementation.
  */
 const config_js_1 = require("./config.js");
+const permission_mode_js_1 = require("./permission-mode.js");
+const permissions_js_1 = require("./permissions.js");
 const auth_store_js_1 = require("./auth-store.js");
 const agent_auth_js_1 = require("./agent-auth.js");
-const client_js_1 = require("./client.js");
 const subject_js_1 = require("./subject.js");
+const client_js_1 = require("./client.js");
+const subject_js_2 = require("./subject.js");
 const branding_js_1 = require("./branding.js");
+const auth_js_1 = require("./auth.js");
+const node_os_1 = require("node:os");
 const tool_catalog_js_1 = require("./tool-catalog.js");
+const opl_js_1 = require("./opl.js");
 const fs = __importStar(require("node:fs"));
 // Additive dashboard section: core Ory service health (see status-system.ts).
 const status_system_js_1 = require("./status-system.js");
 function resolveNamespace() {
-    return process.env.ORY_PERMISSION_NAMESPACE ?? "AgentTools";
+    return process.env.ORY_PERMISSION_NAMESPACE ?? "AgentTool";
 }
 /**
  * Probe the harness's built-in tool catalog against Ory, returning how many
- * tools the resolved user subject is allowed / denied / errored on. Returns
- * undefined when a probe can't run (no project URL, empty catalog, no user
- * identity). Never throws.
+ * tools the resolved user subject is allowed / denied / errored on, plus the
+ * live permission mode and the subject that was checked. Returns undefined when
+ * a probe can't run (no project URL, empty catalog, no user identity). Never
+ * throws.
+ *
+ * Checks route through {@link resolveCheckRelation}, i.e. the `access` permit —
+ * the same relation the runtime gate evaluates — so a tool carrying an explicit
+ * block is reported as denied here too, exactly as a tool call would be.
  */
 async function probePermissionsCoverage(harness) {
     const resolved = (0, config_js_1.resolveConfig)();
@@ -85,16 +97,30 @@ async function probePermissionsCoverage(harness) {
     await (0, agent_auth_js_1.ensureAgentIdentity)(client, { projectUrl: resolved.projectUrl }).catch(() => {
         /* best-effort; the probe still runs with whatever credentials we have */
     });
-    const subject = (0, subject_js_1.resolveUserSubject)(client);
-    if ((0, subject_js_1.subjectLabel)(subject) === "agent:unknown")
+    const subject = (0, subject_js_2.resolveUserSubject)(client);
+    const subjectId = (0, subject_js_2.subjectLabel)(subject);
+    if (subjectId === "agent:unknown")
         return undefined;
+    const agentSubject = (0, subject_js_2.resolveAgentSubject)(client);
+    const live = await (0, permission_mode_js_1.resolvePermissionMode)(client, subject, {
+        additionalSubjects: agentSubject ? [{ scope: "agent", subject: agentSubject }] : [],
+    });
     const namespace = resolveNamespace();
-    const result = { total: catalog.length, allowed: 0, denied: 0, errored: 0 };
+    const relation = (0, permissions_js_1.resolveCheckRelation)("users");
+    const result = {
+        total: catalog.length,
+        allowed: 0,
+        denied: 0,
+        errored: 0,
+        mode: live.mode,
+        modeSource: live.source,
+        subject: subjectId,
+    };
     for (const tool of catalog) {
-        const check = { namespace, object: tool, relation: "use", ...subject };
+        const check = { namespace, object: tool, relation, ...subject };
         try {
             const probe = await client.checkPermission(check, {
-                spanAttributes: { toolName: tool, source: "status_coverage" },
+                activityAttributes: { toolName: tool, source: "status_coverage" },
             });
             if (probe.allowed)
                 result.allowed++;
@@ -121,17 +147,18 @@ function collectConfig(harness) {
         projectIdSource: r.projectIdSource,
         projectName: r.projectName,
         workspaceName: r.workspaceName,
-        apiKeyConfigured: !!r.apiKey,
-        apiKeySource: r.apiKeySource,
         oauth2ClientId: r.oauth2ClientId,
         oauth2ClientIdSource: r.oauth2ClientIdSource,
-        oauth2ClientName: r.oauth2ClientId ? branding_js_1.USER_LOGIN_CLIENT_NAME : undefined,
-        auditOnly: r.auditOnly,
+        oauth2ClientName: (0, branding_js_1.isUserLoginClient)({ clientId: r.oauth2ClientId })
+            ? branding_js_1.USER_LOGIN_CLIENT_NAME
+            : undefined,
+        security: r.security,
         permissionMode: r.permissionMode,
         permissionModeSource: r.permissionModeSource,
         userSubjectNamespace: r.userSubjectNamespace,
         userSubjectNamespaceSource: r.userSubjectNamespaceSource,
         namespace: resolveNamespace(),
+        principalNamespaces: [...opl_js_1.PRINCIPAL_NAMESPACES],
         debugEnabled: process.env.ORY_AGENT_DEBUG === "true",
     };
 }
@@ -144,45 +171,98 @@ function collectUser() {
     return {
         tokenCache: (0, auth_store_js_1.isExpired)(tokens) ? "stale" : "present",
         subject: tokens.subject,
+        displayName: tokens.displayName ?? (0, auth_js_1.displayNameFromIdToken)(tokens.idToken),
         expiresInSeconds: tokens.expiresAt - nowSec,
         clientId: tokens.clientId,
     };
 }
-function collectAgent() {
-    if (process.env.ORY_AGENT_API_KEY) {
-        return { source: "static_api_key", subject: process.env.ORY_AGENT_SUBJECT_ID };
-    }
+/**
+ * Human-readable name for a DCR agent / sub-agent credential: the persisted
+ * `client_name` when present, else a best-effort reconstruction from the
+ * harness and (for sub-agents) type. Reconstruction uses the current hostname,
+ * which may differ from the registration host for credentials saved before the
+ * name was persisted — acceptable for a display-only label.
+ */
+function resolveDynamicName(creds, subAgentType, harness) {
+    return (creds.clientName ??
+        (0, branding_js_1.agentClientName)({
+            harness: creds.harness ?? harness,
+            host: (0, node_os_1.hostname)() || "unknown-host",
+            subAgentType,
+        }));
+}
+function collectAgent(harness, sessionKey) {
     if (process.env.ORY_AGENT_CLIENT_ID && process.env.ORY_AGENT_CLIENT_SECRET) {
         return {
             source: "static_client_credentials",
             clientId: process.env.ORY_AGENT_CLIENT_ID,
-            subject: process.env.ORY_AGENT_SUBJECT_ID ?? process.env.ORY_AGENT_CLIENT_ID,
+            subject: (0, subject_js_2.readAgentSubjectOverride)() ?? process.env.ORY_AGENT_CLIENT_ID,
         };
     }
-    const persisted = (0, agent_auth_js_1.loadAgentDynamicCredentials)();
-    if (!persisted)
+    const selected = sessionKey
+        ? (() => {
+            const credentials = (0, agent_auth_js_1.loadAgentDynamicCredentials)(harness, sessionKey);
+            return credentials ? { sessionKey, credentials } : undefined;
+        })()
+        : (0, agent_auth_js_1.latestAgentRegistration)(harness);
+    if (!selected)
         return { source: "unregistered" };
+    const { sessionKey: credentialSession, credentials: persisted } = selected;
     const resolved = (0, config_js_1.resolveConfig)();
     const mismatch = resolved.projectUrl && persisted.projectUrl !== resolved.projectUrl
         ? { registeredAgainst: persisted.projectUrl, current: resolved.projectUrl }
         : undefined;
+    const subject = (0, subject_js_2.readAgentSubjectOverride)() ?? persisted.clientId;
     return {
         source: "dcr",
+        name: resolveDynamicName(persisted, undefined, harness),
+        sessionKey: credentialSession,
+        ...(credentialSession === config_js_1.SESSIONLESS_KEY
+            ? {}
+            : { sessionSubject: `${subject_js_1.AGENT_NAMESPACE}:${subject}|${credentialSession}` }),
         clientId: persisted.clientId,
-        subject: process.env.ORY_AGENT_SUBJECT_ID ?? persisted.clientId,
+        subject,
         registeredAt: new Date(persisted.registeredAt * 1000).toISOString(),
         projectUrlMismatch: mismatch,
     };
 }
+function collectSubAgents(harness, requestedSession) {
+    const sessionKey = requestedSession
+        ?? (0, agent_auth_js_1.latestAgentRegistration)(harness)?.sessionKey
+        ?? (0, agent_auth_js_1.latestSubAgentSession)(harness);
+    const persisted = sessionKey ? (0, agent_auth_js_1.loadAllSubAgentDynamicCredentials)(harness, sessionKey) : {};
+    const resolved = (0, config_js_1.resolveConfig)();
+    return Object.entries(persisted)
+        .map(([subAgentType, creds]) => {
+        const mismatch = resolved.projectUrl && creds.projectUrl !== resolved.projectUrl
+            ? { registeredAgainst: creds.projectUrl, current: resolved.projectUrl }
+            : undefined;
+        return {
+            subAgentType,
+            name: resolveDynamicName(creds, subAgentType, harness),
+            clientId: creds.clientId,
+            subject: creds.clientId,
+            registeredAt: new Date(creds.registeredAt * 1000).toISOString(),
+            delegatedBy: creds.delegation?.delegatedBy,
+            projectUrlMismatch: mismatch,
+        };
+    })
+        .sort((a, b) => a.subAgentType.localeCompare(b.subAgentType));
+}
 async function collectPermissions(harness) {
     const resolved = (0, config_js_1.resolveConfig)();
     const namespace = resolveNamespace();
     const catalog = (0, tool_catalog_js_1.getToolCatalog)(harness);
-    const base = { mode: resolved.permissionMode, namespace };
-    if (resolved.auditOnly)
-        return { ...base, coverageStatus: "audit_only" };
-    if (!resolved.projectUrl)
-        return { ...base, coverageStatus: "no_project" };
+    // Falls back to the last-known cached mode on every path that can't reach the
+    // project to read it live.
+    const base = {
+        mode: resolved.permissionMode,
+        modeSource: resolved.permissionModeSource,
+        namespace,
+    };
+    // One reason covers both missing values: with either absent no check can run.
+    if (!resolved.security.connected)
+        return { ...base, coverageStatus: "not_connected" };
     if (catalog.length === 0) {
         return { ...base, coverageStatus: "no_catalog", knownHarnesses: [...tool_catalog_js_1.KNOWN_HARNESSES] };
     }
@@ -192,15 +272,17 @@ async function collectPermissions(harness) {
     const coverage = await probePermissionsCoverage(harness);
     if (!coverage)
         return { ...base, coverageStatus: "no_user" };
+    // The probe read the mode live; prefer it over the cached config value.
+    const withMode = { ...base, mode: coverage.mode, modeSource: coverage.modeSource };
     if (coverage.errored > 0 && coverage.allowed === 0 && coverage.denied === 0) {
-        return { ...base, coverageStatus: "probe_failed", coverage };
+        return { ...withMode, coverageStatus: "probe_failed", coverage };
     }
     const status = coverage.allowed === coverage.total
-        ? "bootstrapped"
+        ? "fully_granted"
         : coverage.allowed === 0
-            ? "not_bootstrapped"
+            ? "no_grants"
             : "partial";
-    return { ...base, coverageStatus: status, coverage };
+    return { ...withMode, coverageStatus: status, coverage };
 }
 function isUserTokenUsable() {
     const tokens = (0, auth_store_js_1.loadTokens)();
@@ -221,28 +303,29 @@ function readTail(file, limit) {
     return { file, count: lines.length, recent };
 }
 function collectActivity(harness) {
-    const trace = readTail((0, client_js_1.resolveTraceFilePath)(harness), 10);
     const log = readTail((0, client_js_1.resolveDebugLogPath)(harness), 10);
     return {
-        traceFile: trace.file,
-        traceCount: trace.count,
-        recentSpans: trace.recent,
         logFile: log.file,
         logCount: log.count,
-        recentLogs: log.recent,
+        recentEvents: log.recent,
     };
 }
 /**
  * Gather the full structured status report for a harness. The permissions
  * section runs a live network probe when a project URL and user identity are
  * available (same conditions as the text `status` command).
+ *
+ * `sessionKey` is the run being reported on, when the caller is inside one. The
+ * standalone CLI passes none, so the report selects the harness's newest stored
+ * session rather than inventing an ambient session.
  */
-async function collectStatusReport(harness) {
+async function collectStatusReport(harness, sessionKey) {
     return {
         harness,
         config: collectConfig(harness),
         user: collectUser(),
-        agent: collectAgent(),
+        agent: collectAgent(harness, sessionKey),
+        subAgents: collectSubAgents(harness, sessionKey),
         permissions: await collectPermissions(harness),
         activity: collectActivity(harness),
         system: await (0, status_system_js_1.collectSystemServices)(),

package/dist/subject.d.ts

@@ -1,24 +1,34 @@
 /**
  * User-subject resolution for permission checks.
  *
- * Permission checks need a subject reference that matches the form
- * stored in Keto. Two shapes are supported:
+ * Every principal — user, agent, sub-agent — is addressed as a **SubjectSet**
+ * `<namespace>:<object>` (e.g. `User:<UUID>`). This is the form the Ory Console's
+ * *Add relationship* dialog writes, the form the local-stack seed writes, and the
+ * Zanzibar-idiomatic composition point (grant `Role:developer` `use` on a tool and
+ * add principals to the role, rather than fanning out a tuple per subject). It is
+ * the only first-class subject form: Keto does no cross-form expansion, so a check
+ * must match the write shape exactly, and standardizing on one shape removes that
+ * silent-misfire footgun.
  *
- *   - **SubjectSet** — `<namespace>:<object>` (e.g. `User:<UUID>`). This
- *     is the form the Console's *Add relationship* dialog writes, so
- *     dev/demo flows that grant tuples through the UI use it.
- *
- *   - **Direct SubjectID** — opaque string (e.g. `user:<UUID>` or
- *     `session:<id>`). Backward-compatible default when no subject
- *     namespace is configured.
- *
- * The selection is driven by the user-subject namespace: `ORY_USER_SUBJECT_NAMESPACE`
- * takes precedence, then the client's configured `userSubjectNamespace` (persisted
- * in the shared config, e.g. by the local-stack install path). When a namespace is
- * present the resolver builds a SubjectSet using it; otherwise it falls back to the
- * direct SubjectID chain.
+ * The namespace is resolved by precedence: `ORY_USER_SUBJECT_NAMESPACE` (env) →
+ * the client's configured `userSubjectNamespace` (persisted in the shared config)
+ * → the {@link DEFAULT_USER_SUBJECT_NAMESPACE} (`User`). The env/config values now
+ * *override* the default namespace; they are no longer an opt-in switch that
+ * toggles between SubjectSet and a legacy direct SubjectID.
  */
 import type { OryAgentClient } from "./client.js";
+/**
+ * Default namespace a resolved user principal is addressed under. The
+ * local-stack seed, the Console *Add relationship* dialog, and the Network OPL
+ * provisioning all use `User`, so it is the out-of-the-box default.
+ */
+export declare const DEFAULT_USER_SUBJECT_NAMESPACE = "User";
+/** Namespace the agent principal is addressed under (delegation subjects). */
+export declare const AGENT_NAMESPACE = "Agent";
+/** Namespace a sub-agent principal is addressed under. */
+export declare const SUBAGENT_NAMESPACE = "SubAgent";
+/** Namespace the no-user-identity `session:<id>` fallback is addressed under. */
+export declare const SESSION_NAMESPACE = "Session";
 export type UserSubjectRef = {
     subjectId: string;
 } | {
@@ -33,7 +43,7 @@ export type UserSubjectRef = {
  * client's user principal and the env overrides in
  * {@link resolveUserSubject}. The override only applies within `fn`'s
  * async context, so concurrent calls cannot observe each other's subject.
- * `ORY_USER_SUBJECT_NAMESPACE` SubjectSet shaping still applies.
+ * SubjectSet shaping still applies.
  *
  * A missing/empty `subject` is a no-op: `fn` runs with the normal
  * resolution chain.
@@ -46,13 +56,109 @@ export declare function runWithUserSubject<T>(subject: string | undefined, fn: (
  * legacy `ORY_AGENT_SUBJECT_ID`, then the caller-supplied `fallback`
  * (typically `session:<id>`).
  *
- * Returns a SubjectSet when a user-subject namespace is configured (env or
- * client config) and a concrete subject is available; otherwise a direct
- * SubjectID.
+ * Always returns a SubjectSet. A resolved principal is addressed under the
+ * configured user namespace (`ORY_USER_SUBJECT_NAMESPACE` → client config →
+ * {@link DEFAULT_USER_SUBJECT_NAMESPACE}). A `session:`-prefixed fallback is
+ * addressed under {@link SESSION_NAMESPACE} (`Session:<id>`). Only when nothing
+ * resolves at all do we emit the direct `agent:unknown` sentinel — an error
+ * marker that must never match a stored tuple.
  */
 export declare function resolveUserSubject(client: OryAgentClient, fallback?: string): UserSubjectRef;
 /**
  * Printable label for a `UserSubjectRef`. Used in denial messages and
- * span attributes. SubjectSets render as `<namespace>:<object>`.
+ * activity attributes. SubjectSets render as `<namespace>:<object>`.
  */
 export declare function subjectLabel(ref: UserSubjectRef): string;
+/** Separator between the credential client id and narrower scoping axes. */
+export declare const SUBJECT_AXIS_SEPARATOR = "|";
+/** The env var that overrides the agent's subject. */
+export declare const AGENT_SUBJECT_ID_ENV_VAR = "ORY_AGENT_SUBJECT_ID";
+/**
+ * Validate a subject override (issue #241).
+ *
+ * `deriveSubject` above already refuses to produce a trailing separator,
+ * because a subject ending in `|` silently never matches a stored relation.
+ * The same care is owed to the *base* it joins onto, which arrives from an
+ * operator-settable env var and was previously used verbatim.
+ *
+ * A value containing the axis separator is rejected for two independent
+ * reasons:
+ *
+ * 1. **It collapses the identity grains.** The credential, session, and spawn
+ *    subjects are told apart only by separator position, so an override
+ *    containing one makes them ambiguous: `override="a|b"` in session `c` and
+ *    `override="a"` in session `b|c` produce the same string. A session-scoped
+ *    block written to stop one runaway run could then match the base credential, or a
+ *    different run — and all three grains are read together in one batched
+ *    check, so this is a live semantics break rather than a theoretical one.
+ * 2. **It forges a delegation-node reference** (#225). A join key is exactly
+ *    `<identity>|<harness>|<host>|<session>`, and the two string spaces stay
+ *    disjoint today only because a Hydra client id is a UUID and contains no
+ *    separator. This env var is the one supported knob that breaks that.
+ *
+ * Rejected rather than sanitized: silently stripping the separator would
+ * produce a *different* subject than the operator asked for, which fails just
+ * as confusingly and is harder to notice. Ignoring the value falls back to the
+ * client id — a real, working identity — and says so.
+ */
+export declare function validateSubjectOverride(raw: string | undefined, envVar?: string): {
+    value?: string;
+    warning?: string;
+};
+/**
+ * Read and validate `ORY_AGENT_SUBJECT_ID`. Returns `undefined` when unset or
+ * rejected, pushing an explanation onto `warnings` in the latter case.
+ *
+ * One reader for every site that consumes the override, so the rule cannot hold
+ * in the resolver and not in what `status` reports.
+ */
+export declare function readAgentSubjectOverride(env?: NodeJS.ProcessEnv, warnings?: string[]): string | undefined;
+/**
+ * The registered agent credential subject: `Agent:<clientId>`. For DCR this
+ * client belongs to one session; static credentials may be shared explicitly.
+ *
+ * `undefined` when no agent principal is populated — the agent gate never
+ * blocks, so a session with no resolved machine identity is normal and callers
+ * must treat a missing agent subject as "nothing to check", not as a deny.
+ */
+export declare function resolveAgentSubject(client: OryAgentClient): UserSubjectRef | undefined;
+/**
+ * The **session-level** agent subject: `Agent:<clientId>|<session>`, unique to
+ * one run. Used for a block that stops the session's narrower subject without
+ * blocking its base credential subject.
+ *
+ * `undefined` when there is no agent principal, and — deliberately — also when
+ * there is no session. A caller with no session concept (an SDK integration in
+ * a long-running service) has exactly one sessionless credential subject;
+ * inventing a placeholder session would either collapse every run onto
+ * one string or produce a subject no admin could have written.
+ */
+export declare function resolveAgentSessionSubject(client: OryAgentClient, sessionId?: string): UserSubjectRef | undefined;
+/**
+ * The registered sub-agent credential subject: `SubAgent:<clientId>` for one
+ * typed sub-agent in one session.
+ *
+ * `subAgentClientId` is the client id from {@link ensureSubAgentIdentity};
+ * `undefined` in, and `undefined` out, since a sub-agent whose identity did not
+ * resolve has nothing to check.
+ */
+export declare function resolveSubAgentSubject(subAgentClientId: string | undefined): UserSubjectRef | undefined;
+/**
+ * The **spawn-level** sub-agent subject:
+ * `SubAgent:<clientId>|<session>|<type>[|<spawn>]`, the finest grain available.
+ *
+ * `perSpawnId` distinguishes two *concurrent* same-type sub-agents and is only
+ * present on harnesses that expose one (Cursor's `subagent_id`, Claude Code's
+ * `agent_id`, OpenClaw's `childRunId`, …). Where the harness exposes none the
+ * subject stops at the type and concurrent spawns share it — a limit of the
+ * harness, not of this model.
+ *
+ * As with the agent session subject, a missing session yields `undefined`
+ * rather than a placeholder.
+ */
+export declare function resolveSubAgentSpawnSubject(client: OryAgentClient, args: {
+    subAgentClientId?: string;
+    subAgentType: string;
+    perSpawnId?: string;
+    sessionId?: string;
+}): UserSubjectRef | undefined;