@clearly-hub/node 0.4.0 → 0.4.1

package/README.md

@@ -31,7 +31,7 @@ const hub = clearlyHub({
   m2mClientId: process.env.CLEARLY_HUB_M2M_CLIENT_ID,
   m2mClientSecret: process.env.CLEARLY_HUB_M2M_CLIENT_SECRET,
   appUrl: 'https://app.example.com',
-  secret: process.env.SESSION_SECRET, // 32+ characters
+  secret: process.env.SESSION_SECRET, // 32+ random characters
 });
 
 const app = express();
@@ -114,7 +114,8 @@ or plugin that adds headers to each request. The key lasts an hour; `getToken()`
 time, so call it again rather than keeping the value. On your server, `hub.fetchAsUser(req, url)`
 does the same.
 
-The key is the person's own Clearly.HUB key: keep scripts you don't trust off pages that use it.
+The key is the person's own Clearly.HUB key: send it only to resource URLs from `DATA_PICKER` (Clearly.HUB's
+data proxy), and keep scripts you don't trust off pages that use it. `fetchAsUser` refuses other URLs.
 
 ## The Node package
 
@@ -124,7 +125,7 @@ The key is the person's own Clearly.HUB key: keep scripts you don't trust off pa
 | `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`) on your server, with the person's key                                                                                                |
+| `hub.fetchAsUser(req, url)`                            | Fetch protected or paid data (from `DATA_PICKER`) on your server, with the person's key. Only URLs on Clearly.HUB's data proxy                                                         |
 | `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                                                                                                                             |
@@ -143,11 +144,19 @@ const hub = clearlyHub<express.Request>({
 });
 ```
 
-**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
-store; it's split over several cookies because tokens are large.
+**What it checks for you:** every screen answer's Ed25519 signature, that it answers a screen
+opened in this browser, once (`state`), and that it was given to your app and that screen
+(`client_id`, callback URL, action).
 
-**Local Clearly.HUB:** pass `urls: { screens, api, usage, auth, issuer }`; see
+**What to trust in an answer:** it's a snapshot of the moment the person clicked. For access later,
+ask `getSubscription(hubId)` when it's used, not the `status` you got then. Ignore `answer.user`:
+Clearly.HUB doesn't check it yet. Who's signed in is the session's user.
+
+The session is encrypted in cookies, so there's nothing to store; it's split over several cookies
+because tokens are large. A copied cookie stays valid until its refresh token expires: signing out
+clears only this browser's copy.
+
+**Local Clearly.HUB:** pass `urls: { screens, api, proxy, auth, issuer }`; see
 `examples/express/.env.example`.
 
 ## Not covered (yet)

package/dist/index.cjs

