@ciromaciel/auth-react 1.0.0
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/README.md +169 -0
- package/dist/index.esm.js +3531 -0
- package/dist/index.esm.js.map +1 -0
- package/dist/index.js +3594 -0
- package/dist/index.js.map +1 -0
- package/package.json +88 -0
package/README.md
ADDED
|
@@ -0,0 +1,169 @@
|
|
|
1
|
+
# Auth React
|
|
2
|
+
|
|
3
|
+
<p align="center">
|
|
4
|
+
<a href="https://www.npmjs.com/package/@ciromaciel/auth-react" target="_blank"><img src="https://img.shields.io/npm/v/@ciromaciel/auth-react.svg" alt="npm version" /></a>
|
|
5
|
+
<a href="https://www.npmjs.com/package/@ciromaciel/auth-react" target="_blank"><img src="https://img.shields.io/npm/dm/@ciromaciel/auth-react.svg" alt="npm downloads" /></a>
|
|
6
|
+
<a href="https://www.npmjs.com/package/@ciromaciel/auth-react" target="_blank"><img src="https://img.shields.io/npm/l/@ciromaciel/auth-react.svg" alt="license" /></a>
|
|
7
|
+
</p>
|
|
8
|
+
|
|
9
|
+
Auth SDK for React with JWT and JWKS.
|
|
10
|
+
|
|
11
|
+
## Installation
|
|
12
|
+
|
|
13
|
+
```bash
|
|
14
|
+
bun add @ciromaciel/auth-react
|
|
15
|
+
```
|
|
16
|
+
|
|
17
|
+
## Basic Usage
|
|
18
|
+
|
|
19
|
+
```jsx
|
|
20
|
+
import { AuthProvider, useAuth, useSignIn, Protect, SignedIn, SignedOut, SignIn } from '@ciromaciel/auth-react'
|
|
21
|
+
|
|
22
|
+
// 1. Wrap your app with AuthProvider
|
|
23
|
+
function App() {
|
|
24
|
+
return (
|
|
25
|
+
<AuthProvider apiKey="your-api-key">
|
|
26
|
+
<Routes>
|
|
27
|
+
<Route
|
|
28
|
+
path="/login"
|
|
29
|
+
element={<SignIn />}
|
|
30
|
+
/>
|
|
31
|
+
<Route element={<Protect />}>
|
|
32
|
+
<Route
|
|
33
|
+
path="/"
|
|
34
|
+
element={<Home />}
|
|
35
|
+
/>
|
|
36
|
+
</Route>
|
|
37
|
+
</Routes>
|
|
38
|
+
</AuthProvider>
|
|
39
|
+
)
|
|
40
|
+
}
|
|
41
|
+
|
|
42
|
+
// 2. Use control components for conditional rendering
|
|
43
|
+
function Header() {
|
|
44
|
+
return (
|
|
45
|
+
<header>
|
|
46
|
+
<SignedIn>
|
|
47
|
+
<UserMenu />
|
|
48
|
+
</SignedIn>
|
|
49
|
+
<SignedOut>
|
|
50
|
+
<SignInButton />
|
|
51
|
+
</SignedOut>
|
|
52
|
+
</header>
|
|
53
|
+
)
|
|
54
|
+
}
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
## Components
|
|
58
|
+
|
|
59
|
+
### Authentication Components
|
|
60
|
+
|
|
61
|
+
| Component | Description |
|
|
62
|
+
| --------------------- | --------------------------------------------------------------- |
|
|
63
|
+
| `<SignIn />` | The whole way in: asks for the email, then takes the emailed code |
|
|
64
|
+
| `<UserProfile />` | User profile management modal |
|
|
65
|
+
| `<UserInformation />` | Flexible user details and account menu |
|
|
66
|
+
| `<SocialButtons />` | Sign-in buttons for the providers the application enabled |
|
|
67
|
+
|
|
68
|
+
There is one screen. Sign-up, magic link, password reset and email verification
|
|
69
|
+
were four answers to the same question — does this person control this inbox? —
|
|
70
|
+
and three of them answered it with a URL. The code answers it with none, and the
|
|
71
|
+
account is created, and verified, the first time one is presented.
|
|
72
|
+
|
|
73
|
+
Social sign-in is the one path that does leave for a URL, because it has to: the
|
|
74
|
+
person goes to the provider's consent screen and comes back. `<SignIn />`
|
|
75
|
+
renders those buttons on its own — the `socialLogin` prop defaults to `'auto'`,
|
|
76
|
+
which shows whatever the application owner enabled in the Auth panel and nothing
|
|
77
|
+
at all when they enabled none. An application with no provider configured
|
|
78
|
+
renders exactly what it rendered before.
|
|
79
|
+
|
|
80
|
+
```jsx
|
|
81
|
+
// Nothing to pass: the buttons appear when a provider is live.
|
|
82
|
+
<SignIn />
|
|
83
|
+
|
|
84
|
+
// Or opt out entirely, for a screen that wants the emailed code only.
|
|
85
|
+
<SignIn socialLogin={false} />
|
|
86
|
+
```
|
|
87
|
+
|
|
88
|
+
Building your own screen? `getSocialProviders()` lists what is live,
|
|
89
|
+
`startSocialSignIn(provider, { redirect })` leaves for the provider, and
|
|
90
|
+
`consumeSocialToken()` reads the token the callback leaves in the URL fragment —
|
|
91
|
+
`AuthProvider` already calls that one for you. `startSocialLink()`,
|
|
92
|
+
`unlinkSocialProvider()` and `getLinkedProviders()` manage the connections of an
|
|
93
|
+
account that is already signed in.
|
|
94
|
+
|
|
95
|
+
### Signing in
|
|
96
|
+
|
|
97
|
+
```jsx
|
|
98
|
+
<SignIn
|
|
99
|
+
authenticatedRedirect="/" // where to send someone who already has a session
|
|
100
|
+
onCodeSent={email => notify(`Code sent to ${email}`)}
|
|
101
|
+
onSuccess={(user, { result, redirectHandled }) => notify(`Welcome ${user?.email}`)}
|
|
102
|
+
onError={error => notify(error.message)} {/* error.code traz o identificador estável */}
|
|
103
|
+
/>
|
|
104
|
+
```
|
|
105
|
+
|
|
106
|
+
- `onSuccess` receives the **user** first; the raw API response is `result`.
|
|
107
|
+
- `redirectHandled` is `true` when an OAuth `?redirect=` was already applied — the SDK executes it before calling you, so it is information, not a duty.
|
|
108
|
+
- A wrong code fails with `error.details.attemptsLeft`; five wrong tries destroy the request and the person asks for a new code.
|
|
109
|
+
- Nothing here builds a callback URL. There is no destination to validate, and none to hijack.
|
|
110
|
+
|
|
111
|
+
### Control Components
|
|
112
|
+
|
|
113
|
+
| Component | Description |
|
|
114
|
+
| --------------- | -------------------------------------------- |
|
|
115
|
+
| `<SignedIn>` | Renders children only when authenticated |
|
|
116
|
+
| `<SignedOut>` | Renders children only when NOT authenticated |
|
|
117
|
+
| `<AuthLoading>` | Renders children while auth is loading |
|
|
118
|
+
| `<AuthLoaded>` | Renders children when auth has loaded |
|
|
119
|
+
| `<Protect />` | Protected route wrapper |
|
|
120
|
+
|
|
121
|
+
### Unstyled Buttons
|
|
122
|
+
|
|
123
|
+
| Component | Description |
|
|
124
|
+
| ------------------- | ------------------------- |
|
|
125
|
+
| `<SignInButton />` | Navigates to sign-in page |
|
|
126
|
+
| `<SignOutButton />` | Signs out the user |
|
|
127
|
+
|
|
128
|
+
## Hooks
|
|
129
|
+
|
|
130
|
+
```jsx
|
|
131
|
+
const { user, loading, error, isAuthenticated } = useAuth()
|
|
132
|
+
const { user, updateProfile } = useUser()
|
|
133
|
+
const { requestCode, verifyCode, sending, verifying } = useSignIn()
|
|
134
|
+
const signOut = useSignOut()
|
|
135
|
+
|
|
136
|
+
// The two steps, and nothing else:
|
|
137
|
+
await requestCode(email) // a code goes out by email
|
|
138
|
+
await verifyCode(email, code) // the code becomes a session
|
|
139
|
+
```
|
|
140
|
+
|
|
141
|
+
## Features
|
|
142
|
+
|
|
143
|
+
- ✅ **Social sign-in** - Google, with the application owner's own credentials
|
|
144
|
+
- ✅ **JWT Tokens** - Secure token-based authentication
|
|
145
|
+
- ✅ **JWKS** - Signature verification with `/.well-known/jwks.json`
|
|
146
|
+
- ✅ **Auto refresh** - Tokens renewed automatically
|
|
147
|
+
- ✅ **One way in** - An emailed code, for people and agents alike; no password to leak
|
|
148
|
+
- ✅ **Cross-tab sync** - Synchronized state across tabs
|
|
149
|
+
- ✅ **Route protection** - Protected routes automatically
|
|
150
|
+
- ✅ **Control components** - Clerk-style conditional rendering
|
|
151
|
+
- ✅ **SSR friendly** - Server-side rendering compatible
|
|
152
|
+
|
|
153
|
+
## Removed in 4.0.0
|
|
154
|
+
|
|
155
|
+
Along with the password, magic link, reset and verification flows:
|
|
156
|
+
|
|
157
|
+
| Removed | Use instead |
|
|
158
|
+
| ------------------------------------------------------------------ | ---------------------------------------- |
|
|
159
|
+
| `signUp`, `signIn`, `sendMagicLink`, `verifyMagicLink` | `requestCode` + `verifyCode` |
|
|
160
|
+
| `forgotPassword`, `resetPassword`, `changePassword` | — there is no password |
|
|
161
|
+
| `verifyEmail`, `resendVerification` | — presenting the code already verifies |
|
|
162
|
+
| `changeEmail` | the email is the credential |
|
|
163
|
+
| `socialRedirect` | never existed under that name — social sign-in ships as `startSocialSignIn` |
|
|
164
|
+
| `<SignUp>`, `<MagicLink>`, `<MagicLinkCallback>` | `<SignIn>` |
|
|
165
|
+
| `<ForgotPassword>`, `<ResetPassword>`, `<VerifyEmail>` | `<SignIn>` |
|
|
166
|
+
| `<SignUpButton>` | `<SignInButton>` |
|
|
167
|
+
| `useSignUp`, `useMagicLink`, `usePasswordReset` | `useSignIn` |
|
|
168
|
+
| `useEmailVerification` | `useSignIn` |
|
|
169
|
+
| `SignInForm`, `AccountModal`, `ProtectedRoute`, `useProfile` | `SignIn`, `UserProfile`, `Protect`, `useUser` |
|