@mercury-fw/channel-http 0.6.0 → 0.7.0

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # @mercury-fw/channel-http
 
+## 0.7.0
+
+### Minor Changes
+
+- 2c63bbf: One person across accounts: linking them by a code.
+
+  - `POST /link` on the HTTP surface hands the caller a one-time code (`xxxx-xxxx-xxxx`, ten minutes, single use). They send it from the other account, on any channel, twice. The first time Mercury says whom the account would be linked to, the second time it links it.
+  - From then on the account is the person it's linked to: one private area, one memory, the same roles. Its earlier area stays where it was, and undoing the link gives it back.
+  - A link never touches the terminal, never chains, and is refused for an account the directory already knows as someone else.
+  - The links live on the vault's volume, out of the vault's git and out of reach of the model and the HTTP reads.
+  - `mfw identity links | link | unlink` lets the operator manage them, for instances where nobody can be shown a code.
+  - Channels get the code through the confirmation hook they already call (`ctx.confirm`), and the HTTP surface gets `ctx.linking`.
+  - Fixed: `ctx.confirm` refused someone the core doesn't admit before checking that their text was a token at all. On Google Chat, every message from an unknown sender came back as the refusal.
+
 ## 0.6.0
 
 ### Minor Changes

package/README.md

@@ -78,6 +78,10 @@ Where a person comes back after logging in to a service a plugin acts on as them
 
 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 /link`
+
+A code for linking another of the caller's accounts to them, for the UI to show: `{ ok: true, code, expiresAt }`, or `400` with the reason when there's none. The person sends the code from the other account, on any channel, twice: the first time Mercury says whom the account would be linked to, the second time it links it, and from then on both accounts are one person (one private area, the same roles). The code lasts ten minutes, works once, and only the caller sees it; the model never does. It belongs to the first account that sends it, so it should be sent in a one-to-one conversation, never in a shared space where someone else could send it first. Over HTTP only an account the instance already admits can send it (anyone else is refused before the turn), so an account a closed instance doesn't know links from a chat.
+
 ## `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

@@ -11,7 +11,7 @@
  * injected (`confirm`/`resolveConfirmation`), so this package never imports the app.
  */
 import { type AdmitFn, type CompleteLoginFn, type ConfirmFn, type ResolveConfirmationFn } from "./http-server.ts";
