@ory/argus 0.1.0

package/dist/local/seed.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Seed the local Ory environment with test data for development.
+ *
+ * Creates two principals:
+ *
+ *   1. **Agent** (`agent@ory-local.dev`) — a Kratos identity that the
+ *      harness will register a DCR OAuth2 client *for* on first session
+ *      start. No OAuth2 client is pre-registered here.
+ *
+ *   2. **User** (`user@ory-local.dev`) — a human identity with a known
+ *      password (printed by the launcher) and an OAuth2
+ *      `authorization_code` + PKCE client registered against the
+ *      loopback redirect URIs. The launcher always runs the real PKCE
+ *      browser flow; the user types these credentials into the login
+ *      UI to complete the flow.
+ *
+ * Permission tuples are written as SubjectSet `User:<identity.id>` so
+ * the Console's *Add relationship* dialog (which always emits SubjectSet
+ * subjects) can recreate them by hand for the demo walkthrough. Plugins
+ * build the matching SubjectSet check when `ORY_USER_SUBJECT_NAMESPACE`
+ * is set (the launcher sets it to `User`).
+ *
+ * Idempotent — re-running the seed reuses existing identities and
+ * recreates OAuth2 clients (so the secret is always known).
+ */
+export interface SeededIdentity {
+    id: string;
+    email: string;
+}
+export interface SeededOAuth2Client {
+    clientId: string;
+    clientSecret?: string;
+}
+export interface SeedResult {
+    /**
+     * Agent (machine) identity — Kratos identity only. The agent's OAuth2
+     * client is *not* pre-registered: the harness self-registers via DCR
+     * (RFC 7591) on first session start using the user's bearer as the
+     * initial access token.
+     */
+    agent: {
+        identity: SeededIdentity;
+    };
+    /** User (human) identity — subject of permission checks. */
+    user: {
+        identity: SeededIdentity;
+        /**
+         * Password for the user identity. Printed by the launcher so the
+         * developer can type it into the login UI during the PKCE browser
+         * flow. Local-dev only — never used in production.
+         */
+        password: string;
+        /** OAuth2 authorization_code+PKCE client for interactive logins. */
+        client: SeededOAuth2Client;
+    };
+    /** Permission tuples written against the user's subject. */
+    permissions: {
+        namespace: string;
+        subject: string;
+        tuples: number;
+    };
+}
+/** Subject namespace for user identities in seeded permission tuples. */
+export declare const USER_SUBJECT_NAMESPACE = "User";
+/**
+ * Run the full seed process. Idempotent — safe to run multiple times.
+ *
+ * Returns a `SeedResult` describing both identities, the user's
+ * pre-minted session, and the OAuth2 clients registered for each.
+ */
+export declare function seedLocalEnvironment(namespace?: string): Promise<SeedResult>;

package/dist/local/seed.js

