@ory/argus 0.14.0 → 1.0.1

package/dist/auth-store.d.ts

@@ -18,6 +18,41 @@ export declare function loadTokens(): OryOAuth2Tokens | undefined;
 export declare function saveTokens(tokens: OryOAuth2Tokens): void;
 /** Remove the user's persisted OAuth2 tokens. */
 export declare function clearTokens(): void;
+/**
+ * A user credential supplied out-of-band through the environment (CI, scripted
+ * runs, a harness launched by a wrapper that already authenticated).
+ */
+export interface EnvUserCredential {
+    /** The bearer, if any of the four accepted variables is set. */
+    token?: string;
+    /** `ORY_USER_SUBJECT_ID`, when the operator pinned the subject. */
+    subject?: string;
+}
+/**
+ * Read the pre-supplied user credential from the environment.
+ *
+ * **`ORY_USER_OAUTH2_TOKEN` is the only accepted variable**, because an OAuth2
+ * access token is the only thing the credential is ever used as. All three
+ * consumers of `userPrincipal.token` demand one: broker delegation
+ * authentication and the agent + sub-agent DCR bootstraps (which send it as a
+ * bearer to `/oauth2/register`). Nothing calls `verifySession`, so a Kratos
+ * session token is never consumed as a session token.
+ *
+ * Three variables used to be accepted alongside it and have been removed:
+ * `ORY_USER_SESSION_TOKEN` (plus its legacy alias `ORY_SESSION_TOKEN`) named a
+ * Kratos session token and took *first* precedence, so supplying the credential
+ * its name asked for made every permission check fail `session_inactive` — and
+ * beat the variable that would have worked. `ORY_OAUTH2_TOKEN` was a redundant
+ * legacy alias. Pin the subject with `ORY_USER_SUBJECT_ID`.
+ *
+ * This lives here, and only here, because two call sites depend on agreeing:
+ * the login gate's `env_token` short-circuit (which runs on `SessionStart`) and
+ * the per-client rehydration in `OryAgentClient.fromEnv` (which runs on *every*
+ * lifecycle event, including the subprocess tool-call events where the gate
+ * never runs). If those disagreed, an env-supplied token would authenticate the
+ * session and then silently stop authenticating the permission checks.
+ */
+export declare function readEnvUserCredential(env?: NodeJS.ProcessEnv): EnvUserCredential;
 /** Number of seconds before nominal expiry that we consider tokens stale. */
 export declare const TOKEN_EXPIRY_SKEW_SEC = 60;
 /** Returns true if the access token is missing or within the skew window of expiry. */
@@ -55,8 +90,8 @@ export interface PkceFlightLock {
 export declare function tryAcquirePkceFlightLock(): PkceFlightLock | null;
 /**
  * Unconditionally remove the pkce-flight lock, if any. Use this from
- * single-owner contexts (e.g. the dev launcher at startup) where you
- * know no peer is mid-flow. Returns true when a lock was removed.
+ * single-owner maintenance contexts where no peer is mid-flow. Returns true
+ * when a lock was removed.
  */
 export declare function clearPkceFlightLock(): boolean;
 /**

package/dist/auth-store.js

@@ -50,6 +50,7 @@ exports.TOKEN_EXPIRY_SKEW_SEC = void 0;
 exports.loadTokens = loadTokens;
 exports.saveTokens = saveTokens;
 exports.clearTokens = clearTokens;
+exports.readEnvUserCredential = readEnvUserCredential;
 exports.isExpired = isExpired;
 exports.refreshAndSave = refreshAndSave;
 exports.tryAcquirePkceFlightLock = tryAcquirePkceFlightLock;
@@ -73,9 +74,10 @@ function loadTokens() {
 }
 /** Persist the user's OAuth2 tokens. Existing tokens are replaced atomically. */
 function saveTokens(tokens) {
+    const { idToken: _discardedIdToken, ...persistedTokens } = tokens;
     (0, config_js_1.mutateConfig)((current) => ({
         ...current,
-        user: { ...(current.user ?? {}), oauth2: tokens },
+        user: { ...(current.user ?? {}), oauth2: persistedTokens },
     }));
 }
 /** Remove the user's persisted OAuth2 tokens. */
@@ -93,6 +95,38 @@ function clearTokens() {
         return next;
     });
 }
