@jevitate/cli 0.7.0 → 0.9.0

package/dist/persona-login.d.ts

@@ -0,0 +1,256 @@
+import type { Page } from "playwright";
+import type { BrowserPort } from "@jevitate/playwright";
+import { type BrowserRunOptions } from "./browser-run-options.js";
+/**
+ * #427 — persona sessions from credentials, and the pre-flight that proves a session is still alive.
+ *
+ *  - `mintStorageState` (`jevitate login`, and the refresh below): opens a FRESH context (no
+ *    storage state), fills the sign-in form with a username and password read from the NAMED
+ *    environment variables, submits, checks success by code, and saves the context's storage state
+ *    (mode 0600, written atomically). The login session records nothing: no trace, no video, no HAR,
+ *    no screenshot, no transcript — and no message this module produces carries a credential (every
+ *    error text passes through `redactText` with both values first).
+ *  - `checkSession` (the pre-flight auth check): opens the start URL with the storage state and
+ *    decides, by code, whether the app bounced it to a sign-in page.
+ *  - `ensurePersonaSession`: the check, plus ONE re-mint when the persona has `login` parameters.
+ *
+ * Credentials are never accepted as literal values — only environment variable NAMES travel (flags,
+ * personas files, results). Values are typed only into a page whose origin the run authorizes.
+ */
+/**
+ * #449: a sign-in through an HTTP endpoint (`jevitate login --api`, a personas file's `login.api`):
+ * the credentials are POSTed as JSON, and the response's cookies and/or a token read from its JSON
+ * body (written into the app origin's localStorage) become the storage state. No form is driven.
+ */
+export interface ApiLogin {
+    /** The sign-in endpoint (absolute http(s) URL on an authorized origin). */
+    readonly url: string;
+    /** The JSON body key the username is sent under (default `username`). */
+    readonly userKey: string;
+    /** The JSON body key the password is sent under (default `password`). */
+    readonly passwordKey: string;
+    /** A simple dotted path into the JSON response (`token`, `data.accessToken`) whose value is the session token. */
+    readonly tokenPath?: string;
+    /** The localStorage key the token is written under (default: the token path's last segment). */
+    readonly storageKey?: string;
+    /** Where the token goes: only `local` (a Playwright storage state has no sessionStorage). */
+    readonly storage: "local";
+    /** The page that proves the session (`--verify-url`); default the endpoint's origin root. Its origin receives the token. */
+    readonly verifyUrl?: string;
+}
+/** A persona's login parameters (`jevitate login` flags, or a personas file entry's `login`). */
+export interface PersonaLogin {
+    /** The sign-in page (absolute http(s) URL) — the form path. Exactly one of `url` and `api` is set. */
+    readonly url?: string;
+    /** #449: sign in through an HTTP endpoint instead of a form. */
+    readonly api?: ApiLogin;
+    /** Environment variable holding the username (its NAME — never the value). */
+    readonly userEnv: string;
+    /** Environment variable holding the password (its NAME — never the value). */
+    readonly passwordEnv: string;
+    /** The username field: a label, else a CSS selector. Default: found by autocomplete/type/name heuristics. */
+    readonly userField?: string;
+    /** The password field: a label, else a CSS selector. Default: the visible `input[type=password]`. */
+    readonly passwordField?: string;
+    /** The submit button's accessible name. Default: the form's submit button, else Enter. */
+    readonly submit?: string;
+    /** `urlIncludes:<text>` | `selector:<css>` | `text:<text>`. Default: no password field and no login-like URL. */
+    readonly success?: string;
+}
+export declare class LoginArgsError extends Error {
+    readonly code: "E_LOGIN_ARGS";
+    constructor(message: string);
+}
+/** The login did not succeed (credentials rejected, a field not found, the success check never held). */
+export declare class LoginFailedError extends Error {
+    readonly code: "E_LOGIN_FAILED";
+    constructor(message: string);
+}
+/** Checks an environment variable NAME (a value pasted in its place is never echoed). */
+export declare function assertEnvVarName(name: string, what: string): void;
+/** The names an API login's settings go by in error messages (flags, or a personas file's `login.api.*`). */
+interface ApiLoginLabels {
+    readonly url: string;
+    readonly userKey: string;
+    readonly passwordKey: string;
+    readonly tokenPath: string;
+    readonly storageKey: string;
+    readonly storage: string;
+    readonly verifyUrl: string;
+}
+/** `a.b.0.c` → its segments (strict: identifiers or indexes, no prototype keys). */
+export declare function parseTokenPath(path: string, what: string): string[];
+/** Validates an API login's settings (fail closed before any network). */
+export declare function parseApiLogin(raw: {
+    readonly url: string;
+    readonly userKey?: string | undefined;
+    readonly passwordKey?: string | undefined;
+    readonly tokenPath?: string | undefined;
+    readonly storageKey?: string | undefined;
+    readonly storage?: string | undefined;
+    readonly verifyUrl?: string | undefined;
+}, labels?: ApiLoginLabels): ApiLogin;
+/** Validates a personas file entry's `login` object (`where` names it in errors). */
+export declare function parsePersonaLogin(v: unknown, where: string): PersonaLogin;
+/** `jevitate login`'s flags → a validated `PersonaLogin` (fail closed before any browser opens). */
+export declare function loginFromFlags(f: {
+    readonly url?: string;
+    readonly api?: Parameters<typeof parseApiLogin>[0];
+    readonly userEnv: string;
+    readonly passwordEnv: string;
+    readonly userField?: string;
+    readonly passwordField?: string;
+    readonly submit?: string;
+    readonly success?: string;
+}): PersonaLogin;
+export type LoginSuccess = {
+    readonly kind: "urlIncludes";
+    readonly text: string;
+} | {
+    readonly kind: "selector";
+    readonly selector: string;
+} | {
+    readonly kind: "text";
+    readonly text: string;
+};
+/** `urlIncludes:<text>` | `selector:<css>` | `text:<text>`. */
+export declare function parseLoginSuccess(spec: string): LoginSuccess;
+export type AuthCheck = {
+    readonly mode: "off";
+} | {
+    readonly mode: "auto";
+} | {
+    readonly mode: "urlExcludes";
+    readonly text: string;
+} | {
+    readonly mode: "selector";
+    readonly selector: string;
+};
+/** `--auth-check <off|auto|urlExcludes:<text>|selector:<css>>` (default `auto`). */
+export declare function parseAuthCheck(spec: string | undefined): AuthCheck;
+export interface LoginSecrets {
+    readonly username: string;
+    readonly password: string;
+}
+/** Reads the two credentials from the environment (fail closed: unset/empty refuses, naming the variable only). */
+export declare function resolveLoginSecrets(login: PersonaLogin, env: Readonly<Record<string, string | undefined>>): LoginSecrets;
+/**
+ * Drives the sign-in form on `page` (already open, no storage state): navigates to `login.url`, fills
+ * the fields, submits, and waits for the success check. Throws `LoginFailedError` (scrubbed).
+ * Supports a two-step form (username, then a password page): when no password field is visible yet,
+ * the username is submitted first.
+ */
+export declare function performLogin(page: Page, login: PersonaLogin, secrets: LoginSecrets, opts: {
+    readonly allowlist: readonly string[];
+    readonly timeoutMs: number;
+}): Promise<string>;
+/** Where a storage state goes: refused inside a repo's `.jevitate/`; a warning when it is in a repo and not ignored by git. */
+export declare function checkSaveTarget(file: string, what: string): {
+    readonly path: string;
+    readonly warnings: string[];
+};
+/** Writes the storage state JSON atomically with mode 0600 (a temp file in the same directory, then rename). */
+export declare function writeStorageStateFile(path: string, json: string): void;
+export interface MintOptions {
+    readonly login: PersonaLogin;
+    /** The storage state file to write. */
+    readonly save: string;
+    /** Origins credentials may be typed into (the run's allowlist, the login URL's origin by default). */
+    readonly allowlist: readonly string[];
+    readonly env: Readonly<Record<string, string | undefined>>;
+    readonly port: BrowserPort;
+    readonly browser?: BrowserRunOptions;
+    readonly timeoutMs: number;
+    /**
+     * #449 (an API login only): prove the new session before it is saved — the state is checked against
+     * this URL with this rule (`checkSession`), and nothing is written when the check fails.
+     */
+    readonly verify?: {
+        readonly url: string;
+        readonly check: AuthCheck;
+    };
+}
+export interface MintResult {
+    /** Absolute path of the saved storage state. */
+    readonly saved: string;
+    /** Where the sign-in ended (credentials and token-like query values redacted). */
+    readonly landedUrl: string;
+}
+/** Signs in on a fresh, unrecorded session and saves its storage state (mode 0600). */
+export declare function mintStorageState(o: MintOptions): Promise<MintResult>;
+/** The app page an API login's session is proven on (and whose origin receives the token). */
+export declare function apiVerifyUrl(api: ApiLogin): string;
+export interface SessionCheckOptions {
+    readonly storageState: string;
+    /** The mission's start URL. */
+    readonly url: string;
+    readonly allowlist: readonly string[];
+    readonly check: AuthCheck;
+    readonly port: BrowserPort;
+    readonly browser?: BrowserRunOptions;
+    readonly timeoutMs: number;
+}
+export type SessionCheck = {
+    readonly ok: true;
+    readonly landedUrl?: string;
+} | {
+    readonly ok: false;
+    readonly reason: string;
+    readonly landedUrl: string;
+};
+/**
+ * Opens `url` with the storage state and decides by code whether the session is alive. A start URL
+ * that is itself a sign-in route is never judged (`auto`). An unreachable app is NOT an expired
+ * session: the check passes it on and the mission reports the app as unreachable, as before.
+ */
+export declare function checkSession(o: SessionCheckOptions): Promise<SessionCheck>;
+export interface EnsureSessionOptions extends Omit<SessionCheckOptions, "storageState"> {
+    /** The persona's name, when the session is a persona's (it names the failure). */
+    readonly persona?: string;
+    readonly storageState: string;
+    /** The persona's login parameters: an expired session is re-minted ONCE from them. */
+    readonly login?: PersonaLogin;
+    readonly env: Readonly<Record<string, string | undefined>>;
+    /** A line for the operator (stderr): a refresh happened. */
+    readonly note?: (line: string) => void;
+}
+export type EnsureSession = {
+    readonly ok: true;
+    readonly refreshed: boolean;
+} | {
+    readonly ok: false;
+    readonly reason: string;
+    readonly landedUrl?: string;
+};
+/** The pre-flight: check the session; when it is expired and login parameters exist, re-mint once and re-check. */
+export declare function ensurePersonaSession(o: EnsureSessionOptions): Promise<EnsureSession>;
+/** A run the pre-flight ended (exit 2): `inconclusive`, `failure.kind: "auth-expired"` — the login page was never explored. */
+export interface AuthExpiredResult {
+    readonly strategy: string;
+    readonly outcome: "inconclusive";
+    readonly missionOutcome: "inconclusive";
+    readonly reason: string;
+    readonly failure: {
+        readonly kind: "auth-expired";
+        readonly message: string;
+        readonly persona?: string;
+    };
+    readonly persona?: string;
+    readonly startUrl: string;
+    /** Where the start URL landed (token-like query values redacted). */
+    readonly landedUrl?: string;
+    readonly exitCode: 2;
+    /** #423: a goal run's own ending (the shared `inconclusive`) and why — the run broke before it began. */
+    readonly goalOutcome?: "inconclusive";
+    readonly goalReason?: "broken-run";
+    /** #421/#423: nothing ran, so no defect: the defect verdict is present and `none`. */
+    readonly defects: readonly never[];
+    readonly defectOutcome: {
+        readonly status: "none";
+        readonly byKind: Readonly<Record<string, number>>;
+    };
+}
+export declare function authExpiredResult(strategy: string, startUrl: string, failed: Extract<EnsureSession, {
+    ok: false;
+}>, persona?: string): AuthExpiredResult;
+export {};