mbs-sso-js 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,73 @@
-# Temporary Holding Version
+# mbs-sso-js 0.1.0
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Launch MBS SSO from HTML, React or React Native while keeping OAuth credentials on your application backend. MBS hosts login, enablement, NINAuth, OTP, password setup and consent. Opening a browser is not proof of authentication.
+
+## Install
+
+The package is **not published in the npm registry**. Install the hosted release:
+
+```sh
+npm install https://mbs.d3troit.dev/sdk/mbs-sso-js-0.1.0.tgz
+```
+
+For local development, run `pnpm sdk:build` in the SSO repository, then install its `public/sdk/mbs-sso-js-0.1.0.tgz` file. Node helpers require Node 20+. React and React Native are optional peers; install them only for the adapter you use.
+
+## HTML
+
+See `examples/index.html`. Load the hosted browser script, then call `MbsSso.mountButton(elementOrSelector, { startUrl, label, className, style, disabled, onError })`. It returns `{ button, destroy }`. `destroy()` removes the mounted button and its listener. Custom CSS can supply focus and hover styles; native browser focus indicators remain enabled.
+
+## React
+
+```tsx
+import { MbsSsoButton } from "mbs-sso-js/react";
+<MbsSsoButton startUrl="/auth/mbs/login" className="my-button" style={{ borderRadius: 24 }}>
+  Continue with MBS
+</MbsSsoButton>;
+```
+
+Standard button attributes, custom children, disabled state, inline styles and `onError` are supported. `onClick` can cancel launch using `event.preventDefault()`. For your own button, use `startSso({ startUrl })` from `mbs-sso-js`.
+
+## React Native
+
+```tsx
+import { MbsSsoButton } from "mbs-sso-js/react-native";
+<MbsSsoButton startUrl="https://your-app.example/auth/mbs/login" label="Continue with MBS" />;
+```
+
+Uses `Linking.openURL` to open the system browser. Use an absolute HTTPS start URL. Supports `style`, `textStyle`, disabled state, `onError`, and an injectable `openUrl` function for platform authentication-session integration. Your app must configure its universal/app links and its own authenticated session handoff. A browser cookie does not automatically authenticate a native API client. The backend callback must finish state validation and token exchange first; then issue your application's short-lived, single-use handoff ticket, validate/redeem it on your backend, and establish the native app session. Never put MBS access tokens or client secrets in a deep link. The SDK does not implement or pretend to provide that application-specific backend ticket endpoint.
+
+## Backend start and callback
+
+`startUrl` is **your application's backend route**, not the MBS enrollment page. Implement `/auth/mbs/login` and `/auth/mbs/enablement` using the complete Express example in `examples/server.mjs`.
+
+1. Obtain a client ID and secret from the MBS team. Register your exact callback URL.
+2. Set `MBS_SSO_BASE_URL=https://mbs.d3troit.dev`, `MBS_SSO_CLIENT_ID`, `MBS_SSO_CLIENT_SECRET`, `MBS_SSO_REDIRECT_URI`, and a strong `SESSION_SECRET` on your backend.
+3. `createAuthorizationRequest()` creates random state, nonce and S256 PKCE values. Persist the returned transaction in your server session before redirecting to its `url` (`GET /oauth/authorize`).
+4. In your registered callback, atomically consume the pending transaction. `exchangeAuthorizationCode()` validates its lifetime, callback origin/path, unique state, error and code, then sends a form POST to `/oauth/token` with the original redirect URI, verifier and client credentials.
+5. Call `/oauth/userinfo` server-side and create your own application session. Tokens stay server-side. The helper does not verify an ID-token signature; do not use unverified ID-token claims to authenticate users. Use user info as in the example, or a configured OIDC library for ID-token verification.
+
+The Express example uses a development memory session store and refuses production mode until configured. For deployment, use a persistent shared session store, a session lock/atomic transaction consumption for concurrent callbacks, HTTPS cookies and explicit trusted proxy configuration. Its default session transaction is one pending journey per browser session; starting a second replaces the first.
+
+## Backend compatibility and versioning
+
+The browser adapters know only your start URL. MBS backend improvements remain available in the hosted journey without an SDK update. Changes to the public authorization/token contract may require a new server helper release. Pin the SDK version and test against your registered client. Endpoint behavior is covered by contract tests; a full live sign-in still requires provisioned MBS credentials and NINAuth configuration.
+
+Native browser launch and return-link configuration require device validation; this release has not been tested in an iOS/Android emulator.
+
+## Publish to the npm registry
+
+Run from the SSO repository root:
+
+```sh
+pnpm sdk:build
+cd packages/mbs-sso-js
+npm login
+npm publish --dry-run
+npm publish --access public
+```
+
+Complete npm's browser login and publishing verification using your own account. The prepublishOnly hook rebuilds the SDK and runs the repository checks and tests. The files allowlist publishes dist, examples and the README. Review the dry-run file list before publishing.
+
+The unscoped name `mbs-sso-js` must be available or owned by your npm account. If it is not, change the package name to `@YOUR_NPM_SCOPE/mbs-sso-js` and update the example imports and installation instructions accordingly before release. Confirm your organization's ownership and intended license before publishing; this repository does not choose a license for you.
+
+After successful publication, consumers can install `npm install mbs-sso-js` (or the scoped name you chose). Update the hosted documentation and release metadata only after verifying the registry release. For subsequent releases, increment the SDK package version, update the pinned SDK guide/download references, rebuild and publish; npm does not allow overwriting a published name/version pair.

