Clearly.HUB SDK

Connect your web app to Clearly.HUB with a script, some config and one server handler. You get "Sign in with Clearly.HUB", the hosted screens (choose a plan, pick data, save a result, choose a hub) and each hub's subscription to your app. The refresh token stays on your server; the page gets the access token only when it asks, for protected data.

Preview (0.x). The API may still change between minor versions. Proprietary: see LICENSE.

Quick start

1. Register your app in Clearly.HUB (on your app's page, no code):

2. Mount the server handler (Node 24+):

import express from 'express';
import { clearlyHub } from '@clearly-hub/node';

const hub = clearlyHub({
  clientId: process.env.CLEARLY_HUB_CLIENT_ID,
  m2mClientId: process.env.CLEARLY_HUB_M2M_CLIENT_ID,
  m2mClientSecret: process.env.CLEARLY_HUB_M2M_CLIENT_SECRET,
  appId: process.env.CLEARLY_HUB_APP_ID, // your app's id in Clearly.HUB
  appUrl: 'https://app.example.com',
  secret: process.env.SESSION_SECRET, // 32+ random characters
});

const app = express();
app.use('/clearly-hub', hub.express());

Not Express? hub.handler takes a Request and returns a Response, for Next.js route handlers, Hono, Bun or Deno. Mount it at /clearly-hub/*.

3. Add the script and a button:

<!-- @0.1: follows 0.1.x fixes, not a breaking 0.2 -->
<script src="https://cdn.jsdelivr.net/npm/@clearly-hub/[email protected]/dist/clearly-hub.js"></script>

<clearly-hub-button action="sign-in"></clearly-hub-button>
<clearly-hub-button action="SELECT_DATA"></clearly-hub-button>

<script type="module">
  const session = await clearlyHub.session(); // { signedIn, user }
  window.addEventListener('clearly-hub-answer', (event) =>
    console.log(event.detail),
  );
</script>

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

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: --clearly-hub-color, --clearly-hub-text-color, --clearly-hub-radius, --clearly-hub-padding, --clearly-hub-font. For anything else, style the real button through ::part(button):

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" or "iframe" on the script tag changes that). A blocked popup falls back to a redirect.

In a dialog on your page (display: 'iframe'): the screen shows in a centred dialog and uses the person signed in to your app, so it doesn't sign in itself, the way the Google Drive picker works. A popup does the same. Nobody signed in with Clearly.HUB here: your app's sign-in comes first (for a popup, in that same window). Needs a Clearly.HUB release that allows this (preview). If your app has its own CSP: frame-src https://hub.clearly.app. Style the dialog with --clearly-hub-frame-width, --clearly-hub-frame-height, --clearly-hub-backdrop, or clearly-hub-frame::part(dialog | iframe | close).

Every answer also has user (_id, email): who answered, set by Clearly.HUB. Its _id is the person's sub, the same as session().user.sub.

Protected data

A protected or paid resource from SELECT_DATA (requiresToken: true) has a url on Clearly.HUB, which checks the person's key on every request. Send it as the Authorization header. In the page:

const response = await fetch(resource.url, {
  headers: { Authorization: await clearlyHub.getToken() },
});

Map layers (WMS, WMTS, tiles) load many URLs themselves: use a Leaflet, OpenLayers or Cesium option or plugin that adds headers to each request. The key lasts an hour; getToken() gets a new one in 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: send it only to resource URLs from SELECT_DATA (Clearly.HUB's data proxy), and keep scripts you don't trust off pages that use it. fetchAsUser refuses other URLs.

The Node package

Behind the data proxy

When your API is a protected resource, Clearly.HUB's data proxy can tell it who calls: it adds an x-oup-context header, a JWT signed with Clearly.HUB's key. getProxyContext checks the signature, the expiry and, with audience (your resource id), that it was made for this resource:

app.get('/api/flood-depth', async (req, res) => {
  const context = await hub.getProxyContext(req, { audience: resourceId });
  if (!context) return res.sendStatus(401);
  if (context.hub.role !== 'ADMIN') return res.sendStatus(403);
  // context.sub, context.subscription?.id, context.activeHub, ...
});

It throws a ClearlyHubError with code invalid-context when the header is there but doesn't verify.

The header only proves who calls if the request really came through the proxy. Check the proxy's own secret too, the resource's authentication method (for example a CUSTOM_HEADER), or accept traffic from the proxy only. The proxy drops an x-oup-context a client sends itself. For now the proxy adds the header only when the resource's authentication method has forwardSubscriptionId on.

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:

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, 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).

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. 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.

Another path than /clearly-hub, for example /auth/hub: set it in all three places.

• Server: clearlyHub({ basePath: '/auth/hub', ... }) and mount it there, app.use('/auth/hub', hub.express()). The handler only answers under basePath and builds its callback URLs from it, so mounting alone isn't enough.
• Page: data-base-path="/auth/hub" on the script tag, or clearlyHub.configure({ basePath: '/auth/hub' }).
• Clearly.HUB: the sign-in client's callback URLs become {app}/auth/hub/callback and {app}/auth/hub/answer, and Go to app {app}/auth/hub/sign-in.

Registering data

Register your app's results in a hub from your own UI, without the REGISTER_RESOURCE screen: datasets, their resources, and the authentication methods protected resources use. Server only.

Every call starts with who acts: a request, for the person signed in on it, or 'app', for your app's own key (m2mClientId/m2mClientSecret), for example after a long job when nobody is signed in. A request without anyone signed in fails with UNAUTHENTICATED.

const { datasetId } = await hub.datasets.create(req, {
  title: 'Flood depth',
  ownerHubId,
  findability: 'LIMITED',
});

// Protected data: an authentication method first, then a resource behind the data proxy
const method = await hub.authMethods.create(req, ownerHubId, {
  name: 'Our tile server',
  type: 'CUSTOM_HEADER',
  authData: { parameterName: 'X-Api-Key', parameterValue: apiKey },
});
const resource = await hub.resources.add(req, datasetId, {
  name: 'Flood depth (WMS)',
  format: 'wms',
  sourceUrl: 'https://tiles.example.com/wms',
  authenticationMethodId: method.authMethodId,
});

Who may. Clearly.HUB decides. A person needs to be ADMIN of the hub (for datasets and resources: the dataset's owner hub). Your app's key has its own roles: admin of the hub that owns your app and its sub-hubs, member of that hub's parents, and editor in hubs that subscribed to your app (and their sub-hubs).

Moving a dataset to another ownerHubId also needs the person or app to be in that hub. Market masters can't make changes.

Good to know

• datasets.update and resources.update send everything, as create does: what you leave out may be cleared (spatial is). Start from datasets.get(), which returns the shape update takes. spatial is stored on update only, not on create.
• A protected resource has an authenticationMethodId and a sourceUrl (the address behind the proxy), and no url: Clearly.HUB makes it, on its data proxy. An open resource has a url only. Paid data also has a subscriptionModelId, a plan of the owner hub. format is one of Clearly.HUB's formats (wms, wfs, wmts, tilejson, api, ...). URLs need a domain: localhost is refused, use lvh.me.
• authData holds secrets. Clearly.HUB never gives it back, and update replaces all of it. Fields per type: BASIC_AUTH username, password; URL_PARAMETER and CUSTOM_HEADER parameterName, parameterValue; ISHARE_AUTH_METHOD tokenEndpoint, serviceProviderEORI, entitledPartyEORI; JWT_ENDPOINT tokenEndpoint, username, password, usernameField, passwordField (and accessTokenProperty, refreshTokenProperty); S3 s3AccessKeyId, s3SecretAccessKey; OAUTH2_CLIENT_CREDENTIALS tokenEndpoint, clientId, clientSecret (and accessTokenProperty, secretAsHeader, scope). The types (AuthDataByType) say the same.
• Deleting a dataset deletes its resources and cancels subscriptions to its paid ones.
• Errors are ClearlyHubErrors with Clearly.HUB's message and code (BAD_USER_INPUT, FORBIDDEN, UNAUTHENTICATED). The SDK checks what it can before sending, with the same code.

Not covered (yet)

• Setting up your own workspaces or tenants: do it by hand, with plans that need approval, or in onAnswer for SELECT_SUBSCRIPTION.
• Other server languages (.NET, Python, ...): the browser package works with any backend that answers the same routes. Contact us at [email protected] and we'll help you with yours.

Working on this repo

npm install
npm run build       # both packages
npm test            # vitest
npm run typecheck
npm run lint
npm run example     # examples/express on http://localhost:5175 (copy .env.example to .env first)