@ory/argus 1.2.3 → 1.3.0

package/dist/local/seed.js

@@ -8,10 +8,10 @@
  * redirect URIs. The launcher always runs the real PKCE browser flow; the
  * user types these credentials into the login UI to complete the flow.
  *
- * No agent principal is seeded: the harness self-registers a DCR OAuth2
- * client for the agent on first session start (using the user's bearer as
- * the initial access token), and permission checks are made against the
- * user subject — so a pre-seeded agent Kratos identity would be unused.
+ * No agent principal is seeded: Agent Security enrolls a Talos runtime
+ * credential at session start using the authenticated user's bearer, and
+ * permission checks are made against the user subject. A pre-seeded agent
+ * Kratos identity would be unused.
  *
  * Permission tuples are written as SubjectSet `User:<identity.id>` so
  * the Console's *Add relationship* dialog (which always emits SubjectSet
@@ -157,9 +157,8 @@ async function seedLocalEnvironment(namespace = "AgentTool") {
         throw new Error(`backend services not ready before seed: ${readiness.pending.join(", ")} ` +
             `did not report ready within the timeout. The stack may still be starting — retry in a moment.`);
     }
-    // 1. User identity. No agent identity is seeded — the harness
-    //    self-registers a DCR OAuth2 client for the agent on first session
-    //    start, and permission checks target the user subject.
+    // 1. User identity. No agent identity is seeded; Talos enrollment is owned
+    //    by Agent Security at session start, and checks target the user subject.
     process.stderr.write("  Creating user identity...\n");
     const userIdentity = await seedIdentity(USER_EMAIL, USER_PASSWORD, "Local User");
     process.stderr.write(`  User: ${userIdentity.id} (${userIdentity.email})\n`);
