@ory/argus 0.13.8 → 0.14.0

package/dist/setup-actions.d.ts

@@ -0,0 +1,232 @@
+/**
+ * Headless setup actions — the prompt-free, presentation-free core of the
+ * install walkthrough, driven by the local web installer's JSON API (and
+ * reusable anywhere the interactive TTY wizard's step *decisions* live outside
+ * the process, e.g. in a browser).
+ *
+ * Each function performs exactly one step of the same flow the TTY wizard in
+ * {@link file://./interactive-setup.ts} runs — sign in, pick / create a
+ * workspace and project, enable DCR, provision the OAuth2 client, grant tool
+ * permissions, provision the project API key — but returns a plain result
+ * object instead of prompting or printing. The heavy lifting (CLI arg shapes,
+ * OPL model inspection/merge, Console-API key minting) is imported from
+ * `interactive-setup.ts` so there is a single source of truth for it; only the
+ * thin, prompt-free orchestration lives here.
+ *
+ * Everything is fail-open: an action never throws for an expected failure
+ * (CLI error, network blip, missing session) — it returns `{ ok: false }` with
+ * a short message the UI can surface.
+ */
+import { type OryCliRunner, type OryWorkspace, type OryProject, type PermissionModel, type LoginUiState } from "./interactive-setup.js";
+import { type CreateProjectApiKeyArgs, type ProjectApiKeyResult } from "./project-api-key.js";
+import { type PermissionMode } from "./config.js";
+import { ensureUserAuthenticated } from "./user-login.js";
+import { ensureAgentIdentity } from "./agent-auth.js";
+import { OryAgentClient } from "./client.js";
+import { type UserSubjectRef } from "./subject.js";
+import { ensureLocalOryStack, seedLocalEnvironment } from "./local/index.js";
+/** Injectable dependencies so the web API layer and tests can stub the CLI,
+ *  the login gates, the local stack, and the Console-API key minter. Mirrors
+ *  the subset of {@link InteractiveSetupDeps} the headless actions need. */
+export interface SetupActionDeps {
+    runner?: OryCliRunner;
+    installOryCliFn?: () => Promise<OryCliRunner | null>;
+    clientFactory?: (harness: string) => OryAgentClient;
+    userLoginFn?: typeof ensureUserAuthenticated;
+    agentGateFn?: typeof ensureAgentIdentity;
+    localStackFn?: typeof ensureLocalOryStack;
+    seedFn?: typeof seedLocalEnvironment;
+    createProjectApiKeyFn?: (args: CreateProjectApiKeyArgs) => Promise<ProjectApiKeyResult | null>;
+    validateApiKeyFn?: (apiKey: string, projectUrl: string) => Promise<boolean>;
+}
+export declare function resolveNamespace(): string;
+export interface EnsureOryCliResult {
+    present: boolean;
+    installed: boolean;
+    /** The runner to use for subsequent CLI actions, or null if unavailable. */
+    runner: OryCliRunner | null;
+}
+/**
+ * Ensure the `ory` CLI is available. Probes the default (or injected) runner;
+ * if the binary isn't on `PATH`, installs `@ory/cli` into a plugin-managed dir
+ * and returns a runner bound to it. Never throws.
+ */
+export declare function ensureOryCli(deps?: SetupActionDeps): Promise<EnsureOryCliResult>;
+/** Whether the `ory` CLI already holds a valid Ory Network session. */
+export declare function isSignedIn(runner: OryCliRunner): boolean;
+export interface SignInHandle {
+    /** Resolves to true when `ory auth` exits 0 (signed in), false otherwise. */
+    done: Promise<boolean>;
+    /** Best-effort cancel (kills the child). */
+    cancel(): void;
+}
+/**
+ * Launch the interactive `ory auth` browser sign-in as a detached child so the
+ * HTTP server's event loop stays free (unlike `runner.exec`, which is
+ * spawnSync). The Ory CLI opens its own browser window and runs a local
+ * callback listener; we only watch its exit code. Returns a handle whose
+ * `done` promise resolves when sign-in completes. Requires `runner.bin`.
+ */
+export declare function startSignIn(runner: OryCliRunner): SignInHandle;
+export declare function listWorkspaces(runner: OryCliRunner): OryWorkspace[] | null;
+export interface CreateResult<T> {
+    ok: boolean;
+    value?: T;
+    error?: string;
+}
+export declare function createWorkspace(runner: OryCliRunner, name: string): CreateResult<OryWorkspace>;
+export declare function listProjects(runner: OryCliRunner, workspaceId: string): OryProject[] | null;
+export declare function createProject(runner: OryCliRunner, workspaceId: string, name: string): CreateResult<OryProject>;
+/** Ory Network Developer-plan project cap per workspace. */
+export declare const PROJECT_CAP = 2;
+/**
+ * Resolve a project's canonical SDK URL from its slug, refusing a missing slug
+ * or one that is actually the project id (a UUID) — either would build a URL
+ * that points nowhere.
+ */
+export declare function resolveProjectUrl(project: OryProject): CreateResult<string>;
+/** Current DCR state: true/false when known, null when it couldn't be read. */
+export declare function getDcrState(runner: OryCliRunner, projectId: string): boolean | null;
+/** Enable DCR on the project. Returns true on success. */
+export declare function enableDcrAction(runner: OryCliRunner, projectId: string): boolean;
+/**
+ * Ensure the project's OAuth2 login/consent UI works for a hosted browser
+ * login. A CLI-created project defaults these to the `localhost:3000`
+ * quickstart sample; this clears them so the Ory Managed Account Experience
+ * renders the login instead. Returns the resulting state so the UI can report
+ * it: `managed` (fixed or already managed), `custom_external` (a deliberate
+ * custom UI, left as-is), or `unknown` (couldn't read the config).
+ */
+export declare function ensureManagedLoginUi(runner: OryCliRunner, projectId: string): Exclude<LoginUiState, "loopback">;
+/**
+ * Best-effort human-readable name for a signed-in identity, resolved via the
+ * admin `ory` CLI (`ory get identity`). The PKCE login's id_token carries only
+ * an opaque subject id under the default `openid` scope, so rather than show a
+ * UUID we look the identity up by id and read a display trait (email → username
+ * → name). Returns undefined on any CLI/parse failure so callers fall back to
+ * the id.
+ */
+export declare function resolveIdentityName(runner: OryCliRunner, projectId: string, subjectId: string): string | undefined;
+/**
+ * Readable label for a signed-in user when naming a resource (e.g. a project
+ * API key), so a shared project's resource list shows an email/username rather
+ * than an opaque `user:<uuid>`. Looks the identity up via the admin CLI and
+ * falls back to the subject label when no name resolves (no runner, or the
+ * lookup fails). The raw subject id is read from either subject shape.
+ */
+export declare function resourceUserLabel(runner: OryCliRunner | null | undefined, projectId: string, subject: UserSubjectRef): string;
+export interface OAuth2ClientResult {
+    ok: boolean;
+    clientId?: string;
+    /** Human-readable client name (for display in place of the opaque id). */
+    name: string;
+    /** True when an existing plugin client was reused rather than created. */
+    reused: boolean;
+}
+/**
+ * Find or create the public PKCE OAuth2 client the user login needs. Reuses an
+ * existing plugin-provisioned client on the project so a re-run never mints a
+ * duplicate.
+ */
+export declare function provisionOAuth2Client(runner: OryCliRunner, projectId: string): OAuth2ClientResult;
+/** Persist the resolved Ory Network connection and enable the user login. */
+export declare function saveNetworkConfig(input: {
+    projectUrl: string;
+    projectId: string;
+    oauth2ClientId: string;
+    projectName?: string;
+    workspaceName?: string;
+}): void;
+export interface FullSetupResult {
+    authenticated: boolean;
+    /** The resolved permission subject label (e.g. `user:<id>`), or null. */
+    subjectLabel: string | null;
+    /** The resolved subject reference, for a follow-up permission grant. */
+    subject: UserSubjectRef | null;
+}
+/** The project the wizard resolved this session, to pin the login against. */
+export interface FullSetupTarget {
+    /** The selected SDK/project URL (authoritative for this install). */
+    projectUrl?: string;
+    /** The public OAuth2 client id the PKCE login should use. */
+    oauth2ClientId?: string;
+}
+/**
+ * Run the PKCE user login (opens a browser and awaits the loopback callback)
+ * and resolve the agent DCR identity, so the next session is fully wired.
+ * Best-effort: a declined or failed login just reports `authenticated: false`.
+ *
+ * `target` pins the project the wizard just selected. The login gate resolves
+ * its URL/client id through `resolveConfig()`, which is **env-first** — so a
+ * stale `ORY_PROJECT_URL` / `ORY_SDK_URL` / `ORY_OAUTH2_CLIENT_ID` left in the
+ * user's shell (e.g. `http://localhost:3000` from a local app) would otherwise
+ * override the project they just picked and launch the browser at the wrong
+ * URL. During install the fresh selection is ground truth, so we pin it into
+ * the environment for the login. (The process exits after install, so this
+ * doesn't leak into a long-lived session.)
+ */
+export declare function runFullSetup(binName: string, harness: string, deps?: SetupActionDeps, target?: FullSetupTarget): Promise<FullSetupResult>;
+export interface PermissionModelState {
+    model: PermissionModel["kind"];
+    /** OPL source when the model exists and can be merged (kind === "merge"). */
+    opl?: string;
+}
+/** Inspect how the project's permission model relates to the namespace. */
+export declare function inspectPermissions(runner: OryCliRunner, projectId: string, namespace?: string): Promise<PermissionModelState>;
+/**
+ * Provision (or merge) the namespace into the project's permission model.
+ * Pass `opl` (from a prior `inspectPermissions` "merge" result) to append the
+ * namespace non-destructively; omit it to create a fresh minimal model.
+ */
+export declare function provisionPermissions(runner: OryCliRunner, projectId: string, namespace?: string, opl?: string): boolean;
+export interface GrantResult {
+    ok: boolean;
+    count: number;
+    error?: string;
+}
+/**
+ * Grant `<subject>` the `use` relation on every built-in tool by writing the
+ * relation tuples through the admin-authenticated `ory` CLI. Assumes the
+ * namespace already exists (call {@link inspectPermissions} /
+ * {@link provisionPermissions} first).
+ */
+export declare function grantToolPermissions(runner: OryCliRunner, projectId: string, harness: string, subject: UserSubjectRef, namespace?: string): GrantResult;
+export type ApiKeyStatus = "env" | "valid_existing" | "created" | "failed";
+export interface ApiKeyResult {
+    status: ApiKeyStatus;
+}
+/**
+ * Ensure a valid project API key is stored for runtime permission *checks*.
+ * No-ops for an env-provided key; validates a stored key and re-mints if it is
+ * dead; otherwise mints one via the Console API and persists it. Best-effort.
+ */
+export declare function provisionProjectApiKey(input: {
+    projectId: string;
+    projectUrl: string;
+    harness: string;
+    user?: string;
+}, deps?: SetupActionDeps): Promise<ApiKeyResult>;
+/** Configure audit-only mode (no project, no auth, no checks). */
+export declare function configureAuditOnly(): void;
+/** Set the permission deny posture — `observe` (log) vs `enforce` (block). */
+export declare function setPermissionMode(mode: PermissionMode): void;
+export interface LocalStackResult {
+    running: boolean;
+    detail?: string;
+    seeded: boolean;
+    credentials?: {
+        email: string;
+        password: string;
+    };
+    seedError?: string;
+    projectUrl: string;
+    oauth2ClientId: string;
+    subjectNamespace: string;
+}
+/**
+ * Bring up and seed the local Ory stack, persisting the (stable) local
+ * connection details regardless of whether Docker came up. Mirrors the TTY
+ * wizard's local branch minus the login (the UI drives {@link runFullSetup}
+ * separately). Best-effort throughout.
+ */
+export declare function configureLocalStack(deps?: SetupActionDeps): Promise<LocalStackResult>;