@mercury-fw/channel-http 0.1.1 → 0.2.0

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # @mercury-fw/channel-http
 
+## 0.2.0
+
+### Minor Changes
+
+- 8bed46b: - A turn carries a `Principal` (the person behind it and the provider that vouched for them) instead of the opaque `userId` and `wikiUserId`; the core derives every per-person id from it.
+  - Episodic memory follows the principal, not the channel: a session is captured whenever a provider vouched for the person. Google Chat keeps the ids it had; the terminal and the HTTP channel (until it authenticates its callers) send a principal nobody vouched for, so they stay out of episodic memory as before.
+  - The HTTP channel accepts a `conversationId` on `/turn` and `/confirm` only made of letters, digits, `-` and `_`, up to 128 characters once trimmed, and answers `400` otherwise: a client-chosen id can no longer reach another user's wiki notes, forge log lines or break the turn. An existing HTTP conversation whose id has other characters can still be read with `/conversation`, but not continued. `/conversation` keeps opening any session key `/conversations` lists, whatever channel it came from.
+  - The model's wiki read tools refuse a per-user id that isn't one path segment, as writes already did.
+  - `CHANNEL_API_VERSION` is 2: a channel written for version 1 is refused at load.
+  - The first-party channels declare their channel api version as a literal, so an older channel can't claim a newer contract it doesn't implement.
+
 ## 0.1.1
 
 ### Patch Changes

package/README.md

@@ -36,9 +36,9 @@ Runs one conversational turn; the reply streams back as Server-Sent Events.
 | field | type | required | description |
 |---|---|---|---|
 | `text` | string | yes | The user message. A bare confirmation token here confirms a staged action (see the `pending` event) without invoking the model. |
-| `conversationId` | string | no | Opaque, client-owned id that continues a conversation. Omitted ⇒ a fresh one-off session. |
+| `conversationId` | string | no | Opaque, client-owned id that continues a conversation: letters, digits, `-` and `_`, up to 128 characters (a UUID fits) once surrounding whitespace is trimmed, `400` otherwise. Omitted ⇒ a fresh one-off session. |
 
-**Responses**: `200 text/event-stream` (the events below); `400` if `text` is missing or the body isn't JSON.
+**Responses**: `200 text/event-stream` (the events below); `400` if `text` is missing, the body isn't JSON, or `conversationId` has other characters than the ones above.
 
 Reasoning and answer text arrive as **incremental deltas** — never one finished block — so a UI renders them live; treat the `final` event as the authoritative text. **To cancel** a turn (e.g. a generation that's diverging), close the connection: Mercury aborts the in-flight generation.
 
@@ -63,7 +63,7 @@ curl -N -X POST http://localhost:4100/turn \
 
 ## `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. Never invokes the model.
+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.
 
 ## Read-only introspection
 
@@ -71,7 +71,7 @@ All `GET`, all JSON, all reporting state already held in-process.
 
 | endpoint | `data` on success |
 |---|---|
-| `GET /conversation?id=<conversationId>&limit=<n>&offset=<cursor>` | `{ messages: [{ role, content, timestamp }], nextOffset }` — a conversation's durable transcript in order; `400` if `id` is missing |
+| `GET /conversation?id=<conversationId>&limit=<n>&offset=<cursor>` | `{ messages: [{ role, content, timestamp }], nextOffset }` — a conversation's durable transcript in order; `400` if `id` is missing. Any session key `/conversations` lists opens here, whatever channel it came from |
 | `GET /conversations?limit=<n>` | `{ conversations: [{ sessionKey, lastTimestamp, preview }] }` — known conversations, most-recently-active first |
 | `GET /manifest` | `{ manifest: { coreApiVersion, plugins: [{ name, apiVersion, active, skills, hasBuild, customStatus }], activeClis, skills } }` |
 | `GET /confirmations` | `{ pending: [{ sessionKey, binary, args, expiresAt }] }` — tokens are deliberately never included |

package/dist/http-server.d.ts

@@ -33,7 +33,7 @@ export type TurnRequestDeps = {
 };
 /**
  * Serves the OpenAPI document that describes this surface — the single source
- * of truth in `apps/mercury/openapi.yaml`, also rendered as the GitHub Pages
+ * of truth in this package's `openapi.yaml`, also rendered as the GitHub Pages
  * API docs. Served raw as `text/yaml` (no YAML parser needed at runtime); most
  * tooling (Redoc, Swagger UI, Postman) reads YAML directly.
  */

package/dist/index.d.ts

@@ -11,6 +11,6 @@
  * inversion). Those two are optional on the contract but required here, so a
  * context missing them throws — the loader isolates it fail-soft.
  */
-import { type ChannelPlugin } from "@mercury-fw/channel-types";
+import type { ChannelPlugin } from "@mercury-fw/channel-types";
 export { createHttpProvider, type HttpProviderDeps } from "./http-provider.ts";
 export declare const httpChannel: ChannelPlugin;

package/http-server.ts

@@ -26,6 +26,13 @@ import {
   type ConfirmOutcome,
 } from "@mercury-fw/channel-types";
 
+/**
+ * A client's conversation id becomes the session key, a log prefix and (until
+ * the channel authenticates) the per-person wiki id, so only letters, digits,
+ * `-` and `_` get in: no path segments, no line breaks, nothing to encode.
+ */
+const CONVERSATION_ID = /^[A-Za-z0-9_-]{1,128}$/;
+
 /** 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, userId: string) => Promise<string | null>;
 /** The structured sibling of {@link ConfirmFn}, for the `/confirm` `resolved` flag. Injected by the core (`ctx.resolveConfirmation`). */
