@sequenceholdings/studio-cli 0.1.9 → 0.1.11

package/README.md

@@ -6,9 +6,10 @@ any repo against the platform over HTTP — no monorepo checkout required.
 
 ```
 seq-studio process lint
-seq-studio process plan -e staging
-seq-studio process apply -e staging
-seq-studio artifact deploy -e staging
+seq-studio process plan -e <env>
+seq-studio process apply -e <env>
+seq-studio artifact deploy -e <env>
+seq-studio envs list
 seq-studio doctor
 ```
 
@@ -43,16 +44,17 @@ releases install immediately.)
 
 ## Authenticate
 
-`seq-studio` is a **read-only consumer of seqapi tokens** — it does not
-have its own login flow. Run `seqapi login` once to mint tokens at
-`~/.config/sequence-api/tokens.json`; `seqapi`, `seq-studio process`, and
-`seq-studio artifact` all share that file.
+Run the built-in browser login once. `seq-studio` and `seqapi` share the
+resulting tokens at `~/.config/sequence-api/tokens.json`, so logging in with
+either CLI authenticates both.
 
 ```bash
-seqapi login
+seq-studio login
 seq-studio doctor   # confirms config + auth + authorization
 ```
 
+Use `seq-studio logout` to remove the shared cached tokens.
+
 ### Headless auth (CI) — M2M
 
 When there's no interactive login (CI, automation), set the service-account
@@ -61,7 +63,7 @@ secret and `seq-studio` mints a token via the Auth0 client-credentials grant
 
 ```bash
 export AUTH0_M2M_CLIENT_SECRET=...   # provided by your platform administrator
-seq-studio artifact deploy -e staging
+seq-studio artifact deploy -e <env>
 ```
 
 The secret is read at runtime — never commit it. M2M carries app scopes but
@@ -71,17 +73,35 @@ user-scoped/private resources.
 **Manual escape hatch:** any `artifact` command also accepts an explicit
 `--token <jwt>`, which wins over both the M2M and cached-user paths.
 
-## Environments (`~/.config/lattice/config.toml`)
+## Environments
+
+The CLI ships with a single built-in environment, `local`
+(`http://localhost:5001`). The other environments your identity may target
+are **discovered** after you authenticate: the CLI calls the platform's
+environment-discovery endpoint and caches the result at
+`~/.config/lattice/environments.json`.
+
+```bash
+seq-studio login            # or: export AUTH0_M2M_CLIENT_SECRET=...
+seq-studio envs refresh     # fetch the environments visible to your identity
+seq-studio envs list        # show them (name, URL, source)
+```
+
+Discovery also happens lazily: the first time you pass an `-e <env>` that
+isn't cached yet, the CLI refreshes the catalog before failing. What you can
+see depends on who you are — unauthenticated installs get `local` only, and
+authenticated identities get the deployments they're entitled to. Visibility
+is not access control: every request is still authorized server-side.
 
-Environment names map to platform URLs. Your deployment's URLs are configured
-in `~/.config/lattice/config.toml`:
+You can always add or override environments yourself in
+`~/.config/lattice/config.toml` (user entries win over discovered ones):
 
 ```toml
 [env.local]
 url = "http://localhost:5001"
 
-[env.staging]
-url = "https://staging.example.com"
+[env.my-atlas]
+url = "https://atlas.example.com"
 
 default_env = "local"
 ```
@@ -190,34 +210,33 @@ any username, PAT as password). **You do not need `seqapi`.**
 
 ### Everyone (recommended) — Atlas UI
 