package/dist/browser.d.ts

@@ -0,0 +1,13 @@
+import type { StartOptions } from "./index.js";
+export { startSso, resolveStartUrl } from "./index.js";
+export interface MountOptions extends StartOptions {
+  label?: string;
+  className?: string;
+  style?: Partial<CSSStyleDeclaration>;
+  disabled?: boolean;
+  onError?: (error: unknown) => void;
+}
+export declare function mountButton(
+  target: string | HTMLElement,
+  options: MountOptions,
+): { button: HTMLButtonElement; destroy(): void };

package/dist/browser.js

@@ -0,0 +1,54 @@
+import { startSso, resolveStartUrl, buttonStyle } from "./index.js";
+export { startSso, resolveStartUrl };
+
+export function mountButton(
+  target,
+  {
+    startUrl,
+    label = "Continue with MBS",
+    className = "",
+    style = {},
+    disabled = false,
+    onError,
+    openUrl,
+  } = {},
+) {
+  const container = typeof target === "string" ? document.querySelector(target) : target;
+  if (!container) throw new Error("MBS button container was not found.");
+  resolveStartUrl(startUrl, window.location.href);
+  const button = document.createElement("button");
+  button.type = "button";
+  button.textContent = label;
+  button.className = className;
+  button.disabled = disabled;
+  Object.assign(button.style, buttonStyle, style);
+  const status = document.createElement("span");
+  status.setAttribute("role", "alert");
+  status.style.display = "block";
+  status.style.fontSize = "14px";
+  const click = async () => {
+    if (button.disabled) return;
+    button.disabled = true;
+    button.setAttribute("aria-busy", "true");
+    status.textContent = "";
+    try {
+      await startSso({ startUrl, openUrl });
+    } catch (error) {
+      status.textContent = "Could not open MBS SSO. Please try again.";
+      onError?.(error);
+    } finally {
+      button.disabled = disabled;
+      button.removeAttribute("aria-busy");
+    }
+  };
+  button.addEventListener("click", click);
+  container.append(button, status);
+  return {
+    button,
+    destroy() {
+      button.removeEventListener("click", click);
+      button.remove();
+      status.remove();
+    },
+  };
+}

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export interface StartOptions {
+  startUrl: string;
+  baseUrl?: string;
+  openUrl?: (url: string) => unknown | Promise<unknown>;
+}
+export declare function resolveStartUrl(startUrl: string, baseUrl?: string): string;
+export declare function startSso(options: StartOptions): Promise<void>;
+export declare const buttonStyle: Readonly<Record<string, string>>;

package/dist/index.js