@@ -68,7 +75,7 @@ function preflight(origin: string): Response {
 
 /**
  * Serves the OpenAPI document that describes this surface — the single source
- * of truth in `apps/mercury/openapi.yaml`, also rendered as the GitHub Pages
+ * of truth in this package's `openapi.yaml`, also rendered as the GitHub Pages
  * API docs. Served raw as `text/yaml` (no YAML parser needed at runtime); most
  * tooling (Redoc, Swagger UI, Postman) reads YAML directly.
  */
@@ -105,6 +112,9 @@ export async function handleTurnRequest(req: Request, deps: TurnRequestDeps): Pr
     typeof body.conversationId === "string" && body.conversationId.trim().length > 0
       ? body.conversationId.trim()
       : (deps.newSessionKey ?? (() => crypto.randomUUID()))();
+  if (!CONVERSATION_ID.test(sessionKey)) {
+    return Response.json({ ok: false, error: "invalid conversationId" }, { status: 400, headers: cors });
+  }
 
   // Aborted when the client disconnects (see the stream's `cancel` below) so
   // the in-flight turn stops instead of running to completion — the "stop"
@@ -164,7 +174,9 @@ export async function handleTurnRequest(req: Request, deps: TurnRequestDeps): Pr
             multiUser: false,
             text,
             sessionKey,
-            wikiUserId: sessionKey,
+            // Unauthenticated: the conversation id stands in for the caller,
+            // and nobody vouches for it.
+            principal: { id: sessionKey, provider: "none" },
             logPrefix: `[http:${sessionKey}] `,
             abortSignal: abort.signal,
           },
@@ -218,6 +230,9 @@ export async function handleConfirmRequest(req: Request, deps: ConfirmRequestDep
   if (token.length === 0 || sessionKey.length === 0) {
     return Response.json({ ok: false, error: "missing token or conversationId" }, { status: 400, headers: cors });
   }
+  if (!CONVERSATION_ID.test(sessionKey)) {
+    return Response.json({ ok: false, error: "invalid conversationId" }, { status: 400, headers: cors });
+  }
   const outcome = await deps.resolveConfirmation(token, sessionKey, sessionKey);
   switch (outcome.status) {
     case "not-a-token":

package/index.ts

@@ -11,13 +11,15 @@
  * inversion). Those two are optional on the contract but required here, so a
  * context missing them throws — the loader isolates it fail-soft.
  */
-import { CHANNEL_API_VERSION, type ChannelPlugin } from "@mercury-fw/channel-types";
+import type { ChannelPlugin } from "@mercury-fw/channel-types";
 import { createHttpProvider } from "./http-provider.ts";
 
 export { createHttpProvider, type HttpProviderDeps } from "./http-provider.ts";
 
 export const httpChannel: ChannelPlugin = {
-  apiVersion: CHANNEL_API_VERSION,
+  // The contract this channel is written for, as a literal: importing
+  // CHANNEL_API_VERSION would report whichever contract is installed.
+  apiVersion: 2,
   name: "http",
   build: (ctx) => {
     if (!ctx.resolveConfirmation || !ctx.reads) {

package/openapi.yaml

@@ -69,7 +69,7 @@ paths:
               schema:
                 $ref: "#/components/schemas/TurnEvent"
         "400":
-          description: Missing/invalid body.
+          description: Missing/invalid body, or a conversationId with characters outside the allowed ones.
           content:
             application/json:
               schema:
@@ -98,7 +98,7 @@ paths:
               schema:
                 $ref: "#/components/schemas/ConfirmResult"
         "400":
-          description: Missing token or conversationId.
+          description: Missing token or conversationId, or a conversationId with characters outside the allowed ones.
           content:
             application/json:
               schema:
@@ -110,7 +110,7 @@ paths:
         - name: id
           in: query
           required: true
-          description: The conversationId (session key) whose messages to return.
+          description: The session key whose messages to return, as `/conversations` lists it (any channel's).
           schema:
             type: string
         - name: limit
@@ -304,7 +304,8 @@ components:
           description: The user's message, or a bare confirmation token.
         conversationId:
           type: string
-          description: Opaque, client-owned. Omit to start a fresh ephemeral conversation.
+          pattern: "^[A-Za-z0-9_-]{1,128}$"
+          description: Opaque, client-owned; letters, digits, `-` and `_` (a UUID fits). Omit to start a fresh ephemeral conversation.
     TurnEvent:
       type: object
       description: The shape carried by each SSE `data:` line, per event type.
@@ -350,6 +351,7 @@ components:
           type: string
         conversationId:
           type: string
+          pattern: "^[A-Za-z0-9_-]{1,128}$"
     ConfirmResult:
       type: object
       required: [ok, resolved]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mercury-fw/channel-http",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -18,11 +18,11 @@
     "access": "public"
   },
   "peerDependencies": {
-    "@mercury-fw/channel-types": ">=0.24.0 <1.0.0"
+    "@mercury-fw/channel-types": ">=0.34.0 <1.0.0"
   },
   "devDependencies": {
-    "@mercury-fw/channel-types": "0.31.1",
-    "@mercury-fw/plugin-types": "0.31.1",
+    "@mercury-fw/channel-types": "0.34.0",
+    "@mercury-fw/plugin-types": "0.34.0",
     "@mercury-fw/typescript-config": "*",
     "@types/bun": "^1.4.2",
     "typescript": "^6.0.3"