-1. Open **Settings → Tokens** in Atlas for your environment, e.g.
-   - Staging: https://staging.atlas.seqholdings.com/settings/tokens
-   - Production: https://atlas.seqholdings.com/settings/tokens
-   - BankSouth: https://banksouth.seqholdings.com/settings/tokens
+1. Open **Settings → Tokens** in Atlas for your environment
+   (`<your-atlas-url>/settings/tokens` — run `seq-studio envs list` for the
+   URLs visible to your identity)
 2. **New token** → scopes `repo:read` (add `repo:write` for push) → copy once
 3. Export and clone:
 
 ```bash
 export ATLAS_GIT_PAT=atlas_git_…
-seq-studio repos clone artifacts/ai-fluency -e staging
-# or: git clone https://git:$ATLAS_GIT_PAT@staging.atlas.seqholdings.com/api/git-service/repos/<id>/git
+seq-studio repos clone <namespace>/<repo> -e <env>
+# or: git clone https://git:$ATLAS_GIT_PAT@<your-atlas-host>/api/git-service/repos/<id>/git
 ```
 
 You can also open **Repositories → Access tokens** / the clone popover’s
 **Manage tokens** link.
 
-### Sequence staff — CLI mint (optional)
+### CLI mint (optional)
 
-Requires `seqapi login` (Auth0). Same tokens as the UI:
+Requires Auth0 login. Same identity as the UI:
 
 ```bash
-seqapi login
-seq-studio auth pat create --name laptop --scopes repo:read,repo:write -e staging
+seq-studio login
+seq-studio auth pat create --name laptop --scopes repo:read,repo:write -e <env>
 # optional: --expires 7d|30d|90d|1y|never  (default 30d)
 # optional: --store-credentials   # git credential approve for the env host
 
-seq-studio auth pat list -e staging
-seq-studio auth pat revoke <id> -e staging --yes
+seq-studio auth pat list -e <env>
+seq-studio auth pat revoke <id> -e <env> --yes
 ```
 
 The raw token is printed **once** on create.

package/dist/artifact/delegate.js

@@ -11,8 +11,9 @@
  *      is shared with the rest of `seq-studio`.
  *   4. Forward all remaining argv to `runCli`.
  */
-import { getAccessToken, tryGetAccessToken } from '../auth.js';
-import { readConfig, resolveEnv } from '../config.js';
+import { getAccessToken, M2mTokenError, tryGetAccessToken } from '../auth.js';
+import { readConfig, resolveEnvWithDiscovery } from '../config.js';
+import { fetchCatalog, readCachedCatalog } from '../env-catalog.js';
 import { normalizeShortEnvFlag, readEnvFromArgv } from '../env-flags.js';
 import { PREVIEW_DOMAIN, PREVIEW_PROJECT, resolvePreviewByPr } from '../preview.js';
 const ARTIFACT_USAGE = `usage:
@@ -31,7 +32,8 @@ const ARTIFACT_USAGE = `usage:
   seq-studio artifact whoami -e <env>
   seq-studio artifact env list
 
-  Built-in envs: local, staging, production, banksouth.
+  Environments: see \`seq-studio envs list\` (built-in: local; more are
+  discovered after you authenticate).
 
   Source for build/plan/deploy: a local [dir] (default), a platform git-service
   repo (--repo <ns>/<name>), or any git URL (--git-url <url>). --ref selects a
@@ -48,13 +50,42 @@ const ARTIFACT_USAGE = `usage:
   Preview deploys sit behind a Cloudflare WAF gate. Off the company network/VPN,
   set PREVIEW_ACCESS_HEADER=<secret> and the CLI sends it as x-preview-access.
 