@@ -0,0 +1,237 @@
+"use strict";
+/**
+ * Seed the local Ory environment with test data for development.
+ *
+ * Creates two principals:
+ *
+ *   1. **Agent** (`agent@ory-local.dev`) — a Kratos identity that the
+ *      harness will register a DCR OAuth2 client *for* on first session
+ *      start. No OAuth2 client is pre-registered here.
+ *
+ *   2. **User** (`user@ory-local.dev`) — a human identity with a known
+ *      password (printed by the launcher) and an OAuth2
+ *      `authorization_code` + PKCE client registered against the
+ *      loopback redirect URIs. The launcher always runs the real PKCE
+ *      browser flow; the user types these credentials into the login
+ *      UI to complete the flow.
+ *
+ * Permission tuples are written as SubjectSet `User:<identity.id>` so
+ * the Console's *Add relationship* dialog (which always emits SubjectSet
+ * subjects) can recreate them by hand for the demo walkthrough. Plugins
+ * build the matching SubjectSet check when `ORY_USER_SUBJECT_NAMESPACE`
+ * is set (the launcher sets it to `User`).
+ *
+ * Idempotent — re-running the seed reuses existing identities and
+ * recreates OAuth2 clients (so the secret is always known).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.USER_SUBJECT_NAMESPACE = void 0;
+exports.seedLocalEnvironment = seedLocalEnvironment;
+const auth_js_1 = require("../auth.js");
+const configs_js_1 = require("./configs.js");
+const KRATOS_ADMIN = `http://localhost:${configs_js_1.KRATOS_ADMIN_PORT}`;
+const KETO_WRITE = `http://localhost:${configs_js_1.KETO_WRITE_PORT}`;
+const HYDRA_ADMIN = `http://localhost:${configs_js_1.HYDRA_ADMIN_PORT}`;
+const AGENT_EMAIL = "agent@ory-local.dev";
+const AGENT_PASSWORD = "ory-agent-local-dev-password!";
+const USER_EMAIL = "user@ory-local.dev";
+const USER_PASSWORD = "ory-user-local-dev-password!";
+const USER_CLIENT_NAME = "ory-agent-plugins-local-user";
+const USER_CLIENT_ID = "ory-user-local";
+/**
+ * Common tools that agents typically use. Permission tuples are seeded
+ * so the user identity is allowed to use all of them.
+ */
+const COMMON_TOOLS = [
+    "Read",
+    "Write",
+    "Edit",
+    "Bash",
+    "Glob",
+    "Grep",
+    "WebFetch",
+    "WebSearch",
+    "Agent",
+    "NotebookEdit",
+    "TodoRead",
+    "TodoWrite",
+    "execute_command",
+    "read_file",
+    "write_file",
+    "list_directory",
+    "search_files",
+    "browser",
+];
+async function jsonFetch(url, opts = {}) {
+    const res = await fetch(url, {
+        ...opts,
+        headers: {
+            "Content-Type": "application/json",
+            ...opts.headers,
+        },
+        signal: AbortSignal.timeout(10_000),
+    });
+    const body = await res.text();
+    if (!res.ok) {
+        throw new Error(`${opts.method ?? "GET"} ${url} → ${res.status}: ${body}`);
+    }
+    return body ? JSON.parse(body) : {};
+}
+/** Seed (or look up) a Kratos identity by email + password. */
+async function seedIdentity(email, password, name) {
+    const existing = (await jsonFetch(`${KRATOS_ADMIN}/admin/identities?credentials_identifier=${encodeURIComponent(email)}`));
+    if (existing.length > 0) {
+        return { id: existing[0].id, email };
+    }
+    const identity = (await jsonFetch(`${KRATOS_ADMIN}/admin/identities`, {
+        method: "POST",
+        body: JSON.stringify({
+            schema_id: "agent",
+            traits: { email, name },
+            credentials: {
+                password: { config: { password } },
+            },
+            state: "active",
+        }),
+    }));
+    return { id: identity.id, email };
+}
+/** Subject namespace for user identities in seeded permission tuples. */
+exports.USER_SUBJECT_NAMESPACE = "User";
+/**
+ * Write permission tuples granting the user identity access to all
+ * common tools. The subject is written as a SubjectSet
+ * `User:<userId>` (no relation) so the Console UI's *Add relationship*
+ * dialog — which only emits SubjectSet subjects — can recreate the same
+ * tuple by hand during the runbook walkthrough.
+ */
+async function seedPermissions(userId, namespace) {
+    let created = 0;
+    for (const tool of COMMON_TOOLS) {
+        try {
+            await jsonFetch(`${KETO_WRITE}/admin/relation-tuples`, {
+                method: "PUT",
+                body: JSON.stringify({
+                    namespace,
+                    object: tool,
+                    relation: "use",
+                    subject_set: {
+                        namespace: exports.USER_SUBJECT_NAMESPACE,
+                        object: userId,
+                        relation: "",
+                    },
+                }),
+            });
+            created++;
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            if (!msg.includes("409")) {
+                process.stderr.write(`  Warning: failed to create tuple for ${tool}: ${msg}\n`);
+            }
+            else {
+                created++;
+            }
+        }
+    }
+    return created;
+}
+/**
+ * Delete a Hydra OAuth2 client if it exists, then create it with a
+ * known client_id/secret. We always recreate so the launcher knows the
+ * exact credentials to inject into the harness env.
+ */
+async function ensureOAuth2Client(spec) {
+    // Look up by client_name; delete if present so we can recreate with a
+    // deterministic secret.
+    const existing = (await jsonFetch(`${HYDRA_ADMIN}/admin/clients?client_name=${encodeURIComponent(spec.clientName)}`));
+    for (const c of existing) {
+        if (c.client_name !== spec.clientName)
+            continue;
+        try {
+            await jsonFetch(`${HYDRA_ADMIN}/admin/clients/${encodeURIComponent(c.client_id)}`, {
+                method: "DELETE",
+            });
+        }
+        catch {
+            // best-effort cleanup
+        }
+    }
+    const body = {
+        client_id: spec.clientId,
+        client_name: spec.clientName,
+        grant_types: spec.grantTypes,
+        response_types: spec.responseTypes,
+        scope: spec.scope,
+        token_endpoint_auth_method: spec.tokenEndpointAuthMethod,
+    };
+    if (spec.clientSecret)
+        body.client_secret = spec.clientSecret;
+    if (spec.redirectUris)
+        body.redirect_uris = spec.redirectUris;
+    const client = (await jsonFetch(`${HYDRA_ADMIN}/admin/clients`, {
+        method: "POST",
+        body: JSON.stringify(body),
+    }));
+    return {
+        clientId: client.client_id,
+        clientSecret: client.client_secret ?? spec.clientSecret,
+    };
+}
+/** PKCE redirect URIs — must match the loopback ports the harness binds to. */
+function loopbackRedirectUris() {
+    return auth_js_1.LOOPBACK_PORTS.map((p) => `http://127.0.0.1:${p}/callback`);
+}
+/**
+ * Run the full seed process. Idempotent — safe to run multiple times.
+ *
+ * Returns a `SeedResult` describing both identities, the user's
+ * pre-minted session, and the OAuth2 clients registered for each.
+ */
+async function seedLocalEnvironment(namespace = "AgentTools") {
+    process.stderr.write("Seeding local Ory environment...\n\n");
+    // 1. Identities
+    process.stderr.write("  Creating agent identity...\n");
+    const agentIdentity = await seedIdentity(AGENT_EMAIL, AGENT_PASSWORD, "Local Agent");
+    process.stderr.write(`  Agent: ${agentIdentity.id} (${agentIdentity.email})\n`);
+    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`);
+    // 2. Permission tuples — written against the user's identity since the
+    //    user is the subject of permission checks in the plugin handlers.
+    //    Subject is a SubjectSet `User:<id>` so the Console UI can rewrite
+    //    the same tuple shape by hand during the runbook demo.
+    const subjectLabel = `${exports.USER_SUBJECT_NAMESPACE}:${userIdentity.id}`;
+    process.stderr.write(`  Creating permission tuples for ${COMMON_TOOLS.length} tools...\n`);
+    const tupleCount = await seedPermissions(userIdentity.id, namespace);
+    process.stderr.write(`  Permissions: ${tupleCount} tuples in '${namespace}' for ${subjectLabel}\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.
+    process.stderr.write("  Registering user OAuth2 client (PKCE)...\n");
+    let userClient = { clientId: USER_CLIENT_ID };
+    try {
+        userClient = await ensureOAuth2Client({
+            clientName: USER_CLIENT_NAME,
+            clientId: USER_CLIENT_ID,
+            // Public PKCE client — no secret. Hydra accepts an empty string
+            // for `token_endpoint_auth_method=none`.
+            grantTypes: ["authorization_code", "refresh_token"],
+            responseTypes: ["code"],
+            scope: "openid offline_access",
+            tokenEndpointAuthMethod: "none",
+            redirectUris: loopbackRedirectUris(),
+        });
+        process.stderr.write(`  User client: ${userClient.clientId}\n`);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        process.stderr.write(`  Warning: user OAuth2 client registration failed: ${msg}\n`);
+    }
+    return {
+        agent: { identity: agentIdentity },
+        user: { identity: userIdentity, password: USER_PASSWORD, client: userClient },
+        permissions: { namespace, subject: subjectLabel, tuples: tupleCount },
+    };
+}

