@ory/argus 0.1.0

package/dist/client.js

@@ -0,0 +1,679 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OryAgentClient = void 0;
+exports.extractOryRequestId = extractOryRequestId;
+const client_1 = require("@ory/client");
+const logger_js_1 = require("./logger.js");
+const tracer_js_1 = require("./tracer.js");
+const config_js_1 = require("./config.js");
+const otlp_http_js_1 = require("./otel/otlp-http.js");
+class OryAgentClient {
+    frontend;
+    oauth2;
+    permission;
+    relationship;
+    config;
+    logger;
+    tracer;
+    sessionCache = new Map();
+    sessionCacheTtlMs;
+    /**
+     * The human user — the principal whose permissions we check.
+     * Populated by `ensureUserAuthenticated` on session start.
+     */
+    _userPrincipal = {};
+    /**
+     * The AI agent process — the principal that authenticates outgoing
+     * Ory API calls. Populated by `ensureAgentIdentity`.
+     */
+    _agentPrincipal = {};
+    constructor(config) {
+        this.config = config;
+        this.sessionCacheTtlMs = config.sessionCacheTtlMs ?? 60_000;
+        this.logger = new logger_js_1.DebugLogger(config.harness, {
+            logFile: config.logFile,
+        });
+        this.tracer = new tracer_js_1.Tracer({
+            harness: config.harness,
+            traceFile: config.traceFile,
+            ...(config.exporter ? { exporter: config.exporter } : {}),
+        });
+        // Seed agent principal from the constructor `apiKey` so existing
+        // call sites keep working until they migrate to ensureAgentIdentity.
+        if (config.apiKey)
+            this._agentPrincipal.token = config.apiKey;
+        const { frontend, oauth2, permission, relationship } = this.buildApis();
+        this.frontend = frontend;
+        this.oauth2 = oauth2;
+        this.permission = permission;
+        this.relationship = relationship;
+    }
+    /** Build a fresh set of Ory API instances using the current agent token. */
+    buildApis() {
+        const accessToken = this._agentPrincipal.token;
+        const apiConfig = new client_1.Configuration({
+            basePath: this.config.projectUrl,
+            ...(accessToken ? { accessToken } : {}),
+        });
+        return {
+            frontend: new client_1.FrontendApi(apiConfig),
+            oauth2: new client_1.OAuth2Api(apiConfig),
+            permission: new client_1.PermissionApi(apiConfig),
+            relationship: new client_1.RelationshipApi(apiConfig),
+        };
+    }
+    /** Snapshot of the current user principal. */
+    get userPrincipal() {
+        return { ...this._userPrincipal };
+    }
+    /** Snapshot of the current agent principal. */
+    get agentPrincipal() {
+        return { ...this._agentPrincipal };
+    }
+    /**
+     * Set or update the human user principal. The user is the subject of
+     * permission checks but does not authenticate outgoing API calls.
+     * Pass `{}` (or fields set to undefined) to clear.
+     */
+    setUserPrincipal(principal) {
+        this._userPrincipal = { ...principal };
+    }
+    /**
+     * Set or update the AI agent principal. The agent's token (when
+     * present) is used in the Authorization header for all outgoing Ory
+     * API calls — so the audit log shows "agent X acting on behalf of
+     * user Y". Rebuilds the underlying Ory API instances when the token
+     * actually changes so subsequent calls pick it up; otherwise leaves
+     * the API instances alone (so test stubs survive a no-op update).
+     */
+    setAgentPrincipal(principal) {
+        const tokenChanged = this._agentPrincipal.token !== principal.token;
+        this._agentPrincipal = { ...principal };
+        if (!tokenChanged)
+            return;
+        const { frontend, oauth2, permission, relationship } = this.buildApis();
+        this.frontend = frontend;
+        this.oauth2 = oauth2;
+        this.permission = permission;
+        this.relationship = relationship;
+    }
+    // ─── Session (Ory Identities / Kratos) ──────────────────────────
+    /**
+     * Verify an existing session token. Returns cached result if available.
+     */
+    async verifySession(sessionToken) {
+        this.logger.debug("session.verify.start", { hasToken: !!sessionToken });
+        // Check cache
+        const cached = this.sessionCache.get(sessionToken);
+        if (cached && cached.expiresAt > Date.now()) {
+            this.logger.debug("session.verify.cached", {
+                sessionId: cached.info.sessionId,
+            });
+            return cached.info;
+        }
+        const span = this.tracer.startSpan("session.verify");
+        try {
+            const response = await this.frontend.toSession({
+                xSessionToken: sessionToken,
+            });
+            const session = response.data;
+            const oryRequestId = extractOryRequestId(response.headers);
+            const info = {
+                sessionId: session.id,
+                identityId: session.identity.id,
+                active: session.active ?? false,
+                authenticatedAt: session.authenticated_at ?? "",
+                expiresAt: session.expires_at,
+                authenticatorAssuranceLevel: session.authenticator_assurance_level,
+                authenticationMethods: session.authentication_methods?.map((m) => ({
+                    method: m.method ?? "unknown",
+                    completedAt: m.completed_at,
+                })),
+                traits: session.identity.traits ?? {},
+            };
+            // Cache the result
+            if (this.sessionCacheTtlMs > 0) {
+                this.sessionCache.set(sessionToken, {
+                    info,
+                    expiresAt: Date.now() + this.sessionCacheTtlMs,
+                });
+            }
+            this.logger.info("session.verify.success", {
+                sessionId: info.sessionId,
+                identityId: info.identityId,
+                active: info.active,
+                aal: info.authenticatorAssuranceLevel,
+            });
+            span.end("ok", {
+                sessionId: info.sessionId,
+                identityId: info.identityId,
+                active: info.active,
+                ...(oryRequestId ? { oryRequestId } : {}),
+            });
+            return info;
+        }
+        catch (err) {
+            const oryErr = this.classifyError(err);
+            this.logger.error("session.verify.failed", {
+                code: oryErr.code,
+                status: oryErr.status,
+                message: oryErr.message,
+            });
+            span.end("error", {
+                error: oryErr.code,
+                ...(oryErr.requestId ? { oryRequestId: oryErr.requestId } : {}),
+            });
+            throw oryErr;
+        }
+    }
+    // ─── OAuth2 Token (Ory OAuth2 / Hydra) ──────────────────────────
+    /**
+     * Introspect an OAuth2 access token. Use this when agents authenticate
+     * via client credentials flow instead of session tokens.
+     */
+    async introspectToken(token, scope) {
+        this.logger.debug("oauth2.introspect.start", { hasToken: !!token });
+        const span = this.tracer.startSpan("oauth2.introspect");
+        try {
+            const response = await this.oauth2.introspectOAuth2Token({
+                token,
+                scope,
+            });
+            const data = response.data;
+            const oryRequestId = extractOryRequestId(response.headers);
+            const info = {
+                active: data.active,
+                clientId: data.client_id,
+                scope: data.scope,
+                subject: data.sub,
+                audience: data.aud,
+                expiresAt: data.exp,
+                issuedAt: data.iat,
+                tokenUse: data.token_use,
+                extra: data.ext,
+            };
+            this.logger.info("oauth2.introspect.result", {
+                active: info.active,
+                clientId: info.clientId,
+                subject: info.subject,
+            });
+            span.end("ok", {
+                active: info.active,
+                clientId: info.clientId,
+                subject: info.subject,
+                ...(oryRequestId ? { oryRequestId } : {}),
+            });
+            return info;
+        }
+        catch (err) {
+            const oryErr = this.classifyError(err);
+            this.logger.error("oauth2.introspect.failed", {
+                code: oryErr.code,
+                status: oryErr.status,
+                message: oryErr.message,
+            });
+            span.end("error", {
+                error: oryErr.code,
+                ...(oryErr.requestId ? { oryRequestId: oryErr.requestId } : {}),
+            });
+            throw oryErr;
+        }
+    }
+    // ─── Permissions (Ory Permissions / Keto) ────────────────────────
+    /**
+     * Check if a subject has permission to perform an action.
+     *
+     * `options.spanAttributes` are merged into the `permission.check` trace
+     * span so callers can attach harness-side context (toolName, mcpServer,
+     * etc.) that the wire-level `PermissionCheck` shape doesn't carry.
+     */
+    async checkPermission(check, options) {
+        this.logger.debug("permission.check.start", { ...check });
+        const span = this.tracer.startSpan("permission.check", {
+            attributes: {
+                object: check.object,
+                relation: check.relation,
+                ...this.principalSpanAttributes(),
+                ...options?.spanAttributes,
+            },
+        });
+        try {
+            const response = await this.permission.checkPermission({
+                namespace: check.namespace,
+                object: check.object,
+                relation: check.relation,
+                subjectId: check.subjectId,
+                subjectSetNamespace: check.subjectSet?.namespace,
+                subjectSetObject: check.subjectSet?.object,
+                subjectSetRelation: check.subjectSet?.relation,
+            });
+            const data = response.data;
+            const oryRequestId = extractOryRequestId(response.headers);
+            const result = {
+                allowed: data.allowed,
+                checkedAt: new Date().toISOString(),
+                check,
+            };
+            this.logger.info("permission.check.result", {
+                allowed: result.allowed,
+                namespace: check.namespace,
+                object: check.object,
+                relation: check.relation,
+                subjectId: check.subjectId,
+                subjectSet: check.subjectSet,
+            });
+            span.end(result.allowed ? "ok" : "denied", {
+                allowed: result.allowed,
+                ...(oryRequestId ? { oryRequestId } : {}),
+            });
+            return result;
+        }
+        catch (err) {
+            const oryErr = this.classifyError(err);
+            this.logger.error("permission.check.failed", {
+                code: oryErr.code,
+                status: oryErr.status,
+                message: oryErr.message,
+                ...check,
+            });
+            span.end("error", {
+                error: oryErr.code,
+                ...(oryErr.requestId ? { oryRequestId: oryErr.requestId } : {}),
+            });
+            throw oryErr;
+        }
+    }
+    /**
+     * Check multiple permissions in a single request.
+     *
+     * `options.spanAttributes` are merged into the `permission.batch_check`
+     * span — same purpose as `checkPermission`'s spanAttributes.
+     */
+    async batchCheckPermissions(checks, options) {
+        this.logger.debug("permission.batch_check.start", {
+            count: checks.length,
+        });
+        const span = this.tracer.startSpan("permission.batch_check", {
+            attributes: {
+                count: checks.length,
+                ...this.principalSpanAttributes(),
+                ...options?.spanAttributes,
+            },
+        });
+        try {
+            const response = await this.permission.batchCheckPermission({
+                batchCheckPermissionBody: {
+                    tuples: checks.map((c) => ({
+                        namespace: c.namespace,
+                        object: c.object,
+                        relation: c.relation,
+                        subject_id: c.subjectId,
+                        subject_set: c.subjectSet
+                            ? {
+                                namespace: c.subjectSet.namespace,
+                                object: c.subjectSet.object,
+                                relation: c.subjectSet.relation,
+                            }
+                            : undefined,
+                    })),
+                },
+            });
+            const data = response.data;
+            const oryRequestId = extractOryRequestId(response.headers);
+            const result = {
+                results: data.results.map((r) => ({
+                    allowed: r.allowed,
+                    error: r.error,
+                })),
+                checks,
+                checkedAt: new Date().toISOString(),
+            };
+            const allowed = result.results.filter((r) => r.allowed).length;
+            const denied = result.results.filter((r) => !r.allowed).length;
+            this.logger.info("permission.batch_check.result", {
+                count: checks.length,
+                allowed,
+                denied,
+            });
+            span.end("ok", {
+                allowed,
+                denied,
+                ...(oryRequestId ? { oryRequestId } : {}),
+            });
+            return result;
+        }
+        catch (err) {
+            const oryErr = this.classifyError(err);
+            this.logger.error("permission.batch_check.failed", {
+                code: oryErr.code,
+                status: oryErr.status,
+                message: oryErr.message,
+            });
+            span.end("error", {
+                error: oryErr.code,
+                ...(oryErr.requestId ? { oryRequestId: oryErr.requestId } : {}),
+            });
+            throw oryErr;
+        }
+    }
+    // ─── Relationships (Ory Permissions / Keto write API) ────────────
+    /**
+     * Create a relation tuple in Keto. Idempotent: a 409 (tuple already
+     * exists) is swallowed and reported as success. All other errors are
+     * classified and re-thrown — callers wrap in fail-open semantics if
+     * the tuple is non-critical (e.g. audit-only delegation tracking).
+     *
+     * `options.spanAttributes` are merged into the `relationship.create`
+     * trace span so callers can attach context like `delegation: "user→agent"`.
+     */
+    async createRelationship(check, options) {
+        this.logger.debug("relationship.create.start", { ...check });
+        const span = this.tracer.startSpan("relationship.create", {
+            attributes: {
+                namespace: check.namespace,
+                object: check.object,
+                relation: check.relation,
+                ...this.principalSpanAttributes(),
+                ...options?.spanAttributes,
+            },
+        });
+        try {
+            const response = await this.relationship.createRelationship({
+                createRelationshipBody: {
+                    namespace: check.namespace,
+                    object: check.object,
+                    relation: check.relation,
+                    subject_id: check.subjectId,
+                    ...(check.subjectSet
+                        ? {
+                            subject_set: {
+                                namespace: check.subjectSet.namespace,
+                                object: check.subjectSet.object,
+                                relation: check.subjectSet.relation,
+                            },
+                        }
+                        : {}),
+                },
+            });
+            const oryRequestId = extractOryRequestId(response.headers);
+            this.logger.info("relationship.create.result", {
+                namespace: check.namespace,
+                object: check.object,
+                relation: check.relation,
+                subjectId: check.subjectId,
+            });
+            span.end("ok", {
+                created: true,
+                ...(oryRequestId ? { oryRequestId } : {}),
+            });
+            return { created: true, alreadyExisted: false };
+        }
+        catch (err) {
+            const oryErr = this.classifyError(err);
+            // Keto returns 409 when the tuple already exists; treat as success
+            // so callers can call this on every session start without dedup.
+            if (oryErr.status === 409) {
+                this.logger.debug("relationship.create.exists", {
+                    namespace: check.namespace,
+                    object: check.object,
+                    relation: check.relation,
+                });
+                span.end("ok", {
+                    created: false,
+                    alreadyExisted: true,
+                    ...(oryErr.requestId ? { oryRequestId: oryErr.requestId } : {}),
+                });
+                return { created: false, alreadyExisted: true };
+            }
+            this.logger.error("relationship.create.failed", {
+                code: oryErr.code,
+                status: oryErr.status,
+                message: oryErr.message,
+                ...check,
+            });
+            span.end("error", {
+                error: oryErr.code,
+                ...(oryErr.requestId ? { oryRequestId: oryErr.requestId } : {}),
+            });
+            throw oryErr;
+        }
+    }
+    /**
+     * Delete a relation tuple in Keto. Missing tuples (404) are treated as
+     * success so callers can call this idempotently when unwinding state.
+     */
+    async deleteRelationship(check, options) {
+        this.logger.debug("relationship.delete.start", { ...check });
+        const span = this.tracer.startSpan("relationship.delete", {
+            attributes: {
+                namespace: check.namespace,
+                object: check.object,
+                relation: check.relation,
+                ...this.principalSpanAttributes(),
+                ...options?.spanAttributes,
+            },
+        });
+        try {
+            const response = await this.relationship.deleteRelationships({
+                namespace: check.namespace,
+                object: check.object,
+                relation: check.relation,
+                subjectId: check.subjectId,
+                ...(check.subjectSet
+                    ? {
+                        subjectSetNamespace: check.subjectSet.namespace,
+                        subjectSetObject: check.subjectSet.object,
+                        subjectSetRelation: check.subjectSet.relation,
+                    }
+                    : {}),
+            });
+            const oryRequestId = extractOryRequestId(response.headers);
+            span.end("ok", {
+                deleted: true,
+                ...(oryRequestId ? { oryRequestId } : {}),
+            });
+            return { deleted: true, notFound: false };
+        }
+        catch (err) {
+            const oryErr = this.classifyError(err);
+            if (oryErr.code === "not_found") {
+                span.end("ok", {
+                    deleted: false,
+                    notFound: true,
+                    ...(oryErr.requestId ? { oryRequestId: oryErr.requestId } : {}),
+                });
+                return { deleted: false, notFound: true };
+            }
+            this.logger.error("relationship.delete.failed", {
+                code: oryErr.code,
+                status: oryErr.status,
+                message: oryErr.message,
+                ...check,
+            });
+            span.end("error", {
+                error: oryErr.code,
+                ...(oryErr.requestId ? { oryRequestId: oryErr.requestId } : {}),
+            });
+            throw oryErr;
+        }
+    }
+    /**
+     * Span attributes describing which principals were attached to the
+     * client when the span was started. Useful for correlating audit logs
+     * across the user/agent split.
+     */
+    principalSpanAttributes() {
+        const out = {};
+        if (this._userPrincipal.subject)
+            out.userSubject = this._userPrincipal.subject;
+        if (this._agentPrincipal.subject)
+            out.agentSubject = this._agentPrincipal.subject;
+        return out;
+    }
+    // ─── Error Classification ────────────────────────────────────────
+    /**
+     * Classify an error from any Ory API call into a structured OryError.
+     */
+    classifyError(err) {
+        // Axios errors have a `response` property with status + data
+        if (this.isAxiosError(err)) {
+            const status = err.response?.status;
+            const body = err.response?.data;
+            const errorId = body?.error?.id;
+            const message = body?.error?.message ?? err.message ?? "Unknown Ory error";
+            const requestId = extractOryRequestId(err.response?.headers);
+            let code;
+            switch (status) {
+                case 401:
+                    code =
+                        errorId === "session_aal2_required"
+                            ? "session_aal2_required"
+                            : "session_inactive";
+                    break;
+                case 403:
+                    code =
+                        errorId === "session_aal2_required"
+                            ? "session_aal2_required"
+                            : "forbidden";
+                    break;
+                case 404:
+                    code = "not_found";
+                    break;
+                case 429:
+                    code = "rate_limited";
+                    break;
+                default:
+                    code = "unknown";
+            }
+            return {
+                code,
+                status,
+                message,
+                ...(requestId ? { requestId } : {}),
+                cause: err,
+            };
+        }
+        // Network errors (no response received)
+        if (err instanceof Error && "code" in err) {
+            const netErr = err;
+            if (netErr.code === "ECONNREFUSED" ||
+                netErr.code === "ECONNRESET" ||
+                netErr.code === "ENOTFOUND" ||
+                netErr.code === "ETIMEDOUT") {
+                return {
+                    code: "network_error",
+                    message: `Network error: ${netErr.code} — ${netErr.message}`,
+                    cause: err,
+                };
+            }
+        }
+        return {
+            code: "unknown",
+            message: err instanceof Error ? err.message : String(err),
+            cause: err,
+        };
+    }
+    isAxiosError(err) {
+        return (typeof err === "object" &&
+            err !== null &&
+            "isAxiosError" in err &&
+            err.isAxiosError === true);
+    }
+    // ─── Factory ─────────────────────────────────────────────────────
+    /**
+     * Create a client from environment variables.
+     */
+    /**
+     * Create a client from environment variables, falling back to the
+     * shared config file at ~/.config/ory-agent-plugins/config.json.
+     *
+     * Resolution order for projectUrl and apiKey:
+     *   1. Environment variables (ORY_PROJECT_URL, ORY_API_KEY)
+     *   2. Config file (~/.config/ory-agent-plugins/config.json)
+     *   3. Placeholder (fail-open pass-through mode)
+     */
+    static fromEnv(harness) {
+        const resolved = (0, config_js_1.resolveConfig)();
+        const projectUrl = resolved.projectUrl;
+        if (!projectUrl) {
+            // Use a placeholder URL so the client can be constructed.
+            // API calls will fail with network_error which is handled as fail-open.
+            const client = new OryAgentClient({
+                projectUrl: "http://localhost:0",
+                apiKey: resolved.apiKey,
+                harness,
+                logFile: process.env.ORY_AGENT_LOG_FILE,
+                traceFile: process.env.ORY_AGENT_TRACE_FILE,
+                sessionCacheTtlMs: process.env.ORY_SESSION_CACHE_TTL_MS
+                    ? parseInt(process.env.ORY_SESSION_CACHE_TTL_MS, 10)
+                    : undefined,
+            });
+            client.logger.warn("config.missing_project_url", {
+                message: "ORY_PROJECT_URL is not set and no config file found. " +
+                    "Ory integration is disabled — all hooks will pass through. " +
+                    "Set ORY_PROJECT_URL or run the plugin's configure command.",
+            });
+            attachOtlpExporterFromEnv(client, harness);
+            return client;
+        }
+        const client = new OryAgentClient({
+            projectUrl,
+            apiKey: resolved.apiKey,
+            harness,
+            logFile: process.env.ORY_AGENT_LOG_FILE,
+            traceFile: process.env.ORY_AGENT_TRACE_FILE,
+            sessionCacheTtlMs: process.env.ORY_SESSION_CACHE_TTL_MS
+                ? parseInt(process.env.ORY_SESSION_CACHE_TTL_MS, 10)
+                : undefined,
+        });
+        client.logger.debug("config.resolved", {
+            projectUrlSource: resolved.projectUrlSource,
+            apiKeySource: resolved.apiKeySource,
+        });
+        attachOtlpExporterFromEnv(client, harness);
+        return client;
+    }
+}
+exports.OryAgentClient = OryAgentClient;
+function attachOtlpExporterFromEnv(client, harness) {
+    const meta = client.tracer.processMetadata;
+    const exporter = (0, otlp_http_js_1.otlpExporterFromEnv)({
+        harness,
+        hostname: meta.hostname,
+        user: meta.user,
+        pluginVersion: meta.pluginVersion,
+        cwd: meta.cwd,
+        gitBranch: meta.gitBranch,
+        gitCommit: meta.gitCommit,
+        onError: (err) => client.logger.warn("otel.export.failed", {
+            message: err instanceof Error ? err.message : String(err),
+        }),
+    });
+    if (!exporter)
+        return;
+    client.tracer.setExporter(exporter);
+    client.logger.info("otel.export.enabled", {
+        endpoint: process.env.OTEL_EXPORTER_OTLP_TRACES_ENDPOINT ??
+            process.env.OTEL_EXPORTER_OTLP_ENDPOINT ??
+            process.env.ORY_OTLP_ENDPOINT,
+        serviceName: process.env.OTEL_SERVICE_NAME ?? `ory-agent-plugin-${harness}`,
+    });
+}
+/**
+ * Pull the Ory backend request ID from a response headers bag (axios returns
+ * lowercase header names). Returns undefined when not present.
+ */
+function extractOryRequestId(headers) {
+    if (!headers || typeof headers !== "object")
+        return undefined;
+    const bag = headers;
+    const value = bag["x-request-id"] ??
+        bag["X-Request-Id"] ??
+        bag["X-Request-ID"] ??
+        bag["ory-request-id"];
+    if (typeof value === "string" && value.length > 0)
+        return value;
+    if (Array.isArray(value) && typeof value[0] === "string")
+        return value[0];
+    return undefined;
+}