@mercury-fw/utils 0.38.1 → 0.40.0

package/CHANGELOG.md

@@ -1,5 +1,36 @@
 # @mercury-fw/utils
 
+## 0.40.0
+
+### Minor Changes
+
+- 0739f77: A plugin acts as the person Mercury is talking to, who logs in to the service through Mercury.
+
+  - Plugin contract version 4: a plugin declares `actsAs: "person" | "mercury"`, and one acting as the person contributes a `login`; its tools get the turn's `person` and `requireLogin` in their context.
+  - A person is offered only the plugins acting as the person: their prompt fragments, skills and tools. A plugin acting as Mercury, or declaring nothing, is offered on the terminal only until people can be allowed to make Mercury act as itself; the startup log names it.
+  - `createCliTool` adds `--user` with the person's id to every command, staged confirmations included, and when the CLI exits with code 3 (not logged in) returns their login instead. `createCliPersonLogin` builds a plugin's `login` on a CLI's two-step remote login. A failed `runCli` carries `exitCode`.
+  - Channel contract version 4: channels get `logins` (`accept` a callback URL, `complete` a login) and `detectLoginRequired`.
+  - The HTTP channel, with `HTTP_SURFACE_PUBLIC_URL` set, streams a `login` event with the link to open and takes the person back at `GET /login/callback`, public and protected by the single-use state.
+  - `mercury.cliCredentials` can declare `userSetup`, run by `mfw credentials setup <plugin> --user-app`: the app people log in through, set up without logging anyone in.
+  - plugin-jira and plugin-bitbucket act as the person, on CLIs 2.3.0: set up their people's app with `--user-app` and register `<HTTP_SURFACE_PUBLIC_URL>/login/callback` on it. Jira's skill now says `currentUser()` is the person.
+  - plugin-atlassian-admin acts as Mercury, on CLI 0.2.0, whose `init` asks for the key without echoing it: until permissions exist it's available on the terminal only.
+  - A third-party plugin needs `apiVersion: 4` to load, and `actsAs: "person"` with a `login` to be offered to people.
+
+## 0.39.0
+
+### Minor Changes
+
+- 881835c: A CLI's login is set up inside the app's container, no longer carried in the env file.
+
+  - A plugin declares in `mercury.cliCredentials` the commands that set its CLI's login up (`setup`, required), check it (`check`) and log an identity out (`logout`), each a binary followed by its arguments.
+  - `mfw credentials setup <plugin>` runs the declared setup in a one-off container on your terminal, so the CLI writes its login straight onto the credentials volume; `mfw credentials check <plugin>` runs the declared check.
+  - `mfw credentials reset <plugin> [--user <key>]` runs the declared logout, of the identity Mercury runs as or of one person, instead of deleting the CLI's folder.
+  - `mfw credentials set` is removed, and the core no longer unpacks `*_CONFIG_TAR_B64` variables at startup: it reports a declared login that isn't set up yet, and still links a login kept outside `~/.config` to the volume.
+  - A command the model writes with `--user` is refused: which person a CLI acts as is never the model's to pick.
+  - `cliUserId` (`@mercury-fw/utils`) maps a user key to the id a CLI knows a person by.
+  - plugin-jira and plugin-bitbucket pin their CLIs at 2.1.0, which keep the service identity and each person apart and refuse the old login folder. After updating, remove the plugin's `*_CONFIG_TAR_B64` line from the env file and run `mfw credentials setup` once; on Jira, Mercury now runs as an Atlassian Service Account.
+  - plugin-atlassian-admin keeps its CLI at 0.1.2, whose `init` doesn't prompt for the organization key: until it does, write the key from `mfw shell` with `atlassian-admin init --api-key <KEY> --org-id <ORG_ID>` (the plugin's README says so).
+
 ## 0.38.1
 
 ## 0.38.0

package/README.md

@@ -1,5 +1,5 @@
 # @mercury-fw/utils
 
