@ory/argus 0.13.8 → 0.14.0

package/dist/status-cli.js

@@ -26,21 +26,6 @@ const cli_invocation_js_1 = require("./cli-invocation.js");
 function resolveNamespace() {
     return process.env.ORY_PERMISSION_NAMESPACE ?? "AgentTools";
 }
-/**
- * Human-readable annotation for where the resolved user-login flag came
- * from, so `status` readers know whether to look at the env var or the
- * config file to change it.
- */
-function formatUserLoginSource(source) {
-    switch (source) {
-        case "env":
-            return " (ORY_USER_LOGIN env var)";
-        case "config":
-            return " (saved in config; change with: configure --user-login|--no-user-login)";
-        case "default":
-            return "";
-    }
-}
 /**
  * Format a relative duration like "4h 32m" or "12s" for a future deadline.
  * Returns "expired" when the deadline has already passed.
@@ -61,27 +46,16 @@ function formatExpiresIn(expiresAtSec, nowMs = Date.now()) {
     return `${remaining}s`;
 }
 /**
- * Render the "User identity" block. Shows the `ORY_USER_LOGIN` state and,
- * when a PKCE token is cached, the resolved subject and expiry.
+ * Render the "User identity" block. The interactive PKCE login runs every
+ * session; this shows the cached token's subject and expiry, if any.
  */
 function printUserIdentitySection() {
-    const resolved = (0, config_js_1.resolveConfig)();
-    const loginOn = resolved.userLogin;
     const tokens = (0, auth_store_js_1.loadTokens)();
     console.log("");
     console.log("User identity (interactive PKCE login):");
-    const loginState = loginOn
-        ? `on${formatUserLoginSource(resolved.userLoginSource)}`
-        : "off (enable with: configure --user-login, or ORY_USER_LOGIN=true)";
-    console.log(`  Login:       ${loginState}`);
     if (!tokens) {
         console.log("  Token cache: empty");
-        if (loginOn) {
-            console.log("  Subject:     (will resolve at next session start)");
-        }
-        else {
-            console.log("  Subject:     (login disabled — no PKCE flow will run)");
-        }
+        console.log("  Subject:     (will resolve at next session start)");
         return;
     }
     const expired = (0, auth_store_js_1.isExpired)(tokens);
@@ -225,7 +199,7 @@ async function printPermissionsSection(binName, harness) {
     }
     const hasUser = !!process.env.ORY_USER_SUBJECT_ID || isUserTokenUsable();
     if (!hasUser) {
-        console.log(`  Coverage:    n/a (no cached user identity — run with ORY_USER_LOGIN=true once,`);
+        console.log(`  Coverage:    n/a (no cached user identity — start a session once to sign in,`);
         console.log(`               or set ORY_USER_SUBJECT_ID to probe a known subject)`);
         return;
     }

package/dist/status-data.d.ts

@@ -0,0 +1,96 @@
+import { type StatusSystemSection } from "./status-system.js";
+export interface PermissionsCoverage {
+    total: number;
+    allowed: number;
+    denied: number;
+    errored: number;
+    errorCode?: string;
+}
+/**
+ * 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.
+ */
+export declare function probePermissionsCoverage(harness: string): Promise<PermissionsCoverage | undefined>;
+export interface StatusConfigSection {
+    configPath: string;
+    /** Whether a config file actually exists at `configPath` (vs. where one would be written). */
+    configExists: boolean;
+    projectUrl?: string;
+    projectUrlSource: "env" | "config" | "none";
+    projectId?: string;
+    projectIdSource: "env" | "config" | "none";
+    /** Human-readable project / workspace names captured at install (display only). */
+    projectName?: string;
+    workspaceName?: string;
+    apiKeyConfigured: boolean;
+    apiKeySource: "env" | "config" | "none";
+    oauth2ClientId?: string;
+    oauth2ClientIdSource: "env" | "config" | "none";
+    /** Display name of the shared PKCE user-login client. Deterministic from
+     *  branding; present only when a client id is configured. */
+    oauth2ClientName?: string;
+    auditOnly: boolean;
+    permissionMode: "observe" | "enforce";
+    permissionModeSource: "env" | "config" | "default";
+    userSubjectNamespace?: string;
+    userSubjectNamespaceSource: "env" | "config" | "none";
+    namespace: string;
+    /** Whether debug logging is on (`ORY_AGENT_DEBUG=true`). Env-only, read at
+     *  process start by the logger — not persisted config, so it's shown read-only. */
+    debugEnabled: boolean;
+}
+export interface StatusUserSection {
+    tokenCache: "empty" | "present" | "stale";
+    subject?: string;
+    expiresInSeconds?: number;
+    clientId?: string;
+}
+export type AgentIdentitySource = "static_api_key" | "static_client_credentials" | "dcr" | "unregistered";
+export interface StatusAgentSection {
+    source: AgentIdentitySource;
+    clientId?: string;
+    subject?: string;
+    registeredAt?: string;
+    projectUrlMismatch?: {
+        registeredAgainst: string;
+        current: string;
+    };
+}
+export type PermissionsCoverageStatus = "audit_only" | "no_project" | "no_catalog" | "no_user" | "bootstrapped" | "partial" | "not_bootstrapped" | "probe_failed";
+export interface StatusPermissionsSection {
+    mode: "observe" | "enforce";
+    namespace: string;
+    coverageStatus: PermissionsCoverageStatus;
+    coverage?: PermissionsCoverage;
+    knownHarnesses?: string[];
+}
+export interface StatusActivityEntry {
+    raw: string;
+    parsed?: Record<string, unknown>;
+}
+export interface StatusActivitySection {
+    traceFile?: string;
+    traceCount: number;
+    recentSpans: StatusActivityEntry[];
+    logFile?: string;
+    logCount: number;
+    recentLogs: StatusActivityEntry[];
+}
+export interface StatusReport {
+    harness: string;
+    config: StatusConfigSection;
+    user: StatusUserSection;
+    agent: StatusAgentSection;
+    permissions: StatusPermissionsSection;
+    activity: StatusActivitySection;
+    /** Core Ory service health (Kratos, Hydra, Keto) — the dashboard's "System information". */
+    system: StatusSystemSection;
+}
+/**
+ * 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).
+ */
+export declare function collectStatusReport(harness: string): Promise<StatusReport>;

package/dist/status-data.js

@@ -0,0 +1,250 @@
+"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.probePermissionsCoverage = probePermissionsCoverage;
+exports.collectStatusReport = collectStatusReport;
+/**
+ * Structured status data — the data-gathering half of the `status` command,
+ * shared by the text renderer ({@link file://./status-cli.ts}) and the local
+ * web dashboard. `collectStatusReport(harness)` returns a plain, serializable
+ * object mirroring every section `status` prints (configuration, user identity,
+ * agent identity, permissions coverage, recent activity), so the two surfaces
+ * never drift.
+ *
+ * The live permission-coverage probe ({@link probePermissionsCoverage}) lives
+ * here too and is imported back by `status-cli.ts`, so there is a single probe
+ * implementation.
+ */
+const config_js_1 = require("./config.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 branding_js_1 = require("./branding.js");
+const tool_catalog_js_1 = require("./tool-catalog.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";
+}
+/**
+ * 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.
+ */
+async function probePermissionsCoverage(harness) {
+    const resolved = (0, config_js_1.resolveConfig)();
+    if (!resolved.projectUrl)
+        return undefined;
+    const catalog = (0, tool_catalog_js_1.getToolCatalog)(harness);
+    if (catalog.length === 0)
+        return undefined;
+    const tokens = (0, auth_store_js_1.loadTokens)();
+    const subjectOverride = process.env.ORY_USER_SUBJECT_ID;
+    if (!subjectOverride && (!tokens || (0, auth_store_js_1.isExpired)(tokens))) {
+        return undefined;
+    }
+    const client = client_js_1.OryAgentClient.fromEnv(harness);
+    if (tokens && !(0, auth_store_js_1.isExpired)(tokens)) {
+        client.setUserPrincipal({ subject: tokens.subject, token: tokens.accessToken });
+    }
+    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")
+        return undefined;
+    const namespace = resolveNamespace();
+    const result = { total: catalog.length, allowed: 0, denied: 0, errored: 0 };
+    for (const tool of catalog) {
+        const check = { namespace, object: tool, relation: "use", ...subject };
+        try {
+            const probe = await client.checkPermission(check, {
+                spanAttributes: { toolName: tool, source: "status_coverage" },
+            });
+            if (probe.allowed)
+                result.allowed++;
+            else
+                result.denied++;
+        }
+        catch (err) {
+            const ory = err;
+            result.errored++;
+            result.errorCode = result.errorCode ?? ory.code ?? "unknown";
+        }
+    }
+    return result;
+}
+function collectConfig(harness) {
+    const r = (0, config_js_1.resolveConfig)();
+    const configPath = (0, config_js_1.getConfigPath)();
+    return {
+        configPath,
+        configExists: fs.existsSync(configPath),
+        projectUrl: r.projectUrl,
+        projectUrlSource: r.projectUrlSource,
+        projectId: r.projectId,
+        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,
+        permissionMode: r.permissionMode,
+        permissionModeSource: r.permissionModeSource,
+        userSubjectNamespace: r.userSubjectNamespace,
+        userSubjectNamespaceSource: r.userSubjectNamespaceSource,
+        namespace: resolveNamespace(),
+        debugEnabled: process.env.ORY_AGENT_DEBUG === "true",
+    };
+}
+function collectUser() {
+    const tokens = (0, auth_store_js_1.loadTokens)();
+    if (!tokens) {
+        return { tokenCache: "empty" };
+    }
+    const nowSec = Math.floor(Date.now() / 1000);
+    return {
+        tokenCache: (0, auth_store_js_1.isExpired)(tokens) ? "stale" : "present",
+        subject: tokens.subject,
+        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 };
+    }
+    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,
+        };
+    }
+    const persisted = (0, agent_auth_js_1.loadAgentDynamicCredentials)();
+    if (!persisted)
+        return { source: "unregistered" };
+    const resolved = (0, config_js_1.resolveConfig)();
+    const mismatch = resolved.projectUrl && persisted.projectUrl !== resolved.projectUrl
+        ? { registeredAgainst: persisted.projectUrl, current: resolved.projectUrl }
+        : undefined;
+    return {
+        source: "dcr",
+        clientId: persisted.clientId,
+        subject: process.env.ORY_AGENT_SUBJECT_ID ?? persisted.clientId,
+        registeredAt: new Date(persisted.registeredAt * 1000).toISOString(),
+        projectUrlMismatch: mismatch,
+    };
+}
+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" };
+    if (catalog.length === 0) {
+        return { ...base, coverageStatus: "no_catalog", knownHarnesses: [...tool_catalog_js_1.KNOWN_HARNESSES] };
+    }
+    const hasUser = !!process.env.ORY_USER_SUBJECT_ID || isUserTokenUsable();
+    if (!hasUser)
+        return { ...base, coverageStatus: "no_user" };
+    const coverage = await probePermissionsCoverage(harness);
+    if (!coverage)
+        return { ...base, coverageStatus: "no_user" };
+    if (coverage.errored > 0 && coverage.allowed === 0 && coverage.denied === 0) {
+        return { ...base, coverageStatus: "probe_failed", coverage };
+    }
+    const status = coverage.allowed === coverage.total
+        ? "bootstrapped"
+        : coverage.allowed === 0
+            ? "not_bootstrapped"
+            : "partial";
+    return { ...base, coverageStatus: status, coverage };
+}
+function isUserTokenUsable() {
+    const tokens = (0, auth_store_js_1.loadTokens)();
+    return !!tokens && !(0, auth_store_js_1.isExpired)(tokens);
+}
+function readTail(file, limit) {
+    if (!file || !fs.existsSync(file))
+        return { file, count: 0, recent: [] };
+    const lines = fs.readFileSync(file, "utf-8").trim().split("\n").filter(Boolean);
+    const recent = lines.slice(-limit).map((raw) => {
+        try {
+            return { raw, parsed: JSON.parse(raw) };
+        }
+        catch {
+            return { raw };
+        }
+    });
+    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,
+    };
+}
+/**
+ * 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).
+ */
+async function collectStatusReport(harness) {
+    return {
+        harness,
+        config: collectConfig(harness),
+        user: collectUser(),
+        agent: collectAgent(),
+        permissions: await collectPermissions(harness),
+        activity: collectActivity(harness),
+        system: await (0, status_system_js_1.collectSystemServices)(),
+    };
+}