-  Authenticate with: seqapi login
+  Authenticate with: seq-studio login
 `;
 export async function runArtifactCommand(sub, rest) {
+    // Older artifact-studio versions exposed nested login/logout commands backed
+    // by a separate token file. Keep those commands working, but route them to
+    // seq-studio's shared token so every namespace uses the same identity.
+    if (sub === 'login' || sub === 'logout') {
+        if (rest.length > 0) {
+            if (sub === 'login' && rest.includes('--token')) {
+                // The legacy `artifact login --token <jwt>` persisted a bearer to
+                // artifact-studio's own token file — a store this unification retires.
+                console.error('seq-studio artifact login no longer stores a bearer token.\n' +
+                    'Scripted/headless options:\n' +
+                    '  - pass --token <jwt> directly to the artifact command (deploy/plan/whoami/...)\n' +
+                    '  - export ARTIFACT_STUDIO_TOKEN=<jwt> for the session\n' +
+                    '  - set AUTH0_M2M_CLIENT_SECRET for service-account (M2M) auth in CI');
+            }
+            else {
+                console.error(`seq-studio artifact ${sub} does not accept arguments.`);
+            }
+            return 1;
+        }
+        const auth = await import('../login.js');
+        await auth[sub]();
+        return 0;
+    }
     if (!sub || sub === 'help' || sub === '--help' || sub === '-h') {
         console.log(ARTIFACT_USAGE);
         return sub ? 0 : 1;
     }
+    // `artifact env list` renders the tier-aware discovered catalog instead of
+    // artifact-studio's built-in (local-only) list.
+    if (sub === 'env' && rest[0] === 'list') {
+        const { runEnvsCommand } = await import('../envs/commands.js');
+        return runEnvsCommand('list', []);
+    }
     // Normalize `-e <env>` / `-e=<env>` to `--env <env>` because
     // artifact-studio's argv parser (`shared/services/artifact-studio/src/cli.ts`)
     // only recognizes long flags. Without this rewrite `seq-studio
