@ory/argus 0.13.9 → 1.0.0

package/dist/interactive-setup.d.ts

@@ -1,165 +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, 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.
- *
- * 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";
-/** 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;
-}
-/**
- * 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";
-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 `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.
-     */
-    createProjectApiKeyFn?: (args: CreateProjectApiKeyArgs) => Promise<string | 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>;
-/**
- * Run the interactive setup wizard. Always resolves; never throws.
- */
-export declare function runInteractiveSetup(binName: string, harness: string, args?: string[], deps?: InteractiveSetupDeps): Promise<InteractiveSetupResult>;
-/**
- * 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;
-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.
- */
-export declare function createProjectApiKeyViaConsole(args: CreateProjectApiKeyArgs): Promise<string | null>;
-/**
- * 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>;