@@ -90,6 +90,7 @@ function resolveConfig(options) {
   const appUrl = trimSlash(options.appUrl);
   const hubUrl = trimSlash(options.hubUrl ?? DEFAULT_HUB_URL);
   const api = trimSlash(options.urls?.api ?? hubUrl);
+  const proxy = trimSlash(options.urls?.proxy ?? hubUrl);
   return {
     clientId: options.clientId,
     m2mClientId: options.m2mClientId,
@@ -101,7 +102,8 @@ function resolveConfig(options) {
     urls: {
       screens: trimSlash(options.urls?.screens ?? `${hubUrl}/components`),
       api,
-      usage: options.urls?.usage ?? `${hubUrl}/register-usage`,
+      proxy,
+      usage: options.urls?.usage ?? `${proxy}/register-usage`,
       publicKey: options.urls?.publicKey ?? `${api}/.well-known/public-key.pem`,
       auth: trimSlash(options.urls?.auth ?? DEFAULT_AUTH_URL),
       issuer: options.urls?.issuer ?? DEFAULT_ISSUER
@@ -188,7 +190,7 @@ var Screens = class {
     const { request, response } = JSON.parse(
       new TextDecoder().decode(base64Decode(data))
     );
-    return { state: request.state, response };
+    return { request: request ?? {}, response };
   }
   // Fetched once; a key change needs a restart
   getPublicKey() {
@@ -262,7 +264,10 @@ function createHandler(parts) {
       const isRefusedAnswer = error instanceof AnswerError;
       if (!isRefusedAnswer)
         console.error(`Clearly.HUB: ${route} failed:`, error);
-      response = errorPage(isRefusedAnswer ? 400 : 500, describeError(error));
+      response = isRefusedAnswer ? errorPage(400, error.message) : errorPage(
+        500,
+        config.isSecure ? "Something went wrong with Clearly.HUB. Please try again." : describeError(error)
+      );
     }
     if (JSON.stringify(data) !== before) {
       for (const cookie of await sessions.write(data, chunkCount)) {
@@ -380,10 +385,11 @@ function openScreen(url, session, { config, screens }) {
 }
 async function receiveAnswer(url, session, { config, screens }, incoming) {
   const query = readRawQuery(url);
-  const { state, response } = await screens.readAnswer(
+  const { request, response } = await screens.readAnswer(
     query.get("data") ?? "",
     query.get("signature") ?? ""
   );
+  const state = request.state;
   const pending = state ? session.screens?.[state] : void 0;
   if (!pending || Date.now() - pending.createdAt > SCREEN_TTL_MS) {
     throw new AnswerError(
@@ -391,6 +397,9 @@ async function receiveAnswer(url, session, { config, screens }, incoming) {
     );
   }
   delete session.screens[state];
+  if (request.client_id !== config.clientId || request.redirect_url !== screens.answerUrl || request.actions?.length !== 1 || request.actions[0] !== pending.action) {
+    throw new AnswerError("This answer was given to another app or screen");
+  }
   let result = toScreenResult(pending.action, response);
   try {
     const app = await config.onAnswer?.(result, {
@@ -778,8 +787,14 @@ function clearlyHub(options) {
     },
     getUserToken,
     // Fetch protected or paid data (for example from DATA_PICKER) with the
-    // person's key. Open data works without it.
+    // person's key. Open data works without it. Only URLs on Clearly.HUB's
+    // data proxy: the key would let anyone else act as this person
     async fetchAsUser(request, url, init = {}) {
+      if (!isOnProxy(url, config.urls.proxy)) {
+        throw new Error(
+          `Clearly.HUB: fetchAsUser only sends the person's key to Clearly.HUB's data proxy (${config.urls.proxy}, set with urls.proxy), not to ${url}`
+        );
+      }
       const token = await getUserToken(request);
       if (!token)
         throw new Error("Clearly.HUB: nobody is signed in with Clearly.HUB");
@@ -829,6 +844,15 @@ function clearlyHub(options) {
     }
   };
 }
+function isOnProxy(url, proxy) {
+  try {
+    const target = new URL(url);
+    const base = new URL(`${proxy}/`);
+    return target.origin === base.origin && target.pathname.startsWith(base.pathname);
+  } catch {
+    return false;
+  }
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   clearlyHub

package/dist/index.d.cts

@@ -148,6 +148,7 @@ interface ClearlyHubOptions<Req = unknown> {
 interface ClearlyHubUrls {
     screens: string;
     api: string;
+    proxy: string;
     usage: string;
     publicKey: string;
     auth: string;

package/dist/index.d.ts

@@ -148,6 +148,7 @@ interface ClearlyHubOptions<Req = unknown> {
 interface ClearlyHubUrls {
     screens: string;
     api: string;
+    proxy: string;
     usage: string;
     publicKey: string;
     auth: string;

package/dist/index.js

@@ -54,6 +54,7 @@ function resolveConfig(options) {
   const appUrl = trimSlash(options.appUrl);
   const hubUrl = trimSlash(options.hubUrl ?? DEFAULT_HUB_URL);
   const api = trimSlash(options.urls?.api ?? hubUrl);
+  const proxy = trimSlash(options.urls?.proxy ?? hubUrl);
   return {
     clientId: options.clientId,
     m2mClientId: options.m2mClientId,
@@ -65,7 +66,8 @@ function resolveConfig(options) {
     urls: {
       screens: trimSlash(options.urls?.screens ?? `${hubUrl}/components`),
       api,
-      usage: options.urls?.usage ?? `${hubUrl}/register-usage`,
+      proxy,
+      usage: options.urls?.usage ?? `${proxy}/register-usage`,
       publicKey: options.urls?.publicKey ?? `${api}/.well-known/public-key.pem`,
       auth: trimSlash(options.urls?.auth ?? DEFAULT_AUTH_URL),
       issuer: options.urls?.issuer ?? DEFAULT_ISSUER
@@ -152,7 +154,7 @@ var Screens = class {
     const { request, response } = JSON.parse(
       new TextDecoder().decode(base64Decode(data))
     );
-    return { state: request.state, response };
+    return { request: request ?? {}, response };
   }
   // Fetched once; a key change needs a restart
   getPublicKey() {
@@ -226,7 +228,10 @@ function createHandler(parts) {
       const isRefusedAnswer = error instanceof AnswerError;
       if (!isRefusedAnswer)
         console.error(`Clearly.HUB: ${route} failed:`, error);
-      response = errorPage(isRefusedAnswer ? 400 : 500, describeError(error));
+      response = isRefusedAnswer ? errorPage(400, error.message) : errorPage(
+        500,
+        config.isSecure ? "Something went wrong with Clearly.HUB. Please try again." : describeError(error)
+      );
     }
     if (JSON.stringify(data) !== before) {
       for (const cookie of await sessions.write(data, chunkCount)) {
@@ -344,10 +349,11 @@ function openScreen(url, session, { config, screens }) {
 }
 async function receiveAnswer(url, session, { config, screens }, incoming) {
   const query = readRawQuery(url);
-  const { state, response } = await screens.readAnswer(
+  const { request, response } = await screens.readAnswer(
     query.get("data") ?? "",
     query.get("signature") ?? ""
   );
+  const state = request.state;
   const pending = state ? session.screens?.[state] : void 0;
   if (!pending || Date.now() - pending.createdAt > SCREEN_TTL_MS) {
     throw new AnswerError(
@@ -355,6 +361,9 @@ async function receiveAnswer(url, session, { config, screens }, incoming) {
     );
   }
   delete session.screens[state];
+  if (request.client_id !== config.clientId || request.redirect_url !== screens.answerUrl || request.actions?.length !== 1 || request.actions[0] !== pending.action) {
+    throw new AnswerError("This answer was given to another app or screen");
+  }
   let result = toScreenResult(pending.action, response);
   try {
     const app = await config.onAnswer?.(result, {
@@ -742,8 +751,14 @@ function clearlyHub(options) {
     },
     getUserToken,
     // Fetch protected or paid data (for example from DATA_PICKER) with the
-    // person's key. Open data works without it.
+    // person's key. Open data works without it. Only URLs on Clearly.HUB's
+    // data proxy: the key would let anyone else act as this person
     async fetchAsUser(request, url, init = {}) {
+      if (!isOnProxy(url, config.urls.proxy)) {
+        throw new Error(
+          `Clearly.HUB: fetchAsUser only sends the person's key to Clearly.HUB's data proxy (${config.urls.proxy}, set with urls.proxy), not to ${url}`
+        );
+      }
       const token = await getUserToken(request);
       if (!token)
         throw new Error("Clearly.HUB: nobody is signed in with Clearly.HUB");
@@ -793,6 +808,15 @@ function clearlyHub(options) {
     }
   };
 }
+function isOnProxy(url, proxy) {
+  try {
+    const target = new URL(url);
+    const base = new URL(`${proxy}/`);
+    return target.origin === base.origin && target.pathname.startsWith(base.pathname);
+  } catch {
+    return false;
+  }
+}
 export {
   clearlyHub
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clearly-hub/node",
-  "version": "0.4.0",
+  "version": "0.4.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",