@youkno/edge-cli 1.21.316 → 1.21.318

package/src/lib/auth.ts

@@ -38,13 +38,40 @@ const DEFAULT_DEVICE_NAME = "edge-cli";
  */
 const EXCHANGE_SCOPE_SHELL = "shell";
 
-type AuthAccount = {
+/**
+ * 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;
+
+type AuthSession = {
     accessToken: string;
     refreshToken?: string;
     accessExpEpoch?: number;
     refreshExpEpoch?: number;
 };
 
+type AuthAccount = AuthSession & {
+    /**
+     * A second session exchanged at login with no scope, so its tokens carry only the `edge-api`
+     * audience while the account's main session carries `edge-shell` as well.
+     *
+     * Two sessions rather than one downgraded token because scope is fixed at exchange time and
+     * persisted on `user_session.scope`; refresh re-derives it from the session and ignores the
+     * request, so a shell token cannot be narrowed after the fact. Both exchanges reuse the one
+     * Firebase token the callback delivered, so this costs an HTTP call rather than a second login.
+     *
+     * Optional: accounts stored before this existed have no `api` session, and `edge-cli token`
+     * says so rather than quietly handing back the shell-capable one.
+     */
+    api?: AuthSession;
+};
+
 type ScopeData = {
     default?: string;
     accounts: Record<string, AuthAccount>;
@@ -149,6 +176,26 @@ function decodeJwtPayload(token: string): Record<string, unknown> {
     }
 }
 
+/**
+ * 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: string): boolean {
+    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: string): string {
     const payload = decodeJwtPayload(accessToken);
     const email = payload.email;
@@ -185,12 +232,16 @@ async function requestTokenEndpoint(
     return (await response.json()) as TokenResponse;
 }
 
-async function authExchangeFirebaseToken(cfg: EffectiveConfig, firebaseToken: string): Promise<TokenResponse> {
+async function authExchangeFirebaseToken(
+    cfg: EffectiveConfig,
+    firebaseToken: string,
+    scope: string | null = EXCHANGE_SCOPE_SHELL
+): Promise<TokenResponse> {
     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");
@@ -261,9 +312,14 @@ export async function logout(cfg: EffectiveConfig, email?: string): Promise<stri
         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
         }
@@ -278,21 +334,53 @@ export async function logout(cfg: EffectiveConfig, email?: string): Promise<stri
     return target;
 }
 
-function storeTokens(cfg: EffectiveConfig, email: string, tokenResp: TokenResponse): void {
+function toSession(tokenResp: TokenResponse, now: number): AuthSession {
+    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: EffectiveConfig,
+    email: string,
+    tokenResp: TokenResponse,
+    apiResp?: TokenResponse
+): void {
     const db = readDb();
     const scope = getScope(db, cfg);
     const now = nowEpoch();
+    const existingApi = scope.accounts[email]?.api;
 
     scope.accounts[email] = {
-        accessToken: tokenResp.accessToken,
-        refreshToken: tokenResp.refreshToken,
-        accessExpEpoch: now + (tokenResp.accessTokenExpiresInSec ?? 0),
-        refreshExpEpoch: tokenResp.refreshToken ? now + (tokenResp.refreshTokenExpiresInSec ?? 0) : 0
+        ...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: EffectiveConfig, email: string, apiResp: TokenResponse): void {
+    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: string): {
     email?: string;
     accessToken?: string;
@@ -464,8 +552,13 @@ export async function login(cfg: EffectiveConfig): Promise<string> {
     }
 
     let tokenResp: TokenResponse | undefined;
+    // 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: string | undefined;
     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.
         tokenResp = {
@@ -476,7 +569,8 @@ export async function login(cfg: EffectiveConfig): Promise<string> {
         };
     } 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) {
@@ -484,10 +578,48 @@ export async function login(cfg: EffectiveConfig): Promise<string> {
     }
 
     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: EffectiveConfig,
+    firebaseToken: string | undefined
+): Promise<TokenResponse | undefined> {
+    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: EffectiveConfig, accessToken: string): Promise<boolean> {
     const url = new URL(`${cfg.baseUrl.replace(/\/$/, "")}/shell`);
     url.searchParams.set("cmd", "help");
@@ -569,6 +701,67 @@ export async function resolveAccessToken(cfg: EffectiveConfig, forceRefresh = fa
     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.
+ */
+export async function resolveApiAccessToken(cfg: EffectiveConfig, forceRefresh = false): Promise<string> {
+    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: TokenResponse = {
+                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;
+}
+
 export async function resolveAuthHeader(cfg: EffectiveConfig): Promise<string> {
     const accessToken = await resolveAccessToken(cfg);
     return `Bearer ${accessToken}`;