primitive-admin 1.2.0-alpha.1 → 1.2.0-alpha.11

package/dist/src/commands/auth.js

@@ -1,10 +1,19 @@
-import { loadCredentials, saveCredentials, clearCredentials, isTokenExpired, getCurrentApp, getConfiguredServerUrl, } from "../lib/config.js";
-import { allowGlobalCredentials } from "../lib/credentials-store.js";
+import { loadCredentials, saveCredentials, clearCredentials, isTokenExpired, getConfiguredServerUrl, } from "../lib/config.js";
+import { allowGlobalCredentials, allowGlobalCredentialsForServer, clearLeftoverLogins, environmentToken, getCredentialsFilePath, globalLoginCommand, isProjectMode, leftoverLogins, loginEnvironments, mismatchedLogin, partitionFromEnvironment, sameServer, worktreeLoginNotes, } from "../lib/credentials-store.js";
+import { PrimitiveEnvError } from "../lib/env-resolver-core.js";
+import { isCiToken } from "../lib/session-id.js";
 import { browserLogin } from "../lib/auth-flow.js";
+import { getCurrentEnvironment, getProjectConfig, requireCurrentEnvironment, } from "../lib/env-resolver.js";
+import { buildScopeRequest } from "../lib/scope-request.js";
+import { projectLoginApps } from "../lib/project-login-apps.js";
+import { loginExchangeRefusal } from "../lib/login-exchange-check.js";
+import { ApiClient, ApiError } from "../lib/api-client.js";
 import { fetchWithTLS } from "../lib/fetch.js";
 import { REFRESH_EXPIRED_MESSAGE, RefreshError, refreshAdminCredentials, } from "../lib/refresh-admin-credentials.js";
 import { logoutAdminSession } from "../lib/logout-admin-session.js";
+import { loginScopeLines } from "../lib/login-scope-lines.js";
 import { registerAuthSessionsCommands } from "./auth-sessions.js";
