@spacinbox/sdk 2.0.0 → 2.0.1
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 +2 -144
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,145 +1,3 @@
|
|
|
1
|
-
# @
|
|
1
|
+
# @spacinbox/sdk
|
|
2
2
|
|
|
3
|
-
Official SDK for Spaceinbox
|
|
4
|
-
|
|
5
|
-
## Getting Started
|
|
6
|
-
|
|
7
|
-
1. Create an account at [simple-login.com](https://simple-login.com)
|
|
8
|
-
2. Create an application to get your `clientId` and `clientSecret`
|
|
9
|
-
3. Install the SDK and configure it with your credentials
|
|
10
|
-
|
|
11
|
-
## Installation
|
|
12
|
-
|
|
13
|
-
```bash
|
|
14
|
-
npm install @simple-login/sdk
|
|
15
|
-
```
|
|
16
|
-
|
|
17
|
-
## Configuration
|
|
18
|
-
|
|
19
|
-
### Using environment variables (recommended)
|
|
20
|
-
|
|
21
|
-
Set these environment variables and the SDK will auto-detect them:
|
|
22
|
-
|
|
23
|
-
```bash
|
|
24
|
-
# Private server-side
|
|
25
|
-
SIMPLELOGIN_CLIENT_SECRET=your-client-secret
|
|
26
|
-
|
|
27
|
-
# Public
|
|
28
|
-
VITE_SIMPLELOGIN_CLIENT_ID=your-client-id
|
|
29
|
-
VITE_SIMPLELOGIN_SLUG=your-slug
|
|
30
|
-
VITE_SIMPLELOGIN_REDIRECT_URI=https://your-app.com/auth/callback
|
|
31
|
-
VITE_SIMPLELOGIN_ORIGIN=https://your-app.com
|
|
32
|
-
|
|
33
|
-
# NB: Works with VITE_, NEXT_PUBLIC_, NUXT_PUBLIC_, PUBLIC_, REACT_APP_ and EXPO_PUBLIC_
|
|
34
|
-
```
|
|
35
|
-
|
|
36
|
-
```typescript
|
|
37
|
-
import { SimpleLogin } from '@simple-login/sdk'
|
|
38
|
-
|
|
39
|
-
const simpleLogin = new SimpleLogin()
|
|
40
|
-
```
|
|
41
|
-
|
|
42
|
-
### Explicit configuration
|
|
43
|
-
|
|
44
|
-
You can also pass the config directly (this overrides environment variables):
|
|
45
|
-
|
|
46
|
-
```typescript
|
|
47
|
-
const simpleLogin = new SimpleLogin({
|
|
48
|
-
clientId: 'your-client-id',
|
|
49
|
-
clientSecret: 'your-client-secret',
|
|
50
|
-
redirectUri: 'https://your-app.com/auth/callback',
|
|
51
|
-
origin: 'https://your-app.com',
|
|
52
|
-
})
|
|
53
|
-
```
|
|
54
|
-
|
|
55
|
-
## Quick Start (All-in-One Flow)
|
|
56
|
-
|
|
57
|
-
The SDK provides a batteries-included flow that handles cookies, PKCE, state verification, and token refresh automatically.
|
|
58
|
-
|
|
59
|
-
### 1. Login Route
|
|
60
|
-
|
|
61
|
-
```typescript
|
|
62
|
-
// GET /auth/login
|
|
63
|
-
export async function loader() {
|
|
64
|
-
return simpleLogin.redirectToAuth()
|
|
65
|
-
}
|
|
66
|
-
```
|
|
67
|
-
|
|
68
|
-
### 2. Callback Route
|
|
69
|
-
|
|
70
|
-
```typescript
|
|
71
|
-
// GET /auth/callback
|
|
72
|
-
export async function loader({ request }) {
|
|
73
|
-
const { response, user } = await simpleLogin.handleCallback(request, '/dashboard')
|
|
74
|
-
|
|
75
|
-
// Store user in your database if needed
|
|
76
|
-
await db.users.upsert({
|
|
77
|
-
id: user.id,
|
|
78
|
-
email: user.email,
|
|
79
|
-
name: user.name,
|
|
80
|
-
})
|
|
81
|
-
|
|
82
|
-
return response
|
|
83
|
-
}
|
|
84
|
-
```
|
|
85
|
-
|
|
86
|
-
### 3. Protected Routes
|
|
87
|
-
|
|
88
|
-
```typescript
|
|
89
|
-
// GET /dashboard
|
|
90
|
-
export async function loader({ request }) {
|
|
91
|
-
const auth = await simpleLogin.authenticate(request)
|
|
92
|
-
|
|
93
|
-
if (!auth) {
|
|
94
|
-
return simpleLogin.redirectToAuth()
|
|
95
|
-
}
|
|
96
|
-
|
|
97
|
-
// auth.claims contains decoded JWT claims (sub, application_id, etc.)
|
|
98
|
-
const user = await db.users.findById(auth.claims.sub)
|
|
99
|
-
|
|
100
|
-
// auth.headers contains Set-Cookie if tokens were refreshed
|
|
101
|
-
return json({ user }, { headers: auth.headers })
|
|
102
|
-
}
|
|
103
|
-
```
|
|
104
|
-
|
|
105
|
-
### 4. Logout Route
|
|
106
|
-
|
|
107
|
-
```typescript
|
|
108
|
-
// POST /auth/logout
|
|
109
|
-
export async function action({ request }) {
|
|
110
|
-
return simpleLogin.logout(request)
|
|
111
|
-
}
|
|
112
|
-
```
|
|
113
|
-
|
|
114
|
-
## Security Features
|
|
115
|
-
|
|
116
|
-
### PKCE (Proof Key for Code Exchange)
|
|
117
|
-
|
|
118
|
-
PKCE is automatically enabled for all authorization requests. The SDK generates a cryptographically secure code verifier and challenge, stores the verifier in an HttpOnly cookie, and includes it in the token exchange.
|
|
119
|
-
|
|
120
|
-
### State Parameter
|
|
121
|
-
|
|
122
|
-
A cryptographically secure state parameter is automatically generated (or you can provide your own) and verified on callback to prevent CSRF attacks.
|
|
123
|
-
|
|
124
|
-
### CSRF Protection for Mutations
|
|
125
|
-
|
|
126
|
-
The `authenticate()` method automatically checks the `Origin` or `Referer` header for non-GET requests against your configured `origin`. Returns `null` if the origin doesn't match, preventing CSRF attacks.
|
|
127
|
-
|
|
128
|
-
**Important:** You must set `SIMPLELOGIN_ORIGIN` environment variable (or pass `origin` in config) for CSRF protection to work.
|
|
129
|
-
|
|
130
|
-
### Token Refresh
|
|
131
|
-
|
|
132
|
-
The `authenticate()` method automatically refreshes expired access tokens using the refresh token. When tokens are refreshed, the new cookies are included in `auth.headers` - just pass them to your response.
|
|
133
|
-
|
|
134
|
-
### Secure Cookie Defaults
|
|
135
|
-
|
|
136
|
-
All cookies are set with secure defaults:
|
|
137
|
-
|
|
138
|
-
- `HttpOnly` - Not accessible via JavaScript
|
|
139
|
-
- `Secure` - Only sent over HTTPS
|
|
140
|
-
- `SameSite=Lax` - CSRF protection
|
|
141
|
-
- `Path=/` - Available site-wide
|
|
142
|
-
|
|
143
|
-
## License
|
|
144
|
-
|
|
145
|
-
MIT
|
|
3
|
+
Official SDK for Spaceinbox customer support widget.
|