mbs-sso-js 0.1.0 → 0.2.0

package/README.md

@@ -1,16 +1,16 @@
-# mbs-sso-js 0.1.0
+# mbs-sso-js 0.2.0
 
 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:
+Install the versioned release from the npm registry once npm finishes processing it:
 
 ```sh
-npm install https://mbs.d3troit.dev/sdk/mbs-sso-js-0.1.0.tgz
+npm install mbs-sso-js@0.2.0
 ```
 
-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.
+For local development, run `pnpm sdk:build` in the SSO repository, then install its `public/sdk/mbs-sso-js-0.2.0.tgz` file. Node helpers require Node 20+. React and React Native are optional peers; install them only for the adapter you use.
 
 ## HTML
 
@@ -41,7 +41,7 @@ Uses `Linking.openURL` to open the system browser. Use an absolute HTTPS start U
 `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.
+2. Set `MBS_SSO_BASE_URL=https://api.mbs.gov.ng`, `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.
@@ -54,20 +54,35 @@ The browser adapters know only your start URL. MBS backend improvements remain a
 
 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
+Production API base URL: `https://api.mbs.gov.ng`. Sandbox base URL: `https://mbs.d3troit.dev`. Use app credentials registered for the target environment. In MBS SSO Apps, **App ID** is the OAuth `client_id` (`MBS_SSO_CLIENT_ID`) and **App Secret** is the OAuth `client_secret` (`MBS_SSO_CLIENT_SECRET`). Keep the App Secret on your backend. Register your application’s exact callback URI.
 
-Run from the SSO repository root:
+### Skip business search with an RC number
 
-```sh
-pnpm sdk:build
-cd packages/mbs-sso-js
-npm login
-npm publish --dry-run
-npm publish --access public
-```
+Pass `rcNumber: "216879"` to `startSso`, `MbsSsoButton`, or `mountButton`.
+The SDK adds `rc_number` to your backend start URL. Your backend must forward
+that value as `rcNumber` to `createAuthorizationRequest`. The authorization
+service must preserve `rc_number` on its redirect to the SSO enrollment page
+as a URL parameter. Provider-info describes the integrating application and is never used
+as the taxpayer RC source. The enrollment page automatically searches CAC
+and resolves an exact RC match, displaying Business Found or Business not found.
+Users can select Start again to search manually. RC numbers are lookup hints;
+NINAuth verification and authorization checks still apply.
 
-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.
+```jsx
+<MbsSsoButton startUrl="/auth/mbs/enablement" rcNumber="216879" />
+```
 
-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.
+```js
+await startSso({ startUrl: "/auth/mbs/enablement", rcNumber: "216879" });
+// Backend start route:
+const { url, transaction } = createAuthorizationRequest({
+  baseUrl,
+  clientId,
+  redirectUri,
+  flow: "enablement",
+  rcNumber: typeof req.query.rc_number === "string" ? req.query.rc_number : undefined,
+});
+```
 
-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.
+Omit `rcNumber` or pass an empty string to show manual business search.
+Version 0.2.0 adds this option across browser, React, React Native and server helpers.

package/dist/browser.js

