@ory/argus 0.13.9 → 0.14.0

package/dist/uninstall.js

@@ -1,36 +1,49 @@
 "use strict";
 /**
- * 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.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.clearCredentialsForUninstall = clearCredentialsForUninstall;
 const config_js_1 = require("./config.js");
 const agent_auth_js_1 = require("./agent-auth.js");
 const auth_store_js_1 = require("./auth-store.js");
+const project_api_key_js_1 = require("./project-api-key.js");
 /**
- * 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.
  */
 async function clearCredentialsForUninstall(options = {}) {
     const log = options.log ?? ((msg) => console.log(msg));
@@ -40,12 +53,13 @@ async function clearCredentialsForUninstall(options = {}) {
     const subAgents = config.agent?.subAgents ?? {};
     const subAgentEntries = Object.entries(subAgents);
     const hadCredentials = Boolean(config.user || dynamic || subAgentEntries.length > 0 || config.apiKey);
-    if (!hadCredentials) {
-        log("No stored Ory credentials to remove.");
-        return { hadCredentials: false, revoked: 0, revokeFailures: 0 };
+    if (Object.keys(config).length === 0) {
+        log("No Ory configuration to remove.");
+        return { hadCredentials: false, revoked: 0, revokeFailures: 0, apiKeyDeleted: false };
     }
     let revoked = 0;
     let revokeFailures = 0;
+    let apiKeyDeleted = false;
     if (revoke) {
         const targets = [];
         if (dynamic) {
@@ -81,10 +95,39 @@ async function clearCredentialsForUninstall(options = {}) {
                 log(`  Warning: server-side revoke of ${target.label} ${target.clientId} failed (${detail}). Clearing local state anyway.`);
             }
         }
+        // Delete the project API key the installer minted. Deletion addresses the
+        // token by its id (its secret value can't be used), so it needs both the
+        // project id and the persisted token id. A key present without a tracked id
+        // (minted before id-tracking, or supplied by hand via `configure --api-key`)
+        // can't be removed automatically — warn so it can be pruned in the Console.
+        if (config.apiKey) {
+            if (config.projectId && config.apiKeyId) {
+                const outcome = await (0, project_api_key_js_1.deleteProjectApiKeyViaConsole)({
+                    projectId: config.projectId,
+                    tokenId: config.apiKeyId,
+                });
+                if (outcome.status === "deleted") {
+                    apiKeyDeleted = true;
+                    log("  Deleted the project API key.");
+                }
+                else if (outcome.status === "skipped") {
+                    log(`  Could not delete the project API key (${outcome.message}). Clearing local state anyway.`);
+                }
+                else {
+                    const detail = typeof outcome.httpStatus === "number"
+                        ? `HTTP ${outcome.httpStatus}`
+                        : (outcome.message ?? "unknown error");
+                    log(`  Warning: server-side deletion of the project API key failed (${detail}). Clearing local state anyway.`);
+                }
+            }
+            else {
+                log("  The stored project API key has no tracked token id — remove it manually in the Ory Console if it's no longer needed. Clearing local state anyway.");
+            }
+        }
     }
-    // Drop every credential block; keep all configuration values.
-    (0, config_js_1.saveConfig)({ user: null, agent: null, apiKey: null });
+    // Wipe the entire config file — credentials and configuration alike.
+    (0, config_js_1.mutateConfig)(() => ({}));
     (0, auth_store_js_1.clearPkceFlightLock)();
-    log("Removed stored Ory credentials (user login, agent identity, API key).");
-    return { hadCredentials: true, revoked, revokeFailures };
+    log("Removed all Ory configuration and credentials.");
+    return { hadCredentials, revoked, revokeFailures, apiKeyDeleted };
 }

package/dist/user-login.d.ts

@@ -17,11 +17,15 @@
  * Every terminal path emits exactly one `user.auth` trace span so that
  * the audit trail is complete regardless of outcome.
  *
- * The whole flow is a no-op (mode `disabled`) unless user login is
- * enabled — either via the `ORY_USER_LOGIN` env var (values `1`, `true`,
- * `yes`, `on`) or persisted in the shared config file (`userLogin: true`,
- * set with `configure --user-login`). The env var overrides the config
- * file when set.
+ * The flow runs on **every** session and is **never** blocking: it
+ * establishes or refreshes the user identity for attribution, delegation,
+ * and permission-subject resolution, but a failure to authenticate never
+ * stops the session. Enforcement is governed solely by `permissionMode`
+ * (observe/enforce) at tool-call time — see `checkAndDecide`. The one
+ * exception is `auditOnly`, which disables auth entirely (mode
+ * `audit_only`). When the user can't be authenticated the session still
+ * proceeds; under `enforce` a missing user identity naturally denies at
+ * the tool (no matching tuples), and under `observe` it is audited.
  *
  * This authenticates the *user* (the human at the keyboard). The
  * separate agent identity (the AI process making the calls) is resolved
@@ -32,14 +36,12 @@ import { OryAgentClient } from "./client.js";
 import { type OryOAuth2Tokens } from "./config.js";
 import { promptForProjectUrl } from "./cli.js";
 import { pkceLogin } from "./auth.js";
-export type UserLoginMode = "disabled" | "audit_only" | "env_token" | "ok" | "refreshed" | "skipped" | "declined" | "error";
+export type UserLoginMode = "audit_only" | "env_token" | "ok" | "refreshed" | "skipped" | "declined" | "error";
 export interface UserLoginOptions {
     /** Bin name used in user-facing prompts (e.g. "ory-claude"). */
     binName: string;
     /** Logical harness name (used by the tracer). */
     harness: string;
-    /** Whether the caller can hard-block on auth failure. */
-    allowBlock: boolean;
     /**
      * Optional override of the PKCE login function — used by tests and by
      * harnesses that want to plug in a different flow.
@@ -51,7 +53,12 @@ export interface UserLoginOptions {
     promptForProjectUrlFn?: typeof promptForProjectUrl;
 }
 export interface UserLoginDecision {
-    /** Whether the caller should let the session proceed. */
+    /**
+     * Whether the caller should let the session proceed. User authentication
+     * is non-blocking, so this is **always** `true` — it is retained so the
+     * session-start adapters keep a stable shape. Enforcement lives in
+     * `permissionMode` at tool-call time, not here.
+     */
     proceed: boolean;
     /** Stable mode identifier for telemetry and tests. */
     mode: UserLoginMode;

package/dist/user-login.js

@@ -18,11 +18,15 @@
  * Every terminal path emits exactly one `user.auth` trace span so that
  * the audit trail is complete regardless of outcome.
  *
- * The whole flow is a no-op (mode `disabled`) unless user login is
- * enabled — either via the `ORY_USER_LOGIN` env var (values `1`, `true`,
- * `yes`, `on`) or persisted in the shared config file (`userLogin: true`,
- * set with `configure --user-login`). The env var overrides the config
- * file when set.
+ * The flow runs on **every** session and is **never** blocking: it
+ * establishes or refreshes the user identity for attribution, delegation,
+ * and permission-subject resolution, but a failure to authenticate never
+ * stops the session. Enforcement is governed solely by `permissionMode`
+ * (observe/enforce) at tool-call time — see `checkAndDecide`. The one
+ * exception is `auditOnly`, which disables auth entirely (mode
+ * `audit_only`). When the user can't be authenticated the session still
+ * proceeds; under `enforce` a missing user identity naturally denies at
+ * the tool (no matching tuples), and under `observe` it is audited.
  *
  * This authenticates the *user* (the human at the keyboard). The
  * separate agent identity (the AI process making the calls) is resolved
@@ -37,12 +41,6 @@ const cli_js_1 = require("./cli.js");
 const cli_invocation_js_1 = require("./cli-invocation.js");
 const auth_store_js_1 = require("./auth-store.js");
 const auth_js_1 = require("./auth.js");
-function isUserLoginEnabled() {
-    // Resolves ORY_USER_LOGIN (env, when set) over the persisted
-    // `userLogin` config flag. Centralized in resolveConfig so the gate,
-    // status CLI, and configure command stay in lockstep.
-    return (0, config_js_1.resolveConfig)().userLogin;
-}
 function clientId() {
     // resolveConfig already merges env (ORY_OAUTH2_CLIENT_ID) with the
     // persisted value, env winning. Centralizing here keeps the user gate,
@@ -71,15 +69,6 @@ function recordAuthSpan(client, decision) {
  * to authenticate the human user. Always returns a decision; never throws.
  */
 async function ensureUserAuthenticated(client, options) {
-    if (!isUserLoginEnabled()) {
-        const decision = {
-            proceed: true,
-            mode: "disabled",
-            reason: "User login is not enabled (ORY_USER_LOGIN env / userLogin config)",
-        };
-        recordAuthSpan(client, decision);
-        return decision;
-    }
     try {
         const decision = await runUserLogin(client, options);
         attachUserPrincipal(client, decision);
@@ -88,7 +77,7 @@ async function ensureUserAuthenticated(client, options) {
     }
     catch (err) {
         const decision = {
-            proceed: !options.allowBlock,
+            proceed: true,
             mode: "error",
             reason: err instanceof Error ? err.message : String(err),
         };
@@ -146,7 +135,7 @@ async function runUserLogin(client, options) {
     if (!resolved.projectUrl) {
         if (!tty) {
             return {
-                proceed: !options.allowBlock,
+                proceed: true,
                 mode: "skipped",
                 reason: "No ORY_PROJECT_URL configured and no TTY to prompt",
             };
@@ -155,7 +144,7 @@ async function runUserLogin(client, options) {
         const url = await promptFn(options.binName);
         if (!url) {
             return {
-                proceed: !options.allowBlock,
+                proceed: true,
                 mode: "declined",
                 reason: "User declined to enter an Ory project URL",
             };
@@ -163,7 +152,7 @@ async function runUserLogin(client, options) {
         resolved = (0, config_js_1.resolveConfig)();
         if (!resolved.projectUrl) {
             return {
-                proceed: !options.allowBlock,
+                proceed: true,
                 mode: "error",
                 reason: "Project URL was entered but config did not persist",
             };
@@ -220,7 +209,7 @@ async function runUserLogin(client, options) {
     const cid = clientId();
     if (!cid) {
         return {
-            proceed: !options.allowBlock,
+            proceed: true,
             mode: "skipped",
             reason: "ORY_OAUTH2_CLIENT_ID is not set; cannot start browser login (run `" +
                 (0, cli_invocation_js_1.oryNpx)(options.binName) +
@@ -236,7 +225,8 @@ async function runUserLogin(client, options) {
     // complete sign-in by pasting the URL into any browser that can reach
     // 127.0.0.1. Truly unattended runs (CI=true) are short-circuited by
     // `pkceLogin` itself via `detectHeadless`, and operators can bypass
-    // login entirely with `ORY_USER_SESSION_TOKEN` or `ORY_USER_LOGIN=false`.
+    // login entirely by supplying `ORY_USER_SESSION_TOKEN`, and enforcement
+    // consequences are governed by `permissionMode`, not by this gate.
     // PKCE-flight lock so concurrent processes share a single browser flow.
     const lock = (0, auth_store_js_1.tryAcquirePkceFlightLock)();
     if (!lock) {
@@ -251,7 +241,7 @@ async function runUserLogin(client, options) {
             };
         }
         return {
-            proceed: !options.allowBlock,
+            proceed: true,
             mode: "skipped",
             reason: "Another agent process is mid-login; gave up waiting",
         };
@@ -272,7 +262,7 @@ async function runUserLogin(client, options) {
             };
         }
         return {
-            proceed: !options.allowBlock,
+            proceed: true,
             mode: declineToMode(outcome.reason),
             reason: declineMessage(outcome.reason),
         };

package/dist/web/api.d.ts

@@ -0,0 +1,33 @@
+/**
+ * JSON API for the local web installer / status dashboard. Each route is a
+ * thin wrapper over a headless action in {@link file://../setup-actions.ts} or
+ * the status data in {@link file://../status-data.ts}. All state for one
+ * install run (the resolved `ory` runner, the selected workspace/project, and
+ * the in-flight browser sub-flows) lives in a single {@link SetupSession} held
+ * by the server for its lifetime.
+ *
+ * Handlers never throw for expected failures — they return an `{ error }`
+ * envelope with an appropriate HTTP status so the SPA can surface it and the
+ * user can retry, exactly like the TTY wizard's fail-open steps.
+ */
+import { type SetupActionDeps } from "../setup-actions.js";
+import type { WebAppMode } from "./types.js";
+export interface ApiResult {
+    status: number;
+    json: unknown;
+}
+export interface ApiContext {
+    mode: WebAppMode;
+    harness: string;
+    binName: string;
+    deps: SetupActionDeps;
+    /** Called when the SPA POSTs /api/shutdown. */
+    onShutdown: () => void;
+}
+/**
+ * Build the API request handler bound to one server run. Returns
+ * `handle(method, path, body)` producing an {@link ApiResult}.
+ */
+export declare function createApi(ctx: ApiContext): {
+    handle: (method: string, path: string, body: Record<string, unknown>) => Promise<ApiResult>;
+};

package/dist/web/api.js

@@ -0,0 +1,294 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createApi = createApi;
+/**
+ * JSON API for the local web installer / status dashboard. Each route is a
+ * thin wrapper over a headless action in {@link file://../setup-actions.ts} or
+ * the status data in {@link file://../status-data.ts}. All state for one
+ * install run (the resolved `ory` runner, the selected workspace/project, and
+ * the in-flight browser sub-flows) lives in a single {@link SetupSession} held
+ * by the server for its lifetime.
+ *
+ * Handlers never throw for expected failures — they return an `{ error }`
+ * envelope with an appropriate HTTP status so the SPA can surface it and the
+ * user can retry, exactly like the TTY wizard's fail-open steps.
+ */
+const setup_actions_js_1 = require("../setup-actions.js");
+const status_data_js_1 = require("../status-data.js");
+const config_js_1 = require("../config.js");
+const version_cli_js_1 = require("../version-cli.js");
+const ok = (json = { ok: true }) => ({ status: 200, json });
+const bad = (error, status = 400) => ({ status, json: { error } });
+/**
+ * Build the API request handler bound to one server run. Returns
+ * `handle(method, path, body)` producing an {@link ApiResult}.
+ */
+function createApi(ctx) {
+    const session = {
+        runner: ctx.deps.runner ?? null,
+        subject: null,
+    };
+    /** The runner to use, failing loudly if `POST /api/ory-cli` hasn't run. */
+    function runner() {
+        return session.runner;
+    }
+    async function handle(method, path, body) {
+        const route = `${method} ${path}`;
+        switch (route) {
+            case "GET /api/bootstrap": {
+                const cfg = (0, config_js_1.resolveConfig)();
+                const payload = {
+                    mode: ctx.mode,
+                    harness: ctx.harness,
+                    binName: ctx.binName,
+                    version: (0, version_cli_js_1.resolveCoreVersion)(),
+                    alreadyConfigured: !!cfg.projectUrl || cfg.auditOnly,
+                    auditOnly: cfg.auditOnly,
+                    projectUrl: cfg.projectUrl,
+                };
+                return ok(payload);
+            }
+            case "GET /api/status":
+                return ok(await (0, status_data_js_1.collectStatusReport)(ctx.harness));
+            case "POST /api/ory-cli": {
+                const res = await (0, setup_actions_js_1.ensureOryCli)(ctx.deps);
+                session.runner = res.runner;
+                return ok({ present: res.present, installed: res.installed });
+            }
+            case "GET /api/signin": {
+                const r = runner();
+                return ok({ signedIn: r ? (0, setup_actions_js_1.isSignedIn)(r) : false });
+            }
+            case "POST /api/signin": {
+                const r = runner();
+                if (!r)
+                    return bad("Ory CLI is not ready", 409);
+                if ((0, setup_actions_js_1.isSignedIn)(r))
+                    return ok({ started: false, signedIn: true });
+                const handle = (0, setup_actions_js_1.startSignIn)(r);
+                const task = { handle, state: "running" };
+                session.signIn = task;
+                handle.done.then((success) => {
+                    task.state = success ? "done" : "failed";
+                });
+                return ok({ started: true, signedIn: false });
+            }
+            case "GET /api/signin/status": {
+                const r = runner();
+                const task = session.signIn;
+                const state = task?.state ?? "idle";
+                // Treat a live session as done even if we never launched `ory auth`
+                // (the CLI may already have been signed in).
+                const signedIn = state === "done" || (!!r && (0, setup_actions_js_1.isSignedIn)(r));
+                return ok({ state: signedIn ? "done" : state, signedIn });
+            }
+            case "GET /api/workspaces": {
+                const r = runner();
+                if (!r)
+                    return bad("Ory CLI is not ready", 409);
+                const workspaces = (0, setup_actions_js_1.listWorkspaces)(r);
+                if (workspaces === null)
+                    return bad("Could not list workspaces", 502);
+                session.workspaces = workspaces;
+                return ok({ workspaces });
+            }
+            case "POST /api/workspaces": {
+                const r = runner();
+                if (!r)
+                    return bad("Ory CLI is not ready", 409);
+                const name = str(body.name);
+                if (!name)
+                    return bad("A workspace name is required");
+                const res = (0, setup_actions_js_1.createWorkspace)(r, name);
+                if (!res.ok)
+                    return bad(res.error ?? "Could not create workspace", 502);
+                return ok({ workspace: res.value });
+            }
+            case "GET /api/projects": {
+                const r = runner();
+                if (!r)
+                    return bad("Ory CLI is not ready", 409);
+                const workspaceId = str(body.workspaceId);
+                if (!workspaceId)
+                    return bad("A workspaceId is required");
+                session.workspaceId = workspaceId;
+                session.workspaceName = session.workspaces?.find((w) => w.id === workspaceId)?.name;
+                const projects = (0, setup_actions_js_1.listProjects)(r, workspaceId);
+                if (projects === null)
+                    return bad("Could not list projects", 502);
+                return ok({ projects, cap: setup_actions_js_1.PROJECT_CAP, canCreate: projects.length < setup_actions_js_1.PROJECT_CAP });
+            }
+            case "POST /api/projects": {
+                const r = runner();
+                if (!r)
+                    return bad("Ory CLI is not ready", 409);
+                const workspaceId = str(body.workspaceId) ?? session.workspaceId;
+                const name = str(body.name);
+                if (!workspaceId || !name)
+                    return bad("workspaceId and name are required");
+                const res = (0, setup_actions_js_1.createProject)(r, workspaceId, name);
+                if (!res.ok)
+                    return bad(res.error ?? "Could not create project", 502);
+                return ok({ project: res.value });
+            }
+            case "POST /api/select-project": {
+                const r = runner();
+                if (!r)
+                    return bad("Ory CLI is not ready", 409);
+                const project = body.project;
+                if (!project?.id)
+                    return bad("A project is required");
+                const url = (0, setup_actions_js_1.resolveProjectUrl)(project);
+                if (!url.ok)
+                    return bad(url.error ?? "Could not resolve project URL", 422);
+                session.project = project;
+                session.projectUrl = url.value;
+                // Ensure the OAuth2 login/consent UI is the Ory Managed Account
+                // Experience so the PKCE user login (step 7) renders a working page —
+                // a CLI-created project defaults these to the localhost:3000 sample.
+                const loginUi = (0, setup_actions_js_1.ensureManagedLoginUi)(r, project.id);
+                return ok({ projectUrl: url.value, dcrEnabled: (0, setup_actions_js_1.getDcrState)(r, project.id), loginUi });
+            }
+            case "POST /api/enable-dcr": {
+                const r = runner();
+                if (!r || !session.project)
+                    return bad("No project selected", 409);
+                return ok({ ok: (0, setup_actions_js_1.enableDcrAction)(r, session.project.id) });
+            }
+            case "POST /api/oauth2-client": {
+                const r = runner();
+                if (!r || !session.project)
+                    return bad("No project selected", 409);
+                const res = (0, setup_actions_js_1.provisionOAuth2Client)(r, session.project.id);
+                if (!res.ok || !res.clientId)
+                    return bad("Could not provision the OAuth2 client", 502);
+                session.oauth2ClientId = res.clientId;
+                return ok({ clientId: res.clientId, reused: res.reused, name: res.name });
+            }
+            case "POST /api/save": {
+                if (!session.project || !session.projectUrl || !session.oauth2ClientId) {
+                    return bad("Setup is incomplete (missing project / client)", 409);
+                }
+                (0, setup_actions_js_1.saveNetworkConfig)({
+                    projectUrl: session.projectUrl,
+                    projectId: session.project.id,
+                    oauth2ClientId: session.oauth2ClientId,
+                    projectName: session.project.name ?? session.project.slug,
+                    workspaceName: session.workspaceName,
+                });
+                return ok();
+            }
+            case "POST /api/login": {
+                if (session.login?.state === "running")
+                    return ok({ started: false });
+                // Pin the project the wizard resolved so a stale ORY_PROJECT_URL in the
+                // user's shell can't send the login to the wrong URL (e.g. :3000).
+                const task = {
+                    promise: (0, setup_actions_js_1.runFullSetup)(ctx.binName, ctx.harness, ctx.deps, {
+                        projectUrl: session.projectUrl,
+                        oauth2ClientId: session.oauth2ClientId,
+                    }),
+                    state: "running",
+                };
+                session.login = task;
+                task.promise.then((result) => {
+                    task.state = result.authenticated ? "done" : "failed";
+                    task.result = result;
+                    if (result.subject) {
+                        session.subject = result.subject;
+                        // The login only resolves an opaque subject id; look the identity up
+                        // via the admin CLI to show a readable name (email) instead of a UUID.
+                        const sid = "subjectId" in result.subject
+                            ? result.subject.subjectId
+                            : result.subject.subjectSet.object;
+                        const r = session.runner;
+                        if (r && session.project && sid) {
+                            const name = (0, setup_actions_js_1.resolveIdentityName)(r, session.project.id, sid);
+                            if (name)
+                                task.result = { ...result, subjectLabel: name };
+                        }
+                    }
+                });
+                return ok({ started: true });
+            }
+            case "GET /api/login/status": {
+                const task = session.login;
+                return ok({
+                    state: task?.state ?? "idle",
+                    authenticated: task?.result?.authenticated ?? false,
+                    subjectLabel: task?.result?.subjectLabel ?? null,
+                });
+            }
+            case "GET /api/permissions/model": {
+                const r = runner();
+                if (!r || !session.project)
+                    return bad("No project selected", 409);
+                return ok(await (0, setup_actions_js_1.inspectPermissions)(r, session.project.id));
+            }
+            case "POST /api/permissions/provision": {
+                const r = runner();
+                if (!r || !session.project)
+                    return bad("No project selected", 409);
+                const opl = str(body.opl);
+                return ok({ ok: (0, setup_actions_js_1.provisionPermissions)(r, session.project.id, undefined, opl) });
+            }
+            case "POST /api/permissions/grant": {
+                const r = runner();
+                if (!r || !session.project)
+                    return bad("No project selected", 409);
+                if (!session.subject)
+                    return bad("Sign in first so permissions can be granted to you", 409);
+                const res = (0, setup_actions_js_1.grantToolPermissions)(r, session.project.id, ctx.harness, session.subject);
+                return ok(res);
+            }
+            case "POST /api/api-key": {
+                if (!session.project || !session.projectUrl)
+                    return bad("No project selected", 409);
+                const res = await (0, setup_actions_js_1.provisionProjectApiKey)({
+                    projectId: session.project.id,
+                    projectUrl: session.projectUrl,
+                    harness: ctx.harness,
+                    user: session.subject
+                        ? (0, setup_actions_js_1.resourceUserLabel)(runner(), session.project.id, session.subject)
+                        : undefined,
+                }, ctx.deps);
+                return ok(res);
+            }
+            case "POST /api/audit-only": {
+                (0, setup_actions_js_1.configureAuditOnly)();
+                return ok();
+            }
+            // Live toggle from the dashboard (permission posture).
+            case "POST /api/config": {
+                const patch = {};
+                if ("permissionMode" in body) {
+                    if (body.permissionMode !== "observe" && body.permissionMode !== "enforce") {
+                        return bad("permissionMode must be 'observe' or 'enforce'");
+                    }
+                    (0, setup_actions_js_1.setPermissionMode)(body.permissionMode);
+                    patch.permissionMode = body.permissionMode;
+                }
+                if (Object.keys(patch).length === 0)
+                    return bad("No supported config fields in request");
+                return ok(patch);
+            }
+            case "POST /api/local": {
+                const res = await (0, setup_actions_js_1.configureLocalStack)(ctx.deps);
+                // Record the local connection so the subsequent login pins to it too.
+                session.projectUrl = res.projectUrl;
+                session.oauth2ClientId = res.oauth2ClientId;
+                return ok(res);
+            }
+            case "POST /api/shutdown": {
+                ctx.onShutdown();
+                return ok();
+            }
+            default:
+                return bad(`Unknown route: ${route}`, 404);
+        }
+    }
+    return { handle };
+}
+function str(v) {
+    return typeof v === "string" && v.trim() ? v.trim() : undefined;
+}

package/dist/web/launch.d.ts

@@ -0,0 +1,11 @@
+import type { SetupActionDeps } from "../setup-actions.js";
+/**
+ * Heuristic for whether we can meaningfully open a browser for the user:
+ * an interactive TTY, not CI, not opted-out, and — on Linux — an actual
+ * display server. macOS/Windows are assumed to have a default browser.
+ */
+export declare function canLaunchBrowser(): boolean;
+/** Open the guided install/setup wizard in the browser. */
+export declare function launchWebInstaller(binName: string, harness: string, deps?: SetupActionDeps): Promise<boolean>;
+/** Open the status dashboard in the browser. */
+export declare function launchWebDashboard(binName: string, harness: string, deps?: SetupActionDeps): Promise<boolean>;