@mercury-fw/channel-http 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # @mercury-fw/channel-http
 
+## 0.5.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.4.0
 
 ### Minor Changes

package/README.md

@@ -20,12 +20,13 @@ It needs an auth provider next to it: [`@mercury-fw/auth-oidc`](../../auth/auth-
 |---|---|
 | `HTTP_SURFACE_PORT` | The port (default `4100`). |
 | `HTTP_SURFACE_CORS_ORIGIN` | The origin a browser UI calls from (default `*`). |
+| `HTTP_SURFACE_PUBLIC_URL` | The address people's browsers reach the surface at (e.g. `https://mercury.example.com`). With it, people log in here to the services plugins act on as them (see [`GET /login/callback`](#get-logincallback)); without it, nobody can. |
 
 ## API
 
 It's active whenever it's declared in `mercury.config.ts`'s `channels` with an auth provider; remove it there to turn the surface off. It listens on `HTTP_SURFACE_PORT` (default `4100`). Base URL `http://<host>:<port>`.
 
-**Authentication.** Every route except `GET /openapi.yaml` and the `OPTIONS` preflights needs `Authorization: Bearer <token>`, and the auth provider decides who the token belongs to. A missing or refused token gets `401` with `WWW-Authenticate: Bearer` before anything runs.
+**Authentication.** Every route except `GET /openapi.yaml`, `GET /login/callback` and the `OPTIONS` preflights needs `Authorization: Bearer <token>`, and the auth provider decides who the token belongs to. A missing or refused token gets `401` with `WWW-Authenticate: Bearer` before anything runs.
 
 **Conversations belong to whoever opened them.** The session key is `<caller id>:<conversationId>`, so the same `conversationId` sent by someone else is a conversation of their own, and a confirmation token staged in your conversation can't be confirmed from theirs. Each authenticated caller also gets their own episodic memory and wiki area, as on Google Chat.
 
@@ -60,6 +61,7 @@ Reasoning and answer text arrive as **incremental deltas** — never one finishe
 | `tool_finish` | `{ toolCallId, outcome }` | a tool call settles (`outcome`: `success` \| `failed` \| `pending`) |
 | `text` | `{ chunk }` | an answer-text delta |
 | `pending` | `{ command, token }` | a confirm-required action was staged; send `token` back to confirm it — as a later `/turn` `text`, or via `POST /confirm` |
+| `login` | `{ service, url }` | the caller isn't logged in to `service` yet, which a plugin acts on as them: show them `url` to open (the model never gets it) |
 | `final` | `{ text }` | the complete answer (also emitted for a token confirmation, with no model turn) |
 | `error` | `{ message }` | the turn failed mid-stream |
 
@@ -70,6 +72,12 @@ curl -N -X POST http://localhost:4100/turn \
   -d '{"text":"Quante issue nel progetto KAN?","conversationId":"c1"}'
 ```
 
+## `GET /login/callback`
+
+Where a person comes back after logging in to a service a plugin acts on as them (Jira, Bitbucket): the `login` event's `url` sends them to the service, and the service sends their browser here with `code` and `state`. Mounted only with `HTTP_SURFACE_PUBLIC_URL`, at `<HTTP_SURFACE_PUBLIC_URL>/login/callback`, which is the URL to register as a callback on the service's app (the Atlassian 3LO app, the Bitbucket consumer people log in through). No bearer token: the browser has none here, and the `state` Mercury issued for that person, single-use and valid for ten minutes, is what ties the request to their login. Answers with a plain-text page saying how it went.
+
+Whoever opens the link and accepts decides which account gets linked: a link belongs to the person it was shown to, and someone else accepting it would link their own account to that person's Mercury identity. A UI should say so next to the link. Checking the linked account against the person is [#179](https://github.com/lucabro81/mercury-fw/issues/179).
+
 ## `POST /confirm`
 
 Explicit alternative to re-sending a token as `/turn` `text`. Body `{ token, conversationId }`; returns `{ ok: true, resolved: true, text }` when the token was a pending confirmation, `{ ok: true, resolved: false }` otherwise. `400` if `token` or `conversationId` is missing, or the id has other characters than `/turn` accepts. Never invokes the model.

package/dist/http-provider.d.ts

@@ -10,7 +10,7 @@
  * (that stays with Google Chat). `stop` closes the socket on shutdown. Confirm is
  * injected (`confirm`/`resolveConfirmation`), so this package never imports the app.
  */
-import { type ConfirmFn, type ResolveConfirmationFn } from "./http-server.ts";
+import { type CompleteLoginFn, type ConfirmFn, type ResolveConfirmationFn } from "./http-server.ts";
 import type { Authenticate, Provider, ChannelHostReads } from "@mercury-fw/channel-types";
 export type HttpProviderDeps = {
     port: number;
@@ -23,6 +23,13 @@ export type HttpProviderDeps = {
     authenticate: Authenticate;
     /** Allowed CORS origin echoed to a browser UI; defaults to `*` in the server. */
     corsOrigin?: string;
+    /** People's logins, when the surface has a public URL to be sent back to:
+     * the callback is offered (`accept`) once the server listens. */
+    logins?: {
+        callbackUrl: string;
+        accept: (callbackUrl: string) => void;
+        complete: CompleteLoginFn;
+    };
 };
 export declare function createHttpProvider(deps: HttpProviderDeps): Provider & {
     stop(): Promise<void>;

package/dist/http-server.d.ts

@@ -12,14 +12,17 @@
  * is unit-tested without standing up a socket. The read-only routes (4b) mount
  * alongside `/turn` here, driven by the injected `reads` getters.
  *
- * Every route but the OpenAPI document and the CORS preflights asks the
- * injected `authenticate` (the auth provider the app declares) who is calling
+ * `/login/callback` is where a person's browser comes back after logging in to
+ * a service a plugin acts on as them; the single-use state is its credential.
+ *
+ * Every route but the OpenAPI document, the login callback and the CORS
+ * preflights asks the injected `authenticate` (the auth provider the app declares) who is calling
  * before anything runs, and answers 401 when nobody is. A conversation belongs
  * to whoever opened it: the session key is `<principal.id>:<conversationId>`.
  * Confirm resolution is injected too (`confirm`/`resolveConfirmation`), so this
  * package never imports the app.
  */
-import { type HandleTurn, type Authenticate, type ChannelHostReads, type ConfirmOutcome, type Principal } from "@mercury-fw/channel-types";
+import { type HandleTurn, type Authenticate, type ChannelHostReads, type ConfirmOutcome, type LoginOutcome, type Principal } from "@mercury-fw/channel-types";
 /** Resolves a bare confirmation token to a reply string, or `null` if the input isn't a token. Injected by the core (`ctx.confirm`). */
 export type ConfirmFn = (token: string, sessionKey: string, principal: Principal) => Promise<string | null>;
 /** The structured sibling of {@link ConfirmFn}, for the `/confirm` `resolved` flag. Injected by the core (`ctx.resolveConfirmation`). */
@@ -72,6 +75,18 @@ export type ConfirmRequestDeps = {
  * even token-shaped). Never touches the model.
  */
 export declare function handleConfirmRequest(req: Request, deps: ConfirmRequestDeps): Promise<Response>;
+/** Finishes a person's login, injected by the core (`ChannelLogins.complete`). */
+export type CompleteLoginFn = (state: string, code: string) => Promise<LoginOutcome>;
+/**
+ * `GET /login/callback`: where the provider sends a person back after they log
+ * in, with `code` and `state` (or `error`, when they refused). Public: the
+ * person's browser carries no token here, and the single-use `state` the core
+ * issued for them is what ties the request to their login. Answers with a
+ * plain page telling them how it went.
+ */
+export declare function handleLoginCallback(req: Request, deps: {
+    complete: CompleteLoginFn;
+}): Promise<Response>;
 /** A single read route: its `GET` handler plus the shared `OPTIONS` preflight. */
 type ReadRoute = {
     GET: (req: Request) => Response | Promise<Response>;
@@ -94,6 +109,8 @@ export type HttpServerDeps = TurnRequestDeps & {
     reads?: ChannelHostReads;
     /** The `/confirm` endpoint's structured resolver, injected by the core. */
     resolveConfirmation: ResolveConfirmationFn;
+    /** Finishes people's logins; `/login/callback` is mounted only with it. */
+    completeLogin?: CompleteLoginFn;
 };
 /** Starts the HTTP surface: `POST /turn` (4a) plus the read-only routes (4b)
  * when `reads` is supplied. */

package/dist/index.d.ts

@@ -6,11 +6,13 @@
  * is no runtime inert condition (unlike Google Chat's subscription): if it's
  * declared, it starts.
  *
- * `build` reads its port and CORS origin from `env` and takes the confirm
+ * `build` reads its port, CORS origin and public URL from `env` and takes the confirm
  * capabilities, the in-process reads and the app's auth provider from the
  * injected context (dependency inversion). Those are optional on the contract
  * but required here, so a context missing them throws — the loader isolates it
- * fail-soft, and without an auth provider the surface never opens.
+ * fail-soft, and without an auth provider the surface never opens. With a
+ * public URL (`HTTP_SURFACE_PUBLIC_URL`) it also takes people's logins: it
+ * mounts `<url>/login/callback` and, once it's listening, offers it to the core.
  */
 import type { ChannelPlugin } from "@mercury-fw/channel-types";
 export { createHttpProvider, type HttpProviderDeps } from "./http-provider.ts";

package/http-provider.ts

@@ -10,7 +10,7 @@
  * (that stays with Google Chat). `stop` closes the socket on shutdown. Confirm is
  * injected (`confirm`/`resolveConfirmation`), so this package never imports the app.
  */
-import { startHttpServer, type ConfirmFn, type ResolveConfirmationFn } from "./http-server.ts";
+import { startHttpServer, type CompleteLoginFn, type ConfirmFn, type ResolveConfirmationFn } from "./http-server.ts";
 import type { Authenticate, Provider, HandleTurn, ChannelHostReads } from "@mercury-fw/channel-types";
 
 export type HttpProviderDeps = {
@@ -24,6 +24,9 @@ export type HttpProviderDeps = {
   authenticate: Authenticate;
   /** Allowed CORS origin echoed to a browser UI; defaults to `*` in the server. */
   corsOrigin?: string;
+  /** People's logins, when the surface has a public URL to be sent back to:
+   * the callback is offered (`accept`) once the server listens. */
+  logins?: { callbackUrl: string; accept: (callbackUrl: string) => void; complete: CompleteLoginFn };
 };
 
 export function createHttpProvider(deps: HttpProviderDeps): Provider & { stop(): Promise<void> } {
@@ -38,7 +41,9 @@ export function createHttpProvider(deps: HttpProviderDeps): Provider & { stop():
         reads: deps.reads,
         authenticate: deps.authenticate,
         corsOrigin: deps.corsOrigin,
+        completeLogin: deps.logins?.complete,
       });
+      deps.logins?.accept(deps.logins.callbackUrl);
     },
     async notify(): Promise<{ sessionKey: string }> {
       // No proactive push channel over HTTP (request/response only).

package/http-server.ts

@@ -12,14 +12,18 @@
  * is unit-tested without standing up a socket. The read-only routes (4b) mount
  * alongside `/turn` here, driven by the injected `reads` getters.
  *
- * Every route but the OpenAPI document and the CORS preflights asks the
- * injected `authenticate` (the auth provider the app declares) who is calling
+ * `/login/callback` is where a person's browser comes back after logging in to
+ * a service a plugin acts on as them; the single-use state is its credential.
+ *
+ * Every route but the OpenAPI document, the login callback and the CORS
+ * preflights asks the injected `authenticate` (the auth provider the app declares) who is calling
  * before anything runs, and answers 401 when nobody is. A conversation belongs
  * to whoever opened it: the session key is `<principal.id>:<conversationId>`.
  * Confirm resolution is injected too (`confirm`/`resolveConfirmation`), so this
  * package never imports the app.
  */
 import {
+  detectLoginRequired,
   detectPendingConfirmation,
   PENDING_CONFIRMATION_NOTE,
   type HandleTurn,
@@ -27,6 +31,7 @@ import {
   type Authenticate,
   type ChannelHostReads,
   type ConfirmOutcome,
+  type LoginOutcome,
   type Principal,
 } from "@mercury-fw/channel-types";
 
@@ -188,6 +193,8 @@ export async function handleTurnRequest(req: Request, deps: TurnRequestDeps): Pr
         onStep: (step) => {
           const pending = detectPendingConfirmation(step);
           if (pending) send("pending", { command: pending.summary, token: pending.token });
+          const login = detectLoginRequired(step);
+          if (login) send("login", { service: login.service, url: login.url });
         },
         onUsage: () => {},
         finalize: async (finalText) => send("final", { text: finalText }),
@@ -276,6 +283,46 @@ export async function handleConfirmRequest(req: Request, deps: ConfirmRequestDep
   }
 }
 
+/** Finishes a person's login, injected by the core (`ChannelLogins.complete`). */
+export type CompleteLoginFn = (state: string, code: string) => Promise<LoginOutcome>;
+
+/** A plain-text page for the person's browser, at the end of their login. */
+function loginPage(text: string, status: number): Response {
+  // The URL carried the code and the state: neither kept nor passed on.
+  return new Response(text, {
+    status,
+    headers: { "content-type": "text/plain; charset=utf-8", "cache-control": "no-store", "referrer-policy": "no-referrer" },
+  });
+}
+
+/**
+ * `GET /login/callback`: where the provider sends a person back after they log
+ * in, with `code` and `state` (or `error`, when they refused). Public: the
+ * person's browser carries no token here, and the single-use `state` the core
+ * issued for them is what ties the request to their login. Answers with a
+ * plain page telling them how it went.
+ */
+export async function handleLoginCallback(req: Request, deps: { complete: CompleteLoginFn }): Promise<Response> {
+  const params = new URL(req.url).searchParams;
+  const error = params.get("error");
+  if (error !== null) {
+    const reason = error.replace(/[^A-Za-z0-9_.-]/g, "").slice(0, 64);
+    return loginPage(`The login didn't happen (${reason}). Ask Mercury again for a new link.`, 400);
+  }
+  const code = params.get("code");
+  const state = params.get("state");
+  if (!code || !state) return loginPage("The login link came back without a code or a state. Ask Mercury again for a new link.", 400);
+  const outcome = await deps.complete(state, code);
+  return outcome.ok
+    ? loginPage(`You're logged in to ${outcome.service}. Go back to the conversation and ask again.`, 200)
+    : loginPage(outcome.error, 400);
+}
+
+/** The login callback route, mounted when the server can complete logins. */
+function loginRoutes(complete: CompleteLoginFn): Record<string, { GET: (req: Request) => Promise<Response> }> {
+  return { "/login/callback": { GET: (req) => handleLoginCallback(req, { complete }) } };
+}
+
 /** A single read route: its `GET` handler plus the shared `OPTIONS` preflight. */
 type ReadRoute = {
   GET: (req: Request) => Response | Promise<Response>;
@@ -363,6 +410,8 @@ export type HttpServerDeps = TurnRequestDeps & {
   reads?: ChannelHostReads;
   /** The `/confirm` endpoint's structured resolver, injected by the core. */
   resolveConfirmation: ResolveConfirmationFn;
+  /** Finishes people's logins; `/login/callback` is mounted only with it. */
+  completeLogin?: CompleteLoginFn;
 };
 
 /** Starts the HTTP surface: `POST /turn` (4a) plus the read-only routes (4b)
@@ -389,6 +438,7 @@ export function startHttpServer(deps: HttpServerDeps): ReturnType<typeof Bun.ser
       },
       "/openapi.yaml": { GET: () => openApiResponse(origin), OPTIONS: () => preflight(origin) },
       ...(deps.reads ? readRoutes(deps.reads, deps.authenticate, origin) : {}),
+      ...(deps.completeLogin ? loginRoutes(deps.completeLogin) : {}),
     },
     error: (err) =>
       Response.json(

package/index.ts

@@ -6,11 +6,13 @@
  * is no runtime inert condition (unlike Google Chat's subscription): if it's
  * declared, it starts.
  *
- * `build` reads its port and CORS origin from `env` and takes the confirm
+ * `build` reads its port, CORS origin and public URL from `env` and takes the confirm
  * capabilities, the in-process reads and the app's auth provider from the
  * injected context (dependency inversion). Those are optional on the contract
  * but required here, so a context missing them throws — the loader isolates it
- * fail-soft, and without an auth provider the surface never opens.
+ * fail-soft, and without an auth provider the surface never opens. With a
+ * public URL (`HTTP_SURFACE_PUBLIC_URL`) it also takes people's logins: it
+ * mounts `<url>/login/callback` and, once it's listening, offers it to the core.
  */
 import type { ChannelPlugin } from "@mercury-fw/channel-types";
 import { createHttpProvider } from "./http-provider.ts";
@@ -20,7 +22,7 @@ export { createHttpProvider, type HttpProviderDeps } from "./http-provider.ts";
 export const httpChannel: ChannelPlugin = {
   // The contract this channel is written for, as a literal: importing
   // CHANNEL_API_VERSION would report whichever contract is installed.
-  apiVersion: 3,
+  apiVersion: 4,
   name: "http",
   build: (ctx) => {
     if (!ctx.resolveConfirmation || !ctx.reads) {
@@ -29,6 +31,10 @@ export const httpChannel: ChannelPlugin = {
     if (!ctx.authenticate) {
       throw new Error("http channel requires an auth provider (auth in mercury.config.ts)");
     }
+    // The provider sends a person back here after they log in, so it needs
+    // the address their browser reaches the surface at.
+    const publicUrl = ctx.env.HTTP_SURFACE_PUBLIC_URL?.trim().replace(/\/+$/, "");
+    const logins = publicUrl ? ctx.logins : undefined;
     return createHttpProvider({
       port: Number(ctx.env.HTTP_SURFACE_PORT ?? "4100"),
       corsOrigin: ctx.env.HTTP_SURFACE_CORS_ORIGIN ?? "*",
@@ -36,6 +42,7 @@ export const httpChannel: ChannelPlugin = {
       resolveConfirmation: ctx.resolveConfirmation,
       reads: ctx.reads,
       authenticate: ctx.authenticate,
+      ...(logins ? { logins: { callbackUrl: `${publicUrl}/login/callback`, accept: logins.accept, complete: logins.complete } } : {}),
     });
   },
 };

package/openapi.yaml

@@ -87,7 +87,9 @@ paths:
             An SSE stream. Each event is one of the types in `TurnEvent`:
             `reasoning`/`reasoning_end`, `text` (incremental deltas), `tool`/
             `tool_finish` (status of a tool call), `pending` (a staged
-            confirm-required action, with its command and token), `final` (the
+            confirm-required action, with its command and token), `login` (a
+            service the caller has to log in to first, with the link to open),
+            `final` (the
             authoritative complete answer), and `error`.
           content:
             text/event-stream:
@@ -339,6 +341,30 @@ paths:
             application/json:
               schema:
                 $ref: "#/components/schemas/Error"
+  /login/callback:
+    get:
+      summary: Where a person comes back after logging in to a service
+      description: >
+        Mounted when `HTTP_SURFACE_PUBLIC_URL` is set. The service sends the
+        person's browser here with `code` and `state` (or `error`); the
+        single-use state is the credential, so no bearer token is needed.
+        Answers with a plain-text page.
+      security: []
+      parameters:
+        - { name: code, in: query, schema: { type: string } }
+        - { name: state, in: query, schema: { type: string } }
+        - { name: error, in: query, schema: { type: string } }
+      responses:
+        "200":
+          description: Logged in.
+          content:
+            text/plain:
+              schema: { type: string }
+        "400":
+          description: Refused, expired, already used, or missing code/state.
+          content:
+            text/plain:
+              schema: { type: string }
   /openapi.yaml:
     get:
       summary: This OpenAPI document
@@ -416,6 +442,12 @@ components:
         token:
           type: string
           description: On `pending` — the one-time confirmation token.
+        service:
+          type: string
+          description: On `login` — the service the caller has to log in to.
+        url:
+          type: string
+          description: On `login` — the link the caller opens to log in; it comes back to `/login/callback`.
         text:
           type: string
           description: On `final` — the authoritative complete answer.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mercury-fw/channel-http",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -21,8 +21,8 @@
     "@mercury-fw/channel-types": ">=0.36.0 <1.0.0"
   },
   "devDependencies": {
-    "@mercury-fw/channel-types": "0.36.0",
-    "@mercury-fw/plugin-types": "0.36.0",
+    "@mercury-fw/channel-types": "0.40.0",
+    "@mercury-fw/plugin-types": "0.40.0",
     "@mercury-fw/typescript-config": "*",
     "@types/bun": "^1.4.2",
     "typescript": "^6.0.3"