-import type { Authenticate, Provider, ChannelHostReads } from "@mercury-fw/channel-types";
+import type { Authenticate, Provider, ChannelHostReads, ChannelLinking } from "@mercury-fw/channel-types";
 export type HttpProviderDeps = {
     port: number;
     /** Bare-token interception before the model. */
@@ -32,6 +32,8 @@ export type HttpProviderDeps = {
         accept: (callbackUrl: string) => void;
         complete: CompleteLoginFn;
     };
+    /** Linking another account to the caller (`POST /link`). */
+    linking?: ChannelLinking;
 };
 export declare function createHttpProvider(deps: HttpProviderDeps): Provider & {
     stop(): Promise<void>;

package/dist/http-server.d.ts

@@ -22,7 +22,7 @@
  * Confirm resolution is injected too (`confirm`/`resolveConfirmation`), so this
  * package never imports the app.
  */
-import { type HandleTurn, type Authenticate, type ChannelHostReads, type ConfirmOutcome, type LoginOutcome, type Principal, type Admission } from "@mercury-fw/channel-types";
+import { type HandleTurn, type Authenticate, type ChannelHostReads, type ConfirmOutcome, type LoginOutcome, type Principal, type Admission, type ChannelLinking } 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`). */
@@ -79,6 +79,20 @@ export type ConfirmRequestDeps = {
  * even token-shaped). Never touches the model.
  */
 export declare function handleConfirmRequest(req: Request, deps: ConfirmRequestDeps): Promise<Response>;
+export type LinkRequestDeps = {
+    authenticate: Authenticate;
+    admit?: AdmitFn;
+    /** Hands the caller a link code, injected by the core (`ctx.linking.start`). */
+    start: ChannelLinking["start"];
+    corsOrigin?: string;
+};
+/**
+ * `POST /link` — a one-time code for linking another account to the caller
+ * (the custom UI shows it). The person then sends it from the other account,
+ * on any channel. Nobody but the caller ever sees it, the model included, and
+ * it isn't cached. `400` with the core's reason when there's no code for them.
+ */
+export declare function handleLinkRequest(req: Request, deps: LinkRequestDeps): Promise<Response>;
 /** Finishes a person's login, injected by the core (`ChannelLogins.complete`). */
 export type CompleteLoginFn = (state: string, code: string) => Promise<LoginOutcome>;
 /**
@@ -115,6 +129,8 @@ export type HttpServerDeps = TurnRequestDeps & {
     resolveConfirmation: ResolveConfirmationFn;
     /** Finishes people's logins; `/login/callback` is mounted only with it. */
     completeLogin?: CompleteLoginFn;
+    /** Linking another account to the caller; `/link` is mounted only with it. */
+    linking?: ChannelLinking;
 };
 /** Starts the HTTP surface: `POST /turn` (4a) plus the read-only routes (4b)
  * when `reads` is supplied. */

package/http-provider.ts

@@ -11,7 +11,7 @@
  * injected (`confirm`/`resolveConfirmation`), so this package never imports the app.
  */
 import { startHttpServer, type AdmitFn, type CompleteLoginFn, type ConfirmFn, type ResolveConfirmationFn } from "./http-server.ts";
-import type { Authenticate, Provider, HandleTurn, ChannelHostReads } from "@mercury-fw/channel-types";
+import type { Authenticate, Provider, HandleTurn, ChannelHostReads, ChannelLinking } from "@mercury-fw/channel-types";
 
 export type HttpProviderDeps = {
   port: number;
@@ -29,6 +29,8 @@ export type HttpProviderDeps = {
   /** 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 };
+  /** Linking another account to the caller (`POST /link`). */
+  linking?: ChannelLinking;
 };
 
 export function createHttpProvider(deps: HttpProviderDeps): Provider & { stop(): Promise<void> } {
@@ -45,6 +47,7 @@ export function createHttpProvider(deps: HttpProviderDeps): Provider & { stop():
         ...(deps.admit === undefined ? {} : { admit: deps.admit }),
         corsOrigin: deps.corsOrigin,
         completeLogin: deps.logins?.complete,
+        ...(deps.linking === undefined ? {} : { linking: deps.linking }),
       });
       deps.logins?.accept(deps.logins.callbackUrl);
     },

package/http-server.ts

@@ -34,6 +34,7 @@ import {
   type LoginOutcome,
   type Principal,
   type Admission,
+  type ChannelLinking,
 } from "@mercury-fw/channel-types";
 
 /**
@@ -305,6 +306,33 @@ export async function handleConfirmRequest(req: Request, deps: ConfirmRequestDep
   }
 }
 
+export type LinkRequestDeps = {
+  authenticate: Authenticate;
+  admit?: AdmitFn;
+  /** Hands the caller a link code, injected by the core (`ctx.linking.start`). */
+  start: ChannelLinking["start"];
+  corsOrigin?: string;
+};
+
+/**
+ * `POST /link` — a one-time code for linking another account to the caller
+ * (the custom UI shows it). The person then sends it from the other account,
+ * on any channel. Nobody but the caller ever sees it, the model included, and
+ * it isn't cached. `400` with the core's reason when there's no code for them.
+ */
+export async function handleLinkRequest(req: Request, deps: LinkRequestDeps): Promise<Response> {
+  const origin = deps.corsOrigin ?? "*";
+  const principal = await caller(req, deps, origin);
+  if (principal instanceof Response) return principal;
+  const started = await deps.start(principal);
+  return Response.json(started, { status: started.ok ? 200 : 400, headers: { ...corsHeaders(origin), "cache-control": "no-store" } });
+}
+
+/** `POST /link` and its preflight, mounted when the core offers linking. */
+function linkRoutes(deps: LinkRequestDeps): Record<string, { POST: (req: Request) => Promise<Response>; OPTIONS: () => Response }> {
+  return { "/link": { POST: (req) => handleLinkRequest(req, deps), OPTIONS: () => preflight(deps.corsOrigin ?? "*") } };
+}
+
 /** Finishes a person's login, injected by the core (`ChannelLogins.complete`). */
 export type CompleteLoginFn = (state: string, code: string) => Promise<LoginOutcome>;
 
@@ -439,6 +467,8 @@ export type HttpServerDeps = TurnRequestDeps & {
   resolveConfirmation: ResolveConfirmationFn;
   /** Finishes people's logins; `/login/callback` is mounted only with it. */
   completeLogin?: CompleteLoginFn;
+  /** Linking another account to the caller; `/link` is mounted only with it. */
+  linking?: ChannelLinking;
 };
 
 /** Starts the HTTP surface: `POST /turn` (4a) plus the read-only routes (4b)
@@ -471,6 +501,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.admit) : {}),
       ...(deps.completeLogin ? loginRoutes(deps.completeLogin) : {}),
+      ...(deps.linking ? linkRoutes({ ...deps, start: deps.linking.start, corsOrigin: origin }) : {}),
     },
     error: (err) =>
       Response.json(

package/index.ts

@@ -43,6 +43,7 @@ export const httpChannel: ChannelPlugin = {
       reads: ctx.reads,
       authenticate: ctx.authenticate,
       admit: ctx.admit,
+      ...(ctx.linking === undefined ? {} : { linking: ctx.linking }),
       ...(logins ? { logins: { callbackUrl: `${publicUrl}/login/callback`, accept: logins.accept, complete: logins.complete } } : {}),
     });
   },

package/openapi.yaml

@@ -146,6 +146,45 @@ paths:
             application/json:
               schema:
                 $ref: "#/components/schemas/Error"
+  /link:
+    post:
+      summary: A code for linking another account to the caller
+      description: >
+        A one-time code (`xxxx-xxxx-xxxx`, valid for ten minutes) the person
+        sends from another account, on any channel, twice: the first time
+        Mercury says whom the account would be linked to, the second time it
+        links it. From then on both accounts are one person. Only the caller
+        sees the code; the model never does.
+      responses:
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/NotAdmitted"
+        "503":
+          $ref: "#/components/responses/NotAdmitted"
+        "400":
+          description: No code for this caller, with the reason.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+        "200":
+          description: The code and when it expires.
+          content:
+            application/json:
+              schema:
+                type: object
+                required: [ok, code, expiresAt]
+                properties:
+                  ok:
+                    type: boolean
+                    enum: [true]
+                  code:
+                    type: string
+                    pattern: "^[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}$"
+                  expiresAt:
+                    type: string
+                    format: date-time
   /conversation:
     get:
       summary: A conversation's durable transcript

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mercury-fw/channel-http",
-  "version": "0.6.0",
+  "version": "0.7.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.42.0",
-    "@mercury-fw/plugin-types": "0.42.0",
+    "@mercury-fw/channel-types": "0.44.0",
+    "@mercury-fw/plugin-types": "0.44.0",
     "@mercury-fw/typescript-config": "*",
     "@types/bun": "^1.4.2",
     "typescript": "^6.0.3"