@alphamatica/hub-sdk-express

Express middleware for alpha-hub trust-headers SDK.

In the alpha-hub architecture all browser→service traffic is proxied through alpha-hub core. The hub validates JWT, resolves permissions, audit-logs at edge, then forwards to your service with X-Alpha-User-* headers and a shared X-Alpha-Proxy-Secret. This middleware verifies the secret and parses the headers into req.alphaUser.

Your service needs only the shared proxy secret — no hub URL, no public key.

Install

pnpm add @alphamatica/hub-sdk-express

Quick wire-up

const express = require('express');
const { alphaTrust, requirePermission } = require('@alphamatica/hub-sdk-express');

const app = express();
app.use(express.json());

// Apply trust check on every route
app.use(alphaTrust({ proxySecret: process.env.ALPHA_PROXY_SECRET }));

// Protected route
app.get('/reports',
  requirePermission('agms.reports.read'),
  (req, res) => {
    const locationIds = req.alphaUser.scopes.location_id ?? null;
    // null = unrestricted, else narrow by ids
    res.json({ data: '...' });
  },
);

Environment

| Variable | Description | |---|---| | ALPHA_PROXY_SECRET | Shared secret with alpha-hub. |

Migrating from v0.1.x

v0.1.x had createAlphaAuthState + alphaAuth middleware that validated JWTs locally. v0.2.0 replaces both with alphaTrust({ proxySecret }). Sync helpers (mountAlphaSync, mountAlphaSso) are gone — hub proxy handles those flows.

requirePermission keeps the same name and semantics.