@ory/argus 0.14.0 → 1.0.0

package/dist/interactive-setup.d.ts

@@ -1,286 +0,0 @@
-/**
- * Interactive install wizard. Runs after a harness plugin has been
- * registered, stepping the user through connecting the plugin to Ory:
- *
- *   1. Choose a connection: **Ory Network** (browser login / account
- *      creation) or **local / audit-only** (no project, audit logging only).
- *   2. Ory Network branch: shell out to the official `ory` CLI to log in,
- *      pick a workspace, pick a project (→ `projectUrl`), and create the
- *      public OAuth2 client the PKCE user login needs (→ `oauth2ClientId`).
- *   3. Persist the resolved values to the shared config file and enable the
- *      interactive user login.
- *   4. Best-effort "full setup": run the PKCE user login now (we hold the
- *      project URL + client id), resolve the agent DCR identity, and let the
- *      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, 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
- * browser login + account creation, workspace/project listing, and OAuth2
- * client creation, and the client it creates is exactly the one the plugin
- * READMEs document for manual setup. The one exception is minting the project
- * API key that runtime permission checks need — the CLI exposes no command for
- * it, so that single step calls the Console API directly, reusing the CLI's
- * stored session for auth (see {@link createProjectApiKeyViaConsole}).
- */
-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. */
-export interface OryExecResult {
-    /** Exit code; `null` when the process could not be spawned (CLI missing). */
-    status: number | null;
-    stdout: string;
-    stderr: string;
-}
-/**
- * Thin, injectable wrapper around the `ory` binary. Tests stub this to drive
- * the wizard without a real CLI; the default implementation shells out.
- */
-export interface OryCliRunner {
-    /** Run `ory <args>` capturing stdout/stderr. `opts.input` is written to
-     *  the child's stdin (used to feed JSON to `ory create relationships -f -`). */
-    exec(args: string[], opts?: {
-        input?: string;
-    }): 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
- * `PATH`, or an absolute path to a plugin-installed binary). {@link defaultRunner}
- * uses the bare `"ory"`; {@link installOryCli} returns one bound to the binary
- * it just installed.
- */
-export declare function createOryRunner(oryBin: string): OryCliRunner;
-/**
- * npm spec for the Ory CLI installed on demand when the `ory` binary isn't on
- * `PATH`. `@ory/cli` ships the platform `ory` binary and exposes it as its
- * `bin`, so an isolated `npm install` gives us a working CLI without touching
- * the user's global environment. Pinned to a major to stay reproducible while
- * 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;
-    promptFn?: (prompt: string) => Promise<string | null>;
-    clientFactory?: (harness: string) => OryAgentClient;
-    userLoginFn?: typeof ensureUserAuthenticated;
-    agentGateFn?: typeof ensureAgentIdentity;
-    /** Injectable local-stack bring-up (defaults to {@link ensureLocalOryStack}). */
-    localStackFn?: typeof ensureLocalOryStack;
-    /** Injectable local-stack seeder (defaults to {@link seedLocalEnvironment}). */
-    seedFn?: typeof seedLocalEnvironment;
-    /**
-     * Injectable Ory-CLI installer used when the `ory` binary isn't on `PATH`.
-     * Returns a runner bound to the installed binary, or null if the install
-     * failed. Defaults to a real `npm install` of {@link ORY_CLI_NPM_SPEC}.
-     */
-    installOryCliFn?: () => Promise<OryCliRunner | null>;
-    /**
-     * 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<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
-     * revoked/deleted (so provisioning re-mints one). Defaults to
-     * {@link apiKeyAuthenticates}. Tests stub this to avoid real HTTP.
-     */
-    validateApiKeyFn?: (apiKey: string, projectUrl: string) => Promise<boolean>;
-}
-export type InteractiveSetupOutcome = "skipped_flag" | "skipped_no_tty" | "skipped_configured" | "audit_only" | "local_configured" | "network_configured" | "network_fallback";
-export interface InteractiveSetupResult {
-    outcome: InteractiveSetupOutcome;
-    projectUrl?: string;
-    oauth2ClientId?: string;
-    /** Whether a user identity was authenticated during the wizard. */
-    userAuthenticated?: boolean;
-    /**
-     * When true, the caller should NOT run the DCR-token-based
-     * {@link maybeAutoBootstrap}. The wizard bootstraps permissions itself via
-     * the admin-authenticated `ory` CLI on the Ory Network path — the runtime
-     * agent/user tokens can't write relation tuples on a hosted project, so
-     * running maybeAutoBootstrap there would only produce 403s.
-     */
-    skipAutoBootstrap?: boolean;
-}
-/**
- * The shared post-install entry point every harness's `install` command
- * calls. Runs the interactive setup wizard, then (using whatever identity the
- * wizard cached) bootstraps permissions and prints the onboarding banner.
- *
- * This is the single seam that centralizes what each harness previously
- * 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
- * UUID) reaching here means a slug and an id were confused upstream, which
- * would build a URL that points nowhere, so we refuse it loudly rather than
- * silently misconfigure the plugin.
- */
-export declare function projectUrlFromSlug(slug: string): string;
-/**
- * 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 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
- * `allowed` value) the key is valid; an auth rejection (`session_inactive` /
- * `forbidden` / `session_aal2_required`) means it was revoked or deleted, so we
- * return false and the caller re-provisions. Transient failures (network /
- * rate-limit / unknown) return true so we don't re-mint on a blip. Never throws.
- */
-export declare function apiKeyAuthenticates(apiKey: string, projectUrl: string): Promise<boolean>;