package/dist/logger.d.ts

@@ -0,0 +1,29 @@
+export type LogLevel = "debug" | "info" | "warn" | "error";
+export interface LogEntry {
+    timestamp: string;
+    level: LogLevel;
+    event: string;
+    harness: string;
+    data?: Record<string, unknown>;
+}
+/**
+ * Recursively redact sensitive values from a structured log payload.
+ * The original object is not modified.
+ */
+export declare function redactLogData(value: unknown): unknown;
+export declare class DebugLogger {
+    enabled: boolean;
+    harness: string;
+    logFile: string | null;
+    constructor(harness: string, opts?: {
+        logFile?: string;
+    });
+    get isEnabled(): boolean;
+    enable(): void;
+    disable(): void;
+    log(level: LogLevel, event: string, data?: Record<string, unknown>): void;
+    debug(event: string, data?: Record<string, unknown>): void;
+    info(event: string, data?: Record<string, unknown>): void;
+    warn(event: string, data?: Record<string, unknown>): void;
+    error(event: string, data?: Record<string, unknown>): void;
+}

package/dist/logger.js

@@ -0,0 +1,139 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DebugLogger = void 0;
+exports.redactLogData = redactLogData;
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+/**
+ * Keys whose values are always redacted before being written to stderr or
+ * to the log file. Match is case-insensitive on the final path segment.
+ */
+const REDACTED_KEYS = new Set([
+    "accesstoken",
+    "access_token",
+    "refreshtoken",
+    "refresh_token",
+    "idtoken",
+    "id_token",
+    "sessiontoken",
+    "session_token",
+    "code_verifier",
+    "codeverifier",
+    "client_secret",
+    "clientsecret",
+    "authorization",
+    "password",
+    "apikey",
+    "api_key",
+]);
+/**
+ * Recursively redact sensitive values from a structured log payload.
+ * The original object is not modified.
+ */
+function redactLogData(value) {
+    if (Array.isArray(value)) {
+        return value.map(redactLogData);
+    }
+    if (value && typeof value === "object") {
+        const out = {};
+        for (const [k, v] of Object.entries(value)) {
+            if (REDACTED_KEYS.has(k.toLowerCase()) && v !== undefined && v !== null) {
+                out[k] = "[redacted]";
+            }
+            else {
+                out[k] = redactLogData(v);
+            }
+        }
+        return out;
+    }
+    return value;
+}
+class DebugLogger {
+    enabled;
+    harness;
+    logFile;
+    constructor(harness, opts) {
+        this.enabled = process.env.ORY_AGENT_DEBUG === "true";
+        this.harness = harness;
+        this.logFile = opts?.logFile ?? null;
+    }
+    get isEnabled() {
+        return this.enabled;
+    }
+    enable() {
+        this.enabled = true;
+    }
+    disable() {
+        this.enabled = false;
+    }
+    log(level, event, data) {
+        if (!this.enabled)
+            return;
+        const safeData = data
+            ? redactLogData(data)
+            : undefined;
+        const entry = {
+            timestamp: new Date().toISOString(),
+            level,
+            event,
+            harness: this.harness,
+            ...(safeData ? { data: safeData } : {}),
+        };
+        const line = JSON.stringify(entry);
+        // Always write to stderr so we don't interfere with hook stdout
+        process.stderr.write(`[ory-agent] ${line}\n`);
+        if (this.logFile) {
+            const dir = path.dirname(this.logFile);
+            if (!fs.existsSync(dir)) {
+                fs.mkdirSync(dir, { recursive: true });
+            }
+            fs.appendFileSync(this.logFile, line + "\n");
+        }
+    }
+    debug(event, data) {
+        this.log("debug", event, data);
+    }
+    info(event, data) {
+        this.log("info", event, data);
+    }
+    warn(event, data) {
+        this.log("warn", event, data);
+    }
+    error(event, data) {
+        this.log("error", event, data);
+    }
+}
+exports.DebugLogger = DebugLogger;

