@pofsis-nbt/pofsis-auth 2.0.0 → 2.1.0

package/docs/application-id-consumer-migration.md

@@ -0,0 +1,180 @@
+# Application-ID Integration Update
+
+This guide covers only the frontend integration changes required to migrate an existing POFSIS tool
+from the legacy `@pofsis/auth-react` package and application-name configuration to
+`@pofsis-nbt/pofsis-auth` v2 and an immutable application UUID.
+
+## Required values
+
+Obtain the correct `applications.id` UUID for each environment from the Auth application registry.
+Do not reuse a development UUID in staging or production unless that environment has been verified
+to use the same registration.
+
+For Vite applications, configure:
+
+```env
+VITE_POFSIS_APPLICATION_ID=<APPLICATION_UUID>
+VITE_POFSIS_API_BASE_URL=https://dev-auth.pofsis.com/api
+VITE_POFSIS_AUTH_URL=https://dev-auth.pofsis.com/authorize
+VITE_POFSIS_SCOPE=openid profile email
+```
+
+Remove:
+
+```env
+VITE_POFSIS_APP_NAME=<LEGACY_APPLICATION_NAME>
+```
+
+The application UUID is a public identifier, not a secret. Do not add `client_id`, redirect URI, or
+logout URI to the frontend environment. The library discovers those values through Auth BE using
+the UUID and the browser's exact origin.
+
+## Upgrade the package
+
+Remove the old dependency:
+
+```powershell
+npm uninstall @pofsis/auth-react
+```
+
+Install v2:
+
+```powershell
+npm install @pofsis-nbt/pofsis-auth@^2.0.0
+```
+
+If the old package was vendored under `packages/pofsis-auth-react`, delete that directory after all
+imports have been replaced. Remove any Vite `optimizeDeps.exclude` entry that existed only for the
+vendored package.
+
+Replace imports throughout the tool:
+
+```diff
+- import { PofsisAuth, RequireAuth, useAuth } from '@pofsis/auth-react'
++ import { PofsisAuth, RequireAuth, useAuth } from '@pofsis-nbt/pofsis-auth'
+```
+
+Import the v2 stylesheet exactly once in the application entry point:
+
+```js
+import '@pofsis-nbt/pofsis-auth/style.css'
+```
+
+Check for remaining legacy references:
+
+```powershell
+rg "@pofsis/auth-react|VITE_POFSIS_APP_NAME|appName|\?app=" src .envs package.json vite.config.*
+```
+
+## Configure the React provider
+
+The library does not read environment variables directly. The consuming application must pass its
+configuration to `PofsisAuth`:
+
+```jsx
+import { PofsisAuth } from '@pofsis-nbt/pofsis-auth'
+
+<PofsisAuth
+  applicationId={import.meta.env.VITE_POFSIS_APPLICATION_ID}
+  apiBaseUrl={import.meta.env.VITE_POFSIS_API_BASE_URL}
+  authUrl={import.meta.env.VITE_POFSIS_AUTH_URL}
+  scope={import.meta.env.VITE_POFSIS_SCOPE}
+  callbackPath="/auth/callback"
+  postLoginPath="/"
+>
+  <App />
+</PofsisAuth>
+```
+
+`applicationId`, `apiBaseUrl`, and `authUrl` are required. Missing values fail during configuration
+instead of silently selecting another application.
+
+## Update protected routes
+
+The v2 `RequireAuth` contract is:
+
+```text
+RequireAuth({ children, fallback?, onUnauthenticated? })
+```
+
+Legacy `mode` and `returnTo` props are not supported. The basic integration is:
+
+```jsx
+import { RequireAuth } from '@pofsis-nbt/pofsis-auth'
+
+function ProtectedRoute({ children }) {
+  return (
+    <RequireAuth fallback={<LoadingScreen />}>
+      {children}
+    </RequireAuth>
+  )
+}
+```
+
+Without `onUnauthenticated`, `RequireAuth` starts its default redirect login. A tool that requires
+different unauthenticated behavior can provide its own `onUnauthenticated` callback based on that
+tool's product flow; this guide does not prescribe login, signup, popup, or return-path behavior.
+
+## Keep protected API calls connected
+
+The Axios interceptor signature is unchanged:
+
+```js
+import { attachAuthInterceptor } from '@pofsis-nbt/pofsis-auth'
+
+attachAuthInterceptor(apiClient, auth.getAccessToken, auth.refreshSession)
+```
+
+Attach it only once per Axios client. If it is attached from a component, retain and call the
+returned cleanup function when that component unmounts.
+
+## Framework-neutral integration
+
+Non-React applications can use the core client:
+
+```js
+import { createPofsisAuth } from '@pofsis-nbt/pofsis-auth/core'
+
+const auth = createPofsisAuth({
+  applicationId: runtimeConfig.applicationId,
+  apiBaseUrl: runtimeConfig.apiBaseUrl,
+  authUrl: runtimeConfig.authUrl,
+  scope: 'openid profile email',
+  callbackPath: '/auth/callback',
+})
+```
+
+## Consumer validation
+
+Run the tool's standard checks:
+
+```powershell
+npm install
+npm run test
+npm run lint
+npm run format:check
+npm run build
+```
+
+Run browser or E2E tests when available. Confirm that:
+
+- Client discovery uses the configured application UUID and current browser origin.
+- The generated authorization URL contains `client_id`, `state`, and PKCE fields.
+- The authorization URL does not contain `app`, an application name/code, or `application_id`.
+- The tool's existing authentication entry behavior remains correct for its product flow.
+- `/auth/callback` returns to the requested safe local route.
+- Refresh, logout, profile editing, and protected API calls still work.
+- Invalid UUIDs and origins show an application error and do not start authentication.
+
+## Per-environment integration checklist
+
+- [ ] Confirm the environment-specific application UUID with the Auth owner.
+- [ ] Replace the old package and all imports.
+- [ ] Remove the vendored package and Vite exclusion.
+- [ ] Replace `VITE_POFSIS_APP_NAME` with `VITE_POFSIS_APPLICATION_ID`.
+- [ ] Pass explicit provider configuration.
+- [ ] Update protected routes that used legacy `mode` or `returnTo` props.
+- [ ] Import the package stylesheet once.
+- [ ] Run unit, lint, formatting, build, and E2E checks.
+- [ ] Smoke-test login, signup, callback, refresh, logout, and protected API calls.
+- [ ] Repeat separately for development, staging, and production.