@@ -70,6 +101,7 @@ export async function runArtifactCommand(sub, rest) {
     let resolved;
     let argvForCli = forwardRest;
     if (envUrl !== undefined) {
+        await requireSequenceTier('--env-url');
         const validated = validatePreviewEnvUrl(envUrl);
         // Explicit override wins over everything. Keep the user's --env name if
         // they gave one, else label it `preview`.
@@ -77,13 +109,13 @@ export async function runArtifactCommand(sub, rest) {
         argvForCli = ensureEnvFlag(forwardRest, resolved.name);
     }
     else if (prNumber !== undefined) {
+        await requireSequenceTier('--pr');
         const preview = await resolvePreviewByPr({ pr: prNumber });
         resolved = { name: `preview:${preview.slug}`, url: preview.url };
         argvForCli = ensureEnvFlag(forwardRest, resolved.name);
     }
     else if (requested) {
-        const config = await readConfig();
-        resolved = resolveEnv({ config, requested });
+        resolved = await resolveEnvWithDiscovery({ requested });
         // For `preview:<slug>` normalize the forwarded --env to the canonical name.
         if (resolved.name !== requested)
             argvForCli = ensureEnvFlag(forwardRest, resolved.name);
@@ -96,41 +128,82 @@ export async function runArtifactCommand(sub, rest) {
         if (isPreviewUrl(resolved.url))
             applyPreviewAccessHeader();
     }
-    // Share the seqapi token. `tryGetAccessToken` resolves an M2M
-    // service-account token when AUTH0_M2M_CLIENT_SECRET is set (headless /
-    // CI / cloud-agent path) and otherwise the cached `seqapi login` user
-    // token (see ../auth.ts). If neither is available, artifact-studio
-    // commands that need a token surface their own error — we don't force
-    // `seqapi login` here because some commands (init, validate, build) work
-    // offline. Manual escape hatch: pass `--token <jwt>` (artifact-studio's
-    // CLI accepts it and it wins over everything).
-    const token = await tryGetAccessToken({ failClosedForM2m: true });
-    if (token) {
-        process.env['ARTIFACT_STUDIO_TOKEN'] = token;
-    }
+    // Always hand artifact-studio the env map visible to this identity
+    // (discovered catalog + config.toml). Commands that resolve an env *name*
+    // without an explicit --env flag — the stored `.artifact-studio/config.json`
+    // defaultEnv, `artifact env set <name>` — would otherwise fall back to
+    // artifact-studio's built-in local-only map and fail on deployed envs.
+    const { envs } = await readConfig();
+    process.env['ARTIFACT_STUDIO_ENV_URLS'] = JSON.stringify(Object.fromEntries(Object.entries(envs).map(([name, { url }]) => [name, url])));
+    // An explicit `--token <jwt>` is the manual escape hatch and must win over
+    // everything, including a configured-but-failing M2M credential (which
+    // `tryGetAccessToken({ failClosedForM2m: true })` would otherwise turn into
+    // an abort before argv ever reaches artifact-studio). artifact-studio's
+    // `getOptionalToken` checks `flags.token` first, so when it's present we
+    // skip shared-token resolution entirely. Only the two-token `--token <jwt>`
+    // form counts: artifact-studio's parser does not split `--token=<jwt>`.
+    const hasExplicitToken = hasTokenFlag(argvForCli);
     // Lazy import so `process` / `doctor` commands don't pull in
     // artifact-studio's vite/react/tailwind dependency graph.
     const { runCli: runArtifactStudio, setTokenProvider } = await import('@sequenceholdings/artifact-studio/cli');
-    // The ARTIFACT_STUDIO_TOKEN env var above is captured once and never
-    // refreshes, so long-running commands (notably `artifact dev`) would start
-    // failing with "Authentication failed" once the initial token's TTL elapses.
-    // Hand artifact-studio a refreshing source — getAccessToken() mints a fresh
-    // access token via the Auth0 refresh grant when the cached one is near
-    // expiry — so a watch session survives indefinitely.
-    setTokenProvider(async () => {
-        if (process.env.AUTH0_M2M_CLIENT_SECRET?.trim()) {
-            // Fail closed for configured M2M failures so headless deploys never
-            // silently fall back to another cached identity.
-            return await getAccessToken();
+    if (!hasExplicitToken) {
+        // Share the seqapi token. `tryGetAccessToken` resolves an M2M
+        // service-account token when AUTH0_M2M_CLIENT_SECRET is set (headless /
+        // CI / cloud-agent path) and otherwise the cached interactive user
+        // token (see ../auth.ts). If neither is available, artifact-studio
+        // commands that need a token surface their own error — we don't force
+        // `seq-studio login` here because some commands (init, validate, build)
+        // work offline.
+        const token = await tryGetAccessToken({ failClosedForM2m: true });
+        if (token) {
+            process.env['ARTIFACT_STUDIO_TOKEN'] = token;
         }
+        // The ARTIFACT_STUDIO_TOKEN env var above is captured once and never
+        // refreshes, so long-running commands (notably `artifact dev`) would start
+        // failing with "Authentication failed" once the initial token's TTL
+        // elapses. Hand artifact-studio a refreshing source — getAccessToken()
+        // mints a fresh access token via the Auth0 refresh grant when the cached
+        // one is near expiry — so a watch session survives indefinitely.
+        setTokenProvider(async () => {
+            if (process.env.AUTH0_M2M_CLIENT_SECRET?.trim()) {
+                // Fail closed for configured M2M failures so headless deploys never
+                // silently fall back to another cached identity.
+                return await getAccessToken();
+            }
+            try {
+                return await getAccessToken();
+            }
+            catch {
+                return null;
+            }
+        });
+    }
+    return runArtifactStudio([sub, ...argvForCli]);
+}
+/**
+ * Preview targeting (`preview:<slug>`, `--pr`, `--env-url`) is a
+ * Sequence-staff surface. The tier comes from the cached discovery catalog;
+ * refresh it lazily so a just-logged-in engineer isn't blocked on a stale
+ * anonymous cache.
+ */
+async function requireSequenceTier(flag) {
+    let { tier } = await readConfig();
+    if (tier !== 'sequence') {
         try {
-            return await getAccessToken();
+            tier = (await fetchCatalog())?.tier ?? 'anonymous';
         }
-        catch {
-            return null;
+        catch (err) {
+            // Broken CI credentials must surface as the Auth0 error, not as a
+            // misleading "Sequence-staff surface" rejection.
+            if (err instanceof M2mTokenError)
+                throw err;
+            tier = (await readCachedCatalog())?.tier ?? 'anonymous';
         }
-    });
-    return runArtifactStudio([sub, ...argvForCli]);
+    }
+    if (tier !== 'sequence') {
+        throw new Error(`${flag} targets per-PR preview environments, a Sequence-staff surface. ` +
+            'Authenticate with `seq-studio login` and run `seq-studio envs refresh`.');
+    }
 }
 /**
  * Strip the seq-studio-only `--pr <number>` and `--env-url <url>` flags from
@@ -167,6 +240,18 @@ export function extractPreviewFlags(argv) {
     }
     return { rest, prNumber, envUrl };
 }
+/**
+ * True when argv carries an explicit two-token `--token <jwt>` that
+ * artifact-studio's parser will bind to `flags.token`. `--token=<jwt>` is
+ * excluded because that parser stores it as a stray flag and never binds it.
+ */
+function hasTokenFlag(argv) {
+    const index = argv.indexOf('--token');
+    if (index === -1)
+        return false;
+    const value = argv[index + 1];
+    return value !== undefined && !value.startsWith('--');
+}
 function splitInlineValue(arg) {
     const eq = arg.indexOf('=');
     if (arg.startsWith('--') && eq !== -1)

package/dist/auth-cmds/commands.d.ts

@@ -1,7 +1,7 @@
 import type { ParsedArgs } from '../process/commands.js';
 declare const PAT_SCOPES: readonly ["repo:read", "repo:write", "repo:admin"];
 type PatScope = (typeof PAT_SCOPES)[number];
-export declare const AUTH_USAGE = "usage:\n  seq-studio auth pat create --name <n> [--scopes repo:read,repo:write] [-e env]\n                             [--expires 7d|30d|90d|1y|never] [--store-credentials]\n  seq-studio auth pat list [-e env]\n  seq-studio auth pat revoke <id> [-e env] [--yes]\n\n  Issue a personal access token for git clone / git push against the platform\n  git service.\n\n  Most users (no seqapi): open Atlas \u2192 Settings \u2192 Tokens, or:\n    https://<atlas-host>/settings/tokens\n  Sign in, create a token (repo:read / repo:write), copy once, then:\n    export ATLAS_GIT_PAT=<token>\n\n  Sequence staff: `seqapi login` then `auth pat create` (same Auth0 session\n  as the Atlas UI). The CLI cannot mint a PAT without that login.\n\n  On create the raw token is printed ONCE \u2014 store it; Atlas cannot re-show it.\n  Git Basic auth: any username (e.g. git), PAT as the password.\n\n  Flags: -e/--env <local|staging|production|banksouth>\n";
+export declare const AUTH_USAGE = "usage:\n  seq-studio auth pat create --name <n> [--scopes repo:read,repo:write] [-e env]\n                             [--expires 7d|30d|90d|1y|never] [--store-credentials]\n  seq-studio auth pat list [-e env]\n  seq-studio auth pat revoke <id> [-e env] [--yes]\n\n  Issue a personal access token for git clone / git push against the platform\n  git service.\n\n  Authenticate with `seq-studio login`, then run `auth pat create`.\n  Alternatively, open Atlas \u2192 Settings \u2192 Tokens:\n    https://<atlas-host>/settings/tokens\n  Sign in, create a token (repo:read / repo:write), copy once, then:\n    export ATLAS_GIT_PAT=<token>\n\n  On create the raw token is printed ONCE \u2014 store it; Atlas cannot re-show it.\n  Git Basic auth: any username (e.g. git), PAT as the password.\n\n  Flags: -e/--env <env>  (see: seq-studio envs list)\n";
 export declare function parsePatScopes(raw: string | undefined): PatScope[];
 /**
  * Map UI-style duration choices to an absolute ISO-8601 expiresAt, or undefined

package/dist/auth-cmds/commands.js

@@ -1,10 +1,9 @@
 /**
  * `seq-studio auth <sub>` — PAT management for the platform git service.
  *
- * Issues / lists / revokes Personal Access Tokens via Auth0 bearer auth
- * (`seqapi login` — Sequence staff). Third-party / OpCo developers without
- * seqapi should mint tokens in the Atlas UI at `/settings/tokens` instead;
- * help text and error hints lead with that path.
+ * Issues / lists / revokes Personal Access Tokens via Auth0 bearer auth.
+ * Users authenticate with `seq-studio login`; the Atlas UI at
+ * `/settings/tokens` remains an alternative.
  *
  * The raw token is printed exactly once on create; use it as the Basic-auth
  * password for `git clone` / `git push` (username is ignored).
@@ -12,9 +11,23 @@
 import { deleteNoContent, getJson, postJson } from '../atlas-client.js';
 import { printCliError } from '../cli-errors.js';
 import { buildContext, clientOptions, flagBool, LOG, } from '../functions/commands.js';
+import { readConfig } from '../config.js';
 import { confirmYes } from '../prompt.js';
 import { storeGitCredentials } from '../repos/git-clone.js';
 import { formatPatSetupHint, settingsTokensUrl } from '../pat-hints.js';
+/**
+ * Tokens-page URLs rendered from the environments visible to this identity
+ * (discovered catalog + config.toml). Anonymous users get a generic pointer
+ * instead of a hardcoded list of internal hosts.
+ */
+async function settingsTokensLines() {
+    const config = await readConfig().catch(() => null);
+    const remote = Object.entries(config?.envs ?? {}).filter(([name]) => name !== 'local');
+    if (remote.length === 0) {
+        return ['Tokens page: <your Atlas deployment URL>/settings/tokens'];
+    }
+    return remote.map(([name, { url }]) => `${name}: ${settingsTokensUrl(url)}`);
+}
 const PAT_SCOPES = ['repo:read', 'repo:write', 'repo:admin'];
 function stringFlag(flags, key) {
     const value = flags[key];
@@ -33,37 +46,35 @@ export const AUTH_USAGE = `usage:
   Issue a personal access token for git clone / git push against the platform
   git service.
 
-  Most users (no seqapi): open Atlas → Settings → Tokens, or:
+  Authenticate with \`seq-studio login\`, then run \`auth pat create\`.
+  Alternatively, open Atlas → Settings → Tokens:
     https://<atlas-host>/settings/tokens
   Sign in, create a token (repo:read / repo:write), copy once, then:
     export ATLAS_GIT_PAT=<token>
 
-  Sequence staff: \`seqapi login\` then \`auth pat create\` (same Auth0 session
-  as the Atlas UI). The CLI cannot mint a PAT without that login.
-
   On create the raw token is printed ONCE — store it; Atlas cannot re-show it.
   Git Basic auth: any username (e.g. git), PAT as the password.
 
-  Flags: -e/--env <local|staging|production|banksouth>
+  Flags: -e/--env <env>  (see: seq-studio envs list)
 `;
 async function authContext(args) {
     if (args.flags.env === true || args.flags.e === true) {
-        throw new Error('-e/--env requires a value (local|staging|production|banksouth|preview:<slug>).');
+        throw new Error('-e/--env requires a value — see: seq-studio envs list.');
     }
     try {
         return await buildContext(args);
     }
     catch (err) {
         const message = err instanceof Error ? err.message : String(err);
-        // Prefer the Atlas UI path — third-party / OpCo developers do not have seqapi.
-        // buildContext failed before we know the env URL; point at the common hosts.
+        // buildContext failed before we know the env URL; offer CLI login and
+        // render the tokens-page URLs from the environments visible to this
+        // identity (third-party / OpCo developers only see their own hosts).
+        const tokenUrls = await settingsTokensLines();
         throw new Error(`${message}\n` +
-            `  No seqapi? Mint a PAT in the Atlas UI (Settings → Tokens), then:\n` +
+            `  Run \`seq-studio login\`, then retry \`auth pat create\`.\n` +
+            `  Or mint a PAT in the Atlas UI (Settings → Tokens), then:\n` +
             `    export ATLAS_GIT_PAT=<token>\n` +
-            `  Staging: https://staging.atlas.seqholdings.com/settings/tokens\n` +
-            `  Production: https://atlas.seqholdings.com/settings/tokens\n` +
-            `  BankSouth: https://banksouth.seqholdings.com/settings/tokens\n` +
-            `  Sequence staff: run \`seqapi login\`, then retry \`auth pat create\`.`);
+            tokenUrls.map((line) => `  ${line}`).join('\n'));
     }
 }
 export function parsePatScopes(raw) {

package/dist/auth.d.ts

@@ -1,3 +1,39 @@
+/**
+ * seq-studio and seqapi share one token file and one Auth0 application:
+ * same tenant, client id, audience, and token shape. Either CLI can log in,
+ * and the resulting access token validates against every Atlas /api/* route.
+ *
+ * Two token sources, in the SAME precedence order as seqapi's
+ * `get_access_token` (`shared/seqapi/seqapi/auth.py`):
+ *   1. M2M service account — Auth0 client-credentials grant, used when
+ *      `AUTH0_M2M_CLIENT_SECRET` is set. This is the headless path: CI /
+ *      cloud agents with no interactive login can still push.
+ *      (M2M carries app scopes but NO user identity / workspace membership
+ *      — see the `atlas-test-access` rule.)
+ *   2. Cached user token — read from the seqapi token file and refreshed
+ *      via the Auth0 refresh-token grant when near expiry.
+ *
+ * Login and refresh both write the shared file. This mirrors
+ * `seqapi._save_tokens` exactly:
+ * same fields, same shape, same 0o600 permissions, atomic write via
+ * tmpfile + rename. The M2M token is in-memory only (never persisted).
+ */
+export declare const AUTH0_DOMAIN = "dev-n1t8ts403fp8oyxp.us.auth0.com";
+export declare const AUTH0_CLIENT_ID = "GD9riCDWocfc66odpWBjwBiX43qqAX8r";
+export declare const AUTH0_AUDIENCE = "https://api.studio.com";
+export interface SeqapiTokens {
+    refresh_token?: string;
+    access_token?: string;
+    expires_at?: number;
+}
+/**
+ * A configured M2M credential failed to mint a token. Typed so callers that
+ * normally swallow discovery errors (lazy catalog refresh) can still surface
+ * broken CI credentials instead of a misleading "unknown env" message.
+ */
+export declare class M2mTokenError extends Error {
+    readonly name = "M2mTokenError";
+}
 export declare function seqapiTokenDir(): string;
 export declare function seqapiTokenPath(): string;
 export declare class NotLoggedInError extends Error {
@@ -24,3 +60,16 @@ export declare function tryGetAccessToken(options?: {
      */
     failClosedForM2m?: boolean;
 }): Promise<string | null>;
+/**
+ * Decode the `sub` claim from a JWT without verification. Verification is the
+ * server's job — this is only used to compare identities locally (e.g. to
+ * bind the cached environment catalog to the identity that fetched it).
+ */
+export declare function decodeJwtSub(token: string): string | null;
+/**
+ * The Auth0 subject the CLI would authenticate as right now, without any
+ * network call: the fixed M2M client subject when the secret is configured,
+ * else the `sub` of the cached user token, else null (anonymous).
+ */
+export declare function currentIdentitySubject(): Promise<string | null>;
+export declare function saveTokens(tokens: SeqapiTokens): Promise<void>;