@@ -168,9 +167,8 @@ async function seedLocalEnvironment(namespace = "AgentTool") {
     const subjectLabel = `${exports.USER_SUBJECT_NAMESPACE}:${userIdentity.id}`;
     process.stderr.write("  Native tools: allowed unless explicitly blocked (no baseline grants)\n");
     // 3. User OAuth2 client (PKCE) — pre-registered so the user gate's
-    //    PKCE flow has somewhere to authenticate against. The agent's
-    //    OAuth2 client is intentionally NOT pre-registered; the harness
-    //    will self-register via DCR on first session start.
+    //    PKCE flow has somewhere to authenticate against. Agent identity uses
+    //    Talos runtime enrollment, so no agent OAuth2 client is seeded.
     process.stderr.write("  Registering user OAuth2 client (PKCE)...\n");
     let userClient = { clientId: exports.USER_CLIENT_ID };
     try {

package/dist/permissions.d.ts

@@ -231,13 +231,13 @@ export interface GateToolCallArgs {
     /** Override the resolved {@link PermissionMode}. Tests use this. */
     modeOverride?: PermissionMode;
     /**
-     * Raw shell command string when {@link toolName} is the harness's shell tool
+     * Raw shell command string(s) 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
+     * each 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;
+    shellCommand?: string | readonly 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 ⇒

package/dist/permissions.js

@@ -407,11 +407,36 @@ async function decomposeAndCheck(client, args) {
     // letting the exception bubble to the harness catch, which fails open.
     let parsed;
     try {
-        parsed = await (0, bash_parser_js_1.extractBashCommandWords)(args.shellCommand ?? "");
+        const commands = typeof args.shellCommand === "string"
+            ? [args.shellCommand]
+            : args.shellCommand ?? [];
+        const words = [];
+        const seen = new Set();
+        let tooComplex = false;
+        let parserUnavailable = false;
+        for (const command of commands) {
+            const result = await (0, bash_parser_js_1.extractBashCommandWords)(command);
+            tooComplex ||= result.tooComplex;
+            parserUnavailable ||= result.parserUnavailable === true;
+            for (const word of result.words) {
+                if (!seen.has(word)) {
+                    seen.add(word);
+                    words.push(word);
+                }
+            }
+        }
+        parsed = { words, tooComplex, parserUnavailable };
     }
     catch {
         parsed = { words: [], tooComplex: true };
     }
+    if (args.toolName.toLowerCase() === "powershell"
+        || (args.harness === "cline" && args.toolName === "run_commands" && process.platform === "win32")) {
+        // The bundled grammar models POSIX shell syntax, not PowerShell. Retain its
+        // Never retain words parsed with the incompatible grammar: PowerShell
+        // literals could otherwise be persisted as if they were command names.
+        parsed = { words: [], tooComplex: true, parserUnavailable: false };
+    }
     if (parsed.parserUnavailable) {
         client.logger.warn("bash.parser_unavailable", {
             harness: args.harness,

package/dist/runtime-credential.d.ts

@@ -1,3 +1,5 @@
+import { readFile, realpath } from "node:fs/promises";
+import * as nodeHttps from "node:https";
 /** The broker header a runtime credential must occupy for a request. */
 export type RuntimeAuthorizationHeader = "authorization" | "x-ory-agent-authorization";
 export interface RuntimeAuthenticatedRequest {
@@ -15,10 +17,37 @@ export interface RuntimeAuthenticatedRequest {
  * the request over mTLS without exposing key material to Argus.
  */
 export type RuntimeRequestAuthenticator = (request: RuntimeAuthenticatedRequest) => Promise<Response>;
+export interface SpiffeFileRequestAuthenticatorOptions {
+    /** Atomically switched directory or symlink containing one material generation. */
+    generationPath?: string;
+    certificatePath?: string;
+    privateKeyPath?: string;
+    trustBundlePath?: string;
+    certificateFile?: string;
+    privateKeyFile?: string;
+    trustBundleFile?: string;
+    /** Optional marker read before and after the PEM files to reject mixed generations. */
+    generationFile?: string;
+    /** Exact URI SAN required on the peer leaf certificate. */
+    expectedServerSpiffeId?: string;
+    /** Exact and sole URI SAN required on the loaded client leaf certificate. */
+    expectedClientSpiffeId?: string;
+    /** Explicitly use ordinary HTTPS hostname verification instead of SPIFFE identity. */
+    verifyHostname?: boolean;
+    privateKeyPassphrase?: string;
+    /** @internal Injectable seam for focused transport tests. */
+    readFile?: typeof readFile;
+    /** @internal Injectable seam for focused generation-path tests. */
+    realpath?: typeof realpath;
+    /** @internal Injectable seam for focused transport tests. */
+    request?: typeof nodeHttps.request;
+}
 export type RuntimeCredentialKind = "talos" | "injected";
 export interface RuntimeCredential {
     kind: RuntimeCredentialKind;
     subject?: string;
+    /** @internal Non-secret binding used to recognize the same Talos key after re-resolution. */
+    apiKeyFingerprint?: string;
     authenticate: RuntimeRequestAuthenticator;
 }
 export interface ResolveRuntimeCredentialOptions {
@@ -115,6 +144,12 @@ export declare function talosRuntimeCredential(apiKey: string, options?: {
     /** @internal Injectable seam for testing default-fetch TLS setup. */
     configureSystemCaTrust?: () => void;
 }): RuntimeCredential;
+/**
+ * Build an mTLS authenticator from operator-managed SPIFFE files. The files are
+ * re-read for every request so atomic SVID and trust-bundle rotations are used
+ * without restarting the process.
+ */
+export declare function createSpiffeFileRequestAuthenticator(options: SpiffeFileRequestAuthenticatorOptions): RuntimeRequestAuthenticator;
 /** Resolve only noninteractive runtime credentials. No persisted state is read. */
 export declare function resolveRuntimeCredential(options?: ResolveRuntimeCredentialOptions): RuntimeCredential | undefined;
 /** Explicitly enroll a Talos credential and optionally persist it in an OS store. */

package/dist/runtime-credential.js

@@ -40,13 +40,18 @@ exports.canonicalCredentialIdentity = canonicalCredentialIdentity;
 exports.credentialAccount = credentialAccount;
 exports.createOsTalosCredentialStore = createOsTalosCredentialStore;
 exports.talosRuntimeCredential = talosRuntimeCredential;
+exports.createSpiffeFileRequestAuthenticator = createSpiffeFileRequestAuthenticator;
 exports.resolveRuntimeCredential = resolveRuntimeCredential;
 exports.enrollTalosRuntimeCredential = enrollTalosRuntimeCredential;
 exports.enrollTalosChildRuntimeCredential = enrollTalosChildRuntimeCredential;
 exports.authenticatedRuntimeRequest = authenticatedRuntimeRequest;
 const node_child_process_1 = require("node:child_process");
 const node_crypto_1 = require("node:crypto");
+const promises_1 = require("node:fs/promises");
+const nodeHttps = __importStar(require("node:https"));
+const node_path_1 = require("node:path");
 const nodeTls = __importStar(require("node:tls"));
+const SPIFFE_CREDENTIAL_METHOD = "spiffe_x509_svid";
 const CREDENTIAL_SERVICE = "com.ory.agent-security.runtime-credential";
 const MACOS_CREDENTIAL_SCRIPT = String.raw `
 ObjC.import('Foundation');
@@ -407,6 +412,7 @@ function talosRuntimeCredential(apiKey, options = {}) {
     return {
         kind: "talos",
         ...(options.subject ? { subject: options.subject } : {}),
+        apiKeyFingerprint: (0, node_crypto_1.createHash)("sha256").update(key).digest("hex"),
         authenticate: async ({ url, init, authorizationHeader, fetch: requestFetch, usesDefaultFetch, }) => {
             const headerName = authorizationHeader === "authorization"
                 ? "authorization"
@@ -430,6 +436,205 @@ function talosRuntimeCredential(apiKey, options = {}) {
         },
     };
 }
+/**
+ * Build an mTLS authenticator from operator-managed SPIFFE files. The files are
+ * re-read for every request so atomic SVID and trust-bundle rotations are used
+ * without restarting the process.
+ */
+function createSpiffeFileRequestAuthenticator(options) {
+    const read = options.readFile ?? promises_1.readFile;
+    const resolveRealpath = options.realpath ?? promises_1.realpath;
+    const requestHttps = options.request ?? nodeHttps.request;
+    const expectedServerSpiffeId = options.expectedServerSpiffeId
+        ? canonicalSpiffeId(options.expectedServerSpiffeId)
+        : undefined;
+    const expectedClientSpiffeId = options.expectedClientSpiffeId
+        ? canonicalSpiffeId(options.expectedClientSpiffeId, "expectedClientSpiffeId")
+        : undefined;
+    if (Boolean(expectedServerSpiffeId) === Boolean(options.verifyHostname)) {
+        throw new Error("SPIFFE file authentication requires exactly one of expectedServerSpiffeId or verifyHostname");
+    }
+    const materialPaths = async () => {
+        if (options.generationPath) {
+            const generation = await resolveRealpath(options.generationPath);
+            const files = [
+                options.certificateFile ?? "svid.pem",
+                options.privateKeyFile ?? "svid-key.pem",
+                options.trustBundleFile ?? "bundle.pem",
+                options.generationFile,
+            ];
+            const paths = files.map((file) => {
+                if (file === undefined)
+                    return undefined;
+                if ((0, node_path_1.isAbsolute)(file)) {
+                    throw new Error("SPIFFE generation file names must be relative paths");
+                }
+                const path = (0, node_path_1.resolve)(generation, file);
+                const fromGeneration = (0, node_path_1.relative)(generation, path);
+                if (fromGeneration === ".." || fromGeneration.startsWith(`..${node_path_1.sep}`)) {
+                    throw new Error("SPIFFE generation file names must remain within the generation path");
+                }
+                return path;
+            });
+            return paths;
+        }
+        if (options.generationFile) {
+            throw new Error("SPIFFE generationFile requires generationPath");
+        }
+        if (!options.certificatePath || !options.privateKeyPath || !options.trustBundlePath) {
+            throw new Error("SPIFFE file authentication requires generationPath or all three material paths");
+        }
+        return [options.certificatePath, options.privateKeyPath, options.trustBundlePath];
+    };
+    const isKeyMismatch = (error) => {
+        if (!(error instanceof Error))
+            return false;
+        const code = error.code;
+        return code === "ERR_OSSL_X509_KEY_VALUES_MISMATCH"
+            || /key values mismatch/i.test(error.message);
+    };
+    return async ({ url, init }) => {
+        const target = new URL(url);
+        if (target.protocol !== "https:") {
+            throw new Error("SPIFFE file authentication requires an HTTPS URL");
+        }
+        if (target.username || target.password) {
+            throw new Error("SPIFFE file authentication does not accept URL credentials");
+        }
+        const normalized = new Request(target, init);
+        const body = normalized.body === null
+            ? undefined
+            : Buffer.from(await normalized.arrayBuffer());
+        const send = async () => {
+            let snapshot;
+            for (let attempt = 0; attempt < 2; attempt += 1) {
+                const [certificatePath, privateKeyPath, trustBundlePath, generationFile] = await materialPaths();
+                const generationBefore = generationFile ? await read(generationFile) : undefined;
+                const [cert, key, ca] = await Promise.all([
+                    read(certificatePath),
+                    read(privateKeyPath),
+                    read(trustBundlePath),
+                ]);
+                const generationAfter = generationFile ? await read(generationFile) : undefined;
+                if (!generationBefore || (generationAfter && generationBefore.equals(generationAfter))) {
+                    if (expectedClientSpiffeId) {
+                        validateClientCertificate(cert, expectedClientSpiffeId);
+                    }
+                    snapshot = [cert, key, ca];
+                    break;
+                }
+            }
+            if (!snapshot)
+                throw new Error("SPIFFE material generation changed while loading files");
+            const [cert, key, ca] = snapshot;
+            return await new Promise((resolveResponse, reject) => {
+                const outgoing = requestHttps(target, {
+                    method: normalized.method,
+                    headers: Object.fromEntries(normalized.headers),
+                    cert,
+                    key,
+                    ...(expectedServerSpiffeId ? { ca } : {}),
+                    ...(options.privateKeyPassphrase ? { passphrase: options.privateKeyPassphrase } : {}),
+                    minVersion: "TLSv1.3",
+                    rejectUnauthorized: true,
+                    ...(expectedServerSpiffeId ? {
+                        // Never reuse a connection authenticated under another expected workload ID.
+                        agent: false,
+                        checkServerIdentity: (_hostname, certificate) => {
+                            if (!peerHasExactUriSan(certificate.subjectaltname, expectedServerSpiffeId)) {
+                                return new Error(`Peer certificate does not contain expected SPIFFE URI SAN ${expectedServerSpiffeId}`);
+                            }
+                            return undefined;
+                        },
+                    } : {}),
+                    signal: init.signal ?? undefined,
+                }, (incoming) => {
+                    const chunks = [];
+                    incoming.on("data", (chunk) => {
+                        chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+                    });
+                    incoming.on("end", () => {
+                        const headers = new Headers();
+                        for (let index = 0; index < incoming.rawHeaders.length; index += 2) {
+                            headers.append(incoming.rawHeaders[index], incoming.rawHeaders[index + 1]);
+                        }
+                        resolveResponse(new Response(Buffer.concat(chunks), {
+                            status: incoming.statusCode ?? 500,
+                            statusText: incoming.statusMessage,
+                            headers,
+                        }));
+                    });
+                    incoming.on("error", reject);
+                });
+                outgoing.on("error", reject);
+                if (body)
+                    outgoing.write(body);
+                outgoing.end();
+            });
+        };
+        try {
+            return await send();
+        }
+        catch (error) {
+            if (!isKeyMismatch(error))
+                throw error;
+            return await send();
+        }
+    };
+}
+function canonicalSpiffeId(value, name = "expectedServerSpiffeId") {
+    const parsed = new URL(value);
+    if (parsed.protocol !== "spiffe:"
+        || !parsed.hostname
+        || parsed.username
+        || parsed.password
+        || parsed.port
+        || parsed.search
+        || parsed.hash) {
+        throw new Error(`${name} must be a valid SPIFFE ID`);
+    }
+    return value;
+}
+function validateClientCertificate(certificate, expectedSpiffeId) {
+    let leaf;
+    try {
+        leaf = new node_crypto_1.X509Certificate(certificate);
+    }
+    catch {
+        throw new Error("SPIFFE client certificate is not a valid X.509 certificate");
+    }
+    const uriSans = uriSansFromSubjectAltName(leaf.subjectAltName);
+    if (uriSans.length !== 1 || uriSans[0] !== expectedSpiffeId) {
+        throw new Error(`Client certificate must contain only the expected SPIFFE URI SAN ${expectedSpiffeId}`);
+    }
+    const now = Date.now();
+    if (now < Date.parse(leaf.validFrom) || now > Date.parse(leaf.validTo)) {
+        throw new Error("SPIFFE client certificate is not currently valid");
+    }
+}
+function uriSansFromSubjectAltName(subjectAltName) {
+    if (!subjectAltName)
+        return [];
+    const result = [];
+    for (const entry of subjectAltName.match(/(?:^|, )URI:(?:"(?:\\.|[^"\\])*"|.*?)(?=, [A-Za-z0-9.]+:|$)/g) ?? []) {
+        const encoded = entry.replace(/^, /, "").slice(4);
+        if (!encoded.startsWith('"')) {
+            result.push(encoded);
+            continue;
+        }
+        try {
+            result.push(JSON.parse(encoded));
+        }
+        catch {
+            // Malformed SANs cannot satisfy an exact SPIFFE identity match.
+        }
+    }
+    return result;
+}
+function peerHasExactUriSan(subjectAltName, expected) {
+    const uriSans = uriSansFromSubjectAltName(subjectAltName);
+    return uriSans.length === 1 && uriSans[0] === expected;
+}
 /** Resolve only noninteractive runtime credentials. No persisted state is read. */
 function resolveRuntimeCredential(options = {}) {
     if (options.requestAuthenticator) {
@@ -439,11 +644,57 @@ function resolveRuntimeCredential(options = {}) {
             authenticate: options.requestAuthenticator,
         };
     }
-    const apiKey = (options.env ?? process.env).ORY_AGENT_API_KEY?.trim();
+    const env = options.env ?? process.env;
+    if (env.ORY_AGENT_CREDENTIAL_METHOD?.trim() === SPIFFE_CREDENTIAL_METHOD) {
+        const expectedClientSpiffeId = requiredEnv(env, "ORY_AGENT_SPIFFE_ID");
+        const generationPath = env.ORY_AGENT_SPIFFE_GENERATION_PATH?.trim();
+        const certificatePath = env.ORY_AGENT_SPIFFE_SVID_PATH?.trim();
+        const privateKeyPath = env.ORY_AGENT_SPIFFE_KEY_PATH?.trim();
+        const trustBundlePath = env.ORY_AGENT_SPIFFE_TRUST_BUNDLE_PATH?.trim();
+        const generationFile = env.ORY_SPIFFE_GENERATION_FILE?.trim();
+        const directPaths = [certificatePath, privateKeyPath, trustBundlePath];
+        if (generationPath && directPaths.some(Boolean)) {
+            throw new Error("SPIFFE configuration must use either ORY_AGENT_SPIFFE_GENERATION_PATH or direct material paths");
+        }
+        if (!generationPath && !directPaths.every(Boolean)) {
+            throw new Error("SPIFFE configuration requires ORY_AGENT_SPIFFE_GENERATION_PATH or all three direct material paths");
+        }
+        if (!generationPath && generationFile) {
+            throw new Error("ORY_SPIFFE_GENERATION_FILE requires ORY_AGENT_SPIFFE_GENERATION_PATH");
+        }
+        const expectedServerSpiffeId = env.ORY_AGENT_SPIFFE_SERVER_ID?.trim();
+        return {
+            kind: "injected",
+            ...(options.subject ? { subject: options.subject } : {}),
+            authenticate: createSpiffeFileRequestAuthenticator({
+                ...(generationPath ? {
+                    generationPath,
+                    ...(generationFile
+                        ? { generationFile }
+                        : {}),
+                } : {
+                    certificatePath: certificatePath,
+                    privateKeyPath: privateKeyPath,
+                    trustBundlePath: trustBundlePath,
+                }),
+                expectedClientSpiffeId,
+                ...(expectedServerSpiffeId
+                    ? { expectedServerSpiffeId }
+                    : { verifyHostname: true }),
+            }),
+        };
+    }
+    const apiKey = env.ORY_AGENT_API_KEY?.trim();
     if (!apiKey)
         return undefined;
     return talosRuntimeCredential(apiKey, { subject: options.subject, fetch: options.fetch });
 }
+function requiredEnv(env, name) {
+    const value = env[name]?.trim();
+    if (!value)
+        throw new Error(`SPIFFE configuration requires ${name}`);
+    return value;
+}
 /** Explicitly enroll a Talos credential and optionally persist it in an OS store. */
 async function enrollTalosRuntimeCredential(options) {
     let response;

package/dist/runtime.d.ts

@@ -26,10 +26,10 @@
  *      wired where, so `status` can report the runtime a harness will actually
  *      load, upgrades can rewire, and unreferenced stores can be pruned.
  *
- * A **linked** runtime (`linkedRuntime`) points the shim straight at a
- * workspace build instead of a materialized store. That is the development
- * loop: `pnpm build` + relaunch, with no publish, no version bump, and no
- * registry involved.
+ * A **linked** runtime (`linkedRuntime`) points the shim straight at an
+ * explicit prebuilt package directory instead of a materialized store. This
+ * supports both administrator-managed runtimes and the workspace development
+ * loop (`pnpm build` + relaunch), with no registry involved.
  *
  * ## The shim must fail open
  *
@@ -137,8 +137,8 @@ export declare function materializeRuntime(opts: {
     installer?: NpmInstaller;
 }): RuntimeTarget;
 /**
- * Use an already-built package directory as the runtime — the development
- * path (`install --link <dir>`), where the workspace build *is* the artifact.
+ * Use an explicit prebuilt package directory as the runtime, including a
+ * managed installation or workspace build.
  *
  * Validates that the directory looks like a built package so a typo surfaces
  * at install time instead of as hooks that silently never run.
@@ -206,13 +206,19 @@ export declare function writeMcpShim(opts: {
     target: RuntimeTarget;
     installCommand: string;
 }): string | undefined;
+/**
+ * Resolve the Node executable persisted in subprocess hook and MCP config.
+ * Managed installations can pin an administrator-approved absolute path;
+ * ordinary installations retain the portable `node` command lookup.
+ */
+export declare function resolvePluginNodePath(env?: NodeJS.ProcessEnv): string;
 /**
  * The hook command a harness config should carry: `node "<shim>"`.
  *
- * Quoted because a data dir can contain spaces, and several harnesses run the
- * command through a shell.
+ * Paths are shell-quoted because managed executables and data dirs can contain
+ * spaces or shell metacharacters, and several harnesses run this as a string.
  */
-export declare function hookCommand(shimPath: string): string;
+export declare function hookCommand(shimPath: string, nodePath?: string): string;
 /**
  * True when a command in a harness config is one of ours.
  *
@@ -225,7 +231,7 @@ export declare function hookCommand(shimPath: string): string;
  */
 export declare function isOryRuntimeCommand(command: string | undefined): boolean;
 /** The MCP server registration a harness config should carry. */
-export declare function mcpCommand(shimPath: string): {
+export declare function mcpCommand(shimPath: string, nodePath?: string): {
     command: string;
     args: string[];
 };
@@ -296,8 +302,9 @@ export declare function pruneRuntimeStores(): string[];
  *   `ORY_PLUGIN_RUNTIME_DIR`    → link that directory
  *   otherwise                   → materialize the CLI's own version
  *
- * The flag and the env var support explicit source installs that point at an
- * already-built workspace package instead of materializing from a registry.
+ * The flag and the env var support explicit prebuilt runtime installs,
+ * including administrator-managed package directories and workspace builds,
+ * instead of materializing from a registry.
  *
  * The flag deliberately requires an explicit directory. A bare "link whatever
  * package I am running from" would resolve to npx's ephemeral cache dir under