+/**
+ * Read the pre-supplied user credential from the environment.
+ *
+ * **`ORY_USER_OAUTH2_TOKEN` is the only accepted variable**, because an OAuth2
+ * access token is the only thing the credential is ever used as. All three
+ * consumers of `userPrincipal.token` demand one: broker delegation
+ * authentication and the agent + sub-agent DCR bootstraps (which send it as a
+ * bearer to `/oauth2/register`). Nothing calls `verifySession`, so a Kratos
+ * session token is never consumed as a session token.
+ *
+ * Three variables used to be accepted alongside it and have been removed:
+ * `ORY_USER_SESSION_TOKEN` (plus its legacy alias `ORY_SESSION_TOKEN`) named a
+ * Kratos session token and took *first* precedence, so supplying the credential
+ * its name asked for made every permission check fail `session_inactive` — and
+ * beat the variable that would have worked. `ORY_OAUTH2_TOKEN` was a redundant
+ * legacy alias. Pin the subject with `ORY_USER_SUBJECT_ID`.
+ *
+ * This lives here, and only here, because two call sites depend on agreeing:
+ * the login gate's `env_token` short-circuit (which runs on `SessionStart`) and
+ * the per-client rehydration in `OryAgentClient.fromEnv` (which runs on *every*
+ * lifecycle event, including the subprocess tool-call events where the gate
+ * never runs). If those disagreed, an env-supplied token would authenticate the
+ * session and then silently stop authenticating the permission checks.
+ */
+function readEnvUserCredential(env = process.env) {
+    const token = env.ORY_USER_OAUTH2_TOKEN || undefined;
+    const subject = env.ORY_USER_SUBJECT_ID || undefined;
+    return {
+        ...(token ? { token } : {}),
+        ...(subject ? { subject } : {}),
+    };
+}
 /** Number of seconds before nominal expiry that we consider tokens stale. */
 exports.TOKEN_EXPIRY_SKEW_SEC = 60;
 /** Returns true if the access token is missing or within the skew window of expiry. */
