@ory/argus 0.14.0 → 1.0.0

package/dist/setup-actions.d.ts

@@ -1,232 +0,0 @@
-/**
- * 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>;