mbs-sso-js 0.1.1 → 0.2.0

package/README.md

@@ -1,4 +1,4 @@
-# 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.
 
@@ -7,10 +7,10 @@ Launch MBS SSO from HTML, React or React Native while keeping OAuth credentials
 Install the versioned release from the npm registry once npm finishes processing it:
 
 ```sh
-npm install mbs-sso-js@0.1.1
+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.
@@ -53,3 +53,36 @@ The Express example uses a development memory session store and refuses producti
 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.
+
+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.
+
+### Skip business search with an RC number
+
+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.
+
+```jsx
+<MbsSsoButton startUrl="/auth/mbs/enablement" rcNumber="216879" />
+```
+
+```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,
+});
+```
+
+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.1",
+  "version": "0.2.0",
   "description": "MBS SSO browser, React and React Native launch buttons with Node.js authorization helpers",
   "files": [
     "dist",