@strands.gg/accui 1.0.2 → 1.1.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 +154 -594
- package/dist/accui.css +3 -0
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,673 +1,233 @@
|
|
|
1
1
|
# @strands.gg/accui
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
⚠️ **INTERNAL SYSTEM - NOT FOR PUBLIC USE** ⚠️
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
This is a proprietary authentication UI library specifically designed for the Strands Services ecosystem. It is tightly integrated with our internal authentication API and **will not easily function outside of our infrastructure**.
|
|
6
6
|
|
|
7
|
-
|
|
8
|
-
- **OAuth Providers** - Dynamic OAuth provider discovery from API
|
|
9
|
-
- **Vue 3 Composition API** - Built with modern Vue patterns
|
|
10
|
-
- **TypeScript Support** - Full type safety
|
|
11
|
-
- **Nuxt Module** - First-class Nuxt 3 & 4 support with auto-imports
|
|
12
|
-
- **Customizable UI** - Consistent design system with Tailwind CSS
|
|
13
|
-
- **Responsive Design** - Mobile-first approach
|
|
14
|
-
- **Route Protection** - Built-in middleware for authentication
|
|
7
|
+
## 🔒 System Requirements
|
|
15
8
|
|
|
16
|
-
|
|
9
|
+
This library requires:
|
|
10
|
+
- **Strands Accounts API** backend (proprietary)
|
|
11
|
+
- **Registered application** in our database
|
|
12
|
+
- **Valid domain** registered with Strands Services
|
|
13
|
+
- **Internal infrastructure** access
|
|
17
14
|
|
|
18
|
-
|
|
19
|
-
- ✅ **Proper Module Build** - Nuxt module now builds to both ES and CJS formats with runtime files
|
|
20
|
-
- ✅ **Auto-Import Styles** - Styles automatically imported with components (no manual CSS import needed)
|
|
21
|
-
- ✅ **Custom Styling Control** - `autoImportStyles: false` option for developers who want full styling control
|
|
22
|
-
- ✅ **Enhanced Nuxt Integration** - CSS automatically included in Nuxt builds
|
|
23
|
-
- ✅ **Simplified Setup** - Just install and use, styles are handled automatically
|
|
15
|
+
**This package is published for internal convenience only and cannot be used by external applications.**
|
|
24
16
|
|
|
25
|
-
##
|
|
17
|
+
## 🚀 Features (Internal Use Only)
|
|
26
18
|
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
**
|
|
34
|
-
|
|
35
|
-
- **Vue 3**: Styles load automatically when you import any component
|
|
36
|
-
- **Nuxt 3**: Styles are automatically included when you add the module
|
|
37
|
-
|
|
38
|
-
<details>
|
|
39
|
-
<summary>Manual CSS Import (if needed)</summary>
|
|
40
|
-
|
|
41
|
-
If you need to manually import styles for any reason:
|
|
42
|
-
|
|
43
|
-
```javascript
|
|
44
|
-
// Import the CSS in your main.js or app.vue
|
|
45
|
-
import '@strands.gg/accui/style.css'
|
|
46
|
-
```
|
|
47
|
-
|
|
48
|
-
</details>
|
|
49
|
-
|
|
50
|
-
## 🎯 Quick Start
|
|
51
|
-
|
|
52
|
-
### Basic Vue 3 Usage
|
|
53
|
-
|
|
54
|
-
```vue
|
|
55
|
-
<template>
|
|
56
|
-
<div>
|
|
57
|
-
<!-- Combined Auth Component with tabs -->
|
|
58
|
-
<StrandsAuth
|
|
59
|
-
@success="handleSuccess"
|
|
60
|
-
@error="handleError"
|
|
61
|
-
redirect-url="/dashboard"
|
|
62
|
-
/>
|
|
63
|
-
|
|
64
|
-
<!-- Or use individual components -->
|
|
65
|
-
<StrandsSignIn @success="handleSignInSuccess" />
|
|
66
|
-
<StrandsSignUp @success="handleSignUpSuccess" />
|
|
67
|
-
</div>
|
|
68
|
-
</template>
|
|
69
|
-
|
|
70
|
-
<script setup lang="ts">
|
|
71
|
-
import {
|
|
72
|
-
StrandsAuth,
|
|
73
|
-
StrandsSignIn,
|
|
74
|
-
StrandsSignUp,
|
|
75
|
-
useStrandsAuth
|
|
76
|
-
} from "@strands.gg/accui"
|
|
77
|
-
// Styles are automatically imported! ✨
|
|
78
|
-
|
|
79
|
-
// Access auth state globally
|
|
80
|
-
const { user, isAuthenticated, signOut } = useStrandsAuth()
|
|
81
|
-
|
|
82
|
-
const handleSuccess = (userData: any) => {
|
|
83
|
-
console.log("Authentication successful:", userData)
|
|
84
|
-
}
|
|
85
|
-
|
|
86
|
-
const handleError = (error: string) => {
|
|
87
|
-
console.error("Authentication error:", error)
|
|
88
|
-
}
|
|
89
|
-
|
|
90
|
-
const handleSignUpSuccess = (data: { email: string }) => {
|
|
91
|
-
console.log("Magic link sent to:", data.email)
|
|
92
|
-
}
|
|
93
|
-
</script>
|
|
94
|
-
```
|
|
95
|
-
|
|
96
|
-
### Nuxt 3 Module
|
|
97
|
-
|
|
98
|
-
Add the module to your `nuxt.config.ts`:
|
|
99
|
-
|
|
100
|
-
```typescript
|
|
101
|
-
export default defineNuxtConfig({
|
|
102
|
-
modules: ['@strands.gg/accui/nuxt'], // Styles auto-imported! ✨
|
|
103
|
-
|
|
104
|
-
// Public runtime configuration
|
|
105
|
-
runtimeConfig: {
|
|
106
|
-
public: {
|
|
107
|
-
strandsAuth: {
|
|
108
|
-
apiBaseUrl: 'https://accounts.mydomain.com',
|
|
109
|
-
clientId: 'your-client-id',
|
|
110
|
-
onSignInUrl: '/dashboard',
|
|
111
|
-
onSignOutUrl: '/',
|
|
112
|
-
accentColor: '#EA00A8'
|
|
113
|
-
}
|
|
114
|
-
}
|
|
115
|
-
}
|
|
116
|
-
})
|
|
117
|
-
```
|
|
118
|
-
|
|
119
|
-
**Available Configuration Options:**
|
|
120
|
-
|
|
121
|
-
```typescript
|
|
122
|
-
interface StrandsAuthConfig {
|
|
123
|
-
// Required
|
|
124
|
-
apiBaseUrl?: string // Default: 'https://your-api.example.com'
|
|
125
|
-
clientId?: string // Required for production
|
|
126
|
-
|
|
127
|
-
// Navigation
|
|
128
|
-
onSignInUrl?: string // Default: '/dashboard'
|
|
129
|
-
onSignOutUrl?: string // Default: '/'
|
|
130
|
-
redirectUrl?: string // OAuth callback URL
|
|
131
|
-
|
|
132
|
-
// Styling
|
|
133
|
-
accentColor?: string // Default: '#EA00A8'
|
|
134
|
-
autoImportStyles?: boolean // Default: true (disable for custom styling)
|
|
135
|
-
|
|
136
|
-
// Security & Performance
|
|
137
|
-
autoRefresh?: boolean // Default: true
|
|
138
|
-
refreshInterval?: number // Default: 4 (minutes)
|
|
139
|
-
|
|
140
|
-
// Route Protection
|
|
141
|
-
protectedRoutes?: string[] // Routes requiring authentication
|
|
142
|
-
guestOnlyRoutes?: string[] // Default: ['/auth', '/login', '/register']
|
|
143
|
-
|
|
144
|
-
// Development
|
|
145
|
-
devMode?: boolean // Default: false
|
|
146
|
-
}
|
|
147
|
-
```
|
|
148
|
-
|
|
149
|
-
**Complete Configuration Example:**
|
|
150
|
-
|
|
151
|
-
```typescript
|
|
152
|
-
export default defineNuxtConfig({
|
|
153
|
-
modules: ['@strands.gg/accui/nuxt'],
|
|
154
|
-
|
|
155
|
-
runtimeConfig: {
|
|
156
|
-
public: {
|
|
157
|
-
strandsAuth: {
|
|
158
|
-
// API Configuration
|
|
159
|
-
apiBaseUrl: 'https://accounts.mydomain.com',
|
|
160
|
-
clientId: 'your-production-client-id',
|
|
161
|
-
|
|
162
|
-
// Navigation URLs
|
|
163
|
-
onSignInUrl: '/dashboard',
|
|
164
|
-
onSignOutUrl: '/welcome',
|
|
165
|
-
redirectUrl: '/auth/callback',
|
|
166
|
-
|
|
167
|
-
// Styling
|
|
168
|
-
accentColor: '#8b5cf6',
|
|
169
|
-
autoImportStyles: true, // Set to false for custom styling
|
|
170
|
-
|
|
171
|
-
// Route Protection
|
|
172
|
-
protectedRoutes: [
|
|
173
|
-
'/dashboard/*',
|
|
174
|
-
'/profile',
|
|
175
|
-
'/settings/*',
|
|
176
|
-
'/admin/*'
|
|
177
|
-
],
|
|
178
|
-
guestOnlyRoutes: [
|
|
179
|
-
'/auth',
|
|
180
|
-
'/login',
|
|
181
|
-
'/register',
|
|
182
|
-
'/welcome'
|
|
183
|
-
],
|
|
184
|
-
|
|
185
|
-
// Token Management
|
|
186
|
-
autoRefresh: true,
|
|
187
|
-
refreshInterval: 4, // minutes
|
|
188
|
-
|
|
189
|
-
// Development
|
|
190
|
-
devMode: process.env.NODE_ENV === 'development'
|
|
191
|
-
}
|
|
192
|
-
}
|
|
193
|
-
}
|
|
194
|
-
})
|
|
195
|
-
```
|
|
196
|
-
|
|
197
|
-
**Auto-imported Components & Composables:**
|
|
198
|
-
|
|
199
|
-
```vue
|
|
200
|
-
<template>
|
|
201
|
-
<!-- Authentication Components (auto-imported) -->
|
|
202
|
-
<StrandsAuth @success="handleAuth" />
|
|
203
|
-
<StrandsSignIn @success="handleSignIn" />
|
|
204
|
-
<StrandsSignUp @success="handleSignUp" />
|
|
205
|
-
<StrandsPasswordReset @success="handleReset" />
|
|
206
|
-
<StrandsUserProfile />
|
|
207
|
-
<StrandsMFASetup />
|
|
208
|
-
|
|
209
|
-
<!-- Utility Components (auto-imported) -->
|
|
210
|
-
<SignedIn>
|
|
211
|
-
<p>Welcome back, {{ user?.firstName }}!</p>
|
|
212
|
-
<StrandsUiButton @click="signOut">Sign Out</StrandsUiButton>
|
|
213
|
-
</SignedIn>
|
|
214
|
-
|
|
215
|
-
<SignedOut>
|
|
216
|
-
<p>Please sign in to continue</p>
|
|
217
|
-
<StrandsAuth />
|
|
218
|
-
</SignedOut>
|
|
219
|
-
|
|
220
|
-
<!-- Configuration & Branding -->
|
|
221
|
-
<StrandsConfigProvider :config="customConfig">
|
|
222
|
-
<!-- Scoped configuration -->
|
|
223
|
-
</StrandsConfigProvider>
|
|
224
|
-
|
|
225
|
-
<StrandsSecuredFooter />
|
|
226
|
-
</template>
|
|
227
|
-
|
|
228
|
-
<script setup lang="ts">
|
|
229
|
-
// Composables are auto-imported in Nuxt
|
|
230
|
-
const { user, isAuthenticated, signOut, signIn } = useStrandsAuth()
|
|
231
|
-
const authUser = useAuthUser() // Reactive user object
|
|
232
|
-
const { isAuthenticated: authState, isLoading } = useAuthState()
|
|
233
|
-
|
|
234
|
-
// Event handlers
|
|
235
|
-
const handleAuth = (userData: any) => {
|
|
236
|
-
console.log('Authentication successful:', userData)
|
|
237
|
-
// User is automatically redirected based on onSignInUrl
|
|
238
|
-
}
|
|
19
|
+
- **Magic Link Authentication** - Passwordless signup flow via Strands email service
|
|
20
|
+
- **OAuth Providers** - Dynamic provider discovery from our API
|
|
21
|
+
- **Multi-Factor Authentication** - TOTP, email, and hardware key support
|
|
22
|
+
- **Dynamic CORS** - Automatic origin validation based on registered applications
|
|
23
|
+
- **Vue 3 & Nuxt Support** - Full framework integration
|
|
24
|
+
- **TypeScript** - Complete type safety
|
|
25
|
+
- **Session Management** - JWT token rotation with 5-minute expiry
|
|
239
26
|
|
|
240
|
-
|
|
241
|
-
console.log('Magic link sent to:', data.email)
|
|
242
|
-
// Show success message to user
|
|
243
|
-
}
|
|
244
|
-
</script>
|
|
245
|
-
```
|
|
27
|
+
## 🆕 Recent Updates
|
|
246
28
|
|
|
247
|
-
|
|
29
|
+
### v0.2.8+ (2025)
|
|
30
|
+
- ✅ **Dynamic Origin Support** - Removed hardcoded localhost references
|
|
31
|
+
- ✅ **OAuth2 Redirect URL** - Configurable OAuth callback URLs
|
|
32
|
+
- ✅ **Support Email Config** - Optional support contact display
|
|
33
|
+
- ✅ **CORS Improvements** - Fully dynamic based on registered applications
|
|
34
|
+
- ✅ **Neon Database Support** - Optimized connection pooling for serverless
|
|
35
|
+
- ✅ **Docker Optimizations** - Static binary builds with Alpine Linux
|
|
248
36
|
|
|
249
|
-
|
|
250
|
-
|
|
251
|
-
|
|
252
|
-
|
|
253
|
-
|
|
254
|
-
middleware: 'auth'
|
|
255
|
-
})
|
|
256
|
-
</script>
|
|
257
|
-
|
|
258
|
-
<template>
|
|
259
|
-
<div>
|
|
260
|
-
<h1>Dashboard</h1>
|
|
261
|
-
<p>Protected content here</p>
|
|
262
|
-
</div>
|
|
263
|
-
</template>
|
|
264
|
-
```
|
|
37
|
+
### Previous Updates
|
|
38
|
+
- ✅ **MFA Support** - TOTP, email codes, hardware keys (WebAuthn)
|
|
39
|
+
- ✅ **Improved Error Handling** - Better user feedback
|
|
40
|
+
- ✅ **Auto-Import Styles** - Zero-config styling
|
|
41
|
+
- ✅ **Nuxt 4 Support** - Dedicated module for Nuxt v4
|
|
265
42
|
|
|
266
|
-
|
|
267
|
-
<!-- pages/auth.vue -->
|
|
268
|
-
<script setup lang="ts">
|
|
269
|
-
// Guest-only route - redirects away if already signed in
|
|
270
|
-
definePageMeta({
|
|
271
|
-
middleware: 'guest'
|
|
272
|
-
})
|
|
273
|
-
</script>
|
|
43
|
+
## 📦 Installation (Internal Projects Only)
|
|
274
44
|
|
|
275
|
-
|
|
276
|
-
|
|
277
|
-
<StrandsAuth />
|
|
278
|
-
</div>
|
|
279
|
-
</template>
|
|
45
|
+
```bash
|
|
46
|
+
npm install @strands.gg/accui
|
|
280
47
|
```
|
|
281
48
|
|
|
282
|
-
|
|
49
|
+
## 🎯 Configuration
|
|
283
50
|
|
|
284
|
-
|
|
51
|
+
### Nuxt 3/4 Configuration
|
|
285
52
|
|
|
286
53
|
```typescript
|
|
287
54
|
export default defineNuxtConfig({
|
|
288
|
-
modules: [
|
|
55
|
+
modules: [
|
|
56
|
+
'@strands.gg/accui/nuxt', // Nuxt 3
|
|
57
|
+
// OR
|
|
58
|
+
'@strands.gg/accui/nuxt-v4' // Nuxt 4
|
|
59
|
+
],
|
|
289
60
|
|
|
290
|
-
|
|
291
|
-
|
|
292
|
-
|
|
293
|
-
|
|
294
|
-
|
|
295
|
-
|
|
296
|
-
|
|
297
|
-
|
|
298
|
-
|
|
299
|
-
|
|
300
|
-
|
|
61
|
+
strandsAuth: {
|
|
62
|
+
// API endpoint (required)
|
|
63
|
+
baseUrl: process.env.NODE_ENV === 'development'
|
|
64
|
+
? 'http://localhost:8000'
|
|
65
|
+
: 'https://sessions.strands.gg',
|
|
66
|
+
|
|
67
|
+
// Navigation
|
|
68
|
+
onSignInUrl: '/dashboard',
|
|
69
|
+
onSignOutUrl: '/',
|
|
70
|
+
|
|
71
|
+
// OAuth2 configuration
|
|
72
|
+
oauth2RedirectUrl: 'https://myapp.strands.gg/oauth2/callback', // Optional
|
|
73
|
+
|
|
74
|
+
// Support
|
|
75
|
+
supportEmail: 'support@myapp.strands.gg', // Optional
|
|
76
|
+
|
|
77
|
+
// Development
|
|
78
|
+
devMode: process.env.NODE_ENV === 'development',
|
|
79
|
+
|
|
80
|
+
// Styling
|
|
81
|
+
accentColor: '#EA00A8',
|
|
82
|
+
styles: true, // Auto-import CSS
|
|
83
|
+
|
|
84
|
+
// Security
|
|
85
|
+
autoRefresh: true,
|
|
86
|
+
refreshInterval: 4, // minutes
|
|
87
|
+
|
|
88
|
+
// Route protection
|
|
89
|
+
protectedRoutes: ['/dashboard/*', '/admin/*'],
|
|
90
|
+
guestOnlyRoutes: ['/auth', '/login', '/register']
|
|
301
91
|
}
|
|
302
92
|
})
|
|
303
93
|
```
|
|
304
94
|
|
|
305
|
-
|
|
95
|
+
### Required Backend Setup
|
|
306
96
|
|
|
307
|
-
|
|
308
|
-
- **Compatibility**: Built specifically for Nuxt 4.0+ with updated APIs
|
|
309
|
-
- **Same API**: All configuration options and components remain identical
|
|
310
|
-
- **Future-Ready**: Optimized for Nuxt 4's performance improvements
|
|
97
|
+
Your domain must be registered in our applications database:
|
|
311
98
|
|
|
312
|
-
|
|
313
|
-
|
|
314
|
-
|
|
315
|
-
|
|
316
|
-
- modules: ['@strands.gg/accui/nuxt'],
|
|
317
|
-
+ modules: ['@strands.gg/accui/nuxt-v4'],
|
|
318
|
-
|
|
319
|
-
// Rest of config stays the same!
|
|
320
|
-
runtimeConfig: { /* ... */ }
|
|
321
|
-
})
|
|
99
|
+
```sql
|
|
100
|
+
-- Applications are managed by Strands Services admins
|
|
101
|
+
INSERT INTO applications (domain, name, logo_url)
|
|
102
|
+
VALUES ('myapp.strands.gg', 'My App', 'https://myapp.strands.gg/logo.png');
|
|
322
103
|
```
|
|
323
104
|
|
|
324
105
|
## 🧩 Components
|
|
325
106
|
|
|
326
107
|
### Authentication Components
|
|
327
108
|
|
|
328
|
-
| Component | Description |
|
|
329
|
-
|
|
330
|
-
| `StrandsAuth` | Combined auth with tabs |
|
|
331
|
-
| `StrandsSignIn` | Email + password
|
|
332
|
-
| `StrandsSignUp` | Magic link signup |
|
|
333
|
-
| `
|
|
334
|
-
| `
|
|
335
|
-
| `StrandsUserProfile` | Profile management | User settings |
|
|
336
|
-
| `StrandsMFASetup` | Multi-factor auth setup | Security enhancement |
|
|
337
|
-
|
|
338
|
-
### Utility Components
|
|
339
|
-
|
|
340
|
-
| Component | Description |
|
|
341
|
-
|-----------|-------------|
|
|
342
|
-
| `SignedIn` | Conditional rendering for authenticated users |
|
|
343
|
-
| `SignedOut` | Conditional rendering for unauthenticated users |
|
|
344
|
-
| `StrandsConfigProvider` | Scoped configuration provider |
|
|
345
|
-
| `StrandsLogo` | Strands branding logo |
|
|
346
|
-
| `StrandsSecuredFooter` | "Secured by Strands" footer |
|
|
347
|
-
|
|
348
|
-
### UI Components
|
|
349
|
-
|
|
350
|
-
| Component | Description | Props |
|
|
351
|
-
|-----------|-------------|-------|
|
|
352
|
-
| `UiButton` | Styled button | `variant`, `size`, `loading`, `disabled` |
|
|
353
|
-
| `UiInput` | Form input field | `type`, `label`, `error`, `placeholder` |
|
|
354
|
-
| `UiCard` | Container card | `variant`, `shadow`, `padding` |
|
|
355
|
-
| `UiTabs` | Tab navigation | `tabs`, `modelValue` |
|
|
356
|
-
| `UiAlert` | Status messages | `variant`, `message` |
|
|
357
|
-
| `UiLink` | Styled link | `variant`, `size` |
|
|
358
|
-
|
|
359
|
-
## � Nuxt Module Features
|
|
360
|
-
|
|
361
|
-
The Nuxt module provides a complete authentication solution with:
|
|
362
|
-
|
|
363
|
-
### ✨ **Auto-Registration**
|
|
364
|
-
- **Components**: All authentication and UI components are automatically imported
|
|
365
|
-
- **Composables**: Authentication state management available globally
|
|
366
|
-
- **Middleware**: Route protection built-in (`auth`, `guest`, global middleware)
|
|
367
|
-
- **Types**: Full TypeScript support with auto-completion
|
|
368
|
-
- **Styles**: CSS automatically included in your Nuxt build
|
|
369
|
-
|
|
370
|
-
### 🎨 **Auto-Import Styles**
|
|
371
|
-
The Nuxt module automatically includes all necessary CSS:
|
|
372
|
-
```typescript
|
|
373
|
-
// Automatically added to your project:
|
|
374
|
-
// - Main component styles (@strands.gg/accui/style.css)
|
|
375
|
-
// - Custom accent color variables
|
|
376
|
-
// - Responsive design classes
|
|
377
|
-
// - Dark/light mode support
|
|
378
|
-
```
|
|
379
|
-
|
|
380
|
-
**Custom Styling (Disable Auto-Import):**
|
|
381
|
-
```typescript
|
|
382
|
-
export default defineNuxtConfig({
|
|
383
|
-
modules: ['@strands.gg/accui/nuxt'],
|
|
384
|
-
runtimeConfig: {
|
|
385
|
-
public: {
|
|
386
|
-
strandsAuth: {
|
|
387
|
-
apiBaseUrl: 'https://accounts.mydomain.com',
|
|
388
|
-
clientId: 'your-client-id',
|
|
389
|
-
autoImportStyles: false, // Disable auto-import
|
|
390
|
-
// ... other options
|
|
391
|
-
}
|
|
392
|
-
}
|
|
393
|
-
},
|
|
394
|
-
// Manually control CSS imports
|
|
395
|
-
css: [
|
|
396
|
-
// Import only base styles
|
|
397
|
-
'@strands.gg/accui/style.css',
|
|
398
|
-
// Or use your own custom styles
|
|
399
|
-
'~/assets/css/custom-auth.css'
|
|
400
|
-
]
|
|
401
|
-
})
|
|
402
|
-
```
|
|
403
|
-
|
|
404
|
-
### 🔒 **Route Protection**
|
|
405
|
-
```typescript
|
|
406
|
-
// Automatic protection based on configuration
|
|
407
|
-
protectedRoutes: ['/dashboard/*', '/profile', '/settings/*']
|
|
408
|
-
guestOnlyRoutes: ['/auth', '/login', '/register']
|
|
409
|
-
```
|
|
410
|
-
|
|
411
|
-
### 🎨 **Styling Integration**
|
|
412
|
-
- Custom CSS variables for theming
|
|
413
|
-
- Configurable accent colors
|
|
414
|
-
- TailwindCSS compatibility
|
|
415
|
-
- Dark/light mode support
|
|
416
|
-
|
|
417
|
-
### ⚡ **Performance Optimized**
|
|
418
|
-
- Client-side hydration with SSR support
|
|
419
|
-
- Automatic token refresh
|
|
420
|
-
- Minimal bundle size impact
|
|
421
|
-
- Tree-shaking optimized
|
|
422
|
-
|
|
423
|
-
### 🛠️ **Developer Experience**
|
|
424
|
-
- Hot reload support
|
|
425
|
-
- Development mode with debug logging
|
|
426
|
-
- TypeScript definitions included
|
|
427
|
-
- Comprehensive error handling
|
|
428
|
-
|
|
429
|
-
## �🔧 Composables
|
|
109
|
+
| Component | Description | Requirements |
|
|
110
|
+
|-----------|-------------|--------------|
|
|
111
|
+
| `StrandsAuth` | Combined auth with tabs | Valid application domain |
|
|
112
|
+
| `StrandsSignIn` | Email + password/MFA | Registered user account |
|
|
113
|
+
| `StrandsSignUp` | Magic link signup | SMTP configuration |
|
|
114
|
+
| `StrandsUserProfile` | Profile management | Active session |
|
|
115
|
+
| `StrandsMFASetup` | MFA configuration | User with verified email |
|
|
430
116
|
|
|
431
|
-
###
|
|
432
|
-
|
|
433
|
-
Global authentication state management with clean integration points:
|
|
117
|
+
### Composables
|
|
434
118
|
|
|
435
119
|
```typescript
|
|
436
|
-
|
|
437
|
-
|
|
438
|
-
|
|
439
|
-
|
|
440
|
-
signOut,
|
|
441
|
-
|
|
120
|
+
// Auto-imported in Nuxt
|
|
121
|
+
const {
|
|
122
|
+
user, // Current user from JWT
|
|
123
|
+
isAuthenticated, // Session validity
|
|
124
|
+
signOut, // Clear session
|
|
125
|
+
refreshToken // Rotate JWT token
|
|
442
126
|
} = useStrandsAuth()
|
|
443
127
|
|
|
444
|
-
//
|
|
445
|
-
// Replace placeholder implementations with actual auth service calls
|
|
446
|
-
```
|
|
447
|
-
|
|
448
|
-
### `useStrandsConfig()`
|
|
449
|
-
|
|
450
|
-
Configuration management:
|
|
451
|
-
|
|
452
|
-
```typescript
|
|
128
|
+
// OAuth providers from API
|
|
453
129
|
const {
|
|
454
|
-
|
|
455
|
-
|
|
456
|
-
|
|
457
|
-
```
|
|
458
|
-
|
|
459
|
-
### `useOAuthProviders()`
|
|
460
|
-
|
|
461
|
-
OAuth provider management:
|
|
462
|
-
|
|
463
|
-
```typescript
|
|
464
|
-
const {
|
|
465
|
-
enabledProviders, // Available OAuth providers
|
|
466
|
-
loading, // Loading state
|
|
467
|
-
error, // Error state
|
|
468
|
-
fetchProviders, // Fetch providers from API
|
|
469
|
-
redirectToProvider // Initiate OAuth flow
|
|
130
|
+
providers, // Available OAuth providers
|
|
131
|
+
fetchProviders, // Load from API
|
|
132
|
+
redirectToProvider // Initiate OAuth flow
|
|
470
133
|
} = useOAuthProviders()
|
|
471
134
|
```
|
|
472
135
|
|
|
473
|
-
##
|
|
474
|
-
|
|
475
|
-
The signup component uses a modern magic link approach:
|
|
476
|
-
|
|
477
|
-
```vue
|
|
478
|
-
<template>
|
|
479
|
-
<!-- User enters email only -->
|
|
480
|
-
<StrandsSignUp @success="handleMagicLinkSent" />
|
|
481
|
-
</template>
|
|
482
|
-
|
|
483
|
-
<script setup lang="ts">
|
|
484
|
-
// User receives magic link via email
|
|
485
|
-
// Clicking link completes registration
|
|
486
|
-
const handleMagicLinkSent = (data: { email: string }) => {
|
|
487
|
-
// Show success message
|
|
488
|
-
console.log(`Magic link sent to ${data.email}`)
|
|
489
|
-
}
|
|
490
|
-
</script>
|
|
491
|
-
```
|
|
492
|
-
|
|
493
|
-
## 🔐 Configuration
|
|
136
|
+
## 🔐 Authentication Flow
|
|
494
137
|
|
|
495
|
-
|
|
138
|
+
1. **Sign Up**: Email → Magic Link → Complete Registration
|
|
139
|
+
2. **Sign In**: Email + Password → Optional MFA → JWT Token
|
|
140
|
+
3. **Token Rotation**: 5-minute access tokens, 30-day refresh tokens
|
|
141
|
+
4. **OAuth**: Dynamic provider discovery → Authorization → Callback
|
|
496
142
|
|
|
497
|
-
|
|
498
|
-
import { setStrandsConfig } from '@strands.gg/accui'
|
|
499
|
-
|
|
500
|
-
setStrandsConfig({
|
|
501
|
-
apiBaseUrl: 'https://your-api.com',
|
|
502
|
-
clientId: 'your-client-id',
|
|
503
|
-
// Additional options
|
|
504
|
-
})
|
|
505
|
-
```
|
|
143
|
+
## 🎨 Styling
|
|
506
144
|
|
|
507
|
-
|
|
145
|
+
Components use Tailwind CSS with custom properties:
|
|
508
146
|
|
|
509
|
-
```
|
|
510
|
-
|
|
511
|
-
|
|
512
|
-
|
|
513
|
-
|
|
514
|
-
</template>
|
|
515
|
-
|
|
516
|
-
<script setup lang="ts">
|
|
517
|
-
const scopedConfig = {
|
|
518
|
-
apiBaseUrl: 'https://different-api.com'
|
|
147
|
+
```css
|
|
148
|
+
:root {
|
|
149
|
+
--strands-primary: #EA00A8; /* Strands brand color */
|
|
150
|
+
--strands-secondary: #B8006F;
|
|
151
|
+
/* Set via accentColor config */
|
|
519
152
|
}
|
|
520
|
-
</script>
|
|
521
153
|
```
|
|
522
154
|
|
|
523
|
-
|
|
524
|
-
|
|
525
|
-
|
|
526
|
-
|
|
527
|
-
|
|
528
|
-
// GET /api/v1/oauth/providers
|
|
529
|
-
{
|
|
530
|
-
"providers": [
|
|
531
|
-
{
|
|
532
|
-
"id": "google",
|
|
533
|
-
"name": "Google",
|
|
534
|
-
"displayName": "Google",
|
|
535
|
-
"iconUrl": "https://example.com/google-icon.svg",
|
|
536
|
-
"enabled": true
|
|
537
|
-
}
|
|
538
|
-
]
|
|
155
|
+
To use custom styles:
|
|
156
|
+
```typescript
|
|
157
|
+
strandsAuth: {
|
|
158
|
+
styles: false, // Disable auto-import
|
|
159
|
+
// ... other config
|
|
539
160
|
}
|
|
540
161
|
```
|
|
541
162
|
|
|
542
|
-
##
|
|
163
|
+
## 🚨 Common Issues
|
|
543
164
|
|
|
544
|
-
|
|
165
|
+
### "Cannot connect to API"
|
|
166
|
+
- Verify your domain is registered in applications table
|
|
167
|
+
- Check CORS is enabled for your origin
|
|
168
|
+
- Ensure API is running (development: port 8000)
|
|
545
169
|
|
|
546
|
-
|
|
547
|
-
-
|
|
548
|
-
-
|
|
170
|
+
### "Invalid client configuration"
|
|
171
|
+
- Application domain must match request origin
|
|
172
|
+
- Cannot use from localhost without registration
|
|
549
173
|
|
|
550
|
-
|
|
174
|
+
### "MFA verification failed"
|
|
175
|
+
- TOTP codes expire after 30 seconds
|
|
176
|
+
- Email codes expire after 10 minutes
|
|
177
|
+
- Hardware keys require HTTPS origin
|
|
551
178
|
|
|
552
|
-
|
|
179
|
+
## 🔧 Development Setup
|
|
553
180
|
|
|
554
|
-
|
|
555
|
-
```bash
|
|
556
|
-
npm install @strands.gg/accui
|
|
557
|
-
# Ensure module is in nuxt.config.ts modules array
|
|
558
|
-
# Ensure you're using version 0.0.8+ which includes the fixed module build
|
|
559
|
-
```
|
|
181
|
+
For local development of Strands applications:
|
|
560
182
|
|
|
561
|
-
|
|
183
|
+
1. Run the API locally:
|
|
562
184
|
```bash
|
|
563
|
-
|
|
564
|
-
|
|
565
|
-
```
|
|
566
|
-
|
|
567
|
-
**TypeScript errors:**
|
|
568
|
-
```typescript
|
|
569
|
-
// Add type declaration in nuxt.config.ts
|
|
570
|
-
declare module '@nuxt/schema' {
|
|
571
|
-
interface RuntimeConfig {
|
|
572
|
-
public: {
|
|
573
|
-
strandsAuth: StrandsAuthConfig
|
|
574
|
-
}
|
|
575
|
-
}
|
|
576
|
-
}
|
|
185
|
+
cd apps/accounts-api
|
|
186
|
+
cargo run --bin accounts-api
|
|
577
187
|
```
|
|
578
188
|
|
|
579
|
-
|
|
580
|
-
```
|
|
581
|
-
|
|
582
|
-
|
|
189
|
+
2. Register your local domain:
|
|
190
|
+
```sql
|
|
191
|
+
INSERT INTO applications (domain, name)
|
|
192
|
+
VALUES ('localhost:3001', 'Local Dev');
|
|
583
193
|
```
|
|
584
194
|
|
|
585
|
-
|
|
195
|
+
3. Configure Nuxt:
|
|
586
196
|
```typescript
|
|
587
|
-
|
|
588
|
-
|
|
589
|
-
|
|
590
|
-
strandsAuth: {
|
|
591
|
-
autoImportStyles: true // Enable auto-import
|
|
592
|
-
}
|
|
593
|
-
}
|
|
197
|
+
strandsAuth: {
|
|
198
|
+
baseUrl: 'http://localhost:8000',
|
|
199
|
+
devMode: true
|
|
594
200
|
}
|
|
595
|
-
|
|
596
|
-
// Or manually import styles:
|
|
597
|
-
export default defineNuxtConfig({
|
|
598
|
-
css: ['@strands.gg/accui/style.css'] // Manual import
|
|
599
|
-
})
|
|
600
|
-
|
|
601
|
-
// For completely custom styling:
|
|
602
|
-
runtimeConfig: {
|
|
603
|
-
public: {
|
|
604
|
-
strandsAuth: {
|
|
605
|
-
autoImportStyles: false // Disable auto-import
|
|
606
|
-
}
|
|
607
|
-
}
|
|
608
|
-
}
|
|
609
|
-
```
|
|
610
|
-
|
|
611
|
-
**Middleware not working:**
|
|
612
|
-
```vue
|
|
613
|
-
<!-- Ensure pages are in pages/ directory -->
|
|
614
|
-
<script setup lang="ts">
|
|
615
|
-
definePageMeta({
|
|
616
|
-
middleware: 'auth' // or 'guest'
|
|
617
|
-
})
|
|
618
|
-
</script>
|
|
619
201
|
```
|
|
620
202
|
|
|
621
|
-
|
|
622
|
-
|
|
623
|
-
**Build errors:**
|
|
624
|
-
- Ensure Node.js 16+ is installed
|
|
625
|
-
- Clear `.nuxt` and `node_modules`, reinstall dependencies
|
|
626
|
-
- Check for conflicting CSS frameworks
|
|
627
|
-
|
|
628
|
-
**Runtime errors:**
|
|
629
|
-
- Verify `apiBaseUrl` and `clientId` configuration
|
|
630
|
-
- Check browser console for detailed error messages
|
|
631
|
-
- Enable `devMode: true` for debugging
|
|
632
|
-
|
|
633
|
-
## 🎨 Theming
|
|
634
|
-
|
|
635
|
-
Components use CSS custom properties for theming:
|
|
636
|
-
|
|
637
|
-
```css
|
|
638
|
-
:root {
|
|
639
|
-
--strands-primary: #your-brand-color;
|
|
640
|
-
--strands-secondary: #your-secondary-color;
|
|
641
|
-
/* Additional theme variables */
|
|
642
|
-
}
|
|
643
|
-
```
|
|
644
|
-
|
|
645
|
-
## 📋 TypeScript Support
|
|
646
|
-
|
|
647
|
-
Full TypeScript definitions included:
|
|
203
|
+
## 📋 TypeScript Types
|
|
648
204
|
|
|
649
205
|
```typescript
|
|
650
|
-
import type {
|
|
651
|
-
|
|
652
|
-
|
|
653
|
-
StrandsAuthConfig,
|
|
654
|
-
|
|
655
|
-
|
|
206
|
+
import type {
|
|
207
|
+
User, // User model from API
|
|
208
|
+
Session, // JWT session data
|
|
209
|
+
StrandsAuthConfig, // Module configuration
|
|
210
|
+
MfaDevice, // MFA device types
|
|
211
|
+
AuthResponse // API responses
|
|
656
212
|
} from '@strands.gg/accui'
|
|
657
213
|
```
|
|
658
214
|
|
|
659
|
-
##
|
|
215
|
+
## 🏗️ Infrastructure Requirements
|
|
660
216
|
|
|
661
|
-
- **
|
|
662
|
-
- **
|
|
663
|
-
- **
|
|
664
|
-
- **
|
|
217
|
+
- **Database**: PostgreSQL with migrations
|
|
218
|
+
- **Cache**: Redis for sessions
|
|
219
|
+
- **Email**: SMTP server for magic links
|
|
220
|
+
- **Storage**: S3-compatible for avatars (optional)
|
|
221
|
+
- **Domain**: Registered in applications table
|
|
665
222
|
|
|
666
223
|
## 📄 License
|
|
667
224
|
|
|
668
|
-
|
|
225
|
+
**PROPRIETARY - Strands Services Limited**
|
|
226
|
+
|
|
227
|
+
This software is the proprietary property of Strands Services Limited and may only be used in accordance with the terms of your agreement with Strands Services.
|
|
669
228
|
|
|
670
229
|
---
|
|
671
230
|
|
|
672
|
-
**
|
|
231
|
+
**Internal Support**: Contact the platform team via Slack #platform-support
|
|
673
232
|
|
|
233
|
+
**External Inquiries**: This package is not available for external use. For partnership inquiries, contact business@strands.gg
|
package/dist/accui.css
CHANGED