package/docs/popup-integration.md

@@ -1,162 +1,188 @@
-# POFSIS Auth popup integration
-
-`@pofsis-nbt/pofsis-auth` opens the hosted POFSIS Auth UI in a popup and completes OAuth 2.0 Authorization Code with PKCE in the calling tool. Passwords, OTPs, passkeys, refresh tokens, and Cognito credentials remain owned by POFSIS Auth.
-
-## Prerequisites
-
-- Register the tool's exact origin, callback URI, and logout URI with POFSIS Auth for each environment.
-- Use HTTPS outside local development and allow the tool origin in Auth CORS configuration.
-- Obtain the immutable registered application UUID and allowed public scopes.
-- Never put an OAuth client secret or organization service credential in a browser application.
-
-## Package entry points
-
-```bash
-npm install @pofsis-nbt/pofsis-auth
-```
-
-| Import                             | Use                                             |
-| ---------------------------------- | ----------------------------------------------- |
-| `@pofsis-nbt/pofsis-auth/core`     | Framework-neutral browser SDK                   |
-| `@pofsis-nbt/pofsis-auth/react`    | React provider, hooks, guards, and API helper   |
-| `@pofsis-nbt/pofsis-auth/elements` | Optional `<pofsis-sign-in>` Web Component       |
-| `@pofsis-nbt/pofsis-auth`          | Backward-compatible React API plus core exports |
-
-## Framework-neutral setup
-
-```js
-import { createPofsisAuth, relayPopupCallback } from '@pofsis-nbt/pofsis-auth/core'
-
-const auth = createPofsisAuth({
-    applicationId: '11111111-1111-4111-8111-111111111111',
-    apiBaseUrl: 'https://auth-api.example.com',
-    authUrl: 'https://auth.example.com/authorize',
-})
-
-// Run this before rendering the normal app on /auth/callback.
-if (location.pathname === '/auth/callback') {
-    const relayed = relayPopupCallback()
-    if (!relayed) {
-        const params = new URLSearchParams(location.search)
-        await auth.completeRedirectCallback(params.get('code'), params.get('state'))
-    }
-}
-```
-
-Call popup authentication directly from a click or other user gesture:
-
-```js
-document.querySelector('#login').addEventListener('click', async () => {
-    const result = await auth.login({
-        presentation: 'popup',
-        screen: 'login',
-        returnUrl: location.pathname + location.search,
-    })
-    if (result.status === 'authenticated') renderUser(result.user)
-})
-```
-
-The SDK calls `window.open()` itself. A blocked popup falls back to a full-page redirect. Route guards should explicitly use `presentation: 'redirect'` because they may not run during a user gesture.
-
-## Initialization parameters
-
-| Parameter         | Required | Default                | Meaning                            |
-| ----------------- | -------: | ---------------------- | ---------------------------------- |
-| `applicationId`         |      yes | -                      | Immutable `applications.id` UUID |
-| `apiBaseUrl`      |      yes | -                      | Public POFSIS Auth API base URL    |
-| `authUrl`         |      yes | -                      | Hosted Auth `/authorize` URL       |
-| `scope`           |       no | `openid profile email` | Registered OAuth scopes            |
-| `callbackPath`    |       no | `/auth/callback`       | Local tool callback route          |
-| `popup.width`     |       no | `480`                  | Popup width in pixels              |
-| `popup.height`    |       no | `720`                  | Popup height in pixels             |
-| `popup.name`      |       no | `pofsis-auth`          | Reused browser window name         |
-| `popup.timeoutMs` |       no | `300000`               | Authentication timeout             |
-
-## Launch parameters
-
-| Parameter      | Required | Default      | Meaning                                              |
-| -------------- | -------: | ------------ | ---------------------------------------------------- |
-| `presentation` |       no | `popup`      | `popup` or full-page `redirect`                      |
-| `screen`       |       no | `login`      | `login`, `signup`, or `reset`                        |
-| `method`       |       no | Auth default | `password`, `passkey`, or `otp`                      |
-| `loginHint`    |       no | -            | Editable email or Philippine mobile hint             |
-| `returnUrl`    |       no | -            | Safe application-relative route restored after login |
-
-`returnUrl` must start with one `/` and must not start with `//`. Do not put invitation secrets or external URLs in it.
-
-Convenience methods use the same protocol:
-
-```js
-await auth.signup({ loginHint: 'employee@example.com', method: 'otp' })
-await auth.resetPassword({ loginHint: 'employee@example.com' })
-await auth.login({ method: 'password' })
-await auth.login({ method: 'passkey' })
-```
-
-## React
-
-```tsx
-import { PofsisAuth, useAuth } from '@pofsis-nbt/pofsis-auth/react'
-import '@pofsis-nbt/pofsis-auth/style.css'
-
-function SignInButton() {
-    const { login } = useAuth()
-    return <button onClick={() => void login({ presentation: 'popup' })}>Sign in</button>
-}
-
-export function App() {
-    return (
-        <PofsisAuth
-            applicationId="11111111-1111-4111-8111-111111111111"
-            apiBaseUrl="https://auth-api.example.com"
-            authUrl="https://auth.example.com/authorize"
-        >
-            <SignInButton />
-        </PofsisAuth>
-    )
-}
-```
-
-`RequireAuth` deliberately uses redirect presentation. The provider handles popup and full-page callbacks at `callbackPath`.
-
-## Web Component
-
-Import the package entry or host the generated standalone `dist/pofsis-auth-elements.js` bundle:
-
-```html
-<script type="module" src="https://auth.pofsis.com/sdk/pofsis-auth-elements.js"></script>
-
-<pofsis-sign-in
-    application-id="11111111-1111-4111-8111-111111111111"
-    api-base-url="https://auth-api.example.com"
-    auth-url="https://auth.example.com/authorize"
-    return-url="/dashboard"
-    >Sign in</pofsis-sign-in
->
-```
-
-The element dispatches `pofsis-auth-authenticated`, `pofsis-auth-cancelled`, `pofsis-auth-redirecting`, and `pofsis-auth-error`. It is only a launch control; credential fields always render on the hosted Auth origin.
-
-## Session and API calls
-
-```js
-const unsubscribe = auth.subscribe((session) => updateHeader(session?.user))
-const token = auth.getAccessToken()
-await auth.refreshSession()
-await auth.logout()
-unsubscribe()
-```
-
-Access tokens are held in memory. Use `getAccessToken()` to add a bearer token to the tool's own API calls. Do not write access tokens to URLs or browser storage.
-
-## Results and failures
-
-- `authenticated`: code exchange succeeded and includes the user.
-- `cancelled`: the user closed the popup; this is not an authentication error.
-- `redirecting`: the SDK started full-page navigation, including popup-blocked fallback.
-- Invalid state, origin, popup source, or correlation messages are ignored or rejected.
-- A timeout rejects the launch and closes the popup.
-
-For callback URI mismatches, verify the exact deployed origin and registered URI. For CORS or silent-session failures, verify Auth's origin registry and credentialed cookie configuration. A cancelled or unavailable passkey remains an Auth-screen concern and must retain the password fallback.
-
-The frontend SDK must never call `/api/internal`, Cognito administration APIs, or organization provisioning APIs. Those flows remain tool-backend to Auth-backend operations.
+# POFSIS Auth popup and modal integration
+
+`@pofsis-nbt/pofsis-auth` opens the hosted POFSIS Auth UI in a popup, an SDK-owned iframe modal, or a full-page redirect and completes OAuth 2.0 Authorization Code with PKCE in the calling tool. Passwords, OTPs, passkeys, refresh tokens, and Cognito credentials remain owned by POFSIS Auth.
+
+## Prerequisites
+
+- Register the tool's exact origin, callback URI, and logout URI with POFSIS Auth for each environment.
+- Use HTTPS outside local development and allow the tool origin in Auth CORS configuration.
+- Obtain the immutable registered application UUID and allowed public scopes.
+- Never put an OAuth client secret or organization service credential in a browser application.
+
+## Package entry points
+
+```bash
+npm install @pofsis-nbt/pofsis-auth
+```
+
+| Import                             | Use                                             |
+| ---------------------------------- | ----------------------------------------------- |
+| `@pofsis-nbt/pofsis-auth/core`     | Framework-neutral browser SDK                   |
+| `@pofsis-nbt/pofsis-auth/react`    | React provider, hooks, guards, and API helper   |
+| `@pofsis-nbt/pofsis-auth/elements` | Optional `<pofsis-sign-in>` Web Component       |
+| `@pofsis-nbt/pofsis-auth`          | Backward-compatible React API plus core exports |
+
+## Framework-neutral setup
+
+```js
+import { createPofsisAuth, relayAuthCallback } from '@pofsis-nbt/pofsis-auth/core'
+
+const auth = createPofsisAuth({
+    applicationId: '11111111-1111-4111-8111-111111111111',
+    apiBaseUrl: 'https://auth-api.example.com',
+    authUrl: 'https://auth.example.com/authorize',
+})
+
+// Run this before rendering the normal app on /auth/callback.
+if (location.pathname === '/auth/callback') {
+    const relayed = relayAuthCallback()
+    if (!relayed) {
+        const params = new URLSearchParams(location.search)
+        await auth.completeRedirectCallback(params.get('code'), params.get('state'))
+    }
+}
+```
+
+Call popup authentication directly from a click or other user gesture:
+
+```js
+document.querySelector('#login').addEventListener('click', async () => {
+    const result = await auth.login({
+        presentation: 'popup',
+        screen: 'login',
+        returnUrl: location.pathname + location.search,
+    })
+    if (result.status === 'authenticated') renderUser(result.user)
+})
+```
+
+The SDK calls `window.open()` itself. A blocked popup falls back to a full-page redirect. Route guards should explicitly use `presentation: 'redirect'` because they may not run during a user gesture.
+
+To keep Auth visually inside the tool, request the modal presentation:
+
+```js
+const result = await auth.login({
+    presentation: 'modal',
+    screen: 'login',
+    returnUrl: location.pathname + location.search,
+})
+```
+
+The SDK creates an accessible modal and embeds the hosted Auth origin in an iframe. The tool cannot inspect credential fields. Close, Escape, and backdrop dismissal resolve with `status: 'cancelled'`. A modal does not silently fall back to popup or redirect if embedding fails.
+
+## Initialization parameters
+
+| Parameter              | Required | Default                | Meaning                          |
+| ---------------------- | -------: | ---------------------- | -------------------------------- |
+| `applicationId`        |      yes | -                      | Immutable `applications.id` UUID |
+| `apiBaseUrl`           |      yes | -                      | Public POFSIS Auth API base URL  |
+| `authUrl`              |      yes | -                      | Hosted Auth `/authorize` URL     |
+| `scope`                |       no | `openid profile email` | Registered OAuth scopes          |
+| `callbackPath`         |       no | `/auth/callback`       | Local tool callback route        |
+| `popup.width`          |       no | `480`                  | Popup width in pixels            |
+| `popup.height`         |       no | `720`                  | Popup height in pixels           |
+| `popup.name`           |       no | `pofsis-auth`          | Reused browser window name       |
+| `popup.timeoutMs`      |       no | `300000`               | Authentication timeout           |
+| `modal.width`          |       no | `480`                  | Modal width in pixels            |
+| `modal.height`         |       no | `720`                  | Modal height in pixels           |
+| `modal.timeoutMs`      |       no | `300000`               | Authentication timeout           |
+| `modal.readyTimeoutMs` |       no | `15000`                | Secure iframe handshake timeout  |
+
+## Launch parameters
+
+| Parameter      | Required | Default      | Meaning                                              |
+| -------------- | -------: | ------------ | ---------------------------------------------------- |
+| `presentation` |       no | `popup`      | `popup`, iframe `modal`, or full-page `redirect`     |
+| `screen`       |       no | `login`      | `login`, `signup`, or `reset`                        |
+| `method`       |       no | Auth default | `password`, `passkey`, or `otp`                      |
+| `loginHint`    |       no | -            | Editable email or Philippine mobile hint             |
+| `returnUrl`    |       no | -            | Safe application-relative route restored after login |
+
+`returnUrl` must start with one `/` and must not start with `//`. Do not put invitation secrets or external URLs in it.
+
+Convenience methods use the same protocol:
+
+```js
+await auth.signup({ loginHint: 'employee@example.com', method: 'otp' })
+await auth.resetPassword({ loginHint: 'employee@example.com' })
+await auth.login({ method: 'password' })
+await auth.login({ method: 'passkey' })
+```
+
+## React
+
+```tsx
+import { PofsisAuth, useAuth } from '@pofsis-nbt/pofsis-auth/react'
+import '@pofsis-nbt/pofsis-auth/style.css'
+
+function SignInButton() {
+    const { login } = useAuth()
+    return <button onClick={() => void login({ presentation: 'modal' })}>Sign in</button>
+}
+
+export function App() {
+    return (
+        <PofsisAuth
+            applicationId="11111111-1111-4111-8111-111111111111"
+            apiBaseUrl="https://auth-api.example.com"
+            authUrl="https://auth.example.com/authorize"
+            modal={{ width: 480, height: 720 }}
+        >
+            <SignInButton />
+        </PofsisAuth>
+    )
+}
+```
+
+`RequireAuth` deliberately uses redirect presentation. The provider handles popup, modal, and full-page callbacks at `callbackPath`.
+
+## Web Component
+
+Import the package entry or host the generated standalone `dist/pofsis-auth-elements.js` bundle:
+
+```html
+<script type="module" src="https://auth.pofsis.com/sdk/pofsis-auth-elements.js"></script>
+
+<pofsis-sign-in
+    application-id="11111111-1111-4111-8111-111111111111"
+    api-base-url="https://auth-api.example.com"
+    auth-url="https://auth.example.com/authorize"
+    return-url="/dashboard"
+    presentation="modal"
+    >Sign in</pofsis-sign-in
+>
+```
+
+The element dispatches `pofsis-auth-authenticated`, `pofsis-auth-cancelled`, `pofsis-auth-redirecting`, and `pofsis-auth-error`. It is only a launch control; credential fields always render on the hosted Auth origin.
+
+## Iframe security and hosting
+
+- The Auth frontend verifies a parent-frame handshake against the registered OAuth client before rendering credentials.
+- The callback accepts messages only from the exact iframe window, expected origin, state, and correlation ID.
+- The iframe is sandboxed and receives only the capabilities needed for forms, scripts, external legal links, and WebAuthn.
+- Auth HTML must not send `X-Frame-Options: DENY` or `SAMEORIGIN`. A CSP `frame-ancestors` directive must include every registered tool origin.
+- Third-party-cookie or WebAuthn restrictions vary by browser. Keep popup or redirect available as an explicit consumer fallback when required by browser policy.
+
+## Session and API calls
+
+```js
+const unsubscribe = auth.subscribe((session) => updateHeader(session?.user))
+const token = auth.getAccessToken()
+await auth.refreshSession()
+await auth.logout()
+unsubscribe()
+```
+
+Access tokens are held in memory. Use `getAccessToken()` to add a bearer token to the tool's own API calls. Do not write access tokens to URLs or browser storage.
+
+## Results and failures
+
+- `authenticated`: code exchange succeeded and includes the user.
+- `cancelled`: the user dismissed the popup or modal; this is not an authentication error.
+- `redirecting`: the SDK started full-page navigation, including popup-blocked fallback.
+- Invalid state, origin, popup or iframe source, or correlation messages are ignored or rejected.
+- A timeout rejects the launch and closes the popup or modal. Failure to validate the iframe parent rejects with an embedding error.
+
+For callback URI mismatches, verify the exact deployed origin and registered URI. For CORS or silent-session failures, verify Auth's origin registry and credentialed cookie configuration. A cancelled or unavailable passkey remains an Auth-screen concern and must retain the password fallback.
+
+The frontend SDK must never call `/api/internal`, Cognito administration APIs, or organization provisioning APIs. Those flows remain tool-backend to Auth-backend operations.