+import { outsideProjectServer } from "./apps.js";
 import { success, error, info, keyValue, json } from "../lib/output.js";
 function parseJwt(token) {
     try {
@@ -19,6 +28,120 @@ function parseJwt(token) {
         return {};
     }
 }
+/**
+ * Whether a project is in scope. A project config that cannot be read counts
+ * as one, so the command reports it exactly as it always has.
+ */
+function inProject() {
+    try {
+        return isProjectMode();
+    }
+    catch {
+        return true;
+    }
+}
+/** The environment's app, or undefined outside a project. */
+function environmentAppId() {
+    try {
+        return getCurrentEnvironment()?.config.appId;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * The project a login runs in: its server and the apps of the committed
+ * environments on it (#4512). Undefined outside a project.
+ */
+function loginProject(serverUrl) {
+    const config = getProjectConfig();
+    return config ? { serverUrl, apps: projectLoginApps(config.environments, serverUrl) } : undefined;
+}
+/** The project a login's lines name (#4512); empty outside a project. */
+function loginLinesContext(serverUrl) {
+    const config = getProjectConfig();
+    if (!config)
+        return {};
+    let signedIn = [];
+    try {
+        signedIn = loginEnvironments()?.environments ?? [];
+    }
+    catch {
+        // The environments signed in are a courtesy; the login is stored.
+    }
+    return { serverUrl, environments: config.environments, signedIn };
+}
+/**
+ * The stored login on this server, or null; a scoped login builds on it.
+ * Never `PRIMITIVE_TOKEN`'s credentials (#3890): a login is not built on, nor
+ * saved beside, a CI job's token.
+ */
+function storedLogin(serverUrl) {
+    try {
+        const stored = loadCredentials();
+        return stored && stored.source !== "env" && stored.serverUrl === serverUrl ? stored : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * The environments a login here signs in or out, when it is more than one:
+ * every environment of the project on the login's server (#4512), "dev,
+ * staging, feat". Null when the login is the current environment's alone.
+ */
+function sharedLoginEnvironments() {
+    let shared;
+    try {
+        shared = loginEnvironments();
+    }
+    catch {
+        return null;
+    }
+    return shared && shared.environments.length > 1 ? shared.environments.join(", ") : null;
+}
+/**
+ * Refuse a command that needs a login when there is none, saying why when a
+ * linked git worktree could not use the main worktree's (#4492).
+ */
+function refuseNotLoggedIn() {
+    error("Not logged in. Run 'primitive login' first.");
+    const hint = worktreeLoginNotes.notLoggedIn();
+    if (hint)
+        info(hint);
+    process.exit(2);
+}
+/**
+ * The last line of a login or logout in a linked git worktree that holds a
+ * credentials file of its own, which the shared login makes unused (#4492).
+ */
+function noteIgnoredCredentialsFile() {
+    const ignored = worktreeLoginNotes.ignoredFile();
+    if (ignored)
+        info(ignored);
+}
+/** The session id (`sid`) a stored access token carries. */
+function sessionIdOf(credentials) {
+    const sid = credentials ? parseJwt(credentials.accessToken).sid : undefined;
+    return typeof sid === "string" && sid ? sid : undefined;
+}
+function stepUpFrom(exchange) {
+    return {
+        accessToken: exchange.accessToken,
+        expiresAt: exchange.expiresAt,
+        sessionId: exchange.sessionId ?? "",
+        scope: exchange.scope ?? [],
+        apps: exchange.apps ?? [],
+    };
+}
+function appsLabel(apps) {
+    return apps.length > 0 ? apps.join(", ") : "unpinned";
+}
+/** A stored step-up that has not expired, or null. */
+function liveStepUp(credentials) {
+    const stepUp = credentials.stepUp;
+    return stepUp && new Date(stepUp.expiresAt).getTime() > Date.now() ? stepUp : null;
+}
 function readStdin() {
     return new Promise((resolve, reject) => {
         if (process.stdin.isTTY) {
@@ -32,18 +155,84 @@ function readStdin() {
         process.stdin.on("error", reject);
     });
 }
+/**
+ * `primitive token --scope …` (#3889): a token no wider than the stored login
+ * is derived headlessly; a wider one is approved in the browser. Either way
+ * only the token reaches stdout, and nothing is stored.
+ *
+ * `--step-up` (#4564) always goes to the browser: a derivation signs the
+ * stored login's own kind, so it could only print a token that is no step-up.
+ */
+async function printScopedToken(options) {
+    const credentials = loadCredentials();
+    const built = buildScopeRequest({
+        command: "token",
+        scope: options.scope,
+        app: options.app,
+        ttl: options.ttl,
+        stepUp: options.stepUp,
+        envAppId: environmentAppId(),
+        parentSid: sessionIdOf(credentials),
+    });
+    if ("message" in built) {
+        error(built.message);
+        process.exit(1);
+    }
+    if (!credentials)
+        refuseNotLoggedIn();
+    const query = built.query;
+    const scope = query.scope.split(",");
+    const apps = query.apps ? query.apps.split(",") : [];
+    if (options.stepUp) {
+        info("A step-up needs your approval in the browser.");
+    }
+    else {
+        try {
+            const derived = await new ApiClient().exchangeToken({
+                scope,
+                ...(apps.length > 0 ? { apps } : {}),
+                ...(options.ttl !== undefined ? { ttl: options.ttl } : {}),
+            });
+            console.log(derived.accessToken);
+            return;
+        }
+        catch (err) {
+            if (!(err instanceof ApiError && err.code === "TOKEN_WIDER_THAN_PRESENTED")) {
+                error(err?.message || "Token exchange failed");
+                process.exit(1);
+            }
+        }
+        info("This token is wider than your login, so it needs your approval in the browser.");
+    }
+    const result = await browserLogin(credentials.serverUrl, {
+        query,
+        ...(credentials.globalAdminAppId ? { partition: credentials.globalAdminAppId } : {}),
+        save: false,
+    });
+    if (!result.success || !result.exchange) {
+        error(`Token approval failed: ${result.error || "Unknown error"}`);
+        process.exit(1);
+    }
+    console.log(result.exchange.accessToken);
+}
 export function registerAuthCommands(program) {
     // Login command
     program
         .command("login")
         .description("Authenticate with the Primitive admin API via browser OAuth")
         .option("--token-stdin", "Read a refresh token from stdin instead of browser OAuth")
+        .option("--scope <list>", "Ask for a scoped session (read, write, admin, data:read, data:write); a list with admin asks for a 15-minute step-up")
+        .option("--step-up", "Ask for a 15-minute step-up holding exactly --scope, stored beside your login (writes to a protected app need one)")
+        .option("--app <ids>", "Pin the session to these app ids (comma-separated), or all for every app; by default a login is pinned to the project's apps on its server and a step-up to the environment's app")
         .action(async (options) => {
         // Login is one of the four commands that may work with no project in
         // scope (#3154, intent criterion 5): it is what CREATES the credentials
         // a first `primitive init` then uses. Inside a project this changes
         // nothing — the per-environment slot still answers.
         allowGlobalCredentials();
+        if (environmentToken()) {
+            info("PRIMITIVE_TOKEN is set and takes precedence over this login while it is; unset it to use the login.");
+        }
         // Resolve the target server from the active environment (project mode) or
         // DEFAULT_SERVER_URL (legacy mode). Never a `-s/--server` flag — that was
         // removed in #1343 because it always targeted prod regardless of --env.
@@ -57,6 +246,10 @@ export function registerAuthCommands(program) {
             process.exit(1);
         }
         if (options.tokenStdin) {
+            if (options.scope !== undefined || options.app !== undefined || options.stepUp) {
+                error("--token-stdin takes no --scope, --app or --step-up: the token keeps the scope it was issued with.");
+                process.exit(1);
+            }
             const refreshToken = (await readStdin()).trim();
             if (!refreshToken) {
                 error("No token provided on stdin. Pipe a refresh token, e.g.:");
@@ -69,6 +262,7 @@ export function registerAuthCommands(program) {
                 // shared refresh helper. Only `serverUrl` and `refreshToken` are
                 // needed by the helper; the post-refresh response fills in the
                 // rest. (Codex cleanup #2 — issue #772.)
+                const partition = partitionFromEnvironment();
                 const seed = {
                     serverUrl,
                     accessToken: "",
@@ -77,9 +271,13 @@ export function registerAuthCommands(program) {
                     adminId: "",
                     email: "",
                     role: "admin",
+                    ...(partition ? { globalAdminAppId: partition } : {}),
                 };
                 const refreshed = await refreshAdminCredentials(seed);
                 const payload = parseJwt(refreshed.accessToken);
+                // As with a browser login, a step-up already stored stays usable
+                // (and revocable by logout) until it expires.
+                const existing = storedLogin(serverUrl);
                 const credentials = {
                     ...refreshed,
                     adminId: payload.adminId || "",
@@ -87,15 +285,24 @@ export function registerAuthCommands(program) {
                     role: payload.role || "admin",
                     name: payload.name,
                     globalAdminAppId: payload.globalAdminAppId,
+                    ...(existing?.stepUp ? { stepUp: existing.stepUp } : {}),
                 };
                 saveCredentials(credentials);
                 success(`Logged in as ${credentials.email}`);
+                const shared = sharedLoginEnvironments();
+                if (shared)
+                    info(`Signed in to: ${shared}`);
+                const storedElsewhere = worktreeLoginNotes.storedElsewhere();
+                if (storedElsewhere)
+                    info(storedElsewhere);
                 if (credentials.role === "super-admin") {
                     info("You have super-admin privileges.");
                 }
+                noteIgnoredCredentialsFile();
             }
             catch (err) {
-                if (err instanceof RefreshError && err.code === "SESSION_REVOKED") {
+                if (err instanceof RefreshError &&
+                    (err.code === "SESSION_REVOKED" || err.code === "SESSION_UNSCOPED")) {
                     error(err.message);
                 }
                 else if (err instanceof RefreshError) {
@@ -108,17 +315,69 @@ export function registerAuthCommands(program) {
             }
             return;
         }
-        const result = await browserLogin(serverUrl);
-        if (result.success && result.credentials) {
-            success(`Logged in as ${result.credentials.email}`);
-            if (result.credentials.role === "super-admin") {
-                info("You have super-admin privileges.");
-            }
+        // #3889 — every login is approved in the browser. `--scope`/`--app`
+        // ask for a scoped session or an admin step-up; without `--app`, a
+        // login in a project is pinned to the project's apps on this server
+        // (#4512). The login this one builds on names the step-up's parent and
+        // the partition to exchange in.
+        const existing = storedLogin(serverUrl);
+        const built = buildScopeRequest({
+            command: "login",
+            scope: options.scope,
+            app: options.app,
+            stepUp: options.stepUp === true,
+            envAppId: environmentAppId(),
+            project: loginProject(serverUrl),
+            parentSid: sessionIdOf(existing),
+        });
+        if ("message" in built) {
+            error(built.message);
+            process.exit(1);
         }
-        else {
+        const partition = existing?.globalAdminAppId ?? partitionFromEnvironment();
+        const result = await browserLogin(serverUrl, {
+            ...("query" in built ? { query: built.query } : {}),
+            ...(partition ? { partition } : {}),
+            save: false,
+        });
+        if (!result.success || !result.credentials || !result.exchange) {
             error(`Login failed: ${result.error || "Unknown error"}`);
             process.exit(1);
         }
+        // #4512 — a server older than this CLI mints every app for a pinned
+        // request; nothing is stored unless the session carries the pins asked for.
+        const refusal = "query" in built ? loginExchangeRefusal(built.query, result.exchange) : null;
+        if (refusal) {
+            error(refusal);
+            process.exit(1);
+        }
+        if (result.exchange.kind === "step-up" && existing) {
+            // The step-up sits beside the login; the login itself is unchanged.
+            const stepUp = stepUpFrom(result.exchange);
+            saveCredentials({ ...existing, stepUp });
+            success(`Step-up holding ${stepUp.scope.join(", ")} active until ${stepUp.expiresAt} (${appsLabel(stepUp.apps)}). A command refused for a step-up retries with it.`);
+            noteIgnoredCredentialsFile();
+            return;
+        }
+        // A new login replaces the slot; a step-up already stored stays usable
+        // until it expires.
+        saveCredentials({
+            ...result.credentials,
+            ...(existing?.stepUp ? { stepUp: existing.stepUp } : {}),
+        });
+        success(`Logged in as ${result.credentials.email}`);
+        // #3891, #4512 — say what the login holds and reaches, every
+        // environment it signs in to and which need a login of their own, and
+        // how to step up for what it cannot do.
+        for (const line of loginScopeLines(result.exchange, loginLinesContext(serverUrl)))
+            info(line);
+        const storedElsewhere = worktreeLoginNotes.storedElsewhere();
+        if (storedElsewhere)
+            info(storedElsewhere);
+        if (result.credentials.role === "super-admin") {
+            info("You have super-admin privileges.");
+        }
+        noteIgnoredCredentialsFile();
     });
     // Bootstrap command - create first admin on empty database
     program
@@ -134,6 +393,16 @@ export function registerAuthCommands(program) {
         allowGlobalCredentials();
         const serverUrl = options.server.replace(/\/$/, "");
         try {
+            // Inside a project the login is stored in the current environment's
+            // slot, which only holds a login from that environment's server
+            // (#4492): refuse before an admin is created whose login could not be
+            // stored.
+            const env = getCurrentEnvironment();
+            if (env && !sameServer(serverUrl, env.config.apiUrl)) {
+                error(`"${env.name}" points at ${env.config.apiUrl}, not ${serverUrl}. Run bootstrap outside ` +
+                    `a project, or from an environment that points at ${serverUrl}.`);
+                process.exit(1);
+            }
             const response = await fetchWithTLS(`${serverUrl}/admin/api/bootstrap`, {
                 method: "POST",
                 headers: { "Content-Type": "application/json" },
@@ -172,6 +441,17 @@ export function registerAuthCommands(program) {
     // command fails: re-running it retries the revocation. A 401 means the
     // stored token was already refused — nothing is left to revoke, so the
     // credentials are cleared.
+    //
+    // #4512: every environment on a server uses the server's one login, so
+    // logout in any of them signs out all of them, and says which. A login an
+    // older CLI kept for another environment on the server (a leftover) is
+    // revoked too.
+    //
+    // #4492: a login whose slot records another server than the environment's
+    // is the one no other command uses. Logout revokes it at the server that
+    // issued it — the one that can — and says the environment is not signed in.
+    // In a linked git worktree the login is the main worktree's, so logout signs
+    // out every worktree that holds the project, and says so.
     program
         .command("logout")
         .description("Revoke this login's admin session on the server and clear stored credentials")
@@ -180,14 +460,35 @@ export function registerAuthCommands(program) {
         // would leave a global credentials file no command could clear
         // (#3154, adjudicated finding F1).
         allowGlobalCredentials();
-        const credentials = loadCredentials();
-        if (!credentials) {
+        // #3890 — a CI job's token is not a login to sign out of: its session
+        // is revoked by id, and nothing stored is touched.
+        if (environmentToken()) {
+            error("PRIMITIVE_TOKEN is set; revoke the CI session with `primitive auth sessions revoke <id>` instead.");
+            process.exit(1);
+        }
+        let credentials;
+        let issuedElsewhere = false;
+        try {
+            credentials = loadCredentials();
+        }
+        catch (err) {
+            if (!(err instanceof PrimitiveEnvError && err.kind === "server-mismatch"))
+                throw err;
+            credentials = mismatchedLogin();
+            issuedElsewhere = credentials !== null;
+        }
+        const leftovers = leftoverLogins();
+        if (!credentials && leftovers.length === 0) {
             info("Not logged in.");
+            noteIgnoredCredentialsFile();
             return;
         }
-        let outcome;
+        let outcome = null;
         try {
-            outcome = await logoutAdminSession(credentials);
+            if (credentials)
+                outcome = await logoutAdminSession(credentials);
+            for (const leftover of leftovers)
+                await logoutAdminSession(leftover);
         }
         catch (err) {
             error(`${err?.message || "Logout failed."} The session was NOT revoked, and ` +
@@ -195,15 +496,29 @@ export function registerAuthCommands(program) {
             process.exit(1);
         }
         clearCredentials();
-        if (outcome.kind === "already-invalid") {
+        clearLeftoverLogins();
+        if (outcome?.kind === "already-invalid") {
             success("Logged out. The stored session was already invalid on the server; local credentials cleared.");
         }
-        else if (outcome.revoked.length > 0) {
+        else if (outcome && outcome.revoked.length > 0) {
             success(`Logged out. Revoked session ${outcome.revoked.join(", ")}.`);
         }
         else {
             success("Logged out successfully.");
         }
+        if (issuedElsewhere && credentials) {
+            const env = getCurrentEnvironment();
+            info(`This login was issued by ${credentials.serverUrl}; "${env?.name}" now points at ` +
+                `${env?.config.apiUrl}, where you are not signed in.`);
+        }
+        const shared = sharedLoginEnvironments();
+        if (shared)
+            success(`Signed out of: ${shared}`);
+        const tree = loginEnvironments();
+        const sharedWorktrees = tree ? worktreeLoginNotes.sharedLogout(tree.tree) : null;
+        if (sharedWorktrees)
+            info(sharedWorktrees);
+        noteIgnoredCredentialsFile();
     });
     // Whoami command
     //
@@ -212,34 +527,120 @@ export function registerAuthCommands(program) {
     // about to act on?"); only the source moved, from a per-machine credentials
     // slot to the one place that can name an app. Outside a project there is no
     // environment and so no app, which is the honest answer there.
+    //
+    // #4918 — outside a project it reports the user and server a command run
+    // there would use: the server PRIMITIVE_SERVER_URL names, or production,
+    // and the global login only when that server issued it — the pin
+    // `apps delete` uses (#4905). Inside a project nothing here runs.
     program
         .command("whoami")
-        .description("Show current authenticated user")
+        .description("Show the user, server and app a command run here would use")
         .option("--json", "Output as JSON")
-        .action((options) => {
-        const credentials = loadCredentials();
-        if (!credentials) {
-            error("Not logged in. Run 'primitive login' first.");
-            process.exit(2);
+        .action(async (options) => {
+        const outside = inProject() ? null : outsideProjectServer();
+        let credentials;
+        if (outside !== null) {
+            allowGlobalCredentialsForServer(outside);
+            try {
+                credentials = loadCredentials();
+            }
+            catch (err) {
+                error(err.message);
+                process.exit(1);
+            }
+            if (!credentials) {
+                error(`Not logged in to ${outside}. Run '${globalLoginCommand(outside)} <app-id>' (or --app all) first.`);
+                process.exit(2);
+            }
+        }
+        else {
+            credentials = loadCredentials();
+            if (!credentials)
+                refuseNotLoggedIn();
+        }
+        const env = outside === null ? requireCurrentEnvironment() : null;
+        const app = env ? { appId: env.config.appId, appName: env.config.appName } : null;
+        const fromEnvironment = credentials.source === "env";
+        const serverSource = outside === null ? "environment" : process.env.PRIMITIVE_SERVER_URL?.trim() ? "PRIMITIVE_SERVER_URL" : "default";
+        const authSource = fromEnvironment ? "PRIMITIVE_TOKEN" : outside === null ? "project" : "global";
+        // #3889 — the session's kind, scope and pins, read from the stored
+        // token's claims, and the step-up held beside it. No request.
+        // #3890 — an opaque CI token in PRIMITIVE_TOKEN has no claims to read:
+        // the server says who it is, in one request.
+        let who;
+        let session;
+        if (fromEnvironment && isCiToken(credentials.accessToken)) {
+            try {
+                const me = (await new ApiClient().getMe());
+                who = { email: me.email, adminId: me.adminId, role: me.role };
+                session = me.session ?? null;
+            }
+            catch (err) {
+                error(err?.message || "Could not read the token's session.");
+                process.exit(1);
+            }
         }
-        const app = getCurrentApp();
+        else {
+            const claims = parseJwt(credentials.accessToken);
+            who = fromEnvironment
+                ? {
+                    email: typeof claims.email === "string" ? claims.email : "",
+                    adminId: typeof claims.adminId === "string" ? claims.adminId : "",
+                    role: typeof claims.role === "string" ? claims.role : "",
+                }
+                : { email: credentials.email, adminId: credentials.adminId, role: credentials.role };
+            session = {
+                ...(typeof claims.sid === "string" ? { sessionId: claims.sid } : {}),
+                kind: typeof claims.kind === "string" ? claims.kind : null,
+                scope: Array.isArray(claims.scope) ? claims.scope : "full",
+                apps: Array.isArray(claims.apps) ? claims.apps : [],
+                name: null,
+            };
+        }
+        const kind = session?.kind ?? null;
+        const scope = session?.scope ?? "full";
+        const apps = session?.apps ?? [];
+        const stepUp = liveStepUp(credentials);
         if (options.json) {
             json({
-                email: credentials.email,
-                adminId: credentials.adminId,
-                role: credentials.role,
+                email: who.email,
+                adminId: who.adminId,
+                role: who.role,
                 serverUrl: credentials.serverUrl,
-                currentAppId: app?.appId,
-                currentAppName: app?.appName,
+                serverSource,
+                authSource,
+                environment: env?.name ?? null,
+                currentAppId: app ? app.appId : null,
+                currentAppName: app ? app.appName : null,
+                kind,
+                scope,
+                apps,
+                stepUp: stepUp
+                    ? { expiresAt: stepUp.expiresAt, scope: stepUp.scope, apps: stepUp.apps }
+                    : null,
+                ...(fromEnvironment ? { auth: "env", session } : {}),
             });
             return;
         }
-        keyValue("Email", credentials.email);
-        keyValue("Admin ID", credentials.adminId);
-        keyValue("Role", credentials.role);
+        keyValue("Email", who.email);
+        keyValue("Admin ID", who.adminId);
+        keyValue("Role", who.role);
+        if (env)
+            keyValue("Environment", env.name);
         keyValue("Server", credentials.serverUrl);
-        if (app) {
-            keyValue("Current App", app.appName || app.appId);
+        keyValue("Server Source", env ? `environment "${env.name}"` : serverSource);
+        keyValue("Current App", app ? app.appName || app.appId : "none (pass --app)");
+        if (fromEnvironment)
+            keyValue("Auth", "PRIMITIVE_TOKEN");
+        else if (!env)
+            keyValue("Auth", `global login (${getCredentialsFilePath()})`);
+        keyValue("Kind", kind);
+        if (session?.name)
+            keyValue("Name", session.name);
+        keyValue("Scope", scope === "full" ? "full" : scope.join(", "));
+        keyValue("Apps", appsLabel(apps));
+        if (stepUp) {
+            keyValue("Step-up", `active until ${stepUp.expiresAt}, scope ${stepUp.scope.join(", ")}, ${appsLabel(stepUp.apps)}`);
         }
     });
     // Token command - print access token for scripting
@@ -258,11 +659,34 @@ export function registerAuthCommands(program) {
         .command("token")
         .description("Print the current access token (for scripting)")
         .option("--refresh", "Print the refresh token instead of the access token")
+        .option("--scope <list>", "Print a token with only these scopes; one wider than your login is approved in the browser and cannot be refreshed")
+        .option("--step-up", "Print a 15-minute step-up holding exactly --scope, always approved in the browser")
+        .option("--app <ids>", "Pin the printed token to these app ids (comma-separated), or all for an unpinned one")
+        .option("--ttl <d>", "Lifetime of the printed token, such as 15m (at most 1h; 15m for a step-up)")
         .action(async (options) => {
+        if (options.scope !== undefined ||
+            options.app !== undefined ||
+            options.ttl !== undefined ||
+            options.stepUp) {
+            if (options.refresh) {
+                error("--refresh prints the stored refresh token; it takes no --scope, --app, --ttl or --step-up.");
+                process.exit(1);
+            }
+            await printScopedToken(options);
+            return;
+        }
         const credentials = loadCredentials();
-        if (!credentials) {
-            error("Not logged in. Run 'primitive login' first.");
-            process.exit(2);
+        if (!credentials)
+            refuseNotLoggedIn();
+        // #3890 — the token in PRIMITIVE_TOKEN is printed as it is; it has no
+        // refresh token and is never refreshed here.
+        if (credentials.source === "env") {
+            if (options.refresh) {
+                error("PRIMITIVE_TOKEN has no refresh token.");
+                process.exit(1);
+            }
+            console.log(credentials.accessToken);
+            return;
         }
         if (options.refresh) {
             // Dumb-print contract preserved — see Fork 4 in the design doc.