@pofsis-nbt/pofsis-auth 2.0.0 → 2.0.1

package/Documentation.md

@@ -6,6 +6,10 @@ The repository also includes an interactive [POFSIS Auth documentation portal](.
 
 The [popup integration guide](./docs/popup-integration.md) is the canonical consumer reference for framework-neutral, React, and Web Component popup launches.
 
+Use the [application-ID consumer migration guide](./docs/application-id-consumer-migration.md) to
+upgrade existing tools from application names/codes and the vendored React package to v2 UUID
+discovery, including environment configuration, protected-route changes, and consumer testing.
+
 ## Integration process
 
 1. Install `@pofsis-nbt/pofsis-auth` with its React, React DOM, and optional Axios peers.

package/README.md

@@ -6,6 +6,9 @@ For guided setup and authentication scenarios, open the repository's interactive
 
 For hosted popup setup, parameters, callback handling, React usage, and the optional Web Component, see the [popup integration guide](./docs/popup-integration.md).
 
+For migrating an existing POFSIS tool from application code/name discovery to immutable application
+UUIDs, follow the [application-ID consumer migration guide](./docs/application-id-consumer-migration.md).
+
 ## Install
 
 ```bash

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/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@pofsis-nbt/pofsis-auth",
-    "version": "2.0.0",
+    "version": "2.0.1",
     "description": "POFSIS OAuth/PKCE authentication SDK for browser applications.",
     "type": "module",
     "main": "./dist/index.cjs",