package/dist/status-system.d.ts

@@ -0,0 +1,24 @@
+export interface StatusSystemService {
+    /** Service name, e.g. "Kratos". */
+    name: string;
+    /** One-line role, e.g. "Identities & sessions". */
+    role: string;
+    /** Published host port. */
+    port: number;
+    /** Base URL for the service. */
+    url: string;
+    /** The endpoint probed to decide health. */
+    healthUrl: string;
+    /** true = healthy, false = unreachable/error, null = not probed. */
+    healthy: boolean | null;
+    /** Human-readable detail (HTTP status or error) when unhealthy. */
+    detail?: string;
+}
+export interface StatusSystemSection {
+    services: StatusSystemService[];
+}
+/**
+ * Probe the core Ory services' readiness endpoints and return their health.
+ * Never throws — an unreachable service is reported as `healthy: false`.
+ */
+export declare function collectSystemServices(): Promise<StatusSystemSection>;

package/dist/status-system.js

@@ -0,0 +1,56 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.collectSystemServices = collectSystemServices;
+/**
+ * System-information probe for the dashboard: the health of the core Ory
+ * backend services the plugin authenticates and authorizes against — Kratos
+ * (identities), Hydra (OAuth2), and Keto (permissions).
+ *
+ * This is additive to the shared {@link file://./status-data.ts} report: the
+ * dashboard renders it as a "System information" section, while the installer
+ * simply ignores it. Ports and health endpoints are the same constants the
+ * local-stack manager and `local status` use, so the surfaces never disagree.
+ */
+const configs_js_1 = require("./local/configs.js");
+/** The three core Ory services, in display order. */
+function systemServiceSpecs() {
+    return [
+        { name: "Kratos", role: "Identities & sessions", port: configs_js_1.KRATOS_PUBLIC_PORT, healthPath: "/health/ready" },
+        { name: "Hydra", role: "OAuth2 & OIDC", port: configs_js_1.HYDRA_PUBLIC_PORT, healthPath: "/health/ready" },
+        { name: "Keto", role: "Permissions (Zanzibar relation checks)", port: configs_js_1.KETO_READ_PORT, healthPath: "/health/ready" },
+    ];
+}
+async function probe(healthUrl) {
+    try {
+        const res = await fetch(healthUrl, { signal: AbortSignal.timeout(2500) });
+        if (res.ok)
+            return { healthy: true };
+        return { healthy: false, detail: `HTTP ${res.status}` };
+    }
+    catch (err) {
+        return { healthy: false, detail: err instanceof Error ? err.message : String(err) };
+    }
+}
+/**
+ * Probe the core Ory services' readiness endpoints and return their health.
+ * Never throws — an unreachable service is reported as `healthy: false`.
+ */
+async function collectSystemServices() {
+    const specs = systemServiceSpecs();
+    const services = await Promise.all(specs.map(async (spec) => {
+        const url = `http://localhost:${spec.port}`;
+        const healthUrl = `${url}${spec.healthPath}`;
+        const { healthy, detail } = await probe(healthUrl);
+        const service = {
+            name: spec.name,
+            role: spec.role,
+            port: spec.port,
+            url,
+            healthUrl,
+            healthy,
+            detail,
+        };
+        return service;
+    }));
+    return { services };
+}

