@mesh-tech/mesh-cli 0.20.2 → 0.20.3

package/dist/src/commands/login.d.ts

@@ -1,29 +1,3 @@
-/**
- * mesh login — Authenticate with Zitadel via OIDC PKCE or Device Code flow.
- *
- * Opens browser to Zitadel (PKCE) or prints a code to enter in the browser
- * (Device Code). Exchanges for tokens and caches at ~/.config/mesh/credentials.json.
- *
- * Config is read from ~/.config/mesh/config.json, keyed by context
- * (e.g., "mesh.dev"). After deploying the platform, copy the CLI client ID
- * from the Pulumi stack output into the config file.
- *
- * In containers/SSH sessions, device code flow is used automatically.
- *
- * `mesh login` is for a DEPLOYED platform only — the tenant platform you
- * deploy to, reach the Hub of, or tunnel into. Package-registry access is a
- * separate, global identity owned by `mesh registry login`; a platform login
- * never writes ~/.npmrc, and the reserved `registry` credential key is refused
- * here so the two can never be confused.
- *
- * Usage:
- *   mesh login acme.dev            — authenticate to the acme dev platform
- *   mesh login acme.dev --device   — force device code flow
- *   mesh login acme.dev --status   — show current auth state (Zitadel session if
- *                                    there is one, otherwise whatever the AWS
- *                                    credential chain resolves — SSO or key pair)
- *   mesh logout acme.dev           — clear cached credentials
- */
 import { Command } from "commander";
 import { type AwsIdentity } from "../utils/aws-auth.js";
 declare const CONFIG_DIR: string;