package/dist/mcp.d.ts

@@ -0,0 +1,76 @@
+/**
+ * MCP (Model Context Protocol) server authorization.
+ *
+ * Provides types, parsers, and permission check helpers for securing
+ * MCP tool calls across all harness plugins. Each harness represents
+ * MCP tools differently — parsers normalize them into McpToolIdentifier,
+ * and checkMcpPermission runs server-level (and optionally tool-level)
+ * Ory permission checks.
+ */
+import type { OryAgentClient } from "./client.js";
+import type { UserSubjectRef } from "./subject.js";
+export interface McpToolIdentifier {
+    /** The MCP server name (e.g., "github", "slack", "postgres"). */
+    serverName: string;
+    /** The tool name within the server (e.g., "create_issue", "query"). */
+    toolName: string;
+}
+export interface McpPermissionCheckOptions {
+    /**
+     * Subject for the permission check. Either a direct SubjectID
+     * (e.g. `session:abc123`) or a SubjectSet (e.g. `User:<UUID>`).
+     * Build with `resolveUserSubject(client, fallback)`.
+     */
+    subject: UserSubjectRef;
+    /** Namespace for server-level checks. Default: "mcp_servers". */
+    serverNamespace?: string;
+    /** Namespace for tool-level checks. Default: "mcp_tools". */
+    toolNamespace?: string;
+    /** Whether to also check tool-level permission. Default: false. */
+    checkToolLevel?: boolean;
+    /**
+     * Attributes merged into the permission.check / permission.batch_check
+     * trace spans. Use this to carry the harness-side tool name and any
+     * other context the Zanzibar tuple shape doesn't capture.
+     */
+    spanAttributes?: Record<string, unknown>;
+}
+export interface McpPermissionResult {
+    /** Whether the server-level check passed. */
+    serverAllowed: boolean;
+    /** Whether the tool-level check passed (true if not checked). */
+    toolAllowed: boolean;
+    /** Combined result: both server and tool (if checked) must be allowed. */
+    allowed: boolean;
+    checkedAt: string;
+    mcpTool: McpToolIdentifier;
+}
+/**
+ * Parse a Claude Code MCP tool name of the form `mcp__<server>__<tool>`.
+ * Returns null if the name doesn't match the MCP pattern.
+ *
+ * Claude Code uses double underscores as delimiters. The first `__` after
+ * the `mcp__` prefix separates the server name from the tool name. Server
+ * names may contain single underscores.
+ */
+export declare function parseClaudeCodeMcpTool(toolName: string): McpToolIdentifier | null;
+/**
+ * Parse MCP context from Gemini CLI hook input.
+ * Gemini provides server info via the `mcp_context` field.
+ */
+export declare function parseGeminiMcpTool(toolName: string, mcpContext?: Record<string, unknown>): McpToolIdentifier | null;
+/**
+ * Generic MCP tool parser for harnesses that use a `mcp:<server>:<tool>`
+ * convention. Returns null if the tool ID doesn't start with the prefix.
+ */
+export declare function parseMcpToolGeneric(toolId: string, mcpPrefix?: string): McpToolIdentifier | null;
+/**
+ * Check MCP server-level (and optionally tool-level) permissions.
+ *
+ * Server check: namespace=mcp_servers, object=<serverName>, relation=use
+ * Tool check:   namespace=mcp_tools,   object=<server>:<tool>, relation=invoke
+ *
+ * The subject is whatever the caller resolved (SubjectSet or direct ID).
+ * Throws on API errors — callers handle fail-open behavior.
+ */
+export declare function checkMcpPermission(client: OryAgentClient, mcpTool: McpToolIdentifier, options: McpPermissionCheckOptions): Promise<McpPermissionResult>;

