@youkno/edge-cli 1.21.339 → 1.21.341

package/README.md

@@ -52,6 +52,8 @@ Login creates **two** sessions from the one sign-in: a shell session that drives
 
 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.
 
+To sign in as a member of staff of a particular company, pass its client ID (pin): `edge-cli --client 101 login`. Both sessions are then exchanged for your row in that company, which is where roles such as shell access live once staff accounts are split per company. Without `--client` you sign in as yourself, as before. Only the flag on the `login` command counts. `CLIENT_ID` in `.edge-api` does not, and the REPL's `/login` ignores `--client`: it re-authenticates whatever identity the current session already is, keeping its company when the stored login is `email#clientId`. So a `--client` given for shop context never switches identity. The company session is stored beside your own login as `email#clientId` (for example `ops@example.com#101`), never over it, and becomes the default. `edge-cli login:use <email>` switches back to yourself. A stored session keeps the identity it was created with, so to change company, log in again with a different `--client`.
+
 ```bash
 edge-cli login:list          # see saved accounts
 edge-cli login:use <email>   # switch default account
@@ -105,7 +107,7 @@ edge-cli product:default --clear
 | `--product <name>` | Override product (default from `~/.edge-api`) |
 | `--env <env>` | `prod`, `devel`, or `devlocal` (default: `prod`) |
 | `--base-url <url>` | Override API URL |
-| `--client <clientId>` | Client ID for client-scoped operations |
+| `--client <clientId>` | Client ID for client-scoped operations; with `login`, the company to sign in as staff of |
 | `--config-path <path>` | Additional config file path |
 
 ## Help

package/dist/commands/login.js

@@ -13,7 +13,8 @@ function registerLogin(program) {
         const parent = this.parent;
         const opts = (parent?.opts() ?? {});
         const cfg = await (0, config_1.resolveEffectiveConfig)(opts);
-        const email = await (0, auth_1.login)(cfg);
+        // --client selects the company to sign in as, here and only here: the explicit login.
+        const email = await (0, auth_1.login)({ ...cfg, exchangeClientId: opts.clientId?.trim() || undefined });
         process.stdout.write(`Successfully authenticated as ${email}\n`);
         if (this.opts().shell) {
             await (0, shell_1.repl)(cfg, {});

package/dist/commands/shell.js

@@ -110,7 +110,9 @@ const REPL_COMMANDS = new Map([
             // since resolveAccessToken re-reads the token store on every command, the very next line
             // picks up the new session with nothing to invalidate.
             run: async (cfg) => {
-                const email = await (0, auth_1.login)(cfg);
+                // Re-authenticates the identity the session already is: a company login (`email#101`)
+                // stays that company's. Taken from the stored default, never from a shop-context --client.
+                const email = await (0, auth_1.login)({ ...cfg, exchangeClientId: (0, auth_1.defaultLoginClientId)(cfg) });
                 process.stdout.write(`Successfully authenticated as ${email}\n`);
             }
         }],

package/dist/index.js

@@ -18,7 +18,7 @@ program
     .option("-p, --product <product>", "Product key (youkno, stash, alleaves, ...)")
     .option("--env <env>", "Environment (devlocal|devel|prod)", "prod")
     .option("--base-url <url>", "Override API base URL")
