@ory/argus 0.13.9 → 0.14.0

package/dist/interactive-setup.d.ts

@@ -14,10 +14,10 @@
  *      caller bootstrap permissions from the freshly-cached user identity.
  *
  * The whole wizard is **fail-open and skippable**: on a missing TTY, a
- * `--no-configure` flag, an already-configured plugin (without
- * `--reconfigure`), a missing `ory` CLI, or any `ory` failure it prints the
- * manual `configure` instructions and returns without throwing. Install must
- * never crash because setup was declined or the network was unreachable.
+ * `--no-configure` flag, a declined reconfigure prompt on an already-configured
+ * plugin, a missing `ory` CLI, or any `ory` failure it prints the manual
+ * `configure` instructions and returns without throwing. Install must never
+ * crash because setup was declined or the network was unreachable.
  *
  * The Ory Network integration deliberately reuses the official `ory` CLI
  * rather than re-implementing the Console API: the CLI already owns Network
@@ -32,6 +32,7 @@ import { OryAgentClient } from "./client.js";
 import { ensureUserAuthenticated } from "./user-login.js";
 import { ensureAgentIdentity } from "./agent-auth.js";
 import { ensureLocalOryStack, seedLocalEnvironment } from "./local/index.js";
+import { type CreateProjectApiKeyArgs, type ProjectApiKeyResult } from "./project-api-key.js";
 /** Loopback redirect URIs the PKCE user login expects on the OAuth2 client. */
 export declare const LOOPBACK_REDIRECT_URIS: readonly string[];
 /** Result of running a captured `ory` command. */
@@ -53,6 +54,14 @@ export interface OryCliRunner {
     }): OryExecResult;
     /** Run `ory <args>` inheriting the terminal (for the browser login). */
     execInteractive(args: string[]): number;
+    /**
+     * The resolved `ory` binary this runner invokes (a bare command on `PATH`, or
+     * an absolute path to a plugin-installed binary). Exposed so the web installer
+     * can spawn the interactive browser sign-in (`ory auth`) as a detached child
+     * without blocking the HTTP server's event loop the way `exec` (spawnSync)
+     * would. Absent on stub runners injected by tests.
+     */
+    bin?: string;
 }
 /**
  * Build a runner bound to a specific `ory` binary (a bare command resolved on
@@ -69,6 +78,13 @@ export declare function createOryRunner(oryBin: string): OryCliRunner;
  * still picking up patch/minor fixes.
  */
 export declare const ORY_CLI_NPM_SPEC = "@ory/cli@^1";