-Helpers shared by [Mercury](https://github.com/lucabro81/mercury-fw) packages, today the download of a plugin's pinned CLI binary that the CLI-based plugins run when they install, and reading the CLI login folder a plugin declares (`mercury.cliCredentials`). You don't depend on it directly.
+Helpers shared by [Mercury](https://github.com/lucabro81/mercury-fw) packages, today the download of a plugin's pinned CLI binary that the CLI-based plugins run when they install, reading the CLI login a plugin declares (`mercury.cliCredentials`: where it lives and the commands that set it up), and the id a CLI knows a person by. You don't depend on it directly.
 
 MIT

package/cli-credentials.ts

@@ -1,42 +1,58 @@
 /**
- * The CLI credentials folder a plugin declares in its own package.json
+ * The CLI login a plugin declares in its own package.json
  * (`mercury.cliCredentials`): where the plugin's CLI keeps its login and reads
  * it back at runtime, either `{ folder }` under `~/.config` (the usual place)
- * or `{ path }` anywhere under the home. The app's env file carries it packed
- * into a variable (`mfw credentials set` writes it), and the core unpacks it
- * onto the credentials volume at startup. Declared by the plugin rather than
- * listed anywhere central, so a plugin from any author gets the same
- * mechanism; read as data, so both `mfw` on the host and the core in the
- * container find it without running the plugin's code.
+ * or `{ path }` anywhere under the home, and the commands that set it up,
+ * check it and log an identity out. `mfw credentials` runs those commands
+ * inside the app's container, so the CLI writes its login straight onto the
+ * credentials volume, and the core links a `{ path }` login to the volume at
+ * startup. Declared by the plugin rather than listed anywhere central, so a
+ * plugin from any author gets the same mechanism; read as data, so both `mfw`
+ * on the host and the core in the container find it without running the
+ * plugin's code.
  */
+import { createHash } from "node:crypto";
 import { readFileSync, existsSync } from "node:fs";
 import { join } from "node:path";
 
 /** What a plugin declares: `name` as it was declared (the folder, or the
- * path), which `mfw credentials` takes and the variable is named after, and
- * `path` relative to the home. */
-export type DeclaredCredentials = { name: string; path: string };
+ * path), which `mfw credentials` takes; `path` relative to the home; and the
+ * commands, each a binary on the container's PATH and its arguments: `setup`
+ * sets up the service identity, `userSetup` the app people log in through
+ * (no person logged in), `check` reports on the login, `logout` removes one
+ * identity's login (the service's, or a person's with `--user`). */
+export type DeclaredCredentials = {
+  name: string;
+  path: string;
+  setup: string[];
+  userSetup?: string[];
+  check?: string[];
+  logout?: string[];
+};
 
-/** One dependency's declaration, with the env variable that carries it. */
-export type CliCredentials = DeclaredCredentials & { package: string; variable: string };
+/** One dependency's declaration. */
+export type CliCredentials = DeclaredCredentials & { package: string };
 
 /** What an app's dependencies declare: the usable declarations, and one line
- * per dependency left out (not installed, malformed, sharing a variable). */
+ * per dependency left out (not installed, malformed, clashing with another). */
 export type AppCliCredentials = { declared: CliCredentials[]; problems: string[] };
 
 /** A single folder name: no separators, no `.`/`..`, no leading dot. */
 const FOLDER = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
 
-/** One segment of a home-relative path, never starting with a dash (the last
- * one is a tar member name, not an option); `.` and `..` are refused apart. */
+/** One segment of a home-relative path, never starting with a dash; `.` and
+ * `..` are refused apart. */
 const SEGMENT = /^[A-Za-z0-9._][A-Za-z0-9._-]*$/;
 
+/** A binary found on the PATH: a bare name, never a path or an option. */
+const BINARY = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+
 /** The credentials volume is mounted on `~/.config`; a login declared
  * anywhere else in the home lives on it under this folder. */
 const ELSEWHERE = ".config/mercury-home";
 
 const INVALID =
-  "invalid mercury.cliCredentials in package.json: expected { folder } with a single folder name under ~/.config, or { path } relative to the home and outside ~/.config";
+  "invalid mercury.cliCredentials in package.json: expected { folder } with a single folder name under ~/.config, or { path } relative to the home and outside ~/.config, with setup (and optionally userSetup, check, logout) as a binary name followed by its arguments, e.g. [\"jira\", \"init\"]";
 
 /** Whether `path` is a usable home-relative path for a login: inside the
  * home and outside `~/.config`, the volume, where a login is a `folder`. */
@@ -46,6 +62,16 @@ function isHomePath(path: string): boolean {
   return path !== ".config" && !path.startsWith(".config/");
 }
 
+/** Whether `value` is a command: a binary name, then non-empty arguments. */
+function isCommand(value: unknown): value is string[] {
+  return (
+    Array.isArray(value) &&
+    value.length > 0 &&
+    value.every((a) => typeof a === "string" && a !== "") &&
+    BINARY.test(value[0] as string)
+  );
+}
+
 /**
  * What `mercury.cliCredentials` of a package.json-shaped object declares, or
  * undefined when the package declares nothing. A malformed declaration throws:
@@ -61,12 +87,20 @@ export function readCliCredentials(pkg: unknown): DeclaredCredentials | undefine
   if (!("cliCredentials" in mercury)) return undefined;
   const declared = (mercury as { cliCredentials?: unknown }).cliCredentials;
   if (typeof declared !== "object" || declared === null) throw new Error(INVALID);
-  const { folder, path } = declared as { folder?: unknown; path?: unknown };
+  const { folder, path, setup, userSetup, check, logout } = declared as Record<string, unknown>;
+  const optional = { userSetup, check, logout };
+  if (!isCommand(setup) || Object.values(optional).some((c) => c !== undefined && !isCommand(c))) {
+    throw new Error(INVALID);
+  }
+  const commands: Pick<DeclaredCredentials, "setup" | "userSetup" | "check" | "logout"> = { setup };
+  for (const [field, command] of Object.entries(optional) as [keyof typeof optional, string[] | undefined][]) {
+    if (command !== undefined) commands[field] = command;
+  }
   if (folder !== undefined && path === undefined && typeof folder === "string" && FOLDER.test(folder)) {
-    return { name: folder, path: `.config/${folder}` };
+    return { name: folder, path: `.config/${folder}`, ...commands };
   }
   if (path !== undefined && folder === undefined && typeof path === "string" && isHomePath(path)) {
-    return { name: path, path };
+    return { name: path, path, ...commands };
   }
   throw new Error(INVALID);
 }
@@ -79,21 +113,36 @@ export function volumePath(path: string): string {
   return path.startsWith(".config/") ? path : `${ELSEWHERE}/${path}`;
 }
 
-/** The env variable carrying a declared login packed, named after what was
- * declared: `jira-cli` → `JIRA_CLI_CONFIG_TAR_B64`, `.aws` → `AWS_CONFIG_TAR_B64`. */
-export function credentialsVariable(name: string): string {
-  return `${name.toUpperCase().replace(/[^A-Z0-9]/g, "_").replace(/^_+/, "")}_CONFIG_TAR_B64`;
+/** What the CLIs accept as `--user <id>`. */
+const CLI_USER_ID = /^[a-z0-9][a-z0-9._:-]{0,63}$/;
+
+/** A provider name kept readable in front of a hashed id. */
+const PROVIDER = /^[a-z0-9][a-z0-9._-]{0,30}$/;
+
+/**
+ * The id a CLI knows a person by (`--user <id>`), from Mercury's user key
+ * (`<provider>:<id>`): the key itself when the CLIs accept it, as they do
+ * `static:alice` or an OIDC key with a numeric subject, so a person's folder
+ * stays readable; otherwise the provider and the first 32 hex digits of the
+ * key's SHA-256, since an id with capitals, `/` or more than 64 characters is
+ * refused, and lowering capitals would merge two people.
+ */
+export function cliUserId(key: string): string {
+  if (CLI_USER_ID.test(key)) return key;
+  const provider = key.slice(0, Math.max(key.indexOf(":"), 0));
+  const hash = createHash("sha256").update(key).digest("hex").slice(0, 32);
+  return `${PROVIDER.test(provider) ? provider : "user"}:${hash}`;
 }
 
 /**
  * The declarations of the app's dependencies (its package.json `dependencies`,
  * read from its `node_modules`), in the manifest's order. A dependency that
- * isn't installed or declares a malformed folder is left out with a problem
- * line, and so are all the ones whose declarations map to the same variable (one
- * variable can't carry two logins) or whose paths are one inside the other
- * (one would be linked inside the other's copy on the volume): one bad plugin
- * never costs the others their login. Throws only when the app's own
- * package.json can't be read.
+ * isn't installed or declares a malformed login is left out with a problem
+ * line, and so are all the ones declaring the same login (each would set it up
+ * and log it out for the other) or logins one inside the other (one would be
+ * linked inside the other's copy on the volume): one bad plugin never costs
+ * the others their login. Throws only when the app's own package.json can't be
+ * read.
  */
 export function appCliCredentials(appDir: string): AppCliCredentials {
   const manifest = JSON.parse(readFileSync(join(appDir, "package.json"), "utf-8")) as {
@@ -109,20 +158,18 @@ export function appCliCredentials(appDir: string): AppCliCredentials {
     }
     try {
       const declared = readCliCredentials(JSON.parse(readFileSync(path, "utf-8")));
-      if (declared !== undefined) found.push({ package: name, ...declared, variable: credentialsVariable(declared.name) });
+      if (declared !== undefined) found.push({ package: name, ...declared });
     } catch (err) {
       problems.push(`${name}: ${err instanceof Error ? err.message : String(err)}`);
     }
   }
   const excluded = new Set<CliCredentials>();
   for (const c of found) {
-    const sharing = found.filter((o) => o.variable === c.variable);
+    const sharing = found.filter((o) => o.path === c.path);
     if (sharing.length === 1) continue;
     sharing.forEach((o) => excluded.add(o));
     if (sharing[0] === c) {
-      problems.push(
-        `${sharing.map((o) => o.package).join(" and ")} declare CLI credentials (${sharing.map((o) => o.name).join(", ")}) carried by the same variable ${c.variable}: neither is used`,
-      );
+      problems.push(`${sharing.map((o) => o.package).join(" and ")} declare the same CLI credentials (${c.name}): neither is used`);
     }
   }
   const inside = (outer: string, inner: string) => inner.startsWith(`${outer}/`);

package/dist/cli-credentials.d.ts

@@ -1,17 +1,23 @@
 /** What a plugin declares: `name` as it was declared (the folder, or the
- * path), which `mfw credentials` takes and the variable is named after, and
- * `path` relative to the home. */
+ * path), which `mfw credentials` takes; `path` relative to the home; and the
+ * commands, each a binary on the container's PATH and its arguments: `setup`
+ * sets up the service identity, `userSetup` the app people log in through
+ * (no person logged in), `check` reports on the login, `logout` removes one
+ * identity's login (the service's, or a person's with `--user`). */
 export type DeclaredCredentials = {
     name: string;
     path: string;
+    setup: string[];
+    userSetup?: string[];
+    check?: string[];
+    logout?: string[];
 };
-/** One dependency's declaration, with the env variable that carries it. */
+/** One dependency's declaration. */
 export type CliCredentials = DeclaredCredentials & {
     package: string;
-    variable: string;
 };
 /** What an app's dependencies declare: the usable declarations, and one line
- * per dependency left out (not installed, malformed, sharing a variable). */
+ * per dependency left out (not installed, malformed, clashing with another). */
 export type AppCliCredentials = {
     declared: CliCredentials[];
     problems: string[];
@@ -28,17 +34,23 @@ export declare function readCliCredentials(pkg: unknown): DeclaredCredentials |
  * volume's mount, a declared `folder`), under `~/.config/mercury-home`
  * otherwise, with the home path pointing there. */
 export declare function volumePath(path: string): string;
-/** The env variable carrying a declared login packed, named after what was
- * declared: `jira-cli` → `JIRA_CLI_CONFIG_TAR_B64`, `.aws` → `AWS_CONFIG_TAR_B64`. */
-export declare function credentialsVariable(name: string): string;
+/**
+ * The id a CLI knows a person by (`--user <id>`), from Mercury's user key
+ * (`<provider>:<id>`): the key itself when the CLIs accept it, as they do
+ * `static:alice` or an OIDC key with a numeric subject, so a person's folder
+ * stays readable; otherwise the provider and the first 32 hex digits of the
+ * key's SHA-256, since an id with capitals, `/` or more than 64 characters is
+ * refused, and lowering capitals would merge two people.
+ */
+export declare function cliUserId(key: string): string;
 /**
  * The declarations of the app's dependencies (its package.json `dependencies`,
  * read from its `node_modules`), in the manifest's order. A dependency that
- * isn't installed or declares a malformed folder is left out with a problem
- * line, and so are all the ones whose declarations map to the same variable (one
- * variable can't carry two logins) or whose paths are one inside the other
- * (one would be linked inside the other's copy on the volume): one bad plugin
- * never costs the others their login. Throws only when the app's own
- * package.json can't be read.
+ * isn't installed or declares a malformed login is left out with a problem
+ * line, and so are all the ones declaring the same login (each would set it up
+ * and log it out for the other) or logins one inside the other (one would be
+ * linked inside the other's copy on the volume): one bad plugin never costs
+ * the others their login. Throws only when the app's own package.json can't be
+ * read.
  */
 export declare function appCliCredentials(appDir: string): AppCliCredentials;

package/dist/index.d.ts

@@ -5,4 +5,4 @@
  * as they're factored out.
  */
 export { downloadPinnedBinary, resolvePlatform, binaryAssetUrl, readPinnedBinary, type Platform, type PinnedBinary, } from "./cli-binary.ts";
-export { readCliCredentials, credentialsVariable, appCliCredentials, volumePath, type DeclaredCredentials, type CliCredentials, type AppCliCredentials, } from "./cli-credentials.ts";
+export { readCliCredentials, appCliCredentials, volumePath, cliUserId, type DeclaredCredentials, type CliCredentials, type AppCliCredentials, } from "./cli-credentials.ts";

package/index.ts

@@ -14,9 +14,9 @@ export {
 } from "./cli-binary.ts";
 export {
   readCliCredentials,
-  credentialsVariable,
   appCliCredentials,
   volumePath,
+  cliUserId,
   type DeclaredCredentials,
   type CliCredentials,
   type AppCliCredentials,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mercury-fw/utils",
-  "version": "0.38.1",
+  "version": "0.40.0",
   "license": "MIT",
   "repository": {
     "type": "git",