@clearly-hub/node 0.1.1 → 0.2.1

package/README.md

@@ -11,13 +11,13 @@ hub) and each hub's subscription to your app. Tokens stay on your server.
 
 **1. Register your app in Clearly.HUB** (on your app's page, no code):
 
-| Setting | Value |
-| --- | --- |
-| Go to app | `https://app.example.com/clearly-hub/sign-in` |
+| Setting                             | Value                                                                                                                              |
+| ----------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
+| Go to app                           | `https://app.example.com/clearly-hub/sign-in`                                                                                      |
 | Sign-in client (H2M): callback URLs | `https://app.example.com/clearly-hub/callback`, `https://app.example.com/clearly-hub/answer`, `https://hub.clearly.app/components` |
-| Sign-in client: sign-out URLs | `https://app.example.com`, `https://hub.clearly.app/components` |
-| M2M client | create it, keep the secret on your server |
-| Plans | give each your own plan id as its *External reference*, for example `pro` |
+| Sign-in client: sign-out URLs       | `https://app.example.com`, `https://hub.clearly.app/components`                                                                    |
+| M2M client                          | create it, keep the secret on your server                                                                                          |
+| Plans                               | give each your own plan id as its _External reference_, for example `pro`                                                          |
 
 **2. Mount the server handler** (Node 20+):
 
@@ -55,18 +55,18 @@ Hono, Bun or Deno. Mount it at `/clearly-hub/*`.
 </script>
 ```
 
-Or `npm install @clearly-hub/browser` and `import { clearlyHub } from '@clearly-hub/browser'`.
+Or `npm install @clearly-hub/browser` and `import { clearlyHub } from '@clearly-hub/browser'`. With React and TypeScript, add `import '@clearly-hub/browser/react'` once, so JSX knows `<clearly-hub-button>`.
 
 ## The browser package
 
-| | |
-| --- | --- |
-| `clearlyHub.session()` | `{ signedIn: false }`, or the signed-in user (`sub`, `email`, `name`, `appUserId`) |
-| `clearlyHub.signIn()`, `signOut()` | Go through Clearly.HUB and come back to this page |
-| `clearlyHub.open(action, { data, display })` | Opens a hosted screen; resolves with its checked answer. Call it from a click: browsers only allow popups there |
-| `clearlyHub.result()` | After a redirect screen: its answer, on the page it came back to |
-| `<clearly-hub-button action display data label>` | Branded button for `sign-in`, `sign-out` and each screen |
-| `clearly-hub-answer` event | Every answer, from a popup or after a redirect |
+|                                                  |                                                                                                                 |
+| ------------------------------------------------ | --------------------------------------------------------------------------------------------------------------- |
+| `clearlyHub.session()`                           | `{ signedIn: false }`, or the signed-in user (`sub`, `email`, `name`, `appUserId`)                              |
+| `clearlyHub.signIn()`, `signOut()`               | Go through Clearly.HUB and come back to this page                                                               |
+| `clearlyHub.open(action, { data, display })`     | Opens a hosted screen; resolves with its checked answer. Call it from a click: browsers only allow popups there |
+| `clearlyHub.result()`                            | After a redirect screen: its answer, on the page it came back to                                                |
+| `<clearly-hub-button action display data label>` | Branded button for `sign-in`, `sign-out` and each screen                                                        |
+| `clearly-hub-answer` event                       | Every answer, from a popup or after a redirect                                                                  |
 
 **Styling the button.** It uses your page's font. Attributes for the common cases:
 `variant="outline"`, `size="small"` or `size="large"`. CSS custom properties for your look:
@@ -74,32 +74,51 @@ Or `npm install @clearly-hub/browser` and `import { clearlyHub } from '@clearly-
 `--clearly-hub-font`. For anything else, style the real button through `::part(button)`:
 
 ```css
-clearly-hub-button { --clearly-hub-color: #0b7471; --clearly-hub-radius: 999px; }
-clearly-hub-button::part(button) { text-transform: uppercase; }
+clearly-hub-button {
+  --clearly-hub-color: #0b7471;
+  --clearly-hub-radius: 999px;
+}
+clearly-hub-button::part(button) {
+  text-transform: uppercase;
+}
 ```
 
 Screens open in a popup by default (`data-display="redirect"` on the script tag changes that). A
 blocked popup falls back to a redirect.
 
-| Action | Send in `data` | `answer` when `result` is `SUCCESS` |
-| --- | --- | --- |
-| `SELECT_SUBSCRIPTION` | | `subscription` (`_id`, `status`, `externalReference`), `subscribedHub` (`_id`, `name`, `role`) |
-| `DATA_PICKER` | | `activeHub`, `resources` (`url`, `format`, `accessibility`, `requiresToken`, `hasAccess`) |
-| `REGISTER_RESOURCE` | `{ url, format }` of your result, at a public https URL | `activeHub`, `dataset`, `resource` |
-| `SELECT_HUB` | | `hub` (`_id`, `name`) |
+| Action                | Send in `data`                                          | `answer` when `result` is `SUCCESS`                                                            |
+| --------------------- | ------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
+| `SELECT_SUBSCRIPTION` |                                                         | `subscription` (`_id`, `status`, `externalReference`), `subscribedHub` (`_id`, `name`, `role`) |
+| `DATA_PICKER`         |                                                         | `activeHub`, `resources` (`url`, `format`, `accessibility`, `requiresToken`, `hasAccess`)      |
+| `REGISTER_RESOURCE`   | `{ url, format }` of your result, at a public https URL | `activeHub`, `dataset`, `resource`                                                             |
+| `SELECT_HUB`          |                                                         | `hub` (`_id`, `name`)                                                                          |
 
 ## The Node package
 
-| | |
-| --- | --- |
-| `hub.express()`, `hub.handler` | The routes: `/sign-in`, `/callback`, `/sign-out`, `/session`, `/open`, `/answer`, `/result` |
-| `onSignIn(person)` | Called after each sign-in; return your own user id to keep it in the session |
-| `onAnswer(result, { user })` | Called with each checked answer before it reaches the browser, for example to set up a workspace |
-| `hub.getUser(req)` | Who's signed in, in your own routes |
-| `hub.fetchAsUser(req, url)` | Fetch protected or paid data (from `DATA_PICKER`) with the person's key |
-| `hub.getSubscription(hubId)`, `getSubscriptions()` | A hub's subscription to your app, or all of them |
-| `hub.reportUsage({ request, hubId, quantity })` | Report billable use; Clearly.HUB bills the hub |
-| `hub.getUserToken(req)`, `getAppToken()` | The person's key and your app's key, for calls of your own |
+|                                                        |                                                                                                                                                                                        |
+| ------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `hub.express()`, `hub.handler`                         | The routes: `/sign-in`, `/callback`, `/sign-out`, `/session`, `/open`, `/answer`, `/result`                                                                                            |
+| `onSignIn(person, { request, req })`                   | Called after each sign-in. Return your own user id to keep it in the session, or `{ appUserId, redirectTo }` to also choose the next page                                              |
+| `onAnswer(result, { user, data, request, req })`       | Called with each checked answer before it reaches the browser, for example to set up a workspace. `data` is what the screen was sent; what you return reaches the page as `result.app` |
+| `hub.getUser(req)`                                     | Who's signed in, in your own routes                                                                                                                                                    |
+| `hub.fetchAsUser(req, url)`                            | Fetch protected or paid data (from `DATA_PICKER`) with the person's key                                                                                                                |
+| `hub.getSubscription(hubId)`, `getSubscriptions()`     | A hub's subscription to your app, or all of them                                                                                                                                       |
+| `hub.reportUsage({ request or sub, hubId, quantity })` | Report billable use; Clearly.HUB bills the hub. Pass `sub` for a Clearly.HUB account you stored, without a live sign-in                                                                |
+| `hub.getUserToken(req)`, `getAppToken()`               | The person's key and your app's key, for calls of your own                                                                                                                             |
+
+**Your own session in the hooks.** With `hub.express()`, the hooks get Express's `req` as
+`context.req`, so they can use your own session (for example express-session) alongside Clearly.HUB's:
+
+```ts
+const hub = clearlyHub<express.Request>({
+  // ...
+  onSignIn: (person, { req }) => {
+    const user = findOrCreateUser(person);
+    req!.session.userId = user.id;
+    return { appUserId: user.id };
+  },
+});
+```
 
 **What it checks for you:** every screen answer's Ed25519 signature, and that it answers a screen
 opened in this browser, once (`state`). The session is encrypted in cookies, so there's nothing to
@@ -112,7 +131,6 @@ store; it's split over several cookies because tokens are large.
 
 - Setting up your own workspaces or tenants: do it by hand, with plans that need approval, or in
   `onAnswer` for `SELECT_SUBSCRIPTION`.
-- Child hubs in `session().hubs`: Clearly.HUB only returns root hubs today.
 - Other server languages: follow the Build checklist.
 
 ## Working on this repo

package/dist/index.cjs

@@ -50,8 +50,14 @@ function checkScreenData(action, data) {
   if (typeof url !== "string" || !url || typeof format !== "string" || !format) {
     return 'REGISTER_RESOURCE needs data with a url and a format, for example { url, format: "geojson" }';
   }
-  if (!url.startsWith("https://")) {
-    return "REGISTER_RESOURCE needs a public https url: Clearly.HUB refuses other addresses";
+  let hostname;
+  try {
+    hostname = new URL(url).hostname;
+  } catch {
+    return `REGISTER_RESOURCE: "${url}" is not a URL`;
+  }
+  if (!hostname.includes(".")) {
+    return "REGISTER_RESOURCE needs a url with a domain Clearly.HUB accepts, not localhost";
   }
   return void 0;
 }
@@ -102,7 +108,8 @@ function resolveConfig(options) {
     signedOutUrl: options.signedOutUrl ?? appUrl,
     onSignIn: options.onSignIn,
     onAnswer: options.onAnswer,
-    fetch: options.fetch ?? globalThis.fetch.bind(globalThis),
+    // Looked up on every call, so a fetch wrapped later (logging, tracing) is used
+    fetch: options.fetch ?? ((input, init) => globalThis.fetch(input, init)),
     isSecure: appUrl.startsWith("https://")
   };
 }
@@ -117,7 +124,7 @@ function toNodeMiddleware(handle, appUrl) {
         else if (value !== void 0) headers.set(name, value);
       }
       const url = new URL(req.originalUrl ?? req.url ?? "/", appUrl);
-      const response = await handle(new Request(url, { method: req.method, headers }));
+      const response = await handle(new Request(url, { method: req.method, headers }), req);
       if (response.headers.get("X-Clearly-Hub") === "unhandled" && next) {
         next();
         return;
@@ -217,18 +224,25 @@ var SCREEN_TTL_MS = 30 * 60 * 1e3;
 var MAX_PENDING_SCREENS = 10;
 function createHandler(parts) {
   const { config, sessions } = parts;
-  return async function handle(request) {
+  return async function handle(request, req) {
     const url = new URL(request.url);
     if (!url.pathname.startsWith(config.basePath)) return notFound();
     const route = url.pathname.slice(config.basePath.length) || "/";
     if (request.method !== "GET") return new Response("Method not allowed", { status: 405 });
+    const host = request.headers.get("host");
+    const appHost = new URL(config.appUrl).host;
+    if (host && host !== appHost && (route === ROUTES.signIn || route === ROUTES.open)) {
+      return redirect(`${config.appUrl}${url.pathname}${url.search}`);
+    }
     const { data, chunkCount } = await sessions.read(request);
     const before = JSON.stringify(data);
     let response;
     try {
-      response = await routeRequest(route, url, data, parts);
+      response = await routeRequest(route, url, data, parts, { request, req });
     } catch (error) {
-      response = errorPage(error instanceof AnswerError ? 400 : 500, error.message);
+      const isRefusedAnswer = error instanceof AnswerError;
+      if (!isRefusedAnswer) console.error(`Clearly.HUB: ${route} failed:`, error);
+      response = errorPage(isRefusedAnswer ? 400 : 500, describeError(error));
     }
     if (JSON.stringify(data) !== before) {
       for (const cookie of await sessions.write(data, chunkCount)) {
@@ -238,12 +252,12 @@ function createHandler(parts) {
     return response;
   };
 }
-async function routeRequest(route, url, session, parts) {
+async function routeRequest(route, url, session, parts, incoming) {
   switch (route) {
     case ROUTES.signIn:
       return startSignIn(url, session, parts);
     case ROUTES.callback:
-      return finishSignIn(url, session, parts);
+      return finishSignIn(url, session, parts, incoming);
     case ROUTES.signOut:
       for (const key of Object.keys(session)) delete session[key];
       return redirect(parts.signIn.signOutUrl());
@@ -252,7 +266,7 @@ async function routeRequest(route, url, session, parts) {
     case ROUTES.open:
       return openScreen(url, session, parts);
     case ROUTES.answer:
-      return receiveAnswer(url, session, parts);
+      return receiveAnswer(url, session, parts, incoming);
     case ROUTES.result: {
       const result = session.result ?? null;
       delete session.result;
@@ -267,16 +281,17 @@ async function startSignIn(url, session, { config, signIn }) {
   session.signIn = pending;
   return redirect(authorizationUrl);
 }
-async function finishSignIn(url, session, { config, signIn }) {
+async function finishSignIn(url, session, { config, signIn }, incoming) {
   const pending = session.signIn;
   if (!pending) return redirect(config.appUrl);
   delete session.signIn;
   const currentUrl = new URL(`${signIn.callbackUrl}${url.search}`);
   const { person, tokens } = await signIn.finish(currentUrl, pending);
-  const appUserId = await config.onSignIn?.(person) ?? void 0;
+  const decision = await config.onSignIn?.(person, incoming);
+  const { appUserId, redirectTo } = typeof decision === "string" ? { appUserId: decision, redirectTo: void 0 } : decision ?? {};
   session.user = { ...person, appUserId };
   session.tokens = tokens;
-  return redirect(`${config.appUrl}${pending.returnTo}`);
+  return redirect(`${config.appUrl}${safePath(redirectTo, config) ?? pending.returnTo}`);
 }
 async function readSession(session, parts) {
   const accessToken = await getFreshAccessToken(session, parts);
@@ -317,11 +332,12 @@ function openScreen(url, session, { config, screens }) {
     display,
     ref: url.searchParams.get("ref") ?? state,
     returnTo: safeReturnTo(url, config),
-    createdAt: Date.now()
+    createdAt: Date.now(),
+    data
   };
   return redirect(screens.screenUrl(action, state, session.user?.email, data));
 }
-async function receiveAnswer(url, session, { config, screens }) {
+async function receiveAnswer(url, session, { config, screens }, incoming) {
   const query = readRawQuery(url);
   const { state, response } = await screens.readAnswer(
     query.get("data") ?? "",
@@ -334,7 +350,12 @@ async function receiveAnswer(url, session, { config, screens }) {
   delete session.screens[state];
   let result = toScreenResult(pending.action, response);
   try {
-    await config.onAnswer?.(result, { user: session.user });
+    const app = await config.onAnswer?.(result, {
+      ...incoming,
+      user: session.user,
+      data: pending.data
+    });
+    if (app !== void 0) result = { ...result, app };
   } catch (error) {
     result = { action: pending.action, result: "FAILURE", error: error.message };
   }
@@ -360,12 +381,14 @@ function pruneScreens(screens = {}) {
   return Object.fromEntries(fresh);
 }
 function safeReturnTo(url, config) {
-  const returnTo = url.searchParams.get("returnTo") ?? "/";
-  if (!returnTo.startsWith("/") || returnTo.startsWith("//")) return "/";
+  return safePath(url.searchParams.get("returnTo") ?? void 0, config) ?? "/";
+}
+function safePath(path, config) {
+  if (!path || !path.startsWith("/") || path.startsWith("//")) return void 0;
   try {
-    return new URL(returnTo, config.appUrl).origin === new URL(config.appUrl).origin ? returnTo : "/";
+    return new URL(path, config.appUrl).origin === new URL(config.appUrl).origin ? path : void 0;
   } catch {
-    return "/";
+    return void 0;
   }
 }
 var redirect = (location) => new Response(null, { status: 302, headers: { Location: location } });
@@ -374,6 +397,13 @@ var json = (body) => new Response(JSON.stringify(body), {
 });
 var html = (body, status = 200) => new Response(body, { status, headers: { "Content-Type": "text/html; charset=utf-8" } });
 var notFound = () => new Response("Not found", { status: 404, headers: { "X-Clearly-Hub": "unhandled" } });
+function describeError(error) {
+  const messages = [];
+  for (let current = error; current instanceof Error && messages.length < 5; current = current.cause) {
+    if (!messages.includes(current.message)) messages.push(current.message);
+  }
+  return messages.join(": ") || String(error);
+}
 function errorPage(status, message) {
   const escaped = message.replace(/[&<>"]/g, (char) => `&#${char.charCodeAt(0)};`);
   return html(
@@ -391,6 +421,15 @@ var HubApi = class {
   config;
   appToken;
   subscriptions;
+  // A call to Clearly.HUB. When it can't be reached at all, say where: "fetch
+  // failed" alone doesn't tell you which service isn't running
+  async call(url, init) {
+    try {
+      return await this.config.fetch(url, init);
+    } catch (error) {
+      throw new Error(`Clearly.HUB could not be reached at ${url}`, { cause: error });
+    }
+  }
   get hasAppKey() {
     return Boolean(this.config.m2mClientId && this.config.m2mClientSecret);
   }
@@ -403,7 +442,7 @@ var HubApi = class {
       throw new Error("Clearly.HUB: m2mClientId and m2mClientSecret are needed for this");
     }
     const credentials = btoa(`${this.config.m2mClientId}:${this.config.m2mClientSecret}`);
-    const response = await this.config.fetch(`${this.config.urls.auth}/oauth2/token`, {
+    const response = await this.call(`${this.config.urls.auth}/oauth2/token`, {
       method: "POST",
       headers: {
         "Content-Type": "application/x-www-form-urlencoded",
@@ -426,7 +465,7 @@ var HubApi = class {
     if (this.subscriptions && Date.now() - this.subscriptions.fetchedAt < SUBSCRIPTIONS_CACHE_MS) {
       return this.subscriptions.value;
     }
-    const response = await this.config.fetch(`${this.config.urls.api}/api/app-api/subscriptions`, {
+    const response = await this.call(`${this.config.urls.api}/api/app-api/subscriptions`, {
       headers: { Authorization: `Bearer ${await this.getAppToken()}` }
     });
     if (!response.ok) {
@@ -446,7 +485,7 @@ var HubApi = class {
   }
   // Report one billable use; Clearly.HUB bills the hub
   async reportUsage(usage) {
-    const response = await this.config.fetch(this.config.urls.usage, {
+    const response = await this.call(this.config.urls.usage, {
       method: "POST",
       headers: {
         "Content-Type": "application/json",
@@ -653,20 +692,25 @@ function clearlyHub(options) {
     async getSubscription(hubId) {
       return pickSubscription(await parts.api.getSubscriptions(), hubId) ?? null;
     },
-    // Report billable use by the signed-in person in a hub
+    // Report billable use in a hub, by the person signed in with Clearly.HUB
+    // (request), or by a Clearly.HUB account you stored earlier (sub), for
+    // example for someone who signed in with your own login, or a nightly job
     async reportUsage({
       request,
+      sub,
       hubId,
       quantity = 1
     }) {
-      const { data } = await parts.sessions.read(request);
-      if (!data.user) throw new Error("Clearly.HUB: nobody is signed in with Clearly.HUB");
+      const person = sub ?? (request && (await parts.sessions.read(request)).data.user?.sub);
+      if (!person) {
+        throw new Error("Clearly.HUB: reportUsage needs the sub of a Clearly.HUB account");
+      }
       const subscription = pickSubscription(await parts.api.getSubscriptions(), hubId);
       if (subscription?.status !== "ACTIVE") {
         throw new Error(`Clearly.HUB: hub ${hubId} has no active subscription to your app`);
       }
       await parts.api.reportUsage({
-        sub: data.user.sub,
+        sub: person,
         hubId,
         subscriptionId: subscription.subscriptionId,
         quantity

package/dist/index.d.cts

@@ -62,11 +62,13 @@ type ScreenResult<A extends ScreenAction = ScreenAction> = {
     action: A;
     result: 'SUCCESS';
     answer: ScreenAnswers[A];
+    app?: unknown;
 } | {
     action: A;
     result: 'CANCELLED' | 'FAILURE';
     answer?: undefined;
     error?: string;
+    app?: unknown;
 };
 
 interface SessionUser {
@@ -112,7 +114,19 @@ interface SignedInPerson {
     email: string;
     name?: string;
 }
-interface ClearlyHubOptions {
+interface HookContext<Req = unknown> {
+    request: Request;
+    req?: Req;
+}
+interface SignInDecision {
+    appUserId?: string;
+    redirectTo?: string;
+}
+interface AnswerContext<Req = unknown> extends HookContext<Req> {
+    user?: SessionUser;
+    data?: unknown;
+}
+interface ClearlyHubOptions<Req = unknown> {
     clientId: string;
     m2mClientId?: string;
     m2mClientSecret?: string;
@@ -122,10 +136,8 @@ interface ClearlyHubOptions {
     hubUrl?: string;
     urls?: Partial<ClearlyHubUrls>;
     signedOutUrl?: string;
-    onSignIn?: (person: SignedInPerson) => Promise<string | void> | string | void;
-    onAnswer?: (result: ScreenResult, context: {
-        user?: SessionUser;
-    }) => Promise<void> | void;
+    onSignIn?: (person: SignedInPerson, context: HookContext<Req>) => Promise<string | SignInDecision | void> | string | SignInDecision | void;
+    onAnswer?: (result: ScreenResult, context: AnswerContext<Req>) => unknown;
     fetch?: typeof fetch;
 }
 interface ClearlyHubUrls {
@@ -146,8 +158,8 @@ type CookieSource = Request | {
     headers: Record<string, string | string[] | undefined>;
 };
 
-declare function clearlyHub(options: ClearlyHubOptions): {
-    handler: (request: Request) => Promise<Response>;
+declare function clearlyHub<Req = unknown>(options: ClearlyHubOptions<Req>): {
+    handler: (request: Request, req?: unknown) => Promise<Response>;
     express: () => (req: http.IncomingMessage & {
         originalUrl?: string;
     }, res: http.ServerResponse, next?: (error?: unknown) => void) => Promise<void>;
@@ -157,8 +169,9 @@ declare function clearlyHub(options: ClearlyHubOptions): {
     getAppToken: () => Promise<string>;
     getSubscriptions: () => Promise<AppSubscription[]>;
     getSubscription(hubId: string): Promise<AppSubscription | null>;
-    reportUsage({ request, hubId, quantity, }: {
-        request: CookieSource;
+    reportUsage({ request, sub, hubId, quantity, }: {
+        request?: CookieSource;
+        sub?: string;
         hubId: string;
         quantity?: number;
     }): Promise<void>;
@@ -166,4 +179,4 @@ declare function clearlyHub(options: ClearlyHubOptions): {
 type ClearlyHub = ReturnType<typeof clearlyHub>;
 
 export { ANSWER_CHANNEL, DEFAULT_AUTH_URL, DEFAULT_BASE_PATH, DEFAULT_HUB_URL, DEFAULT_ISSUER, ROUTES, SCREEN_ACTIONS, checkScreenData, clearlyHub, isScreenAction };
-export type { AnswerMessage, AppSubscription, ClearlyHub, ClearlyHubOptions, ClearlyHubUrls, CookieSource, HubRef, HubSubscription, PickedResource, ScreenAction, ScreenAnswers, ScreenData, ScreenDisplay, ScreenResult, Session, SessionUser, SignedInPerson };
+export type { AnswerContext, AnswerMessage, AppSubscription, ClearlyHub, ClearlyHubOptions, ClearlyHubUrls, CookieSource, HookContext, HubRef, HubSubscription, PickedResource, ScreenAction, ScreenAnswers, ScreenData, ScreenDisplay, ScreenResult, Session, SessionUser, SignInDecision, SignedInPerson };

package/dist/index.d.ts

@@ -62,11 +62,13 @@ type ScreenResult<A extends ScreenAction = ScreenAction> = {
     action: A;
     result: 'SUCCESS';
     answer: ScreenAnswers[A];
+    app?: unknown;
 } | {
     action: A;
     result: 'CANCELLED' | 'FAILURE';
     answer?: undefined;
     error?: string;
+    app?: unknown;
 };
 
 interface SessionUser {
@@ -112,7 +114,19 @@ interface SignedInPerson {
     email: string;
     name?: string;
 }
-interface ClearlyHubOptions {
+interface HookContext<Req = unknown> {
+    request: Request;
+    req?: Req;
+}
+interface SignInDecision {
+    appUserId?: string;
+    redirectTo?: string;
+}
+interface AnswerContext<Req = unknown> extends HookContext<Req> {
+    user?: SessionUser;
+    data?: unknown;
+}
+interface ClearlyHubOptions<Req = unknown> {
     clientId: string;
     m2mClientId?: string;
     m2mClientSecret?: string;
@@ -122,10 +136,8 @@ interface ClearlyHubOptions {
     hubUrl?: string;
     urls?: Partial<ClearlyHubUrls>;
     signedOutUrl?: string;
-    onSignIn?: (person: SignedInPerson) => Promise<string | void> | string | void;
-    onAnswer?: (result: ScreenResult, context: {
-        user?: SessionUser;
-    }) => Promise<void> | void;
+    onSignIn?: (person: SignedInPerson, context: HookContext<Req>) => Promise<string | SignInDecision | void> | string | SignInDecision | void;
+    onAnswer?: (result: ScreenResult, context: AnswerContext<Req>) => unknown;
     fetch?: typeof fetch;
 }
 interface ClearlyHubUrls {
@@ -146,8 +158,8 @@ type CookieSource = Request | {
     headers: Record<string, string | string[] | undefined>;
 };
 
-declare function clearlyHub(options: ClearlyHubOptions): {
-    handler: (request: Request) => Promise<Response>;
+declare function clearlyHub<Req = unknown>(options: ClearlyHubOptions<Req>): {
+    handler: (request: Request, req?: unknown) => Promise<Response>;
     express: () => (req: http.IncomingMessage & {
         originalUrl?: string;
     }, res: http.ServerResponse, next?: (error?: unknown) => void) => Promise<void>;
@@ -157,8 +169,9 @@ declare function clearlyHub(options: ClearlyHubOptions): {
     getAppToken: () => Promise<string>;
     getSubscriptions: () => Promise<AppSubscription[]>;
     getSubscription(hubId: string): Promise<AppSubscription | null>;
-    reportUsage({ request, hubId, quantity, }: {
-        request: CookieSource;
+    reportUsage({ request, sub, hubId, quantity, }: {
+        request?: CookieSource;
+        sub?: string;
         hubId: string;
         quantity?: number;
     }): Promise<void>;
@@ -166,4 +179,4 @@ declare function clearlyHub(options: ClearlyHubOptions): {
 type ClearlyHub = ReturnType<typeof clearlyHub>;
 
 export { ANSWER_CHANNEL, DEFAULT_AUTH_URL, DEFAULT_BASE_PATH, DEFAULT_HUB_URL, DEFAULT_ISSUER, ROUTES, SCREEN_ACTIONS, checkScreenData, clearlyHub, isScreenAction };
-export type { AnswerMessage, AppSubscription, ClearlyHub, ClearlyHubOptions, ClearlyHubUrls, CookieSource, HubRef, HubSubscription, PickedResource, ScreenAction, ScreenAnswers, ScreenData, ScreenDisplay, ScreenResult, Session, SessionUser, SignedInPerson };
+export type { AnswerContext, AnswerMessage, AppSubscription, ClearlyHub, ClearlyHubOptions, ClearlyHubUrls, CookieSource, HookContext, HubRef, HubSubscription, PickedResource, ScreenAction, ScreenAnswers, ScreenData, ScreenDisplay, ScreenResult, Session, SessionUser, SignInDecision, SignedInPerson };

package/dist/index.js

@@ -14,8 +14,14 @@ function checkScreenData(action, data) {
   if (typeof url !== "string" || !url || typeof format !== "string" || !format) {
     return 'REGISTER_RESOURCE needs data with a url and a format, for example { url, format: "geojson" }';
   }
-  if (!url.startsWith("https://")) {
-    return "REGISTER_RESOURCE needs a public https url: Clearly.HUB refuses other addresses";
+  let hostname;
+  try {
+    hostname = new URL(url).hostname;
+  } catch {
+    return `REGISTER_RESOURCE: "${url}" is not a URL`;
+  }
+  if (!hostname.includes(".")) {
+    return "REGISTER_RESOURCE needs a url with a domain Clearly.HUB accepts, not localhost";
   }
   return void 0;
 }
@@ -66,7 +72,8 @@ function resolveConfig(options) {
     signedOutUrl: options.signedOutUrl ?? appUrl,
     onSignIn: options.onSignIn,
     onAnswer: options.onAnswer,
-    fetch: options.fetch ?? globalThis.fetch.bind(globalThis),
+    // Looked up on every call, so a fetch wrapped later (logging, tracing) is used
+    fetch: options.fetch ?? ((input, init) => globalThis.fetch(input, init)),
     isSecure: appUrl.startsWith("https://")
   };
 }
@@ -81,7 +88,7 @@ function toNodeMiddleware(handle, appUrl) {
         else if (value !== void 0) headers.set(name, value);
       }
       const url = new URL(req.originalUrl ?? req.url ?? "/", appUrl);
-      const response = await handle(new Request(url, { method: req.method, headers }));
+      const response = await handle(new Request(url, { method: req.method, headers }), req);
       if (response.headers.get("X-Clearly-Hub") === "unhandled" && next) {
         next();
         return;
@@ -181,18 +188,25 @@ var SCREEN_TTL_MS = 30 * 60 * 1e3;
 var MAX_PENDING_SCREENS = 10;
 function createHandler(parts) {
   const { config, sessions } = parts;
-  return async function handle(request) {
+  return async function handle(request, req) {
     const url = new URL(request.url);
     if (!url.pathname.startsWith(config.basePath)) return notFound();
     const route = url.pathname.slice(config.basePath.length) || "/";
     if (request.method !== "GET") return new Response("Method not allowed", { status: 405 });
+    const host = request.headers.get("host");
+    const appHost = new URL(config.appUrl).host;
+    if (host && host !== appHost && (route === ROUTES.signIn || route === ROUTES.open)) {
+      return redirect(`${config.appUrl}${url.pathname}${url.search}`);
+    }
     const { data, chunkCount } = await sessions.read(request);
     const before = JSON.stringify(data);
     let response;
     try {
-      response = await routeRequest(route, url, data, parts);
+      response = await routeRequest(route, url, data, parts, { request, req });
     } catch (error) {
-      response = errorPage(error instanceof AnswerError ? 400 : 500, error.message);
+      const isRefusedAnswer = error instanceof AnswerError;
+      if (!isRefusedAnswer) console.error(`Clearly.HUB: ${route} failed:`, error);
+      response = errorPage(isRefusedAnswer ? 400 : 500, describeError(error));
     }
     if (JSON.stringify(data) !== before) {
       for (const cookie of await sessions.write(data, chunkCount)) {
@@ -202,12 +216,12 @@ function createHandler(parts) {
     return response;
   };
 }
-async function routeRequest(route, url, session, parts) {
+async function routeRequest(route, url, session, parts, incoming) {
   switch (route) {
     case ROUTES.signIn:
       return startSignIn(url, session, parts);
     case ROUTES.callback:
-      return finishSignIn(url, session, parts);
+      return finishSignIn(url, session, parts, incoming);
     case ROUTES.signOut:
       for (const key of Object.keys(session)) delete session[key];
       return redirect(parts.signIn.signOutUrl());
@@ -216,7 +230,7 @@ async function routeRequest(route, url, session, parts) {
     case ROUTES.open:
       return openScreen(url, session, parts);
     case ROUTES.answer:
-      return receiveAnswer(url, session, parts);
+      return receiveAnswer(url, session, parts, incoming);
     case ROUTES.result: {
       const result = session.result ?? null;
       delete session.result;
@@ -231,16 +245,17 @@ async function startSignIn(url, session, { config, signIn }) {
   session.signIn = pending;
   return redirect(authorizationUrl);
 }
-async function finishSignIn(url, session, { config, signIn }) {
+async function finishSignIn(url, session, { config, signIn }, incoming) {
   const pending = session.signIn;
   if (!pending) return redirect(config.appUrl);
   delete session.signIn;
   const currentUrl = new URL(`${signIn.callbackUrl}${url.search}`);
   const { person, tokens } = await signIn.finish(currentUrl, pending);
-  const appUserId = await config.onSignIn?.(person) ?? void 0;
+  const decision = await config.onSignIn?.(person, incoming);
+  const { appUserId, redirectTo } = typeof decision === "string" ? { appUserId: decision, redirectTo: void 0 } : decision ?? {};
   session.user = { ...person, appUserId };
   session.tokens = tokens;
-  return redirect(`${config.appUrl}${pending.returnTo}`);
+  return redirect(`${config.appUrl}${safePath(redirectTo, config) ?? pending.returnTo}`);
 }
 async function readSession(session, parts) {
   const accessToken = await getFreshAccessToken(session, parts);
@@ -281,11 +296,12 @@ function openScreen(url, session, { config, screens }) {
     display,
     ref: url.searchParams.get("ref") ?? state,
     returnTo: safeReturnTo(url, config),
-    createdAt: Date.now()
+    createdAt: Date.now(),
+    data
   };
   return redirect(screens.screenUrl(action, state, session.user?.email, data));
 }
-async function receiveAnswer(url, session, { config, screens }) {
+async function receiveAnswer(url, session, { config, screens }, incoming) {
   const query = readRawQuery(url);
   const { state, response } = await screens.readAnswer(
     query.get("data") ?? "",
@@ -298,7 +314,12 @@ async function receiveAnswer(url, session, { config, screens }) {
   delete session.screens[state];
   let result = toScreenResult(pending.action, response);
   try {
-    await config.onAnswer?.(result, { user: session.user });
+    const app = await config.onAnswer?.(result, {
+      ...incoming,
+      user: session.user,
+      data: pending.data
+    });
+    if (app !== void 0) result = { ...result, app };
   } catch (error) {
     result = { action: pending.action, result: "FAILURE", error: error.message };
   }
@@ -324,12 +345,14 @@ function pruneScreens(screens = {}) {
   return Object.fromEntries(fresh);
 }
 function safeReturnTo(url, config) {
-  const returnTo = url.searchParams.get("returnTo") ?? "/";
-  if (!returnTo.startsWith("/") || returnTo.startsWith("//")) return "/";
+  return safePath(url.searchParams.get("returnTo") ?? void 0, config) ?? "/";
+}
+function safePath(path, config) {
+  if (!path || !path.startsWith("/") || path.startsWith("//")) return void 0;
   try {
-    return new URL(returnTo, config.appUrl).origin === new URL(config.appUrl).origin ? returnTo : "/";
+    return new URL(path, config.appUrl).origin === new URL(config.appUrl).origin ? path : void 0;
   } catch {
-    return "/";
+    return void 0;
   }
 }
 var redirect = (location) => new Response(null, { status: 302, headers: { Location: location } });
@@ -338,6 +361,13 @@ var json = (body) => new Response(JSON.stringify(body), {
 });
 var html = (body, status = 200) => new Response(body, { status, headers: { "Content-Type": "text/html; charset=utf-8" } });
 var notFound = () => new Response("Not found", { status: 404, headers: { "X-Clearly-Hub": "unhandled" } });
+function describeError(error) {
+  const messages = [];
+  for (let current = error; current instanceof Error && messages.length < 5; current = current.cause) {
+    if (!messages.includes(current.message)) messages.push(current.message);
+  }
+  return messages.join(": ") || String(error);
+}
 function errorPage(status, message) {
   const escaped = message.replace(/[&<>"]/g, (char) => `&#${char.charCodeAt(0)};`);
   return html(
@@ -355,6 +385,15 @@ var HubApi = class {
   config;
   appToken;
   subscriptions;
+  // A call to Clearly.HUB. When it can't be reached at all, say where: "fetch
+  // failed" alone doesn't tell you which service isn't running
+  async call(url, init) {
+    try {
+      return await this.config.fetch(url, init);
+    } catch (error) {
+      throw new Error(`Clearly.HUB could not be reached at ${url}`, { cause: error });
+    }
+  }
   get hasAppKey() {
     return Boolean(this.config.m2mClientId && this.config.m2mClientSecret);
   }
@@ -367,7 +406,7 @@ var HubApi = class {
       throw new Error("Clearly.HUB: m2mClientId and m2mClientSecret are needed for this");
     }
     const credentials = btoa(`${this.config.m2mClientId}:${this.config.m2mClientSecret}`);
-    const response = await this.config.fetch(`${this.config.urls.auth}/oauth2/token`, {
+    const response = await this.call(`${this.config.urls.auth}/oauth2/token`, {
       method: "POST",
       headers: {
         "Content-Type": "application/x-www-form-urlencoded",
@@ -390,7 +429,7 @@ var HubApi = class {
     if (this.subscriptions && Date.now() - this.subscriptions.fetchedAt < SUBSCRIPTIONS_CACHE_MS) {
       return this.subscriptions.value;
     }
-    const response = await this.config.fetch(`${this.config.urls.api}/api/app-api/subscriptions`, {
+    const response = await this.call(`${this.config.urls.api}/api/app-api/subscriptions`, {
       headers: { Authorization: `Bearer ${await this.getAppToken()}` }
     });
     if (!response.ok) {
@@ -410,7 +449,7 @@ var HubApi = class {
   }
   // Report one billable use; Clearly.HUB bills the hub
   async reportUsage(usage) {
-    const response = await this.config.fetch(this.config.urls.usage, {
+    const response = await this.call(this.config.urls.usage, {
       method: "POST",
       headers: {
         "Content-Type": "application/json",
@@ -617,20 +656,25 @@ function clearlyHub(options) {
     async getSubscription(hubId) {
       return pickSubscription(await parts.api.getSubscriptions(), hubId) ?? null;
     },
-    // Report billable use by the signed-in person in a hub
+    // Report billable use in a hub, by the person signed in with Clearly.HUB
+    // (request), or by a Clearly.HUB account you stored earlier (sub), for
+    // example for someone who signed in with your own login, or a nightly job
     async reportUsage({
       request,
+      sub,
       hubId,
       quantity = 1
     }) {
-      const { data } = await parts.sessions.read(request);
-      if (!data.user) throw new Error("Clearly.HUB: nobody is signed in with Clearly.HUB");
+      const person = sub ?? (request && (await parts.sessions.read(request)).data.user?.sub);
+      if (!person) {
+        throw new Error("Clearly.HUB: reportUsage needs the sub of a Clearly.HUB account");
+      }
       const subscription = pickSubscription(await parts.api.getSubscriptions(), hubId);
       if (subscription?.status !== "ACTIVE") {
         throw new Error(`Clearly.HUB: hub ${hubId} has no active subscription to your app`);
       }
       await parts.api.reportUsage({
-        sub: data.user.sub,
+        sub: person,
         hubId,
         subscriptionId: subscription.subscriptionId,
         quantity

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clearly-hub/node",
-  "version": "0.1.1",
+  "version": "0.2.1",
   "description": "Clearly.HUB for Node servers: sign-in, hosted screens, subscriptions and usage in one handler",
   "license": "SEE LICENSE IN LICENSE",
   "author": "Future Insight Group BV",