package/dist/mcp.js

@@ -0,0 +1,122 @@
+"use strict";
+/**
+ * MCP (Model Context Protocol) server authorization.
+ *
+ * Provides types, parsers, and permission check helpers for securing
+ * MCP tool calls across all harness plugins. Each harness represents
+ * MCP tools differently — parsers normalize them into McpToolIdentifier,
+ * and checkMcpPermission runs server-level (and optionally tool-level)
+ * Ory permission checks.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseClaudeCodeMcpTool = parseClaudeCodeMcpTool;
+exports.parseGeminiMcpTool = parseGeminiMcpTool;
+exports.parseMcpToolGeneric = parseMcpToolGeneric;
+exports.checkMcpPermission = checkMcpPermission;
+// ─── Parsers ───────────────────────────────────────────────────────
+/**
+ * Parse a Claude Code MCP tool name of the form `mcp__<server>__<tool>`.
+ * Returns null if the name doesn't match the MCP pattern.
+ *
+ * Claude Code uses double underscores as delimiters. The first `__` after
+ * the `mcp__` prefix separates the server name from the tool name. Server
+ * names may contain single underscores.
+ */
+function parseClaudeCodeMcpTool(toolName) {
+    if (!toolName.startsWith("mcp__"))
+        return null;
+    const rest = toolName.slice(5); // remove "mcp__"
+    const idx = rest.indexOf("__");
+    if (idx <= 0 || idx >= rest.length - 2)
+        return null;
+    return {
+        serverName: rest.slice(0, idx),
+        toolName: rest.slice(idx + 2),
+    };
+}
+/**
+ * Parse MCP context from Gemini CLI hook input.
+ * Gemini provides server info via the `mcp_context` field.
+ */
+function parseGeminiMcpTool(toolName, mcpContext) {
+    if (!mcpContext || typeof mcpContext.server_name !== "string")
+        return null;
+    return {
+        serverName: mcpContext.server_name,
+        toolName,
+    };
+}
+/**
+ * Generic MCP tool parser for harnesses that use a `mcp:<server>:<tool>`
+ * convention. Returns null if the tool ID doesn't start with the prefix.
+ */
+function parseMcpToolGeneric(toolId, mcpPrefix = "mcp:") {
+    if (!toolId.startsWith(mcpPrefix))
+        return null;
+    const rest = toolId.slice(mcpPrefix.length);
+    const sepIdx = rest.indexOf(":");
+    if (sepIdx === -1) {
+        return { serverName: rest, toolName: "" };
+    }
+    return {
+        serverName: rest.slice(0, sepIdx),
+        toolName: rest.slice(sepIdx + 1),
+    };
+}
+// ─── Permission Check ──────────────────────────────────────────────
+/**
+ * Check MCP server-level (and optionally tool-level) permissions.
+ *
+ * Server check: namespace=mcp_servers, object=<serverName>, relation=use
+ * Tool check:   namespace=mcp_tools,   object=<server>:<tool>, relation=invoke
+ *
+ * The subject is whatever the caller resolved (SubjectSet or direct ID).
+ * Throws on API errors — callers handle fail-open behavior.
+ */
+async function checkMcpPermission(client, mcpTool, options) {
+    const serverNamespace = options.serverNamespace ??
+        (process.env.ORY_MCP_SERVER_NAMESPACE ?? "mcp_servers");
+    const toolNamespace = options.toolNamespace ??
+        (process.env.ORY_MCP_TOOL_NAMESPACE ?? "mcp_tools");
+    const checkToolLevel = options.checkToolLevel ??
+        process.env.ORY_MCP_TOOL_LEVEL_CHECKS === "true";
+    const serverCheck = {
+        namespace: serverNamespace,
+        object: mcpTool.serverName,
+        relation: "use",
+        ...options.subject,
+    };
+    const spanAttributes = {
+        mcpServer: mcpTool.serverName,
+        ...(mcpTool.toolName ? { mcpTool: mcpTool.toolName } : {}),
+        ...options.spanAttributes,
+    };
+    if (!checkToolLevel || !mcpTool.toolName) {
+        // Server-only check
+        const result = await client.checkPermission(serverCheck, { spanAttributes });
+        return {
+            serverAllowed: result.allowed,
+            toolAllowed: true,
+            allowed: result.allowed,
+            checkedAt: result.checkedAt,
+            mcpTool,
+        };
+    }
+    // Batch check: server + tool
+    const toolCheck = {
+        namespace: toolNamespace,
+        object: `${mcpTool.serverName}:${mcpTool.toolName}`,
+        relation: "invoke",
+        ...options.subject,
+    };
+    const batchResult = await client.batchCheckPermissions([serverCheck, toolCheck], { spanAttributes });
+    const serverAllowed = batchResult.results[0]?.allowed ?? false;
+    const toolAllowed = batchResult.results[1]?.allowed ?? false;
+    return {
+        serverAllowed,
+        toolAllowed,
+        allowed: serverAllowed && toolAllowed,
+        checkedAt: batchResult.checkedAt,
+        mcpTool,
+    };
+}

package/dist/otel/exporter.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Span exporter contract.
+ *
+ * Implementations ship completed TraceSpan records to an external trace
+ * sink (OTLP collector, vendor backend, in-process pipeline, etc.).
+ *
+ * Exporters must never throw. Transport failures, malformed responses,
+ * and shutdown races are all swallowed and logged through whatever
+ * channel the implementation chooses.
+ */
+import type { TraceSpan } from "../tracer.js";
+export interface SpanExporter {
+    /** Best-effort export of one or more spans. Must never throw. */
+    export(spans: ReadonlyArray<TraceSpan>): Promise<void>;
+    /** Flush any pending state and release resources. Must never throw. */
+    shutdown(): Promise<void>;
+}