@pofsis-nbt/pofsis-auth 1.0.2 → 1.0.3
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/Documentation.md +141 -141
- package/README.md +119 -119
- package/dist/index.cjs +1 -1
- package/dist/index.cjs.map +1 -1
- package/dist/index.js +1 -1
- package/dist/index.js.map +1 -1
- package/package.json +62 -62
package/Documentation.md
CHANGED
|
@@ -1,141 +1,141 @@
|
|
|
1
|
-
# POFSIS Auth Documentation
|
|
2
|
-
|
|
3
|
-
This is the complete public API and integration reference for `@pofsis-nbt/pofsis-auth@1.0.1`.
|
|
4
|
-
|
|
5
|
-
The repository also includes an interactive [POFSIS Auth documentation portal](./index.html) with required environment configuration, generated setup examples, and authentication scenario links. The portal does not persist or transmit entered values and is intentionally excluded from the npm package.
|
|
6
|
-
|
|
7
|
-
## Integration process
|
|
8
|
-
|
|
9
|
-
1. Install `@pofsis-nbt/pofsis-auth` with its React, React DOM, and optional Axios peers.
|
|
10
|
-
2. Import `@pofsis-nbt/pofsis-auth/style.css` once.
|
|
11
|
-
3. Wrap the application in `PofsisAuth` and supply runtime configuration.
|
|
12
|
-
4. Protect authenticated content with `RequireAuth` or use `useAuth` directly.
|
|
13
|
-
5. Register `/auth/callback` and the application origin with the POFSIS Auth service.
|
|
14
|
-
|
|
15
|
-
The consuming application owns environment lookup. The library never reads `import.meta.env`.
|
|
16
|
-
|
|
17
|
-
## Public components
|
|
18
|
-
|
|
19
|
-
### `PofsisAuth`
|
|
20
|
-
|
|
21
|
-
The provider restores the cookie-backed session, manages the in-memory access token, coordinates cross-tab logout, runs OAuth/PKCE, and handles fixed auth paths.
|
|
22
|
-
|
|
23
|
-
`PofsisAuthProps`:
|
|
24
|
-
|
|
25
|
-
| Prop | Type | Required | Meaning |
|
|
26
|
-
| --------------- | ------------------------ | -------- | -------------------------------------- |
|
|
27
|
-
| `children` | `ReactNode` | yes | Application content |
|
|
28
|
-
| `appName` | `string` | yes | Registered POFSIS application identity |
|
|
29
|
-
| `apiBaseUrl` | `string` | yes | Auth API base URL |
|
|
30
|
-
| `authUrl` | `string` | yes | OAuth authorize URL |
|
|
31
|
-
| `scope` | `string` | no | Defaults to `openid profile email` |
|
|
32
|
-
| `postLoginPath` | `string` | no | Callback destination; defaults to `/` |
|
|
33
|
-
| `components` | `AuthComponentOverrides` | no | Custom loading and error screens |
|
|
34
|
-
|
|
35
|
-
```tsx
|
|
36
|
-
<PofsisAuth
|
|
37
|
-
appName="ORBIT"
|
|
38
|
-
apiBaseUrl={runtimeConfig.authApi}
|
|
39
|
-
authUrl={runtimeConfig.authorizeUrl}
|
|
40
|
-
components={{ LoadingScreen: AppLoader, ErrorScreen: AppAuthError }}
|
|
41
|
-
>
|
|
42
|
-
<App />
|
|
43
|
-
</PofsisAuth>
|
|
44
|
-
```
|
|
45
|
-
|
|
46
|
-
### `RequireAuth`
|
|
47
|
-
|
|
48
|
-
`RequireAuth({ children, fallback?, onUnauthenticated? })` renders authenticated content. `fallback` overrides loading UI for that guard. Without `onUnauthenticated`, an unauthenticated visitor starts login; failures route to `/auth/error`.
|
|
49
|
-
|
|
50
|
-
### `AuthLoadingScreen`
|
|
51
|
-
|
|
52
|
-
The default full-screen loader. `AuthLoadingScreenProps.callback` changes the message for login/callback work.
|
|
53
|
-
|
|
54
|
-
### `AuthErrorScreen`
|
|
55
|
-
|
|
56
|
-
The default error page. `AuthErrorScreenProps.retryHref` defaults to `/login`. Its illustration is emitted into the compiled bundle as a data asset.
|
|
57
|
-
|
|
58
|
-
## `useAuth`
|
|
59
|
-
|
|
60
|
-
`useAuth(): AuthContextValue` must be called below `PofsisAuth`.
|
|
61
|
-
|
|
62
|
-
| Value or method | Meaning |
|
|
63
|
-
| --------------------------------------- | ----------------------------------------------------------------------------- |
|
|
64
|
-
| `user` | Current `PofsisUser`, or `null` |
|
|
65
|
-
| `session` | Current `SessionPayload`, or `null` |
|
|
66
|
-
| `isAuthenticated` | Whether a session is present |
|
|
67
|
-
| `isLoading` | Whether initial session restoration is running |
|
|
68
|
-
| `login(options?)` | Starts OAuth/PKCE login |
|
|
69
|
-
| `logout()` | Ends the remote session, clears local state, broadcasts logout, and redirects |
|
|
70
|
-
| `refreshSession()` | Exchanges the refresh cookie for a new access token |
|
|
71
|
-
| `getAccessToken()` | Returns the in-memory token or `null` |
|
|
72
|
-
| `getAccountProfile()` | Fetches and merges the current `AccountProfile` |
|
|
73
|
-
| `updateAccountProfile(profile)` | Updates first and/or last name |
|
|
74
|
-
| `uploadAccountProfileImage(kind, file)` | Uploads a `profile` or `cover` image |
|
|
75
|
-
| `deleteAccountProfileImage(kind)` | Removes a `profile` or `cover` image |
|
|
76
|
-
| `completeCallback(code, state)` | Completes PKCE callback; normally used internally |
|
|
77
|
-
|
|
78
|
-
## Login options and URL hints
|
|
79
|
-
|
|
80
|
-
`login(options)` accepts `AuthLaunchOptions`:
|
|
81
|
-
|
|
82
|
-
- `returnUrl`: accepted only when it starts with `/` and not `//`; unsafe or external values are discarded.
|
|
83
|
-
- `screen`: `login`, `signup`, or `reset`; legacy `register` is normalized to `signup`.
|
|
84
|
-
- `loginHint`: valid email or Philippine mobile number. Emails are trimmed/lowercased; mobile numbers normalize to `+63`; invalid or values over 320 characters are ignored.
|
|
85
|
-
- `method`: `password`, `passkey`, or `otp`. Login accepts all three methods. Signup accepts `password` or `otp`; OTP signup continues to the verification-code page after the identifier is submitted.
|
|
86
|
-
|
|
87
|
-
The `/login` route also reads `screen`, `login_hint`, and `method`. Legacy `email` is accepted only as an email hint and only when canonical `login_hint` is absent. Unknown values are ignored. Signup defaults to password when no method is supplied and preserves an explicit `otp`; reset does not forward a method.
|
|
88
|
-
|
|
89
|
-
Fixed paths are `/login`, `/auth/callback`, and `/auth/error`. Saved callback destinations are restricted to safe local paths.
|
|
90
|
-
|
|
91
|
-
## Axios interceptor
|
|
92
|
-
|
|
93
|
-
`attachAuthInterceptor(client, getToken, refresh)` adds the current bearer token and performs one refresh-and-retry after a 401. It returns a cleanup function that ejects both interceptors. Axios is optional unless this helper is used.
|
|
94
|
-
|
|
95
|
-
## Configuration helper
|
|
96
|
-
|
|
97
|
-
`resolveConfig(overrides: ConfigOverrides)` validates `appName`, `apiBaseUrl`, and `authUrl`, trims values, removes a trailing slash from URLs, and supplies the default scope. Missing required values throw synchronously.
|
|
98
|
-
|
|
99
|
-
## Exported types
|
|
100
|
-
|
|
101
|
-
- `PofsisAuthProps`, `PofsisAuthConfig`, `ConfigOverrides`, `AuthComponentOverrides`
|
|
102
|
-
- `AuthLoadingScreenProps`, `AuthErrorScreenProps`, `RequireAuthProps`
|
|
103
|
-
- `AuthContextValue`, `AuthLaunchOptions`, `AuthScreen`, `AuthMethod`
|
|
104
|
-
- `PofsisUser`, `AccountProfile`, `SessionPayload`, `TokenResponse`
|
|
105
|
-
- `OAuthClientConfig`
|
|
106
|
-
|
|
107
|
-
`SessionPayload` contains `token_type`, `expires_in`, and `user`. `TokenResponse` adds `access_token`. Access tokens remain in memory. `PofsisUser` exposes identity, display/profile media, and optional roles. `AccountProfile` represents the editable account profile and timestamps. `OAuthClientConfig` represents server-resolved client, redirect, and logout details.
|
|
108
|
-
|
|
109
|
-
## Module formats
|
|
110
|
-
|
|
111
|
-
ESM/JavaScript and TypeScript use the same package import:
|
|
112
|
-
|
|
113
|
-
```ts
|
|
114
|
-
import { PofsisAuth, useAuth } from '@pofsis-nbt/pofsis-auth'
|
|
115
|
-
```
|
|
116
|
-
|
|
117
|
-
CommonJS uses:
|
|
118
|
-
|
|
119
|
-
```js
|
|
120
|
-
const { PofsisAuth, useAuth } = require('@pofsis-nbt/pofsis-auth')
|
|
121
|
-
```
|
|
122
|
-
|
|
123
|
-
TypeScript declarations resolve from `dist/index.d.ts`. No separate TypeScript package is needed.
|
|
124
|
-
|
|
125
|
-
## Build and verification process
|
|
126
|
-
|
|
127
|
-
```bash
|
|
128
|
-
npm run format:check
|
|
129
|
-
npm run typecheck
|
|
130
|
-
npm test
|
|
131
|
-
npm run build
|
|
132
|
-
npm run pack:check
|
|
133
|
-
```
|
|
134
|
-
|
|
135
|
-
`dist/` contains ESM and CommonJS JavaScript, source maps, declaration files/maps, component declarations, and `style.css`. The npm package includes only `dist`, `package.json`, `README.md`, and `Documentation.md`.
|
|
136
|
-
|
|
137
|
-
## Public boundary and migration
|
|
138
|
-
|
|
139
|
-
Supported imports are the package root and `@pofsis-nbt/pofsis-auth/style.css`. Files under `auth/`, `components/`, `context/`, `src/`, and `dist/` are implementation details and are not exported.
|
|
140
|
-
|
|
141
|
-
Migrating from `@pofsis/auth-react` requires changing the package name, passing explicit provider configuration, and importing the stylesheet. OAuth paths, PKCE/session behavior, hooks, profile methods, UI overrides, and interceptor behavior remain available.
|
|
1
|
+
# POFSIS Auth Documentation
|
|
2
|
+
|
|
3
|
+
This is the complete public API and integration reference for `@pofsis-nbt/pofsis-auth@1.0.1`.
|
|
4
|
+
|
|
5
|
+
The repository also includes an interactive [POFSIS Auth documentation portal](./index.html) with required environment configuration, generated setup examples, and authentication scenario links. The portal does not persist or transmit entered values and is intentionally excluded from the npm package.
|
|
6
|
+
|
|
7
|
+
## Integration process
|
|
8
|
+
|
|
9
|
+
1. Install `@pofsis-nbt/pofsis-auth` with its React, React DOM, and optional Axios peers.
|
|
10
|
+
2. Import `@pofsis-nbt/pofsis-auth/style.css` once.
|
|
11
|
+
3. Wrap the application in `PofsisAuth` and supply runtime configuration.
|
|
12
|
+
4. Protect authenticated content with `RequireAuth` or use `useAuth` directly.
|
|
13
|
+
5. Register `/auth/callback` and the application origin with the POFSIS Auth service.
|
|
14
|
+
|
|
15
|
+
The consuming application owns environment lookup. The library never reads `import.meta.env`.
|
|
16
|
+
|
|
17
|
+
## Public components
|
|
18
|
+
|
|
19
|
+
### `PofsisAuth`
|
|
20
|
+
|
|
21
|
+
The provider restores the cookie-backed session, manages the in-memory access token, coordinates cross-tab logout, runs OAuth/PKCE, and handles fixed auth paths.
|
|
22
|
+
|
|
23
|
+
`PofsisAuthProps`:
|
|
24
|
+
|
|
25
|
+
| Prop | Type | Required | Meaning |
|
|
26
|
+
| --------------- | ------------------------ | -------- | -------------------------------------- |
|
|
27
|
+
| `children` | `ReactNode` | yes | Application content |
|
|
28
|
+
| `appName` | `string` | yes | Registered POFSIS application identity |
|
|
29
|
+
| `apiBaseUrl` | `string` | yes | Auth API base URL |
|
|
30
|
+
| `authUrl` | `string` | yes | OAuth authorize URL |
|
|
31
|
+
| `scope` | `string` | no | Defaults to `openid profile email` |
|
|
32
|
+
| `postLoginPath` | `string` | no | Callback destination; defaults to `/` |
|
|
33
|
+
| `components` | `AuthComponentOverrides` | no | Custom loading and error screens |
|
|
34
|
+
|
|
35
|
+
```tsx
|
|
36
|
+
<PofsisAuth
|
|
37
|
+
appName="ORBIT"
|
|
38
|
+
apiBaseUrl={runtimeConfig.authApi}
|
|
39
|
+
authUrl={runtimeConfig.authorizeUrl}
|
|
40
|
+
components={{ LoadingScreen: AppLoader, ErrorScreen: AppAuthError }}
|
|
41
|
+
>
|
|
42
|
+
<App />
|
|
43
|
+
</PofsisAuth>
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
### `RequireAuth`
|
|
47
|
+
|
|
48
|
+
`RequireAuth({ children, fallback?, onUnauthenticated? })` renders authenticated content. `fallback` overrides loading UI for that guard. Without `onUnauthenticated`, an unauthenticated visitor starts login; failures route to `/auth/error`.
|
|
49
|
+
|
|
50
|
+
### `AuthLoadingScreen`
|
|
51
|
+
|
|
52
|
+
The default full-screen loader. `AuthLoadingScreenProps.callback` changes the message for login/callback work.
|
|
53
|
+
|
|
54
|
+
### `AuthErrorScreen`
|
|
55
|
+
|
|
56
|
+
The default error page. `AuthErrorScreenProps.retryHref` defaults to `/login`. Its illustration is emitted into the compiled bundle as a data asset.
|
|
57
|
+
|
|
58
|
+
## `useAuth`
|
|
59
|
+
|
|
60
|
+
`useAuth(): AuthContextValue` must be called below `PofsisAuth`.
|
|
61
|
+
|
|
62
|
+
| Value or method | Meaning |
|
|
63
|
+
| --------------------------------------- | ----------------------------------------------------------------------------- |
|
|
64
|
+
| `user` | Current `PofsisUser`, or `null` |
|
|
65
|
+
| `session` | Current `SessionPayload`, or `null` |
|
|
66
|
+
| `isAuthenticated` | Whether a session is present |
|
|
67
|
+
| `isLoading` | Whether initial session restoration is running |
|
|
68
|
+
| `login(options?)` | Starts OAuth/PKCE login |
|
|
69
|
+
| `logout()` | Ends the remote session, clears local state, broadcasts logout, and redirects |
|
|
70
|
+
| `refreshSession()` | Exchanges the refresh cookie for a new access token |
|
|
71
|
+
| `getAccessToken()` | Returns the in-memory token or `null` |
|
|
72
|
+
| `getAccountProfile()` | Fetches and merges the current `AccountProfile` |
|
|
73
|
+
| `updateAccountProfile(profile)` | Updates first and/or last name |
|
|
74
|
+
| `uploadAccountProfileImage(kind, file)` | Uploads a `profile` or `cover` image |
|
|
75
|
+
| `deleteAccountProfileImage(kind)` | Removes a `profile` or `cover` image |
|
|
76
|
+
| `completeCallback(code, state)` | Completes PKCE callback; normally used internally |
|
|
77
|
+
|
|
78
|
+
## Login options and URL hints
|
|
79
|
+
|
|
80
|
+
`login(options)` accepts `AuthLaunchOptions`:
|
|
81
|
+
|
|
82
|
+
- `returnUrl`: accepted only when it starts with `/` and not `//`; unsafe or external values are discarded.
|
|
83
|
+
- `screen`: `login`, `signup`, or `reset`; legacy `register` is normalized to `signup`.
|
|
84
|
+
- `loginHint`: valid email or Philippine mobile number. Emails are trimmed/lowercased; mobile numbers normalize to `+63`; invalid or values over 320 characters are ignored.
|
|
85
|
+
- `method`: `password`, `passkey`, or `otp`. Login accepts all three methods. Signup accepts `password` or `otp`; OTP signup continues to the verification-code page after the identifier is submitted.
|
|
86
|
+
|
|
87
|
+
The `/login` route also reads `screen`, `login_hint`, and `method`. Legacy `email` is accepted only as an email hint and only when canonical `login_hint` is absent. Unknown values are ignored. Signup defaults to password when no method is supplied and preserves an explicit `otp`; reset does not forward a method.
|
|
88
|
+
|
|
89
|
+
Fixed paths are `/login`, `/auth/callback`, and `/auth/error`. Saved callback destinations are restricted to safe local paths.
|
|
90
|
+
|
|
91
|
+
## Axios interceptor
|
|
92
|
+
|
|
93
|
+
`attachAuthInterceptor(client, getToken, refresh)` adds the current bearer token and performs one refresh-and-retry after a 401. It returns a cleanup function that ejects both interceptors. Axios is optional unless this helper is used.
|
|
94
|
+
|
|
95
|
+
## Configuration helper
|
|
96
|
+
|
|
97
|
+
`resolveConfig(overrides: ConfigOverrides)` validates `appName`, `apiBaseUrl`, and `authUrl`, trims values, removes a trailing slash from URLs, and supplies the default scope. Missing required values throw synchronously.
|
|
98
|
+
|
|
99
|
+
## Exported types
|
|
100
|
+
|
|
101
|
+
- `PofsisAuthProps`, `PofsisAuthConfig`, `ConfigOverrides`, `AuthComponentOverrides`
|
|
102
|
+
- `AuthLoadingScreenProps`, `AuthErrorScreenProps`, `RequireAuthProps`
|
|
103
|
+
- `AuthContextValue`, `AuthLaunchOptions`, `AuthScreen`, `AuthMethod`
|
|
104
|
+
- `PofsisUser`, `AccountProfile`, `SessionPayload`, `TokenResponse`
|
|
105
|
+
- `OAuthClientConfig`
|
|
106
|
+
|
|
107
|
+
`SessionPayload` contains `token_type`, `expires_in`, and `user`. `TokenResponse` adds `access_token`. Access tokens remain in memory. `PofsisUser` exposes identity, display/profile media, and optional roles. `AccountProfile` represents the editable account profile and timestamps. `OAuthClientConfig` represents server-resolved client, redirect, and logout details.
|
|
108
|
+
|
|
109
|
+
## Module formats
|
|
110
|
+
|
|
111
|
+
ESM/JavaScript and TypeScript use the same package import:
|
|
112
|
+
|
|
113
|
+
```ts
|
|
114
|
+
import { PofsisAuth, useAuth } from '@pofsis-nbt/pofsis-auth'
|
|
115
|
+
```
|
|
116
|
+
|
|
117
|
+
CommonJS uses:
|
|
118
|
+
|
|
119
|
+
```js
|
|
120
|
+
const { PofsisAuth, useAuth } = require('@pofsis-nbt/pofsis-auth')
|
|
121
|
+
```
|
|
122
|
+
|
|
123
|
+
TypeScript declarations resolve from `dist/index.d.ts`. No separate TypeScript package is needed.
|
|
124
|
+
|
|
125
|
+
## Build and verification process
|
|
126
|
+
|
|
127
|
+
```bash
|
|
128
|
+
npm run format:check
|
|
129
|
+
npm run typecheck
|
|
130
|
+
npm test
|
|
131
|
+
npm run build
|
|
132
|
+
npm run pack:check
|
|
133
|
+
```
|
|
134
|
+
|
|
135
|
+
`dist/` contains ESM and CommonJS JavaScript, source maps, declaration files/maps, component declarations, and `style.css`. The npm package includes only `dist`, `package.json`, `README.md`, and `Documentation.md`.
|
|
136
|
+
|
|
137
|
+
## Public boundary and migration
|
|
138
|
+
|
|
139
|
+
Supported imports are the package root and `@pofsis-nbt/pofsis-auth/style.css`. Files under `auth/`, `components/`, `context/`, `src/`, and `dist/` are implementation details and are not exported.
|
|
140
|
+
|
|
141
|
+
Migrating from `@pofsis/auth-react` requires changing the package name, passing explicit provider configuration, and importing the stylesheet. OAuth paths, PKCE/session behavior, hooks, profile methods, UI overrides, and interceptor behavior remain available.
|
package/README.md
CHANGED
|
@@ -1,119 +1,119 @@
|
|
|
1
|
-
# @pofsis-nbt/pofsis-auth
|
|
2
|
-
|
|
3
|
-
React OAuth 2.0/PKCE authentication for POFSIS applications. One package serves JavaScript and TypeScript consumers through ESM, CommonJS, generated declarations, and extracted CSS.
|
|
4
|
-
|
|
5
|
-
For guided setup and authentication scenarios, open the repository's interactive [POFSIS Auth documentation portal](./index.html). It validates consumer-supplied environment values and generates safe `/login` launch links without storing them.
|
|
6
|
-
|
|
7
|
-
## Install
|
|
8
|
-
|
|
9
|
-
```bash
|
|
10
|
-
npm install @pofsis-nbt/pofsis-auth axios react react-dom
|
|
11
|
-
```
|
|
12
|
-
|
|
13
|
-
Import the package stylesheet once in the application entry point:
|
|
14
|
-
|
|
15
|
-
```ts
|
|
16
|
-
import '@pofsis-nbt/pofsis-auth/style.css'
|
|
17
|
-
```
|
|
18
|
-
|
|
19
|
-
## Quick start
|
|
20
|
-
|
|
21
|
-
```tsx
|
|
22
|
-
import { PofsisAuth, RequireAuth } from '@pofsis-nbt/pofsis-auth'
|
|
23
|
-
import '@pofsis-nbt/pofsis-auth/style.css'
|
|
24
|
-
|
|
25
|
-
export function App() {
|
|
26
|
-
return (
|
|
27
|
-
<PofsisAuth
|
|
28
|
-
appName="ORBIT"
|
|
29
|
-
apiBaseUrl="https://auth-api.example.com"
|
|
30
|
-
authUrl="https://auth.example.com/authorize"
|
|
31
|
-
>
|
|
32
|
-
<RequireAuth>
|
|
33
|
-
<Dashboard />
|
|
34
|
-
</RequireAuth>
|
|
35
|
-
</PofsisAuth>
|
|
36
|
-
)
|
|
37
|
-
}
|
|
38
|
-
```
|
|
39
|
-
|
|
40
|
-
`appName`, `apiBaseUrl`, and `authUrl` are required. The library does not read environment variables. A Vite application may pass its own values:
|
|
41
|
-
|
|
42
|
-
```tsx
|
|
43
|
-
<PofsisAuth
|
|
44
|
-
appName={import.meta.env.VITE_POFSIS_APP_NAME}
|
|
45
|
-
apiBaseUrl={import.meta.env.VITE_POFSIS_API_BASE_URL}
|
|
46
|
-
authUrl={import.meta.env.VITE_POFSIS_AUTH_URL}
|
|
47
|
-
scope={import.meta.env.VITE_POFSIS_SCOPE}
|
|
48
|
-
>
|
|
49
|
-
<App />
|
|
50
|
-
</PofsisAuth>
|
|
51
|
-
```
|
|
52
|
-
|
|
53
|
-
The same props may come from server-injected runtime configuration or hardcoded deployment configuration. The default scope is `openid profile email`.
|
|
54
|
-
|
|
55
|
-
## Session and login
|
|
56
|
-
|
|
57
|
-
```tsx
|
|
58
|
-
import { useAuth } from '@pofsis-nbt/pofsis-auth'
|
|
59
|
-
|
|
60
|
-
function AccountMenu() {
|
|
61
|
-
const { user, login, logout } = useAuth()
|
|
62
|
-
if (!user) return <button onClick={() => void login()}>Sign in</button>
|
|
63
|
-
return <button onClick={() => void logout()}>Sign out {user.displayName}</button>
|
|
64
|
-
}
|
|
65
|
-
```
|
|
66
|
-
|
|
67
|
-
The provider handles `/login`, `/auth/callback`, and `/auth/error`. Login supports `screen`, `loginHint`, `method`, and a safe application-relative `returnUrl`. An OTP signup opens the signup page and continues to account verification after the identifier is submitted. See [Documentation.md](./Documentation.md) for the complete API.
|
|
68
|
-
|
|
69
|
-
## Axios
|
|
70
|
-
|
|
71
|
-
```ts
|
|
72
|
-
import axios from 'axios'
|
|
73
|
-
import { attachAuthInterceptor, useAuth } from '@pofsis-nbt/pofsis-auth'
|
|
74
|
-
|
|
75
|
-
const api = axios.create({ baseURL: '/api' })
|
|
76
|
-
|
|
77
|
-
function ApiAuthBridge() {
|
|
78
|
-
const { getAccessToken, refreshSession } = useAuth()
|
|
79
|
-
React.useEffect(
|
|
80
|
-
() => attachAuthInterceptor(api, getAccessToken, refreshSession),
|
|
81
|
-
[getAccessToken, refreshSession],
|
|
82
|
-
)
|
|
83
|
-
return null
|
|
84
|
-
}
|
|
85
|
-
```
|
|
86
|
-
|
|
87
|
-
## CommonJS
|
|
88
|
-
|
|
89
|
-
```js
|
|
90
|
-
const { PofsisAuth, RequireAuth, useAuth } = require('@pofsis-nbt/pofsis-auth')
|
|
91
|
-
require('@pofsis-nbt/pofsis-auth/style.css')
|
|
92
|
-
```
|
|
93
|
-
|
|
94
|
-
JavaScript consumers use the compiled JavaScript. TypeScript consumers use the same imports and automatically receive declarations.
|
|
95
|
-
|
|
96
|
-
## Development
|
|
97
|
-
|
|
98
|
-
Requires Node `^20.19.0` or `>=22.12.0`.
|
|
99
|
-
|
|
100
|
-
```bash
|
|
101
|
-
npm install
|
|
102
|
-
npm run format:check
|
|
103
|
-
npm run typecheck
|
|
104
|
-
npm test
|
|
105
|
-
npm run build
|
|
106
|
-
npm run pack:check
|
|
107
|
-
```
|
|
108
|
-
|
|
109
|
-
Build output is written to `dist/` with ESM (`index.js`), CommonJS (`index.cjs`), source maps, declarations, and `style.css`.
|
|
110
|
-
|
|
111
|
-
## Migration
|
|
112
|
-
|
|
113
|
-
When migrating from `@pofsis/auth-react`:
|
|
114
|
-
|
|
115
|
-
1. Change imports to `@pofsis-nbt/pofsis-auth`.
|
|
116
|
-
2. Pass `appName`, `apiBaseUrl`, and `authUrl` to `PofsisAuth`.
|
|
117
|
-
3. Import `@pofsis-nbt/pofsis-auth/style.css` once.
|
|
118
|
-
|
|
119
|
-
Do not import `src/`, `dist/` internals, or internal auth helpers. Only the package-root exports and `style.css` are supported.
|
|
1
|
+
# @pofsis-nbt/pofsis-auth
|
|
2
|
+
|
|
3
|
+
React OAuth 2.0/PKCE authentication for POFSIS applications. One package serves JavaScript and TypeScript consumers through ESM, CommonJS, generated declarations, and extracted CSS.
|
|
4
|
+
|
|
5
|
+
For guided setup and authentication scenarios, open the repository's interactive [POFSIS Auth documentation portal](./index.html). It validates consumer-supplied environment values and generates safe `/login` launch links without storing them.
|
|
6
|
+
|
|
7
|
+
## Install
|
|
8
|
+
|
|
9
|
+
```bash
|
|
10
|
+
npm install @pofsis-nbt/pofsis-auth axios react react-dom
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
Import the package stylesheet once in the application entry point:
|
|
14
|
+
|
|
15
|
+
```ts
|
|
16
|
+
import '@pofsis-nbt/pofsis-auth/style.css'
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
## Quick start
|
|
20
|
+
|
|
21
|
+
```tsx
|
|
22
|
+
import { PofsisAuth, RequireAuth } from '@pofsis-nbt/pofsis-auth'
|
|
23
|
+
import '@pofsis-nbt/pofsis-auth/style.css'
|
|
24
|
+
|
|
25
|
+
export function App() {
|
|
26
|
+
return (
|
|
27
|
+
<PofsisAuth
|
|
28
|
+
appName="ORBIT"
|
|
29
|
+
apiBaseUrl="https://auth-api.example.com"
|
|
30
|
+
authUrl="https://auth.example.com/authorize"
|
|
31
|
+
>
|
|
32
|
+
<RequireAuth>
|
|
33
|
+
<Dashboard />
|
|
34
|
+
</RequireAuth>
|
|
35
|
+
</PofsisAuth>
|
|
36
|
+
)
|
|
37
|
+
}
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
`appName`, `apiBaseUrl`, and `authUrl` are required. The library does not read environment variables. A Vite application may pass its own values:
|
|
41
|
+
|
|
42
|
+
```tsx
|
|
43
|
+
<PofsisAuth
|
|
44
|
+
appName={import.meta.env.VITE_POFSIS_APP_NAME}
|
|
45
|
+
apiBaseUrl={import.meta.env.VITE_POFSIS_API_BASE_URL}
|
|
46
|
+
authUrl={import.meta.env.VITE_POFSIS_AUTH_URL}
|
|
47
|
+
scope={import.meta.env.VITE_POFSIS_SCOPE}
|
|
48
|
+
>
|
|
49
|
+
<App />
|
|
50
|
+
</PofsisAuth>
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
The same props may come from server-injected runtime configuration or hardcoded deployment configuration. The default scope is `openid profile email`.
|
|
54
|
+
|
|
55
|
+
## Session and login
|
|
56
|
+
|
|
57
|
+
```tsx
|
|
58
|
+
import { useAuth } from '@pofsis-nbt/pofsis-auth'
|
|
59
|
+
|
|
60
|
+
function AccountMenu() {
|
|
61
|
+
const { user, login, logout } = useAuth()
|
|
62
|
+
if (!user) return <button onClick={() => void login()}>Sign in</button>
|
|
63
|
+
return <button onClick={() => void logout()}>Sign out {user.displayName}</button>
|
|
64
|
+
}
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
The provider handles `/login`, `/auth/callback`, and `/auth/error`. Login supports `screen`, `loginHint`, `method`, and a safe application-relative `returnUrl`. An OTP signup opens the signup page and continues to account verification after the identifier is submitted. See [Documentation.md](./Documentation.md) for the complete API.
|
|
68
|
+
|
|
69
|
+
## Axios
|
|
70
|
+
|
|
71
|
+
```ts
|
|
72
|
+
import axios from 'axios'
|
|
73
|
+
import { attachAuthInterceptor, useAuth } from '@pofsis-nbt/pofsis-auth'
|
|
74
|
+
|
|
75
|
+
const api = axios.create({ baseURL: '/api' })
|
|
76
|
+
|
|
77
|
+
function ApiAuthBridge() {
|
|
78
|
+
const { getAccessToken, refreshSession } = useAuth()
|
|
79
|
+
React.useEffect(
|
|
80
|
+
() => attachAuthInterceptor(api, getAccessToken, refreshSession),
|
|
81
|
+
[getAccessToken, refreshSession],
|
|
82
|
+
)
|
|
83
|
+
return null
|
|
84
|
+
}
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
## CommonJS
|
|
88
|
+
|
|
89
|
+
```js
|
|
90
|
+
const { PofsisAuth, RequireAuth, useAuth } = require('@pofsis-nbt/pofsis-auth')
|
|
91
|
+
require('@pofsis-nbt/pofsis-auth/style.css')
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
JavaScript consumers use the compiled JavaScript. TypeScript consumers use the same imports and automatically receive declarations.
|
|
95
|
+
|
|
96
|
+
## Development
|
|
97
|
+
|
|
98
|
+
Requires Node `^20.19.0` or `>=22.12.0`.
|
|
99
|
+
|
|
100
|
+
```bash
|
|
101
|
+
npm install
|
|
102
|
+
npm run format:check
|
|
103
|
+
npm run typecheck
|
|
104
|
+
npm test
|
|
105
|
+
npm run build
|
|
106
|
+
npm run pack:check
|
|
107
|
+
```
|
|
108
|
+
|
|
109
|
+
Build output is written to `dist/` with ESM (`index.js`), CommonJS (`index.cjs`), source maps, declarations, and `style.css`.
|
|
110
|
+
|
|
111
|
+
## Migration
|
|
112
|
+
|
|
113
|
+
When migrating from `@pofsis/auth-react`:
|
|
114
|
+
|
|
115
|
+
1. Change imports to `@pofsis-nbt/pofsis-auth`.
|
|
116
|
+
2. Pass `appName`, `apiBaseUrl`, and `authUrl` to `PofsisAuth`.
|
|
117
|
+
3. Import `@pofsis-nbt/pofsis-auth/style.css` once.
|
|
118
|
+
|
|
119
|
+
Do not import `src/`, `dist/` internals, or internal auth helpers. Only the package-root exports and `style.css` are supported.
|