@@ -0,0 +1,41 @@
+/** Resolve a customer-owned backend start route. No OAuth credentials belong here. */
+export function resolveStartUrl(startUrl, baseUrl) {
+  if (typeof startUrl !== "string" || !startUrl.trim())
+    throw new Error("Provide your backend startUrl.");
+  const url = new URL(startUrl, baseUrl);
+  const local = ["localhost", "127.0.0.1", "[::1]"].includes(url.hostname);
+  if (url.protocol !== "https:" && !(url.protocol === "http:" && local)) {
+    throw new Error("startUrl must use HTTPS (HTTP is allowed on localhost).");
+  }
+  if (url.username || url.password) throw new Error("Do not put credentials in startUrl.");
+  for (const key of ["client_secret", "access_token", "id_token", "code_verifier"]) {
+    if (url.searchParams.has(key)) throw new Error(`Do not put ${key} in startUrl.`);
+  }
+  return url.href;
+}
+
+export async function startSso({ startUrl, openUrl, baseUrl } = {}) {
+  const browser = typeof window !== "undefined" ? window : undefined;
+  const url = resolveStartUrl(startUrl, baseUrl ?? browser?.location?.href);
+  if (openUrl) await openUrl(url);
+  else if (browser?.location?.assign) browser.location.assign(url);
+  else throw new Error("Provide openUrl outside a browser.");
+}
+
+export const buttonStyle = Object.freeze({
+  display: "inline-flex",
+  alignItems: "center",
+  justifyContent: "center",
+  gap: "8px",
+  minHeight: "48px",
+  maxWidth: "100%",
+  padding: "12px 24px",
+  border: "1px solid transparent",
+  borderRadius: "8px",
+  backgroundColor: "#14ae5c",
+  color: "#ffffff",
+  font: "inherit",
+  fontWeight: "500",
+  lineHeight: "1.4",
+  cursor: "pointer",
+});

package/dist/react-native.d.ts

@@ -0,0 +1,10 @@
+import type { ReactElement } from "react";
+import type { PressableProps, StyleProp, TextStyle } from "react-native";
+import type { StartOptions } from "./index.js";
+export interface MbsSsoButtonProps
+  extends Omit<PressableProps, "onPress" | "onError">, StartOptions {
+  label?: string;
+  textStyle?: StyleProp<TextStyle>;
+  onError?: (error: unknown) => void;
+}
+export declare function MbsSsoButton(props: MbsSsoButtonProps): ReactElement;

package/dist/react-native.js

@@ -0,0 +1,62 @@
+import { createElement, useState } from "react";
+import { Linking, Pressable, Text, View } from "react-native";
+import { startSso } from "./index.js";
+export function MbsSsoButton({
+  startUrl,
+  baseUrl,
+  label = "Continue with MBS",
+  style,
+  textStyle,
+  disabled = false,
+  onError,
+  openUrl = Linking.openURL,
+  ...props
+}) {
+  const [pending, setPending] = useState(false);
+  const [error, setError] = useState("");
+  const onPress = async () => {
+    if (disabled || pending) return;
+    setPending(true);
+    setError("");
+    try {
+      await startSso({ startUrl, openUrl, baseUrl });
+    } catch (reason) {
+      setError("Could not open MBS SSO. Please try again.");
+      onError?.(reason);
+    } finally {
+      setPending(false);
+    }
+  };
+  return createElement(
+    View,
+    null,
+    createElement(
+      Pressable,
+      {
+        ...props,
+        onPress,
+        disabled: disabled || pending,
+        accessibilityRole: "button",
+        accessibilityLabel: label,
+        accessibilityState: { disabled: disabled || pending, busy: pending },
+        style: (pressState) => [
+          {
+            backgroundColor: "#14ae5c",
+            borderRadius: 8,
+            paddingVertical: 12,
+            paddingHorizontal: 24,
+            alignItems: "center",
+            opacity: disabled || pending ? 0.5 : 1,
+          },
+          typeof style === "function" ? style(pressState) : style,
+        ],
+      },
+      createElement(
+        Text,
+        { style: [{ color: "#ffffff", fontSize: 16, fontWeight: "500" }, textStyle] },
+        label,
+      ),
+    ),
+    error ? createElement(Text, { accessibilityRole: "alert" }, error) : null,
+  );
+}