@@ -5,6 +5,7 @@ export function mountButton(
   target,
   {
     startUrl,
+    rcNumber,
     label = "Continue with MBS",
     className = "",
     style = {},
@@ -32,7 +33,7 @@ export function mountButton(
     button.setAttribute("aria-busy", "true");
     status.textContent = "";
     try {
-      await startSso({ startUrl, openUrl });
+      await startSso({ startUrl, openUrl, rcNumber });
     } catch (error) {
       status.textContent = "Could not open MBS SSO. Please try again.";
       onError?.(error);

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 export interface StartOptions {
   startUrl: string;
+  rcNumber?: string;
   baseUrl?: string;
   openUrl?: (url: string) => unknown | Promise<unknown>;
 }

package/dist/index.js

@@ -14,9 +14,12 @@ export function resolveStartUrl(startUrl, baseUrl) {
   return url.href;
 }
 
-export async function startSso({ startUrl, openUrl, baseUrl } = {}) {
+export async function startSso({ startUrl, openUrl, baseUrl, rcNumber } = {}) {
   const browser = typeof window !== "undefined" ? window : undefined;
-  const url = resolveStartUrl(startUrl, baseUrl ?? browser?.location?.href);
+  const target = new URL(resolveStartUrl(startUrl, baseUrl ?? browser?.location?.href));
+  if (rcNumber != null && String(rcNumber).trim())
+    target.searchParams.set("rc_number", String(rcNumber).trim());
+  const url = target.href;
   if (openUrl) await openUrl(url);
   else if (browser?.location?.assign) browser.location.assign(url);
   else throw new Error("Provide openUrl outside a browser.");

package/dist/react-native.js

@@ -3,6 +3,7 @@ import { Linking, Pressable, Text, View } from "react-native";
 import { startSso } from "./index.js";
 export function MbsSsoButton({
   startUrl,
+  rcNumber,
   baseUrl,
   label = "Continue with MBS",
   style,
@@ -19,7 +20,7 @@ export function MbsSsoButton({
     setPending(true);
     setError("");
     try {
-      await startSso({ startUrl, openUrl, baseUrl });
+      await startSso({ startUrl, openUrl, baseUrl, rcNumber });
     } catch (reason) {
       setError("Could not open MBS SSO. Please try again.");
       onError?.(reason);

package/dist/react.js

@@ -3,6 +3,7 @@ import { createElement, useState } from "react";
 import { buttonStyle, startSso } from "./index.js";
 export function MbsSsoButton({
   startUrl,
+  rcNumber,
   baseUrl,
   children,
   label = "Continue with MBS",
@@ -21,7 +22,7 @@ export function MbsSsoButton({
     setPending(true);
     setError("");
     try {
-      await startSso({ startUrl, openUrl, baseUrl });
+      await startSso({ startUrl, openUrl, baseUrl, rcNumber });
     } catch (reason) {
       setError("Could not open MBS SSO. Please try again.");
       onError?.(reason);

package/dist/server.d.ts

@@ -11,6 +11,7 @@ export interface AuthorizationOptions {
   redirectUri: string;
   flow?: "login" | "enablement";
   scope?: string;
+  rcNumber?: string;
   now?: number;
 }
 export declare function createAuthorizationRequest(options: AuthorizationOptions): {

package/dist/server.js

@@ -7,6 +7,7 @@ export function createAuthorizationRequest({
   redirectUri,
   flow = "login",
   scope = "profile",
+  rcNumber,
   now = Date.now(),
 }) {
   if (!clientId || !redirectUri) throw new Error("clientId and redirectUri are required.");
@@ -28,6 +29,8 @@ export function createAuthorizationRequest({
     code_challenge: createHash("sha256").update(verifier).digest("base64url"),
     code_challenge_method: "S256",
   }).toString();
+  if (rcNumber != null && String(rcNumber).trim())
+    url.searchParams.set("rc_number", String(rcNumber).trim());
   return {
     url: url.href,
     transaction: { state, nonce, verifier, redirectUri, expiresAt: now + 600_000 },

package/examples/index.html

@@ -7,7 +7,7 @@
   </head>
   <body>
     <div id="mbs-login"></div>
-    <script src="https://mbs.d3troit.dev/sdk/mbs-sso-js-0.1.0.js"></script>
+    <script src="https://mbs.d3troit.dev/sdk/mbs-sso-js-0.2.0.js"></script>
     <script>
       MbsSso.mountButton("#mbs-login", {
         startUrl: "/auth/mbs/login",

package/examples/server.mjs

@@ -25,7 +25,7 @@ app.use(
     cookie: { httpOnly: true, secure: production, sameSite: "lax", maxAge: 600_000 },
   }),
 );
-const baseUrl = process.env.MBS_SSO_BASE_URL ?? "https://mbs.d3troit.dev";
+const baseUrl = process.env.MBS_SSO_BASE_URL ?? "https://api.mbs.gov.ng";
 const redirectUri = process.env.MBS_SSO_REDIRECT_URI;
 const clientId = process.env.MBS_SSO_CLIENT_ID;
 
@@ -37,6 +37,7 @@ for (const flow of ["login", "enablement"]) {
         clientId,
         redirectUri,
         flow,
+        rcNumber: typeof req.query.rc_number === "string" ? req.query.rc_number : undefined,
       });
       req.session.mbs = transaction;
       // Persist state and verifier before leaving the application.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mbs-sso-js",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "MBS SSO browser, React and React Native launch buttons with Node.js authorization helpers",
   "files": [
     "dist",