@@ -203,8 +237,8 @@ function isLockStale(file) {
 }
 /**
  * Unconditionally remove the pkce-flight lock, if any. Use this from
- * single-owner contexts (e.g. the dev launcher at startup) where you
- * know no peer is mid-flow. Returns true when a lock was removed.
+ * single-owner maintenance contexts where no peer is mid-flow. Returns true
+ * when a lock was removed.
  */
 function clearPkceFlightLock() {
     try {

package/dist/auth.d.ts

@@ -14,14 +14,31 @@
 import { OryOAuth2Tokens } from "./config.js";
 /** Loopback ports tried in order. All must be registered as redirect URIs on the Ory OAuth2 client. */
 export declare const LOOPBACK_PORTS: readonly [47823, 47824, 47825, 47826];
-/** Hard timeout if the user never returns to the browser. */
-export declare const DEFAULT_LOGIN_TIMEOUT_MS = 120000;
+/**
+ * Hard timeout if the user never returns to the browser.
+ *
+ * Sized to fit **inside** the tightest session-start hook window any harness
+ * will accept, so the login always gives up on its own terms and records a
+ * `timeout` decline the user can act on. Being SIGKILLed by the harness
+ * instead surfaces nothing at all: the session proceeds with no user identity,
+ * and under `enforce` every subsequent tool is denied for a reason nothing
+ * explains (#220).
+ *
+ * The binding constraint is Antigravity, which validates its hook timeout to
+ * `5..120` seconds — so 120s is the ceiling, and this leaves headroom for the
+ * agent DCR registration and delegation record that run after the login inside
+ * the same hook invocation. See `hook-timeout.ts`, which derives every
+ * harness's declared window and asserts it outlasts this value.
+ */
+export declare const DEFAULT_LOGIN_TIMEOUT_MS = 90000;
 export interface PkceLoginOptions {
     /** Ory project URL (e.g. https://your-project.projects.oryapis.com). */
     projectUrl: string;
     /** Public OAuth2 client id registered with the loopback redirect URIs. */
     clientId: string;
-    /** Scopes to request. Defaults to `openid offline_access`. */
+    /** Scopes to request. Defaults to `openid offline_access profile email`
+     *  — `profile` / `email` populate the id_token's name/username/email
+     *  claims so the signed-in user can be shown by name, not just subject id. */
     scope?: string;
     /** Audience to request, if any. */
     audience?: string;
@@ -42,8 +59,20 @@ export type PkceLoginOutcome = {
 } | {
     kind: "declined";
     reason: PkceDeclineReason;
+    /**
+     * Concise, secret-free diagnostic for the failure, surfaced in the
+     * `user.auth` audit event and the operator message. Populated for
+     * `token_exchange_failed` (the underlying HTTP status / OAuth2 error,
+     * or a fetch cause code such as `UNABLE_TO_GET_ISSUER_CERT_LOCALLY` /
+     * `ECONNREFUSED`). Never contains the authorization code or a token.
+     */
+    detail?: string;
 };
-export type PkceDeclineReason = "headless" | "timeout" | "user_denied" | "state_mismatch" | "no_port" | "browser_launch_failed" | "aborted" | "token_exchange_failed";
+export type PkceDeclineReason = "headless" | "timeout" | "user_denied" | "state_mismatch" | "no_port" | "browser_launch_failed" | "aborted" | "token_exchange_failed"
+/** The authorization server rejected the requested scope (`invalid_scope`). */
+ | "invalid_scope"
+/** The authorization server returned some other `error` on the redirect. */
+ | "oauth_error";
 /**
  * Default headless heuristic. Returns true only for unattended runs
  * (CI=true / CI=1) so {@link pkceLogin} can short-circuit instead of

package/dist/auth.js

@@ -59,10 +59,34 @@ const node_http_1 = require("node:http");
 const node_url_1 = require("node:url");
 const fs = __importStar(require("node:fs"));
 const path = __importStar(require("node:path"));
+const branding_js_1 = require("./branding.js");
 /** Loopback ports tried in order. All must be registered as redirect URIs on the Ory OAuth2 client. */
 exports.LOOPBACK_PORTS = [47823, 47824, 47825, 47826];
-/** Hard timeout if the user never returns to the browser. */
-exports.DEFAULT_LOGIN_TIMEOUT_MS = 120_000;
+/**
+ * Hard timeout if the user never returns to the browser.
+ *
+ * Sized to fit **inside** the tightest session-start hook window any harness
+ * will accept, so the login always gives up on its own terms and records a
+ * `timeout` decline the user can act on. Being SIGKILLed by the harness
+ * instead surfaces nothing at all: the session proceeds with no user identity,
+ * and under `enforce` every subsequent tool is denied for a reason nothing
+ * explains (#220).
+ *
+ * The binding constraint is Antigravity, which validates its hook timeout to
+ * `5..120` seconds — so 120s is the ceiling, and this leaves headroom for the
+ * agent DCR registration and delegation record that run after the login inside
+ * the same hook invocation. See `hook-timeout.ts`, which derives every
+ * harness's declared window and asserts it outlasts this value.
+ */
+exports.DEFAULT_LOGIN_TIMEOUT_MS = 90_000;
+/**
+ * Login scopes, derived from the single source of truth in branding so the
+ * PKCE request can never drift from what the install registers the client
+ * with. `WIDE` (with profile/email) is requested by default and dropped to
+ * `BASE` if the client isn't allowed those scopes (see {@link pkceLogin}).
+ */
+const BASE_LOGIN_SCOPE = branding_js_1.USER_LOGIN_BASE_SCOPES.join(" ");
+const WIDE_LOGIN_SCOPE = branding_js_1.USER_LOGIN_SCOPE_OAUTH;
 /**
  * Default headless heuristic. Returns true only for unattended runs
  * (CI=true / CI=1) so {@link pkceLogin} can short-circuit instead of
@@ -87,12 +111,40 @@ function detectHeadless(env = process.env) {
  */
 async function pkceLogin(options) {
     const isHeadless = options.isHeadless ?? detectHeadless;
-    const headless = isHeadless();
-    if (headless) {
+    if (isHeadless()) {
         // Unattended environment (CI). No human to follow the URL, so we
         // skip the loopback listener entirely instead of timing out.
         return { kind: "declined", reason: "headless" };
     }
+    // An explicit scope is honored verbatim. The default asks for `profile` and
+    // `email` (so the id_token carries the signed-in user's name) but falls back
+    // to the base scope when the login client isn't allowed them — otherwise a
+    // client not configured for those scopes could never complete login
+    // (`invalid_scope`). The fallback costs one extra redirect, no user action.
+    const scopes = options.scope ? [options.scope] : [WIDE_LOGIN_SCOPE, BASE_LOGIN_SCOPE];
+    let outcome = { kind: "declined", reason: "user_denied" };
+    for (let i = 0; i < scopes.length; i++) {
+        const scopeFallbackPending = i < scopes.length - 1;
+        outcome = await runPkceAttempt(options, scopes[i], scopeFallbackPending);
+        if (outcome.kind === "ok")
+            return outcome;
+        if (outcome.reason === "invalid_scope" && scopeFallbackPending) {
+            process.stderr.write("The sign-in client isn't allowed the requested profile/email scopes; " +
+                "retrying with basic scopes (your name may not be shown in status).\n\n");
+            continue;
+        }
+        return outcome;
+    }
+    return outcome;
+}
+/**
+ * One PKCE attempt with a specific scope string: bind a loopback port, open the
+ * browser, wait for the callback, and exchange the code. `scopeFallbackPending`
+ * is true when {@link pkceLogin} will retry with a narrower scope if this
+ * attempt is rejected for `invalid_scope`, so the browser page can say
+ * "reconnecting" instead of showing a hard failure.
+ */
+async function runPkceAttempt(options, scope, scopeFallbackPending) {
     const { server, port } = await listenOnFirstAvailablePort(options.ports ?? exports.LOOPBACK_PORTS);
     if (!server || port === null) {
         return { kind: "declined", reason: "no_port" };
@@ -101,7 +153,6 @@ async function pkceLogin(options) {
     const codeChallenge = sha256Base64Url(codeVerifier);
     const state = (0, node_crypto_1.randomBytes)(16).toString("base64url");
     const redirectUri = `http://127.0.0.1:${port}/callback`;
-    const scope = options.scope ?? "openid offline_access";
     const authorizeUrl = buildAuthorizeUrl({
         projectUrl: options.projectUrl,
         clientId: options.clientId,
@@ -123,6 +174,7 @@ async function pkceLogin(options) {
         expectedState: state,
         timeoutMs,
         signal: options.signal,
+        scopeFallbackPending,
     });
     // Browser launch is best-effort. If `open` throws or the platform has
     // no usable browser, we keep the callback server alive and rely on the
@@ -153,10 +205,35 @@ async function pkceLogin(options) {
         });
         return { kind: "ok", tokens };
     }
-    catch {
-        return { kind: "declined", reason: "token_exchange_failed" };
+    catch (err) {
+        // Surface the underlying cause (HTTP status + OAuth2 error, or a fetch
+        // cause code like a TLS-trust failure) instead of swallowing it — this
+        // is the difference between a diagnosable failure and a bare
+        // "exchange failed" message. The detail is secret-free.
+        return {
+            kind: "declined",
+            reason: "token_exchange_failed",
+            detail: describeExchangeError(err),
+        };
     }
 }
+/**
+ * Render an error thrown by {@link exchangeCodeForTokens} into a concise,
+ * secret-free detail string. For a failed `fetch` the useful signal is the
+ * low-level cause code (`UNABLE_TO_GET_ISSUER_CERT_LOCALLY`, `ECONNREFUSED`,
+ * …); for a non-2xx response the message already carries the HTTP status and
+ * the OAuth2 `error`. Neither includes the authorization code or any token.
+ */
+function describeExchangeError(err) {
+    if (err instanceof Error) {
+        const cause = err.cause;
+        const code = cause && typeof cause === "object" && "code" in cause
+            ? String(cause.code)
+            : undefined;
+        return code ? `${err.message} (${code})` : err.message;
+    }
+    return String(err);
+}
 // ─── PKCE primitives ──────────────────────────────────────────────────
 /** Generate a 64-byte (≈86-char base64url) code verifier per RFC 7636. */
 function generateCodeVerifier() {
@@ -247,8 +324,27 @@ function waitForCallback(server, opts) {
             }
             const error = url.searchParams.get("error");
             if (error) {
-                respondHtml(res, 400, resultPage("cancelled"));
-                settle({ kind: "declined", reason: "user_denied" });
+                const description = url.searchParams.get("error_description") ?? undefined;
+                // `access_denied` is the user clicking "cancel" — not an error to alarm
+                // them with. Everything else is a real authorization-server rejection
+                // (misconfigured client, unsupported scope, …); show the actual reason
+                // so it can be acted on rather than a generic "cancelled".
+                if (error === "access_denied") {
+                    respondHtml(res, 400, resultPage("cancelled"));
+                    settle({ kind: "declined", reason: "user_denied" });
+                }
+                else if (error === "invalid_scope") {
+                    // A pending scope fallback will retry immediately with fewer scopes,
+                    // so don't flash a hard failure — say we're reconnecting.
+                    respondHtml(res, 400, opts.scopeFallbackPending
+                        ? resultPage("reconnecting")
+                        : resultPage("error", { code: error, description }));
+                    settle({ kind: "declined", reason: "invalid_scope" });
+                }
+                else {
+                    respondHtml(res, 400, resultPage("error", { code: error, description }));
+                    settle({ kind: "declined", reason: "oauth_error" });
+                }
                 return;
             }
             const state = url.searchParams.get("state");
@@ -280,14 +376,13 @@ function respondHtml(res, status, html) {
 }
 /**
  * Serve the shared Ory favicon (identical to console.ory.com's) so the sign-in
- * result page carries the same tab icon as the Console. It ships alongside the
- * built dashboard at `dist/webapp/favicon.ico`; if that file isn't present
- * (e.g. the webapp wasn't built), fall back to a 404 — the page still renders,
- * just without a favicon. Same-origin on the loopback server, so no external
- * request is made.
+ * result page carries the same tab icon as the Console, when a bundled
+ * `dist/webapp/favicon.ico` is present. It normally isn't, so this falls back
+ * to a 404 — the page still renders, just without a favicon. Same-origin on the
+ * loopback server, so no external request is made.
  */
 function respondFavicon(res) {
-    // Compiled to dist/auth.js; the SPA (and its favicon) is built to dist/webapp.
+    // Compiled to dist/auth.js; look for an optional favicon under dist/webapp.
     const file = path.join(__dirname, "webapp", "favicon.ico");
     try {
         const buf = fs.readFileSync(file);
@@ -309,7 +404,7 @@ function respondFavicon(res) {
  * external requests — the only asset is the same-origin Ory favicon the
  * loopback server serves — so it renders identically offline.
  */
-function resultPage(kind) {
+function resultPage(kind, detail) {
     const view = {
         success: {
             accent: "#22C55E", // green — a positive "done" check
@@ -329,7 +424,24 @@ function resultPage(kind) {
             title: "Sign-in could not be verified",
             body: "The login response failed a security check. <strong>Close this tab</strong> and re-run the login from your terminal.",
         },
+        error: {
+            accent: "#F43F5E",
+            icon: "!",
+            title: "Sign-in failed",
+            body: "Ory rejected the sign-in request. <strong>Close this tab</strong> and return to your terminal — the details below say why.",
+        },
+        reconnecting: {
+            accent: "#6366F1", // indigo — a neutral "in progress"
+            icon: "&#8635;", // ↻
+            title: "Reconnecting…",
+            body: "Re-opening sign-in with basic permissions. You can <strong>close this tab</strong>; a new one will open to continue.",
+        },
     }[kind];
+    // The authorization server's own `error` / `error_description`, shown verbatim
+    // (escaped) so a misconfiguration is actionable instead of opaque.
+    const detailBlock = detail && (detail.code || detail.description)
+        ? `\n    <pre class="detail">${escapeHtml([detail.code, detail.description].filter(Boolean).join("\n"))}</pre>`
+        : "";
     return `<!doctype html>
 <html lang="en">
 <head>
@@ -355,18 +467,32 @@ function resultPage(kind) {
   h1 { font-size: 1.35rem; margin: 0 0 .5rem; color: #F8FAFC; }
   p { margin: 0; line-height: 1.55; color: #94A3B8; }
   strong { color: #E2E8F0; font-weight: 600; }
+  .detail {
+    margin: 1.25rem 0 0; padding: .75rem 1rem; text-align: left;
+    border-radius: .5rem; background: #1E293B; color: #CBD5E1;
+    font-size: .8rem; line-height: 1.5; white-space: pre-wrap; word-break: break-word;
+  }
 </style>
 </head>
 <body>
   <div class="card">
     <div class="badge">${view.icon}</div>
     <h1>${view.title}</h1>
-    <p>${view.body}</p>
+    <p>${view.body}</p>${detailBlock}
   </div>
 </body>
 </html>
 `;
 }
+/** Minimal HTML-entity escape for untrusted text interpolated into the page. */
+function escapeHtml(s) {
+    return s
+        .replace(/&/g, "&amp;")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;")
+        .replace(/"/g, "&quot;")
+        .replace(/'/g, "&#39;");
+}
 // ─── Browser launch ───────────────────────────────────────────────────
 async function launchBrowser(url, override) {
     if (override) {
@@ -396,7 +522,23 @@ async function exchangeCodeForTokens(args) {
         body: body.toString(),
     });
     if (!res.ok) {
-        throw new Error(`Token exchange failed: HTTP ${res.status}`);
+        // Include the OAuth2 error from the body when present. `error` /
+        // `error_description` are standard OAuth2 diagnostics (e.g.
+        // `invalid_client`, `invalid_grant`), not secrets — they turn an opaque
+        // 400/401 into an actionable message.
+        let suffix = "";
+        try {
+            const body = (await res.json());
+            const error = typeof body.error === "string" ? body.error : undefined;
+            if (error) {
+                const desc = typeof body.error_description === "string" ? body.error_description : undefined;
+                suffix = desc ? `: ${error} — ${desc}` : `: ${error}`;
+            }
+        }
+        catch {
+            // Non-JSON body; the status alone is the diagnostic.
+        }
+        throw new Error(`Token exchange failed: HTTP ${res.status}${suffix}`);
     }
     const json = (await res.json());
     return tokensFromTokenResponse(json, args.clientId);
@@ -433,14 +575,15 @@ function tokensFromTokenResponse(json, clientId, fallbackRefreshToken) {
         throw new Error("Token response missing access_token");
     const expiresIn = typeof json.expires_in === "number" ? json.expires_in : 3600;
     const refreshToken = typeof json.refresh_token === "string" ? json.refresh_token : fallbackRefreshToken;
+    const idToken = typeof json.id_token === "string" ? json.id_token : undefined;
     return {
         accessToken,
         refreshToken,
         expiresAt: Math.floor(Date.now() / 1000) + expiresIn,
         clientId,
-        idToken: typeof json.id_token === "string" ? json.id_token : undefined,
+        displayName: displayNameFromIdToken(idToken),
         scope: typeof json.scope === "string" ? json.scope : undefined,
-        subject: subjectFromIdToken(typeof json.id_token === "string" ? json.id_token : undefined),
+        subject: subjectFromIdToken(idToken),
     };
 }
 /** Best-effort sub-claim extraction from a JWT id_token. Returns undefined on any failure. */

package/dist/bash-parser.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Shell-command decomposition for fine-grained permission checks.
+ *
+ * The permission gate authorizes on *tool name* only, so a denied surface
+ * (`WebFetch`, `Read`, an MCP write) is trivially reached through
+ * `bash -c "curl …"`. This module parses a shell command with the
+ * `tree-sitter-bash` grammar (via `web-tree-sitter`) into a **structured
+ * command model** — the shared foundation for the permission work:
+ *
+ *   - #76 (this): check each command word as `ShellTool:<word>#use`.
+ *     Derived from `ParsedShell.commands.map(c => c.name)`.
+ *   - #77 (argument scoping): per-binary extractors read `ShellCommand.args`.
+ *   - #78 (combinatory dataflow): edges are built from `ShellCommand.pipeline`
+ *     grouping and `ShellCommand.redirects`.
+ *   - #79 (env escalation): `ShellCommand.assignments` and redirect targets.
+ *
+ * Building the model once (one parse, one AST walk) keeps every follow-on
+ * additive instead of re-walking the tree.
+ *
+ * **Why a grammar parser, not a regex/tokenizer.** A hand-rolled tokenizer is
+ * vulnerable to *parser-differential attacks* — where the checker reads a
+ * command differently than the shell that will run it. tree-sitter-bash gives
+ * us the shell's own view of the command.
+ *
+ * **Failure postures (two, deliberately opposite):**
+ *   - `tooComplex` — parsed but unresolvable (dynamic command name, parse
+ *     error, dynamic `sh -c` target). Security signal: enforce denies.
+ *   - `parserUnavailable` — the runtime/grammar could not load. Availability
+ *     signal: the gate falls open. A broken build must never block shell use.
+ *
+ * **Known static-analysis limits (checks for them are #77/#78/#79):** command
+ * names built at runtime, programs invoked as interpreter arguments
+ * (`python -c "…"`, `find -exec`), and dynamic dataflow. The backstop is that
+ * the decode/exec primitives themselves (`sh`, `bash`, `eval`, `base64`, …) are
+ * ordinary checked words.
+ */
+/** A redirection attached to a command (`> file`, `< file`, `2>err`, `>/dev/tcp/…`). */
+export interface ShellRedirect {
+    /** Raw operator text (`>`, `>>`, `<`, `2>`, `&>`, …). */
+    operator: string;
+    /** Literal redirect target (path / fd / device), or `null` when dynamic. */
+    target: string | null;
+    /** `read` for `<`/`<<`/`<<<`, `write` for `>`/`>>`/`&>`. */
+    direction: "read" | "write";
+}
+/** A NAME=value assignment (an `env`-style prefix on a command). */
+export interface ShellAssignment {
+    name: string;
+    /** Literal value, or `null` when it contains an expansion. */
+    value: string | null;
+}
+/** One effective command invocation extracted from a shell command line. */
+export interface ShellCommand {
+    /**
+     * Resolved program/builtin word, normalized to its basename. `null` when the
+     * command name is dynamic/unresolvable (`$X`, `$(…)`), which also flips
+     * {@link ParsedShell.tooComplex}.
+     */
+    name: string | null;
+    /** Raw text of each argument token, in order (for #77 argument scoping). */
+    args: string[];
+    /** `NAME=value` assignment prefixes on this command (for #79 env scoping). */
+    assignments: ShellAssignment[];
+    /** Redirects on this command / its enclosing statement (for #78/#79). */
+    redirects: ShellRedirect[];
+    /**
+     * Pipeline group id. Commands joined by `|` share an id, so #78 can form the
+     * pipe edges between them. Standalone commands each get a distinct id.
+     */
+    pipeline: number;
+}
+/** Structured result of decomposing one shell command line. */
+export interface ParsedShell {
+    /** Every effective command invocation (including wrapper- and `sh -c`-nested). */
+    commands: ShellCommand[];
+    /** Something couldn't be resolved statically (dynamic name / parse error). */
+    tooComplex: boolean;
+    /** The tree-sitter runtime/grammar failed to load — fail OPEN, don't block. */
+    parserUnavailable?: boolean;
+}
+/** Back-compat flat view used by the #76 gate: the deduped command words. */
+export interface BashParseResult {
+    words: string[];
+    tooComplex: boolean;
+    parserUnavailable?: boolean;
+}
+/**
+ * Decompose a shell command into a {@link ParsedShell} model. Never throws.
+ * This is the shared foundation; see {@link extractBashCommandWords} for the
+ * flat word list the #76 gate uses.
+ */
+export declare function extractShellCommands(command: string): Promise<ParsedShell>;
+/**
+ * Flat view of {@link extractShellCommands} for the #76 gate: the deduped set
+ * of command/builtin words the command will execute. Never throws. See
+ * {@link BashParseResult} for the two failure postures.
+ */
+export declare function extractBashCommandWords(command: string): Promise<BashParseResult>;