package/dist/testing.d.ts

@@ -14,6 +14,14 @@ export { runHarnessContractSuite, type HarnessContractAdapter, type ContractCont
  * Pass overrides to customize (e.g. a different harness name).
  */
 export declare function createMockClient(overrides?: Partial<ConstructorParameters<typeof OryAgentClient>[0]>): OryAgentClient;
+/**
+ * Control what the exact-tuple existence probe ({@link OryAgentClient.relationshipExists},
+ * used by `ensureRelationship`) reports. Pass `true` to model a tuple that is
+ * already stored (the write is then skipped), `false` for absent (the write
+ * proceeds). Returns the spy so callers can e.g. `.mockRejectedValue(...)` to
+ * model a failed probe.
+ */
+export declare function stubRelationshipExists(client: OryAgentClient, exists: boolean): import("vitest").Mock<(check: import("./types.js").PermissionCheck) => Promise<boolean>>;
 /**
  * Stub an internal API instance method on the client.
  * Returns a vi.fn mock so callers can assert on calls.

package/dist/testing.js

@@ -42,6 +42,7 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.BATCH_SERVER_DENIED = exports.BATCH_SERVER_ALLOWED_TOOL_DENIED = exports.BATCH_BOTH_ALLOWED = exports.PERMISSION_DENIED = exports.PERMISSION_ALLOWED = exports.MOCK_INACTIVE_OAUTH2_RESPONSE = exports.MOCK_OAUTH2_RESPONSE = exports.MOCK_INACTIVE_SESSION_RESPONSE = exports.MOCK_SESSION_RESPONSE = exports.runHarnessContractSuite = void 0;
 exports.createMockClient = createMockClient;
+exports.stubRelationshipExists = stubRelationshipExists;
 exports.stubApi = stubApi;
 exports.makeAxiosError = makeAxiosError;
 exports.makeNetworkError = makeNetworkError;
@@ -85,13 +86,31 @@ Object.defineProperty(exports, "runHarnessContractSuite", { enumerable: true, ge
  * Pass overrides to customize (e.g. a different harness name).
  */
 function createMockClient(overrides) {
-    return new client_js_1.OryAgentClient({
+    const client = new client_js_1.OryAgentClient({
         projectUrl: "https://test.projects.oryapis.com",
         apiKey: "test-api-key",
         harness: "test",
         sessionCacheTtlMs: 0,
         ...overrides,
     });
+    // `ensureRelationship` probes for the exact tuple before writing. Default
+    // to "no tuple exists" so a plain createRelationship-asserting test sees the
+    // write proceed; tests that model an already-present tuple override this via
+    // `stubRelationshipExists`. We spy the public `relationshipExists` method
+    // (not the internal getRelationships API) because setAgentPrincipal rebuilds
+    // the Keto API instance and would discard an API-level stub.
+    vitest_1.vi.spyOn(client, "relationshipExists").mockResolvedValue(false);
+    return client;
+}
+/**
+ * Control what the exact-tuple existence probe ({@link OryAgentClient.relationshipExists},
+ * used by `ensureRelationship`) reports. Pass `true` to model a tuple that is
+ * already stored (the write is then skipped), `false` for absent (the write
+ * proceeds). Returns the spy so callers can e.g. `.mockRejectedValue(...)` to
+ * model a failed probe.
+ */
+function stubRelationshipExists(client, exists) {
+    return vitest_1.vi.spyOn(client, "relationshipExists").mockResolvedValue(exists);
 }
 /**
  * Stub an internal API instance method on the client.

package/dist/uninstall.d.ts

@@ -1,25 +1,37 @@
 /**
- * Credential teardown shared by every plugin's `uninstall` command.
+ * Config teardown shared by every plugin's `uninstall` command.
  *
- * Uninstalling a plugin removes all *authentication* state from the shared
- * config file while preserving *configuration* (project URL, OAuth2 client
- * id, audit mode, permission mode, user-login flag). The intent is that a
- * later re-install re-authenticates from scratch — the user logs in again
- * and the agent registers a fresh dynamic client — rather than silently
- * inheriting stale credentials.
+ * Uninstalling a plugin wipes the shared config file completely — every
+ * value is removed, both *authentication* state (user tokens, agent DCR
+ * credentials, static API key) and *configuration* (project URL, OAuth2
+ * client id, audit mode, permission mode, user-login flag). The file is
+ * left as an empty object, so a later re-install starts from a clean
+ * slate rather than inheriting any stale state.
  *
  * What is removed:
  *   - the user's persisted OAuth2 tokens (`user`)
  *   - the agent's dynamic-registration credentials and every sub-agent
  *     registration (`agent`)
  *   - the operator-supplied static agent API key (`apiKey`)
+ *   - all configuration values (`projectUrl`, `projectId`, `projectName`,
+ *     `workspaceName`, `oauth2ClientId`, `auditOnly`, `permissionMode`,
+ *     `userLogin`, `userSubjectNamespace`)
  *   - any dangling PKCE-flight lock
  *
- * Before clearing local state, each dynamically-registered client (the
- * agent and each sub-agent) is revoked server-side via RFC 7592 so the
- * Ory project isn't left with orphaned OAuth2 clients accumulating across
- * install/uninstall cycles. Revocation is best-effort: failures warn and
- * local state is cleared regardless.
+ * Server-side teardown runs first, best-effort:
+ *   - Each dynamically-registered OAuth2 client (the agent and every
+ *     sub-agent) is revoked via RFC 7592, so the Ory project isn't left
+ *     with orphaned clients accumulating across install/uninstall cycles.
+ *   - The project API key the installer minted is deleted via the Ory
+ *     Console API (addressed by the persisted token id).
+ *
+ * The one server-side resource deliberately **left behind** is the shared
+ * user-login PKCE OAuth2 client (`oauth2ClientId`): it is a public,
+ * identity-free client that every user and every harness install on the
+ * project reuses, so deleting it would break other installations. It is
+ * only forgotten locally (its id is wiped from the config file). Every
+ * server-side step is best-effort: failures warn and local state is
+ * cleared regardless.
  */
 export interface ClearCredentialsOptions {
     /**
@@ -38,10 +50,16 @@ export interface ClearCredentialsResult {
     revoked: number;
     /** Number of dynamic clients whose server-side revoke failed. */
     revokeFailures: number;
+    /**
+     * Whether the project API key was deleted server-side (includes an
+     * already-gone key). `false` when there was none to delete, its token id
+     * wasn't tracked, or the deletion failed/was skipped.
+     */
+    apiKeyDeleted: boolean;
 }
 /**
- * Remove all authentication state from the shared config file, revoking
- * dynamically-registered clients server-side first. Preserves every
- * non-credential configuration value. Never throws.
+ * Wipe the shared config file completely — every value, both credentials
+ * and configuration — revoking dynamically-registered clients server-side
+ * first. The file is left as an empty object. Never throws.
  */
 export declare function clearCredentialsForUninstall(options?: ClearCredentialsOptions): Promise<ClearCredentialsResult>;