@youkno/edge-cli 1.21.316 → 1.21.318

package/.yarnrc.yml

@@ -1,3 +1,14 @@
+# The cache lives inside the repo, not in ~/.yarn/berry/cache.
+#
+# .pnp.cjs is committed and stores package locations as paths RELATIVE TO ITSELF. With a global
+# cache those paths have to climb out of the repo to reach $HOME, so the number of `../` encodes how
+# deep the checkout happens to be on the machine that ran `yarn install`. The committed file carried
+# six levels; a checkout three levels deep resolves them to nothing and every CLI invocation dies
+# with "the locator that owns .../commander/ can't be found inside the dependency tree".
+#
+# A repo-local cache makes those paths `./.yarn/cache/...`, which means the same for everyone.
+enableGlobalCache: false
+
 approvedGitRepositories:
   - "**"
 

package/README.md

@@ -48,6 +48,10 @@ edge-cli login
 
 This opens your browser to the admin sign-in page. After signing in, tokens are saved to `~/.edge-cli-auth/accounts.json`.
 
+Login creates **two** sessions from the one sign-in: a shell session that drives `edge-cli shell`, and an API-only session that `edge-cli token` prints. Token scope is fixed when the session is created and a refresh re-derives it from the session, so a shell token cannot be narrowed afterwards — the second session is what makes an API-only token possible without a second sign-in.
+
+Prefer the API-only token anywhere a token leaves the CLI (Postman, scripts, a colleague's terminal): a `--scope shell` token can run any shell command your account is allowed to, against whatever environment it was issued for. If you logged in before this existed, `edge-cli token` will tell you to log in again rather than hand back the shell-capable one.
+
 ```bash
 edge-cli login:list          # see saved accounts
 edge-cli login:use <email>   # switch default account
@@ -65,9 +69,10 @@ edge-cli health-check
 edge-cli config
 
 # Get an API token (useful for Postman or curl)
-edge-cli token
-edge-cli token --refresh     # force token refresh
-edge-cli token --header      # print as Authorization header
+edge-cli token                    # API-only token (aud: edge-api)
+edge-cli token --scope shell      # also carries edge-shell; can run shell commands
+edge-cli token --refresh          # force token refresh
+edge-cli token --header           # print as Authorization header
 
 # Run a shell command
 edge-cli shell "<command>"

package/dist/commands/token.js

@@ -3,17 +3,28 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.registerToken = registerToken;
 const auth_1 = require("../lib/auth");
 const config_1 = require("../lib/config");
+const SCOPES = ["api", "shell"];
 function registerToken(program) {
     program
         .command("token")
         .description("Print a JWT access token for API calls (e.g. Postman)")
         .option("--refresh", "Force refresh using refresh token when available")
         .option("--header", "Print as Authorization header line")
+        .option("--scope <scope>", `Which token to print: ${SCOPES.join(" | ")}. 'api' carries the edge-api audience only; ` +
+        `'shell' also carries edge-shell and can run shell commands`, "api")
         .action(async function tokenAction(commandOptions) {
         const parent = this.parent;
         const opts = (parent?.opts() ?? {});
         const cfg = await (0, config_1.resolveEffectiveConfig)(opts);
-        const token = await (0, auth_1.resolveAccessToken)(cfg, Boolean(commandOptions.refresh));
+        const requested = (commandOptions.scope ?? "api").toLowerCase();
+        if (!SCOPES.includes(requested)) {
+            // Refused rather than defaulted: printing a token of a scope nobody asked for is
+            // how a shell-capable credential ends up somewhere it was never meant to go.
+            throw new Error(`Unknown --scope: ${commandOptions.scope} (expected ${SCOPES.join(" or ")})`);
+        }
+        const token = requested === "shell"
+            ? await (0, auth_1.resolveAccessToken)(cfg, Boolean(commandOptions.refresh))
+            : await (0, auth_1.resolveApiAccessToken)(cfg, Boolean(commandOptions.refresh));
         if (commandOptions.header) {
             process.stdout.write(`Authorization: Bearer ${token}\n`);
             return;

package/dist/lib/auth.js

@@ -8,6 +8,7 @@ exports.setDefaultLogin = setDefaultLogin;
 exports.logout = logout;
 exports.login = login;
 exports.resolveAccessToken = resolveAccessToken;
+exports.resolveApiAccessToken = resolveApiAccessToken;
 exports.resolveAuthHeader = resolveAuthHeader;
 exports.resolveAuthHeaderFast = resolveAuthHeaderFast;
 const node_fs_1 = __importDefault(require("node:fs"));
@@ -45,6 +46,16 @@ const DEFAULT_DEVICE_NAME = "edge-cli";
  * exchange.
  */
 const EXCHANGE_SCOPE_SHELL = "shell";
+/**
+ * The app scope is the *absence* of a scope field -- `TokenScope.fromWire` maps blank to `APP` --
+ * so an API-only session is requested by omitting it, not by sending a name for it.
+ *
+ * `null`, never `undefined`: a default parameter fires when an argument is `undefined`, so passing
+ * an `undefined` sentinel to `authExchangeFirebaseToken` silently selected the shell default and
+ * every "API-only" session came back with the `edge-shell` audience. `f(null)` does not trigger the
+ * default.
+ */
+const EXCHANGE_SCOPE_APP = null;
 function scopeKey(cfg) {
     return `${cfg.product}/${cfg.env}`;
 }
@@ -124,6 +135,24 @@ function decodeJwtPayload(token) {
         return {};
     }
 }
+/**
+ * The extra audience `TokenScope.SHELL` stamps. Matched by name rather than by "anything that is
+ * not the API audience", because the API audience is server-configurable (`api.jwt.audience`) and
+ * the CLI cannot know what it was set to.
+ */
+const SHELL_AUDIENCE = "edge-shell";
+/**
+ * Whether a token can drive the shell.
+ *
+ * Read from the token rather than inferred from what was requested. Asking for an app-scoped
+ * session and checking nothing is how every "API-only" token shipped carrying `edge-shell`: the
+ * exchange succeeded, so nothing looked wrong, and the CLI handed out shell credentials for a day.
+ */
+function carriesShellAudience(accessToken) {
+    const aud = decodeJwtPayload(accessToken).aud;
+    const list = Array.isArray(aud) ? aud : typeof aud === "string" ? [aud] : [];
+    return list.some((entry) => entry === SHELL_AUDIENCE);
+}
 function extractEmailFromToken(accessToken) {
     const payload = decodeJwtPayload(accessToken);
     const email = payload.email;
@@ -151,12 +180,12 @@ async function requestTokenEndpoint(cfg, endpoint, payload) {
     }
     return (await response.json());
 }
-async function authExchangeFirebaseToken(cfg, firebaseToken) {
+async function authExchangeFirebaseToken(cfg, firebaseToken, scope = EXCHANGE_SCOPE_SHELL) {
     const resp = await requestTokenEndpoint(cfg, "exchange", {
         firebaseToken,
         deviceId: authDeviceId(),
         deviceName: DEFAULT_DEVICE_NAME,
-        scope: EXCHANGE_SCOPE_SHELL
+        ...(scope === null ? {} : { scope })
     });
     if (!resp?.accessToken) {
         throw new Error("Token exchange did not return accessToken");
@@ -222,9 +251,14 @@ async function logout(cfg, email) {
     if (!account) {
         throw new Error(`Account not found for ${cfg.product}/${cfg.env}: ${target}`);
     }
-    if (account.refreshToken) {
+    // Both sessions, or logout leaves the API-only one alive on the server after the CLI has
+    // forgotten it -- a session nobody can see and nobody will revoke.
+    for (const refreshToken of [account.refreshToken, account.api?.refreshToken]) {
+        if (!refreshToken) {
+            continue;
+        }
         try {
-            await authLogoutRefreshToken(cfg, account.refreshToken);
+            await authLogoutRefreshToken(cfg, refreshToken);
         }
         catch {
             // best effort
@@ -238,19 +272,44 @@ async function logout(cfg, email) {
     writeDb(db);
     return target;
 }
-function storeTokens(cfg, email, tokenResp) {
-    const db = readDb();
-    const scope = getScope(db, cfg);
-    const now = nowEpoch();
-    scope.accounts[email] = {
+function toSession(tokenResp, now) {
+    return {
         accessToken: tokenResp.accessToken,
         refreshToken: tokenResp.refreshToken,
         accessExpEpoch: now + (tokenResp.accessTokenExpiresInSec ?? 0),
         refreshExpEpoch: tokenResp.refreshToken ? now + (tokenResp.refreshTokenExpiresInSec ?? 0) : 0
     };
+}
+/**
+ * @param apiResp the API-only session, when this call has a fresh one. Omitted on a shell refresh,
+ *     which must leave any existing `api` session in place -- rewriting the account wholesale would
+ *     silently drop it and send `edge-cli token` back to "run login again" after every refresh.
+ */
+function storeTokens(cfg, email, tokenResp, apiResp) {
+    const db = readDb();
+    const scope = getScope(db, cfg);
+    const now = nowEpoch();
+    const existingApi = scope.accounts[email]?.api;
+    scope.accounts[email] = {
+        ...toSession(tokenResp, now),
+        api: apiResp ? toSession(apiResp, now) : existingApi
+    };
     scope.default = email;
     writeDb(db);
 }
+/**
+ * Replace only the API session, leaving the shell session untouched.
+ */
+function storeApiTokens(cfg, email, apiResp) {
+    const db = readDb();
+    const scope = getScope(db, cfg);
+    const account = scope.accounts[email];
+    if (!account) {
+        return;
+    }
+    account.api = toSession(apiResp, nowEpoch());
+    writeDb(db);
+}
 function parseCallbackQuery(queryString) {
     const query = queryString.startsWith("?") ? queryString.slice(1) : queryString;
     const params = new URLSearchParams(query);
@@ -401,8 +460,13 @@ async function login(cfg) {
         throw new Error("Authentication callback returned code-based response, exchange not implemented.");
     }
     let tokenResp;
+    // Kept so the API-only session can be exchanged from the same credential below. The
+    // already-first-party branch leaves it undefined: there is no Firebase token to re-exchange,
+    // so that path yields a shell session only.
+    let firebaseToken;
     if (parsed.firebaseToken) {
-        tokenResp = await authExchangeFirebaseToken(cfg, parsed.firebaseToken);
+        firebaseToken = parsed.firebaseToken;
+        tokenResp = await authExchangeFirebaseToken(cfg, firebaseToken);
     }
     else if (parsed.accessToken && parsed.refreshToken) {
         // Already a first-party pair; nothing to exchange.
@@ -415,15 +479,47 @@ async function login(cfg) {
     }
     else if (parsed.accessToken) {
         // No refresh token alongside it means this is the console's `?jwt=` Firebase token.
-        tokenResp = await exchangeCallbackToken(cfg, parsed.accessToken);
+        firebaseToken = parsed.accessToken;
+        tokenResp = await exchangeCallbackToken(cfg, firebaseToken);
     }
     if (!tokenResp?.accessToken) {
         throw new Error("Authentication callback did not include usable token data.");
     }
     const email = parsed.email ?? extractEmailFromToken(tokenResp.accessToken);
-    storeTokens(cfg, email, tokenResp);
+    storeTokens(cfg, email, tokenResp, await exchangeApiSession(cfg, firebaseToken));
     return email;
 }
+/**
+ * Exchange the same Firebase token a second time for an API-only session.
+ *
+ * Failure is reported and swallowed rather than failing the login: the shell session -- the reason
+ * anyone runs this CLI -- already succeeded by this point, and taking the whole login down over the
+ * optional half would turn a working setup into a broken one. `edge-cli token` says what to do when
+ * the session is missing.
+ */
+async function exchangeApiSession(cfg, firebaseToken) {
+    if (!firebaseToken) {
+        return undefined;
+    }
+    try {
+        const resp = await authExchangeFirebaseToken(cfg, firebaseToken, EXCHANGE_SCOPE_APP);
+        if (carriesShellAudience(resp.accessToken)) {
+            // Storing it would put a shell-capable token behind `edge-cli token`, which is the one
+            // outcome this whole feature exists to prevent. Better no API session than a mislabelled
+            // one.
+            process.stderr.write("Warning: the server returned a shell-scoped token for an app-scoped exchange; " +
+                "discarding it.\n'edge-cli token' will need --scope shell until this is resolved.\n");
+            return undefined;
+        }
+        return resp;
+    }
+    catch (err) {
+        const reason = err instanceof Error ? err.message : String(err);
+        process.stderr.write(`Warning: could not create an API-only session (${reason}).\n` +
+            `'edge-cli token' will need --scope shell until the next successful login.\n`);
+        return undefined;
+    }
+}
 async function validateAccessToken(cfg, accessToken) {
     const url = new URL(`${cfg.baseUrl.replace(/\/$/, "")}/shell`);
     url.searchParams.set("cmd", "help");
@@ -496,6 +592,60 @@ async function resolveAccessToken(cfg, forceRefresh = false, skipValidate = fals
     }
     return accessToken;
 }
+/**
+ * The account's API-only access token, refreshed when it is at or near expiry.
+ *
+ * Deliberately does no liveness probe. `validateAccessToken` asks `GET /shell?cmd=help`, which this
+ * token is *supposed* to be refused by -- running it here would read a correctly-scoped token as a
+ * broken one and refresh it on every call.
+ *
+ * A missing API session is an error rather than a silent fall back to the shell token: handing back
+ * a token with more audiences than the caller asked for is the same silent substitution the server
+ * refuses when it will not downgrade a shell request to APP.
+ */
+async function resolveApiAccessToken(cfg, forceRefresh = false) {
+    const db = readDb();
+    const scope = getScope(db, cfg);
+    const email = scope.default;
+    if (!email) {
+        throw new Error(`No JWT session for ${cfg.product}/${cfg.env}. Run 'edge-cli login'.`);
+    }
+    const account = scope.accounts[email];
+    if (!account) {
+        throw new Error(`No access token for ${email}. Run 'edge-cli login'.`);
+    }
+    const api = account.api;
+    if (!api?.accessToken) {
+        throw new Error(`No API-only session for ${email} on ${cfg.product}/${cfg.env}.\n` +
+            `Run 'edge-cli login' to create one, or 'edge-cli token --scope shell' to print the ` +
+            `shell-capable token instead (it also drives the shell, so do not paste it elsewhere).`);
+    }
+    // Checked on read, not only on write, so a session stored by a build that asked for the wrong
+    // scope is refused rather than handed out. Those tokens are already on disk in the wild.
+    if (carriesShellAudience(api.accessToken)) {
+        throw new Error(`The stored API session for ${email} carries the ${SHELL_AUDIENCE} audience, so it is ` +
+            `not API-only. Run 'edge-cli login' to replace it.`);
+    }
+    const expiry = api.accessExpEpoch ?? 0;
+    const stale = expiry > 0 && expiry <= nowEpoch() + 60;
+    if ((forceRefresh || stale) && api.refreshToken) {
+        try {
+            const refreshed = await authRefreshToken(cfg, api.refreshToken);
+            const merged = {
+                accessToken: refreshed.accessToken,
+                refreshToken: refreshed.refreshToken || api.refreshToken,
+                accessTokenExpiresInSec: refreshed.accessTokenExpiresInSec,
+                refreshTokenExpiresInSec: refreshed.refreshTokenExpiresInSec
+            };
+            storeApiTokens(cfg, email, merged);
+            return merged.accessToken;
+        }
+        catch {
+            // Fall through to the stored token; it may still have life left in it.
+        }
+    }
+    return api.accessToken;
+}
 async function resolveAuthHeader(cfg) {
     const accessToken = await resolveAccessToken(cfg);
     return `Bearer ${accessToken}`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@youkno/edge-cli",
-  "version": "1.21.316",
+  "version": "1.21.318",
   "description": "Cross-platform Edge CLI",
   "bin": "dist/index.js",
   "publishConfig": {

package/src/commands/token.ts

@@ -1,20 +1,43 @@
 import { Command } from "commander";
 
-import { resolveAccessToken } from "../lib/auth";
+import { resolveAccessToken, resolveApiAccessToken } from "../lib/auth";
 import { resolveEffectiveConfig } from "../lib/config";
 import { CliOptions } from "../lib/types";
 
+const SCOPES = ["api", "shell"] as const;
+type TokenScope = (typeof SCOPES)[number];
+
 export function registerToken(program: Command): void {
     program
         .command("token")
         .description("Print a JWT access token for API calls (e.g. Postman)")
         .option("--refresh", "Force refresh using refresh token when available")
         .option("--header", "Print as Authorization header line")
-        .action(async function tokenAction(this: Command, commandOptions: { refresh?: boolean; header?: boolean }) {
+        .option(
+            "--scope <scope>",
+            `Which token to print: ${SCOPES.join(" | ")}. 'api' carries the edge-api audience only; ` +
+                `'shell' also carries edge-shell and can run shell commands`,
+            "api"
+        )
+        .action(async function tokenAction(
+            this: Command,
+            commandOptions: { refresh?: boolean; header?: boolean; scope?: string }
+        ) {
             const parent = this.parent;
             const opts = (parent?.opts() ?? {}) as CliOptions;
             const cfg = await resolveEffectiveConfig(opts);
-            const token = await resolveAccessToken(cfg, Boolean(commandOptions.refresh));
+
+            const requested = (commandOptions.scope ?? "api").toLowerCase();
+            if (!SCOPES.includes(requested as TokenScope)) {
+                // Refused rather than defaulted: printing a token of a scope nobody asked for is
+                // how a shell-capable credential ends up somewhere it was never meant to go.
+                throw new Error(`Unknown --scope: ${commandOptions.scope} (expected ${SCOPES.join(" or ")})`);
+            }
+
+            const token =
+                requested === "shell"
+                    ? await resolveAccessToken(cfg, Boolean(commandOptions.refresh))
+                    : await resolveApiAccessToken(cfg, Boolean(commandOptions.refresh));
 
             if (commandOptions.header) {
                 process.stdout.write(`Authorization: Bearer ${token}\n`);