-    .option("--client <clientId>", "Client ID")
+    .option("--client <clientId>", "Client ID (with login: the company to sign in as staff of)")
     .option("--config-path <path>", "Additional edge-api style config file")
     .hook("preAction", (command) => {
     const env = command.opts().env;

package/dist/lib/auth.js

@@ -6,6 +6,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.ShellAuthMethodError = void 0;
 exports.listLogins = listLogins;
 exports.setDefaultLogin = setDefaultLogin;
+exports.defaultLoginClientId = defaultLoginClientId;
 exports.logout = logout;
 exports.login = login;
 exports.resolveAccessToken = resolveAccessToken;
@@ -115,6 +116,24 @@ function setDefaultLogin(cfg, email) {
     scope.default = email;
     writeDb(db);
 }
+/**
+ * The key a login is stored under: the email for the person's own session, `email#clientId` for a
+ * session exchanged into a company with `--client`, so one never overwrites the other.
+ */
+function accountKeyFor(email, clientId) {
+    return clientId ? `${email}#${clientId}` : email;
+}
+/**
+ * The client ID the default stored login was exchanged into, from its `email#clientId` key, or
+ * undefined for the person's own login. Lets the REPL's `/login` re-authenticate the same identity
+ * it is running as -- taken from the stored session, never from a `--client` given for shop context.
+ */
+function defaultLoginClientId(cfg) {
+    const key = getScope(readDb(), cfg).default ?? "";
+    const hash = key.lastIndexOf("#");
+    const clientId = hash > 0 ? key.slice(hash + 1) : "";
+    return /^[A-Za-z0-9_-]+$/.test(clientId) ? clientId : undefined;
+}
 function authStateHeader(cfg) {
     return `${cfg.product}.${cfg.env}`;
 }
@@ -221,6 +240,36 @@ function asShellAuthMethodError(err, hint) {
     const detail = err.problem.detail ?? err.problem.title ?? "Shell access requires a different sign-in method.";
     return new ShellAuthMethodError(`${detail}${hint}`);
 }
+/**
+ * The server's `errorCode`s for an exchange whose subject cannot be selected. Mirror
+ * `ApiErrorCode.NOT_A_MEMBER`, `VULGUS_NOT_SELECTABLE` and `VIRTUAL_CREDENTIAL_REFUSED`.
+ */
+const ERROR_CODE_NOT_A_MEMBER = 403012;
+const ERROR_CODE_VULGUS_NOT_SELECTABLE = 400006;
+const ERROR_CODE_VIRTUAL_CREDENTIAL_REFUSED = 400007;
+/**
+ * A `--client` refusal as an error that says what to do, or undefined when this failure is
+ * something else. Matched on errorCode, never on the prose.
+ */
+function asCompanySelectionError(err, cfg) {
+    if (!(err instanceof AuthEndpointError)) {
+        return undefined;
+    }
+    switch (err.problem?.errorCode) {
+        case ERROR_CODE_NOT_A_MEMBER:
+            return new Error(`Login failed: you are not a member of client ${cfg.exchangeClientId} ` +
+                `on ${cfg.product}. Check --client, or omit it to sign in as yourself.`, { cause: err });
+        case ERROR_CODE_VULGUS_NOT_SELECTABLE:
+            return new Error(`Login failed: --client ${cfg.exchangeClientId} is the Vulgus company, ` +
+                `which is your own account. Omit --client.`, { cause: err });
+        case ERROR_CODE_VIRTUAL_CREDENTIAL_REFUSED:
+            return new Error("Login failed: the console handed over a company session's Firebase token. " +
+                "It must hand over the person's own Firebase token, not the company session's; " +
+                "sign out of the console, sign in again, and retry.", { cause: err });
+        default:
+            return undefined;
+    }
+}
 async function requestTokenEndpoint(cfg, endpoint, payload) {
     const url = `${cfg.baseUrl.replace(/\/$/, "")}/api/v1/auth/${endpoint}`;
     const response = await fetch(url, {
@@ -240,13 +289,24 @@ async function requestTokenEndpoint(cfg, endpoint, payload) {
     }
     return (await response.json());
 }
-async function authExchangeFirebaseToken(cfg, firebaseToken, scope = EXCHANGE_SCOPE_SHELL) {
-    const resp = await requestTokenEndpoint(cfg, "exchange", {
+/**
+ * The body of a token exchange. `clientId` is sent only when `--client` was given, so the server
+ * makes the person's row in that company the subject (after the virtual-users migration, staff of
+ * the Operations company hold SHELL_ACCESS there, not on their own row). Absent, the exchange is
+ * exactly what it was before the field existed. Like `scope`, it is sent on exchange only: a refresh
+ * re-mints whatever subject the session was created for.
+ */
+function buildExchangePayload(cfg, firebaseToken, scope, deviceId) {
+    return {
         firebaseToken,
-        deviceId: authDeviceId(),
+        deviceId,
         deviceName: DEFAULT_DEVICE_NAME,
-        ...(scope === null ? {} : { scope })
-    });
+        ...(scope === null ? {} : { scope }),
+        ...(cfg.exchangeClientId ? { clientId: cfg.exchangeClientId } : {})
+    };
+}
+async function authExchangeFirebaseToken(cfg, firebaseToken, scope = EXCHANGE_SCOPE_SHELL) {
+    const resp = await requestTokenEndpoint(cfg, "exchange", buildExchangePayload(cfg, firebaseToken, scope, authDeviceId()));
     if (!resp?.accessToken) {
         throw new Error("Token exchange did not return accessToken");
     }
@@ -293,6 +353,10 @@ async function exchangeCallbackToken(cfg, callbackToken) {
         if (refusal) {
             throw refusal;
         }
+        const companyRefusal = asCompanySelectionError(err, cfg);
+        if (companyRefusal) {
+            throw companyRefusal;
+        }
         const reason = err instanceof Error ? err.message : String(err);
         // The identity hint only fits a 401. On a network error or a 5xx, telling someone to check
         // which account they used is misdirection -- the same species of misleading report this
@@ -530,10 +594,17 @@ async function login(cfg) {
     let firebaseToken;
     if (parsed.firebaseToken) {
         firebaseToken = parsed.firebaseToken;
-        tokenResp = await authExchangeFirebaseToken(cfg, firebaseToken);
+        tokenResp = await exchangeCallbackToken(cfg, firebaseToken);
     }
     else if (parsed.accessToken && parsed.refreshToken) {
-        // Already a first-party pair; nothing to exchange.
+        // Already a first-party pair; nothing to exchange -- and so nothing to apply --client to.
+        // Refused rather than stored: the pair is for whichever identity the console chose, and
+        // saving it under a login that asked for a company would sign in as the wrong one.
+        if (cfg.exchangeClientId) {
+            throw new Error(`Login failed: --client ${cfg.exchangeClientId} could not be applied because the ` +
+                "console returned a finished session instead of a Firebase token to exchange. " +
+                "Log in without --client, or from a console that returns a Firebase token.");
+        }
         tokenResp = {
             accessToken: parsed.accessToken,
             refreshToken: parsed.refreshToken,
@@ -550,8 +621,11 @@ async function login(cfg) {
         throw new Error("Authentication callback did not include usable token data.");
     }
     const email = parsed.email ?? extractEmailFromToken(tokenResp.accessToken);
-    storeTokens(cfg, email, tokenResp, await exchangeApiSession(cfg, firebaseToken));
-    return email;
+    // A company session is stored beside the person's own, never over it: `email#clientId`. It
+    // becomes the default like any fresh login; `login:use <email>` switches back.
+    const accountKey = accountKeyFor(email, cfg.exchangeClientId);
+    storeTokens(cfg, accountKey, tokenResp, await exchangeApiSession(cfg, firebaseToken));
+    return accountKey;
 }
 /**
  * Exchange the same Firebase token a second time for an API-only session.
@@ -578,7 +652,8 @@ async function exchangeApiSession(cfg, firebaseToken) {
         return resp;
     }
     catch (err) {
-        const reason = err instanceof Error ? err.message : String(err);
+        const reason = asCompanySelectionError(err, cfg)?.message
+            ?? (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;

package/package.json

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

package/src/commands/login.ts

@@ -14,7 +14,8 @@ export function registerLogin(program: Command): void {
             const parent = this.parent;
             const opts = (parent?.opts() ?? {}) as CliOptions;
             const cfg = await resolveEffectiveConfig(opts);
-            const email = await login(cfg);
+            // --client selects the company to sign in as, here and only here: the explicit login.
+            const email = await login({ ...cfg, exchangeClientId: opts.clientId?.trim() || undefined });
             process.stdout.write(`Successfully authenticated as ${email}\n`);
             if (this.opts<{ shell?: boolean }>().shell) {
                 await repl(cfg, {});

package/src/commands/shell.ts

@@ -4,7 +4,7 @@ import readline from "node:readline";
 
 import { Command } from "commander";
 
-import { login, resolveAuthHeader, resolveAuthHeaderFast } from "../lib/auth";
+import { defaultLoginClientId, login, resolveAuthHeader, resolveAuthHeaderFast } from "../lib/auth";
 import { resolveEffectiveConfig } from "../lib/config";
 import { baseHeaders, checkedText } from "../lib/request";
 import { CliOptions, EffectiveConfig } from "../lib/types";
@@ -154,7 +154,9 @@ const REPL_COMMANDS = new Map<string, ReplCommand>([
         // since resolveAccessToken re-reads the token store on every command, the very next line
         // picks up the new session with nothing to invalidate.
         run: async (cfg) => {
-            const email = await login(cfg);
+            // Re-authenticates the identity the session already is: a company login (`email#101`)
+            // stays that company's. Taken from the stored default, never from a shop-context --client.
+            const email = await login({ ...cfg, exchangeClientId: defaultLoginClientId(cfg) });
             process.stdout.write(`Successfully authenticated as ${email}\n`);
         }
     }],

package/src/index.ts

@@ -21,7 +21,7 @@ program
     .option("-p, --product <product>", "Product key (youkno, stash, alleaves, ...)")
     .option("--env <env>", "Environment (devlocal|devel|prod)", "prod")
     .option("--base-url <url>", "Override API base URL")
-    .option("--client <clientId>", "Client ID")
+    .option("--client <clientId>", "Client ID (with login: the company to sign in as staff of)")
     .option("--config-path <path>", "Additional edge-api style config file")
     .hook("preAction", (command) => {
         const env = command.opts().env as string;

package/src/lib/auth.ts

@@ -153,6 +153,26 @@ export function setDefaultLogin(cfg: EffectiveConfig, email: string): void {
     writeDb(db);
 }
 
+/**
+ * The key a login is stored under: the email for the person's own session, `email#clientId` for a
+ * session exchanged into a company with `--client`, so one never overwrites the other.
+ */
+function accountKeyFor(email: string, clientId: string | undefined): string {
+    return clientId ? `${email}#${clientId}` : email;
+}
+
+/**
+ * The client ID the default stored login was exchanged into, from its `email#clientId` key, or
+ * undefined for the person's own login. Lets the REPL's `/login` re-authenticate the same identity
+ * it is running as -- taken from the stored session, never from a `--client` given for shop context.
+ */
+export function defaultLoginClientId(cfg: EffectiveConfig): string | undefined {
+    const key = getScope(readDb(), cfg).default ?? "";
+    const hash = key.lastIndexOf("#");
+    const clientId = hash > 0 ? key.slice(hash + 1) : "";
+    return /^[A-Za-z0-9_-]+$/.test(clientId) ? clientId : undefined;
+}
+
 function authStateHeader(cfg: EffectiveConfig): string {
     return `${cfg.product}.${cfg.env}`;
 }
@@ -273,6 +293,38 @@ function asShellAuthMethodError(err: unknown, hint: string): ShellAuthMethodErro
     return new ShellAuthMethodError(`${detail}${hint}`);
 }
 
+/**
+ * The server's `errorCode`s for an exchange whose subject cannot be selected. Mirror
+ * `ApiErrorCode.NOT_A_MEMBER`, `VULGUS_NOT_SELECTABLE` and `VIRTUAL_CREDENTIAL_REFUSED`.
+ */
+const ERROR_CODE_NOT_A_MEMBER = 403012;
+const ERROR_CODE_VULGUS_NOT_SELECTABLE = 400006;
+const ERROR_CODE_VIRTUAL_CREDENTIAL_REFUSED = 400007;
+
+/**
+ * A `--client` refusal as an error that says what to do, or undefined when this failure is
+ * something else. Matched on errorCode, never on the prose.
+ */
+function asCompanySelectionError(err: unknown, cfg: EffectiveConfig): Error | undefined {
+    if (!(err instanceof AuthEndpointError)) {
+        return undefined;
+    }
+    switch (err.problem?.errorCode) {
+        case ERROR_CODE_NOT_A_MEMBER:
+            return new Error(`Login failed: you are not a member of client ${cfg.exchangeClientId} ` +
+                `on ${cfg.product}. Check --client, or omit it to sign in as yourself.`, { cause: err });
+        case ERROR_CODE_VULGUS_NOT_SELECTABLE:
+            return new Error(`Login failed: --client ${cfg.exchangeClientId} is the Vulgus company, ` +
+                `which is your own account. Omit --client.`, { cause: err });
+        case ERROR_CODE_VIRTUAL_CREDENTIAL_REFUSED:
+            return new Error("Login failed: the console handed over a company session's Firebase token. " +
+                "It must hand over the person's own Firebase token, not the company session's; " +
+                "sign out of the console, sign in again, and retry.", { cause: err });
+        default:
+            return undefined;
+    }
+}
+
 async function requestTokenEndpoint(
     cfg: EffectiveConfig,
     endpoint: "exchange" | "refresh" | "logout",
@@ -304,17 +356,35 @@ async function requestTokenEndpoint(
     return (await response.json()) as TokenResponse;
 }
 
+/**
+ * The body of a token exchange. `clientId` is sent only when `--client` was given, so the server
+ * makes the person's row in that company the subject (after the virtual-users migration, staff of
+ * the Operations company hold SHELL_ACCESS there, not on their own row). Absent, the exchange is
+ * exactly what it was before the field existed. Like `scope`, it is sent on exchange only: a refresh
+ * re-mints whatever subject the session was created for.
+ */
+function buildExchangePayload(
+    cfg: Pick<EffectiveConfig, "exchangeClientId">,
+    firebaseToken: string,
+    scope: string | null,
+    deviceId: string
+): Record<string, unknown> {
+    return {
+        firebaseToken,
+        deviceId,
+        deviceName: DEFAULT_DEVICE_NAME,
+        ...(scope === null ? {} : { scope }),
+        ...(cfg.exchangeClientId ? { clientId: cfg.exchangeClientId } : {})
+    };
+}
+
 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 === null ? {} : { scope })
-    });
+    const resp = await requestTokenEndpoint(cfg, "exchange",
+        buildExchangePayload(cfg, firebaseToken, scope, authDeviceId()));
     if (!resp?.accessToken) {
         throw new Error("Token exchange did not return accessToken");
     }
@@ -363,6 +433,10 @@ async function exchangeCallbackToken(cfg: EffectiveConfig, callbackToken: string
         if (refusal) {
             throw refusal;
         }
+        const companyRefusal = asCompanySelectionError(err, cfg);
+        if (companyRefusal) {
+            throw companyRefusal;
+        }
 
         const reason = err instanceof Error ? err.message : String(err);
         // The identity hint only fits a 401. On a network error or a 5xx, telling someone to check
@@ -635,9 +709,16 @@ export async function login(cfg: EffectiveConfig): Promise<string> {
     let firebaseToken: string | undefined;
     if (parsed.firebaseToken) {
         firebaseToken = parsed.firebaseToken;
-        tokenResp = await authExchangeFirebaseToken(cfg, firebaseToken);
+        tokenResp = await exchangeCallbackToken(cfg, firebaseToken);
     } else if (parsed.accessToken && parsed.refreshToken) {
-        // Already a first-party pair; nothing to exchange.
+        // Already a first-party pair; nothing to exchange -- and so nothing to apply --client to.
+        // Refused rather than stored: the pair is for whichever identity the console chose, and
+        // saving it under a login that asked for a company would sign in as the wrong one.
+        if (cfg.exchangeClientId) {
+            throw new Error(`Login failed: --client ${cfg.exchangeClientId} could not be applied because the ` +
+                "console returned a finished session instead of a Firebase token to exchange. " +
+                "Log in without --client, or from a console that returns a Firebase token.");
+        }
         tokenResp = {
             accessToken: parsed.accessToken,
             refreshToken: parsed.refreshToken,
@@ -655,8 +736,11 @@ export async function login(cfg: EffectiveConfig): Promise<string> {
     }
 
     const email = parsed.email ?? extractEmailFromToken(tokenResp.accessToken);
-    storeTokens(cfg, email, tokenResp, await exchangeApiSession(cfg, firebaseToken));
-    return email;
+    // A company session is stored beside the person's own, never over it: `email#clientId`. It
+    // becomes the default like any fresh login; `login:use <email>` switches back.
+    const accountKey = accountKeyFor(email, cfg.exchangeClientId);
+    storeTokens(cfg, accountKey, tokenResp, await exchangeApiSession(cfg, firebaseToken));
+    return accountKey;
 }
 
 /**
@@ -688,7 +772,8 @@ async function exchangeApiSession(
         }
         return resp;
     } catch (err) {
-        const reason = err instanceof Error ? err.message : String(err);
+        const reason = asCompanySelectionError(err, cfg)?.message
+            ?? (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`

package/src/lib/types.ts

@@ -29,5 +29,14 @@ export type EffectiveConfig = {
     baseUrl: string;
     consoleBaseUrl?: string;
     clientId?: string;
+    /**
+     * The company to sign in as a member of staff of, sent as `clientId` on the token exchange.
+     * Never set by `resolveEffectiveConfig`: only the explicit `login` command fills it, from an
+     * explicit `--client`. Not from `CLIENT_ID` in a config file (that exists for client-scoped
+     * commands such as `upload-users`), and not for the REPL's `/login`, so a `--client` given for
+     * shop context never switches which identity a session signs in as. Unset means the person's
+     * own row, as before.
+     */
+    exchangeClientId?: string;
     configFiles: string[];
 };