@@ -32,33 +6,11 @@ declare const CREDENTIALS_FILE: string;
 interface ContextConfig {
     issuer: string;
     clientId: string;
-    /**
-     * Default IAM role ARN to assume for this context when no `--role` flag
-     * and no `MESH_AWS_ROLE` env var are provided. Set automatically the first
-     * time `mesh login ... --export --role <arn>` runs against this context;
-     * subsequent `--role` values overwrite it.
-     */
     defaultRole?: string;
-    /**
-     * Optional admin-tier IAM role for this context. When set,
-     * `selectRoleForCaller` upgrades to this ARN automatically when the
-     * caller's Zitadel JWT carries the admin role (default
-     * `mesh.platform:admin`; override via adminClaimRoles).
-     */
     adminRole?: string;
-    /**
-     * Zitadel role names that map a caller to `adminRole`. Defaults to
-     * `["mesh.platform:admin"]` when omitted.
-     */
     adminClaimRoles?: string[];
-    /** Headscale login server (published by the platform). */
     vpn?: string;
-    /** Zero-touch pre-auth broker URL (published by the platform). */
     vpnJoinBroker?: string;
-    /**
-     * Zitadel-gated registry-auth broker URL (published by the platform).
-     * With this set, `mesh registry login` needs no AWS credentials at all.
-     */
     registryBroker?: string;
 }
 interface CachedCredentials {
@@ -72,164 +24,37 @@ interface CachedCredentials {
 type ConfigFile = Record<string, ContextConfig>;
 type CredentialsFile = Record<string, CachedCredentials>;
 export declare function writeContextConfig(context: string, config: ContextConfig): void;
-/**
- * Forget a cached context config so the next use runs discovery again.
- *
- * @example
- * clearContextConfig("registry"); // `mesh registry logout` — re-discovers the registry next time
- */
 export declare function clearContextConfig(context: string): void;
 declare function getContextConfig(context: string): ContextConfig | null;
-/**
- * Anonymous discovery against `https://cli.<domain>/.well-known/mesh.json`.
- *
- * `quiet: true` returns the payload WITHOUT caching it under `contextKey` and
- * without the progress lines — for a caller that stores the record itself
- * under a name that is not a platform context (the package registry's
- * reserved key). Warnings still print, because a failed discovery is the
- * caller's problem either way.
- *
- * @example
- * const cfg = await discoverConfigFromWellKnown("dev.platform.meshtech.io", "registry", { quiet: true });
- */
 export declare function discoverConfigFromWellKnown(domain: string, contextKey?: string, opts?: {
     quiet?: boolean;
 }): Promise<ContextConfig | null>;
 declare function readAllCredentials(): CredentialsFile;
 declare function readCredentials(context: string): CachedCredentials | null;
-/**
- * Write `data` to `path` atomically: write to a temp file in the SAME
- * directory as `path` (so the subsequent rename is same-filesystem, hence
- * atomic), then `fs.renameSync` it into place. This guarantees concurrent
- * readers (e.g. other `credential_process` invocations racing a refresh)
- * only ever observe a fully-written file — never a truncated one from an
- * interleaved `fs.writeFileSync`.
- *
- * On any error, best-effort removes the temp file before rethrowing.
- *
- * Exported for unit testing.
- */
 export declare function atomicWriteFileSync(path: string, data: string, mode: number): void;
 declare function clearCredentials(context: string): void;
 declare function decodeJwtPayload(token: string): Record<string, unknown>;
-/**
- * Run device-code login, re-issuing a fresh code (up to `maxCodes`) if the user
- * doesn't finish before a code expires. `attempt` performs ONE code's
- * request+poll and resolves `"success"` or `"expired"`; it rejects only on a
- * hard error (denied / network). Extracted + injectable so the reissue loop is
- * unit-testable without real network calls.
- */
 export declare function deviceLoginWithReissue(attempt: (codeNumber: number) => Promise<"success" | "expired">, maxCodes?: number): Promise<void>;
-/**
- * Detect an environment where the PKCE browser-callback flow won't work — a
- * container, a remote/SSH session, or any non-interactive shell (piped output,
- * headless, agent/CI-run). In all of these the callback flow has no browser to
- * open and no interactive terminal, so it can only hang until the 2-minute
- * timeout. Device-code flow (print a URL + code to complete elsewhere) is the
- * correct fallback, so callers use it whenever this returns true.
- *
- * Exported for tests.
- */
 export declare function isRemoteEnvironment(): boolean;
-/**
- * What `--status` reports when there is no usable Zitadel session.
- *
- * Zitadel is one way to reach a platform's AWS account, not the only one. A
- * profile authenticated with SSO — or with a plain access-key/secret pair —
- * is just as good, and everything downstream already accepts it: aws-auth's
- * path 1 (ambient env creds) and path 3 (AssumeRole via the current session)
- * never touch the OIDC cache. Reporting "not logged in" purely because that
- * cache is empty sent people off to run a device flow they did not need, and
- * failed the check for anyone deliberately using static credentials.
- *
- * So: fall through to the AWS credential chain and report what it finds.
- */
-/** One `--status` output line plus which logger it goes through. */
 export interface StatusLine {
     level: "success" | "info" | "warn";
     text: string;
 }
-/**
- * The account id embedded in an IAM role ARN
- * (`arn:aws:iam::123456789012:role/...`), or undefined when there is no ARN
- * to read one from.
- */
 export declare function accountIdFromRoleArn(roleArn: string | undefined): string | undefined;
-/**
- * Decide everything `--status` says (and its exit code) when there is no
- * usable Zitadel session — pure so the wording and the exit decision are
- * pinned by tests.
- *
- * The probe only proves "some AWS identity works on this machine"; it says
- * nothing about whether that identity belongs to `context`. So the claim is
- * scoped to the credentials — unless the context config carries a role ARN,
- * whose account id makes the context check free: verify when we can, say so
- * when we can't.
- */
 export declare function renderAwsFallbackStatus(context: string, reason: string, identity: AwsIdentity | null, expectedAccountId?: string): {
     lines: StatusLine[];
     exitCode: 0 | 1;
 };
 export declare function registerLoginCommand(program: Command): void;
-/**
- * The credential key the package registry's own session lives under. Not a
- * platform: `mesh login` / `mesh logout` refuse it, and the post-login hints
- * (VPN, tenants) never apply to it. `utils/registry-identity.ts` owns the
- * registry side of this contract and re-exports the key.
- */
 export declare const RESERVED_REGISTRY_CONTEXT = "registry";
-/** Printed once when `--no-registry` is passed: the flag no longer changes anything. */
 export declare const NO_REGISTRY_DEPRECATED = "--no-registry is deprecated and ignored: mesh login no longer touches the registry.";
-/** Printed after a platform login on a machine with no package-registry access. */
 export declare const REGISTRY_SEPARATE_HINT = "Package registry access is separate from platform sign-in \u2014 run: mesh registry login";
-/**
- * The "no configuration found" explanation for a context that neither SSM,
- * the pinned first-party table, nor the well-known endpoint could resolve —
- * every path tried, then the `config.json` snippet to add by hand.
- *
- * Shared by the `login` command and the `mesh init` wizard's platform step so
- * a discovery failure reads the same wherever it happens.
- *
- * @example
- * logError(renderNoConfigHelp("acme.dev"));
- */
 export declare function renderNoConfigHelp(context: string): string;
-/**
- * Get a valid access token for the given context, refreshing if needed.
- *
- * Returns the id token (a JWT with `sub` claim) suitable for
- * Authorization: Bearer headers. Returns null if no credentials are
- * cached or refresh fails.
- */
-/**
- * True while a cached token is still valid, treating anything within `marginMs`
- * of expiry as already stale. The margin lets pollers (e.g. the dev-user
- * token-server) re-mint BEFORE expiry instead of handing out a token that dies
- * before the caller's next poll.
- */
 export declare function tokenStillValid(expiresAt: string, marginMs?: number, now?: number): boolean;
 declare function getValidToken(context: string, opts?: {
     marginMs?: number;
 }): Promise<string | null>;
-/**
- * Re-mint a context's session now, whether or not its token has expired.
- * Zitadel writes project roles into a token when it issues it, so a role
- * granted after the sign-in stays invisible until a new token is minted —
- * this is how a caller picks the grant up without a second browser trip.
- * Null when there is no session, no refresh token, or the issuer refuses.
- *
- * @example
- * const idToken = await forceRefreshToken("registry");
- * if (idToken) console.log("session re-minted");
- */
 export declare function forceRefreshToken(context: string): Promise<string | null>;
-/**
- * Structured diagnosis of the deployer-credential path for a context/role,
- * without mutating anything. The shared seam behind `mesh dev doctor`'s creds
- * check and the launch preflight (MESH-2015), reusing the same
- * `getValidToken` + `assumeRoleCredentials` path as `--credential-process`
- * (MESH-1965).
- */
 export type CredProbe = {
     state: "ok";
     ttlSeconds: number;
@@ -245,77 +70,22 @@ export type CredProbe = {
 } | {
     state: "stale-env-override";
 };
-/**
- * Probe deployer creds for `context`/`roleArn`. Order matters:
- *   1. No cached Zitadel session → `no-session`.
- *   2. Cached session AND ambient `AWS_*` env keys present → `stale-env-override`
- *      (the frozen triple would override the self-refreshing profile at
- *      runtime — the exact `mesh dev` trap). Guarded on a cached session so
- *      legitimate CI env-key credentials, which have no `mesh login` session,
- *      are not misreported.
- *   3. Session can't be refreshed → `expired-session`.
- *   4. AssumeRoleWithWebIdentity fails → `assume-denied` (valid identity, wrong
- *      IAM/role/policy).
- *   5. Otherwise → `ok` with the STS TTL.
- */
 export declare function probeCredentials(context: string, roleArn: string): Promise<CredProbe>;
-/**
- * Render the `--static` output: raw temporary AWS credentials as shell
- * `export` statements (the old frozen ~1h triple). Pure — no I/O. Includes a
- * trailing newline. Exported for unit testing.
- */
 export declare function renderExportStaticLines(args: {
     accessKey: string;
     secretKey: string;
     sessionToken: string;
     region: string;
 }): string;
-/**
- * Render the default `--export` output: point the shell at a self-refreshing
- * `credential_process` profile. The leading `unset` clears any stale STS
- * triple already in the shell so it can't shadow the profile. Pure — no I/O.
- * Includes a trailing newline. Exported for unit testing.
- *
- * Deliberately does NOT export `AWS_CONFIG_FILE`: the profile lives in the
- * user's REAL AWS config file (managed marker section — see
- * `upsertManagedAwsConfigSection`), so their other profiles (e.g.
- * `AWS_PROFILE=mesh-dev` InfraAdmin) keep working in the same shell.
- * Redirecting AWS_CONFIG_FILE to a mesh-private file used to clobber
- * ~/.aws/config for every subsequent AWS command.
- */
 export declare function renderExportProfileLines(args: {
     profileName: string;
     region: string;
 }): string;
-/**
- * The AWS config file the managed profile section is written into: the
- * user's `$AWS_CONFIG_FILE` when THEY have set one, else `~/.aws/config` —
- * the same file `aws configure sso` manages. Exported for unit testing.
- */
 export declare function resolveUserAwsConfigPath(env?: Record<string, string | undefined>): string;
-/**
- * Where to write the managed AWS profile, with a safehouse fallback. Normally
- * the user's real `~/.aws/config` (augmented in place, so their other tools see
- * the profile — hence `redirected: false`, we don't touch their `AWS_CONFIG_FILE`).
- * But when `~/.aws` is not writable (a sandbox without a `~/.aws` grant), fall
- * back to a mesh-managed file under `~/.config/mesh` we CAN write, and set
- * `redirected: true` so the caller also exports `AWS_CONFIG_FILE` (otherwise the
- * AWS SDK, looking only at `~/.aws/config`, would never find the profile). An
- * explicit `AWS_CONFIG_FILE` always wins and is never redirected.
- */
 export declare function resolveAwsConfigTarget(env?: Record<string, string | undefined>): {
     configPath: string;
     redirected: boolean;
 };
-/**
- * Resolve which IAM role ARN to use, honoring the same precedence in both
- * `--export` and `--credential-process`: explicit `--role` wins, then
- * `MESH_AWS_ROLE`, then the context's cached `defaultRole`. Pure aside from
- * reading `process.env.MESH_AWS_ROLE` — returns an explanatory error instead
- * of throwing so callers can route it to stderr and exit non-zero.
- *
- * Exported for unit testing.
- */
 export declare function resolveRoleOrExplain(opts: {
     role?: string;
 }, config: {
@@ -325,50 +95,15 @@ export declare function resolveRoleOrExplain(opts: {
 } | {
     error: string;
 };
-/**
- * Ensure a valid Zitadel ID token is cached for the given context — refreshing
- * or running the full login flow as needed. Returns null on failure.
- */
-/**
- * Run the sign-in itself — browser PKCE, or the device-code flow when asked
- * for or when there is no browser to open (`isRemoteEnvironment`) — and cache
- * the resulting session under `context`. Rejects when the user denies, the
- * flow times out, or the issuer refuses.
- *
- * The one sign-in routine every caller shares: the `login` command, on-demand
- * login from other commands, and the package registry's own session.
- *
- * @example
- * await runLoginFlow("acme.dev", config, { device: false });
- */
 export declare function runLoginFlow(context: string, config: ContextConfig, opts?: {
     device?: boolean;
 }): Promise<void>;
-/**
- * Ensure a valid login session for `context`, running the login flow (device
- * code in remote/non-TTY, browser callback otherwise) if none is cached. Returns
- * the cached credentials, or null if no config is available to log in with.
- *
- * For use by other commands (e.g. `secrets set`, the AWS-cred resolver) so they
- * can trigger login on demand instead of just failing with guidance.
- */
 export declare function ensureLogin(context: string, opts?: {
     device?: boolean;
     interactive?: boolean;
 }): Promise<CachedCredentials | null>;
 export { CONFIG_DIR, CONFIG_FILE, CREDENTIALS_FILE };
 export type { ContextConfig, CachedCredentials, CredentialsFile };
-/** Every cached context config, keyed by context name. */
 export declare function readAllContextConfigs(): ConfigFile;
-/**
- * The discovery chain on its own, without the browser flow that follows it.
- *
- * Exported so the clean-laptop bootstrap — SSM → pinned first-party alias →
- * full-domain, and the anti-phishing refusal for an unknown short context — can
- * be exercised end-to-end against the live well-known endpoint. The `login`
- * command's own path is otherwise only reachable by completing an interactive
- * sign-in, which is why this leg had no coverage above the unit tier.
- */
 export declare function discoverConfigForContext(context: string): Promise<ContextConfig | null>;
 export { readCredentials, readAllCredentials, getContextConfig, decodeJwtPayload, getValidToken, clearCredentials };
-//# sourceMappingURL=login.d.ts.map