package/dist/react.d.ts

@@ -0,0 +1,8 @@
+import type { ButtonHTMLAttributes, ReactElement } from "react";
+import type { StartOptions } from "./index.js";
+export interface MbsSsoButtonProps
+  extends Omit<ButtonHTMLAttributes<HTMLButtonElement>, "onError">, StartOptions {
+  label?: string;
+  onError?: (error: unknown) => void;
+}
+export declare function MbsSsoButton(props: MbsSsoButtonProps): ReactElement;

package/dist/react.js

@@ -0,0 +1,49 @@
+"use client";
+import { createElement, useState } from "react";
+import { buttonStyle, startSso } from "./index.js";
+export function MbsSsoButton({
+  startUrl,
+  baseUrl,
+  children,
+  label = "Continue with MBS",
+  style,
+  disabled,
+  onError,
+  openUrl,
+  onClick,
+  ...props
+}) {
+  const [pending, setPending] = useState(false);
+  const [error, setError] = useState("");
+  const handleClick = async (event) => {
+    onClick?.(event);
+    if (event.defaultPrevented || pending || disabled) return;
+    setPending(true);
+    setError("");
+    try {
+      await startSso({ startUrl, openUrl, baseUrl });
+    } catch (reason) {
+      setError("Could not open MBS SSO. Please try again.");
+      onError?.(reason);
+    } finally {
+      setPending(false);
+    }
+  };
+  return createElement(
+    "span",
+    { style: { display: "inline-block", maxWidth: "100%" } },
+    createElement(
+      "button",
+      {
+        ...props,
+        type: "button",
+        style: { ...buttonStyle, ...style },
+        disabled: disabled || pending,
+        "aria-busy": pending || undefined,
+        onClick: handleClick,
+      },
+      children ?? label,
+    ),
+    error ? createElement("span", { role: "alert", style: { display: "block" } }, error) : null,
+  );
+}

package/dist/server.d.ts

@@ -0,0 +1,39 @@
+export interface Transaction {
+  state: string;
+  nonce: string;
+  verifier: string;
+  redirectUri: string;
+  expiresAt: number;
+}
+export interface AuthorizationOptions {
+  baseUrl: string;
+  clientId: string;
+  redirectUri: string;
+  flow?: "login" | "enablement";
+  scope?: string;
+  now?: number;
+}
+export declare function createAuthorizationRequest(options: AuthorizationOptions): {
+  url: string;
+  transaction: Transaction;
+};
+export declare function validateCallback(
+  callbackUrl: string,
+  transaction: Transaction,
+  now?: number,
+): string;
+export interface ExchangeOptions {
+  baseUrl: string;
+  clientId: string;
+  clientSecret: string;
+  callbackUrl: string;
+  transaction: Transaction;
+  fetch?: typeof fetch;
+  now?: number;
+}
+export declare function exchangeAuthorizationCode(options: ExchangeOptions): Promise<{
+  access_token: string;
+  id_token?: string;
+  expires_in?: number;
+  [key: string]: unknown;
+}>;

package/dist/server.js