+/**
+ * Best-effort install of the Ory CLI into a plugin-managed directory under the
+ * shared data dir, returning a runner bound to the installed binary (or null
+ * on any failure). Uses `npm install --prefix` so nothing global is modified;
+ * the binary lands at `<dataDir>/cli/node_modules/.bin/ory`. Never throws.
+ */
+export declare function installOryCli(): Promise<OryCliRunner | null>;
 export interface InteractiveSetupDeps {
     runner?: OryCliRunner;
     isTtyAvailableFn?: () => boolean;
@@ -87,12 +103,12 @@ export interface InteractiveSetupDeps {
      */
     installOryCliFn?: () => Promise<OryCliRunner | null>;
     /**
-     * Injectable project-API-key minter. Returns the `ory_pat_…` value or null on
-     * any failure. Defaults to {@link createProjectApiKeyViaConsole} (Ory Console
-     * API, authenticated with the `ory` CLI's stored session). Tests stub this to
-     * avoid real HTTP.
+     * Injectable project-API-key minter. Returns the minted `{ value, id }` or
+     * null on any failure. Defaults to {@link createProjectApiKeyViaConsole} (Ory
+     * Console API, authenticated with the `ory` CLI's stored session). Tests stub
+     * this to avoid real HTTP.
      */
-    createProjectApiKeyFn?: (args: CreateProjectApiKeyArgs) => Promise<string | null>;
+    createProjectApiKeyFn?: (args: CreateProjectApiKeyArgs) => Promise<ProjectApiKeyResult | null>;
     /**
      * Injectable validity probe for an already-stored project API key. Returns
      * true when the key still authenticates against Keto, false when it's been
@@ -126,10 +142,125 @@ export interface InteractiveSetupResult {
  * open-coded as a local `postInstallPermissions` helper.
  */
 export declare function runPostInstall(binName: string, harness: string, args?: string[], deps?: InteractiveSetupDeps): Promise<void>;
+export interface OryWorkspace {
+    id: string;
+    name?: string;
+}
+export interface OryProject {
+    id: string;
+    name?: string;
+    slug?: string;
+}
 /**
  * Run the interactive setup wizard. Always resolves; never throws.
  */
 export declare function runInteractiveSetup(binName: string, harness: string, args?: string[], deps?: InteractiveSetupDeps): Promise<InteractiveSetupResult>;
+/**
+ * How the project's permission model relates to the namespace we need:
+ *
+ *   - `present` — the namespace is already defined; grant directly.
+ *   - `empty`   — the project has no model at all (a fresh Ory Network project
+ *                 reports this as `null`, an absent key, an empty list, or an
+ *                 empty `location`); provisioning a minimal model is safe.
+ *   - `merge`   — a model exists and its OPL *source* was fetched (carries it
+ *                 in `opl`), but doesn't define our namespace; we append the
+ *                 namespace to that source and re-upload it, leaving the other
+ *                 namespaces intact.
+ *   - `blocked` — a model provably exists but its source couldn't be retrieved
+ *                 (fetch failed, or only compiled namespace *names* are exposed
+ *                 with no source), so we can't merge and mustn't overwrite.
+ *   - `unknown` — the config couldn't be read/parsed at all; treated as `empty`
+ *                 by the caller (provision a fresh minimal model, prompted).
+ */
+export type PermissionModel = {
+    kind: "present";
+} | {
+    kind: "empty";
+} | {
+    kind: "merge";
+    opl: string;
+} | {
+    kind: "blocked";
+} | {
+    kind: "unknown";
+};
+/**
+ * Inspect the project's permission model. Ory Network reports the config in one
+ * of two shapes: `{ namespaces: [] }` (or `null`) for a project with no model,
+ * and `{ namespaces: { location: "https://….txt" } }` for an OPL-configured
+ * one — where the `.txt` is the full OPL *source*. We fetch that source so a
+ * missing namespace can be merged in rather than clobbering the whole model.
+ */
+export declare function inspectPermissionModel(runner: OryCliRunner, projectId: string, namespace: string): Promise<PermissionModel>;
+/**
+ * Provision a permission model that defines `<namespace>` with a `use`
+ * relation, via `ory update opl`. The namespace becomes an OPL class, so it
+ * must be a valid identifier; if not, we bail (caller guides instead).
+ *
+ * When `existingOpl` is given, the namespace is appended to that source
+ * (preserving the model's other namespaces); otherwise a fresh minimal model
+ * is generated. Writes the OPL to a temp file because `ory update opl` reads
+ * `--file` only (no stdin). Returns true on success.
+ */
+export declare function provisionPermissionModel(runner: OryCliRunner, projectId: string, namespace: string, existingOpl?: string): boolean;
+export declare function oryCliPresent(runner: OryCliRunner): boolean;
+export declare function listProjects(runner: OryCliRunner, workspaceId: string): OryProject[] | null;
+/**
+ * Read the project's current DCR state via `ory get oauth2-config`.
+ * Returns `true`/`false` when the value is known, or `null` when it can't be
+ * determined (CLI error, unparseable output) so the caller falls open and
+ * prompts anyway rather than assuming a state.
+ */
+export declare function dcrEnabled(runner: OryCliRunner, projectId: string): boolean | null;
+/**
+ * Patch the project's oauth2-config to enable Dynamic Client Registration.
+ * Prompt-free; returns true on success. Shared by the TTY wizard's
+ * {@link maybeEnableDcr} and the web installer API.
+ */
+export declare function enableDcr(runner: OryCliRunner, projectId: string): boolean;
+/** How a project's browser-login UI (across both configs) is currently wired. */
+export type LoginUiState = "managed" | "loopback" | "custom_external" | "unknown";
+/**
+ * Classify the project's browser-login UI across the identity-config
+ * (self-service) and oauth2-config (login/consent) URLs:
+ *  - `loopback` — at least one URL points at a `localhost` sample (needs fixing).
+ *  - `custom_external` — a deliberate custom UI is set and none are loopback.
+ *  - `managed` — everything is empty / relative / on the managed AX.
+ *  - `unknown` — neither config could be read.
+ */
+export declare function projectLoginUiState(runner: OryCliRunner, projectId: string): LoginUiState;
+/**
+ * Point the project's browser-login UI at the Ory Managed Account Experience by
+ * clearing any loopback (localhost sample) URLs in *both* the identity-config
+ * (self-service flows) and the oauth2-config (login/consent). Clearing a UI URL
+ * makes Ory Network fall back to the managed AX. Best-effort; returns true when
+ * the patches succeeded (or there was nothing to clear). Never touches a
+ * deliberate non-loopback custom UI.
+ */
+export declare function useManagedAccountExperience(runner: OryCliRunner, projectId: string): boolean;
+/**
+ * Enable OAuth2 Dynamic Client Registration on the project so the agent
+ * identity can self-register (RFC 7591) at runtime. First probes the project's
+ * current DCR state and skips silently when it's already enabled. Otherwise
+ * prompts (default yes) since it changes project-wide config; best-effort and
+ * fail-open — a decline or failure just prints the manual command and continues.
+ */
+/**
+ * Look for an already-provisioned public PKCE client on the project so a
+ * re-run — or another user installing against the same shared project — reuses
+ * the one client instead of minting a duplicate. Matches the current
+ * {@link USER_LOGIN_CLIENT_NAME} *and* any legacy name an older install may
+ * have used, so a rename never orphans a still-valid client. Best-effort: any
+ * CLI or parse failure returns null and the caller falls back to creating one.
+ */
+export declare function findExistingOAuth2Client(runner: OryCliRunner, projectId: string): string | null;
+export declare function createOAuth2Client(runner: OryCliRunner, projectId: string): string | null;
+/**
+ * Parse a JSON list from `ory --format json` output. Tolerates both a bare
+ * array and the `{ <key>: [...] }` envelope the Console list endpoints use.
+ */
+export declare function parseList<T>(stdout: string, key: string): T[] | null;
+export declare function parseObject<T>(stdout: string): T | null;
 /**
  * Derive the canonical Ory Network project SDK/API URL from a project **slug**.
  * The subdomain is always the slug — never the project id. A project id (a
@@ -138,22 +269,12 @@ export declare function runInteractiveSetup(binName: string, harness: string, ar
  * silently misconfigure the plugin.
  */
 export declare function projectUrlFromSlug(slug: string): string;
-export interface CreateProjectApiKeyArgs {
-    projectId: string;
-    /** Human-readable label shown in the Console's API-keys list. */
-    name: string;
-}
 /**
- * Mint an Ory Network **project API key** via the Console API
- * (`POST /projects/{id}/tokens`), authenticated with the `ory` CLI session.
- * Returns the `ory_pat_…` value, or null on any failure (no session, non-2xx,
- * missing value). Never throws — provisioning is best-effort.
- *
- * This is the one place the wizard reaches past the `ory` CLI to the Console
- * API: the CLI (as of v1.3) exposes no project-API-key command, and Keto
- * permission checks can't authenticate without one.
+ * A project URL on a loopback host is the self-hosted local stack (the dev
+ * launcher's gateway on localhost), not a hosted Ory Network project — so the
+ * "Mode" summary should read "local stack" for it.
  */
-export declare function createProjectApiKeyViaConsole(args: CreateProjectApiKeyArgs): Promise<string | null>;
+export declare function isLocalProjectUrl(url: string | undefined): boolean;
 /**
  * Best-effort check that an already-stored project API key still authenticates
  * against Keto. Runs one permission check with the key: if it completes (any