@empowernow/common

Browser-safe, framework-agnostic security SDK used by EmpowerNow front-ends and back-ends.

OAuth 2.1 + PKCE • OpenID Connect • AuthZEN PDP client • RFC-8693 Token Exchange

Features

• OAuthClient – Authorization-Code + PKCE flow, token refresh, persistent storage (optional).
• Token validation – ID-token checks (issuer, aud, exp, nonce). • Token exchange – Minimal helper for server-side RFC-8693 (urn:ietf:params:oauth:grant-type:token-exchange). • AuthZEN PDP client – Typed client with true LRU cache & TTL. • Typed error model – Fine-grained ErrorCode enum for telemetry & UX. • ESM + CJS bundles, generated d.ts typings. Works in modern browsers and Node ≥ 18.

Installation

npm install @empowernow/common

Quick-start (browser)

import { OAuthClient } from "@empowernow/common";

const oauth = new OAuthClient(
  "https://idp.example.com",          // issuer
  "client_id_123",                   // OAuth client id
  { redirectUri: window.location.origin, scopes: ["openid", "profile"] }
);

// 1) Start login ► redirect the user
window.location.assign(await oauth.createAuthorizationUrl());

// 2) On the redirect URI page
await oauth.handleRedirectCallback();
const accessToken = await oauth.getAccessToken();

Quick-start (Node – token exchange)

import { exchangeToken } from "@empowernow/common";

const jwt = await exchangeToken(
  {
    tokenEndpoint: "https://idp.example.com/oauth2/token",
    clientId: "backend-client",
    clientSecret: process.env.CLIENT_SECRET!,
    audience: "https://api.example.com"
  },
  { subjectToken: userAccessToken }
);

AuthZEN PDP evaluation

import { PDPClient } from "@empowernow/common";

const pdp = new PDPClient({
  pdpUrl: "https://authz.example.com",
  clientId: "pdp-client",
  clientSecret: process.env.PDP_SECRET,
  cacheSize: 1000,
  ttl: 300
});

const decision = await pdp.evaluate({
  subject: { id: "alice", type: "user" },
  action: { name: "transfer" },
  resource: { id: "account-123" },
  context: { amount: 250 }
});

if (decision.decision === "ALLOW") {
  // …
}

Error handling

import { TokenValidationError, ErrorCode } from "@empowernow/common";

try {
  await oauth.handleRedirectCallback();
} catch (e) {
  if (e instanceof TokenValidationError && e.errorCode === ErrorCode.ID_NONCE_MISMATCH) {
    // display friendly error …
  }
}

Browser / Node support

• Modern browsers (ES2019 & fetch, crypto.subtle available).
• Node ≥ 18 (global fetch + crypto APIs). For Node 16 use a polyfill.

License

Apache-2.0 – © EmpowerNow