@@ -0,0 +1,93 @@
+import { randomBytes, createHash, timingSafeEqual } from "node:crypto";
+import { resolveStartUrl } from "./index.js";
+
+export function createAuthorizationRequest({
+  baseUrl,
+  clientId,
+  redirectUri,
+  flow = "login",
+  scope = "profile",
+  now = Date.now(),
+}) {
+  if (!clientId || !redirectUri) throw new Error("clientId and redirectUri are required.");
+  if (!["login", "enablement"].includes(flow)) throw new Error("flow must be login or enablement.");
+  const base = resolveStartUrl(baseUrl);
+  resolveStartUrl(redirectUri);
+  const state = randomBytes(32).toString("base64url");
+  const nonce = randomBytes(32).toString("base64url");
+  const verifier = randomBytes(32).toString("base64url");
+  const url = new URL("/oauth/authorize", base);
+  url.search = new URLSearchParams({
+    response_type: "code",
+    client_id: clientId,
+    redirect_uri: redirectUri,
+    flow,
+    scope,
+    state,
+    nonce,
+    code_challenge: createHash("sha256").update(verifier).digest("base64url"),
+    code_challenge_method: "S256",
+  }).toString();
+  return {
+    url: url.href,
+    transaction: { state, nonce, verifier, redirectUri, expiresAt: now + 600_000 },
+  };
+}
+
+export function validateCallback(callbackUrl, transaction, now = Date.now()) {
+  if (!transaction || !Number.isFinite(transaction.expiresAt) || now >= transaction.expiresAt)
+    throw new Error("The SSO transaction is missing or expired.");
+  const url = new URL(callbackUrl);
+  const expected = new URL(transaction.redirectUri);
+  if (url.origin !== expected.origin || url.pathname !== expected.pathname)
+    throw new Error("Unexpected callback URL.");
+  const states = url.searchParams.getAll("state");
+  const actual = Buffer.from(states[0] ?? "");
+  const saved = Buffer.from(transaction.state ?? "");
+  if (
+    states.length !== 1 ||
+    !saved.length ||
+    actual.length !== saved.length ||
+    !timingSafeEqual(actual, saved)
+  )
+    throw new Error("The callback state does not match.");
+  if (url.searchParams.has("error"))
+    throw new Error("MBS authorization was declined or could not be completed.");
+  const codes = url.searchParams.getAll("code");
+  if (codes.length !== 1 || !codes[0])
+    throw new Error("The callback is missing a unique authorization code.");
+  return codes[0];
+}
+
+export async function exchangeAuthorizationCode({
+  baseUrl,
+  clientId,
+  clientSecret,
+  callbackUrl,
+  transaction,
+  fetch: request = globalThis.fetch,
+  now = Date.now(),
+}) {
+  if (!clientId || !clientSecret)
+    throw new Error("Server-side clientId and clientSecret are required.");
+  const code = validateCallback(callbackUrl, transaction, now);
+  const response = await request(new URL("/oauth/token", resolveStartUrl(baseUrl)), {
+    method: "POST",
+    redirect: "error",
+    headers: { "Content-Type": "application/x-www-form-urlencoded", Accept: "application/json" },
+    body: new URLSearchParams({
+      grant_type: "authorization_code",
+      code,
+      redirect_uri: transaction.redirectUri,
+      code_verifier: transaction.verifier,
+      client_id: clientId,
+      client_secret: clientSecret,
+    }),
+  });
+  if (!response.ok) throw new Error(`MBS token exchange failed (HTTP ${response.status}).`);
+  const body = await response.json();
+  const tokens = body.data ?? body;
+  if (body.error || body.status === false || !tokens.access_token)
+    throw new Error("MBS did not return a valid access token.");
+  return tokens;
+}

package/examples/index.html

@@ -0,0 +1,19 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width,initial-scale=1" />
+    <title>Connect with MBS</title>
+  </head>
+  <body>
+    <div id="mbs-login"></div>
+    <script src="https://mbs.d3troit.dev/sdk/mbs-sso-js-0.1.0.js"></script>
+    <script>
+      MbsSso.mountButton("#mbs-login", {
+        startUrl: "/auth/mbs/login",
+        label: "Continue with MBS",
+        style: { borderRadius: "24px" },
+      });
+    </script>
+  </body>
+</html>

package/examples/server.mjs

@@ -0,0 +1,94 @@
+// Node 20+, Express and express-session. Run behind HTTPS in production.
+import express from "express";
+import session from "express-session";
+import { createAuthorizationRequest, exchangeAuthorizationCode } from "mbs-sso-js/server";
+
+const app = express();
+const production = process.env.NODE_ENV === "production";
+for (const name of [
+  "SESSION_SECRET",
+  "MBS_SSO_CLIENT_ID",
+  "MBS_SSO_CLIENT_SECRET",
+  "MBS_SSO_REDIRECT_URI",
+]) {
+  if (!process.env[name]) throw new Error(`Set ${name} on the backend.`);
+}
+if (production)
+  throw new Error(
+    "Configure a shared persistent session store and trusted proxy before deploying this example.",
+  );
+app.use(
+  session({
+    secret: process.env.SESSION_SECRET,
+    resave: false,
+    saveUninitialized: false,
+    cookie: { httpOnly: true, secure: production, sameSite: "lax", maxAge: 600_000 },
+  }),
+);
+const baseUrl = process.env.MBS_SSO_BASE_URL ?? "https://mbs.d3troit.dev";
+const redirectUri = process.env.MBS_SSO_REDIRECT_URI;
+const clientId = process.env.MBS_SSO_CLIENT_ID;
+
+for (const flow of ["login", "enablement"]) {
+  app.get(`/auth/mbs/${flow}`, (req, res, next) => {
+    try {
+      const { url, transaction } = createAuthorizationRequest({
+        baseUrl,
+        clientId,
+        redirectUri,
+        flow,
+      });
+      req.session.mbs = transaction;
+      // Persist state and verifier before leaving the application.
+      req.session.save((error) => (error ? next(error) : res.redirect(url)));
+    } catch (error) {
+      next(error);
+    }
+  });
+}
+app.get(new URL(redirectUri).pathname, async (req, res, next) => {
+  const transaction = req.session.mbs;
+  delete req.session.mbs; // Consume the pending transaction before exchange, including failed callbacks.
+  req.session.save(async (error) => {
+    if (error) return next(error);
+    try {
+      const callback = new URL(redirectUri);
+      callback.search = new URL(req.originalUrl, redirectUri).search;
+      const tokens = await exchangeAuthorizationCode({
+        baseUrl,
+        clientId,
+        clientSecret: process.env.MBS_SSO_CLIENT_SECRET,
+        callbackUrl: callback.href,
+        transaction,
+      });
+      const response = await fetch(new URL("/oauth/userinfo", baseUrl), {
+        headers: { Authorization: `Bearer ${tokens.access_token}`, Accept: "application/json" },
+        redirect: "error",
+      });
+      if (!response.ok) throw new Error("User info could not be retrieved.");
+      const body = await response.json();
+      const profile = body.data ?? body;
+      if (body.error || body.status === false || !profile.sub)
+        throw new Error("Invalid user info response.");
+      req.session.regenerate((regenerateError) => {
+        if (regenerateError) return next(regenerateError);
+        req.session.user = { sub: profile.sub, entity_id: profile.entity_id };
+        req.session.cookie.maxAge = 3_600_000;
+        req.session.save((saveError) => (saveError ? next(saveError) : res.redirect("/app")));
+      });
+    } catch {
+      res.status(400).send("Sign-in could not be completed. Start again from your application.");
+    }
+  });
+});
+app.get("/app", (req, res) => {
+  if (!req.session.user) return res.status(401).send("Sign in first.");
+  res.type("text").send(`Signed in as ${req.session.user.sub}`);
+});
+app.use((error, req, res, next) => {
+  void error;
+  void req;
+  void next;
+  res.status(500).send("SSO is temporarily unavailable.");
+});
+app.listen(Number(process.env.PORT ?? 3000));

package/package.json

@@ -1,6 +1,56 @@
 {
   "name": "mbs-sso-js",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "MBS SSO browser, React and React Native launch buttons with Node.js authorization helpers",
+  "files": [
+    "dist",
+    "examples",
+    "README.md"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./react": {
+      "types": "./dist/react.d.ts",
+      "import": "./dist/react.js"
+    },
+    "./react-native": {
+      "types": "./dist/react-native.d.ts",
+      "import": "./dist/react-native.js"
+    },
+    "./server": {
+      "types": "./dist/server.d.ts",
+      "import": "./dist/server.js"
+    },
+    "./browser": {
+      "types": "./dist/browser.d.ts",
+      "import": "./dist/browser.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "scripts": {
+    "prepublishOnly": "cd ../.. && pnpm sdk:build && pnpm check && pnpm test"
+  },
+  "peerDependencies": {
+    "react": ">=18",
+    "react-native": ">=0.73"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    },
+    "react-native": {
+      "optional": true
+    }
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}