@strands.gg/accui

⚠️ INTERNAL SYSTEM - NOT FOR PUBLIC USE ⚠️

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.

🔒 System Requirements

This library requires:

• Strands Accounts API backend (proprietary)
• Registered application in our database
• Valid domain registered with Strands Services
• Internal infrastructure access

This package is published for internal convenience only and cannot easily be used by external applications.

🚀 Features (Internal Use Only)

• Magic Link Authentication - Passwordless signup flow via Strands email service
• OAuth Providers - Dynamic provider discovery from our API
• Multi-Factor Authentication - TOTP, email, and hardware key support
• Dynamic CORS - Automatic origin validation based on registered applications
• Vue 3 & Nuxt Support - Full framework integration
• TypeScript - Complete type safety
• Session Management - JWT token rotation with 5-minute expiry

🆕 Recent Updates

v0.2.8+ (2025)

• ✅ Dynamic Origin Support - Removed hardcoded localhost references
• ✅ OAuth2 Redirect URL - Configurable OAuth callback URLs
• ✅ Support Email Config - Optional support contact display
• ✅ CORS Improvements - Fully dynamic based on registered applications
• ✅ Neon Database Support - Optimized connection pooling for serverless
• ✅ Docker Optimizations - Static binary builds with Alpine Linux

Previous Updates

• ✅ MFA Support - TOTP, email codes, hardware keys (WebAuthn)
• ✅ Improved Error Handling - Better user feedback
• ✅ Auto-Import Styles - Zero-config styling
• ✅ Nuxt 4 Support - Dedicated module for Nuxt v4

📦 Installation (Internal Projects Only)

npm install @strands.gg/accui

🎯 Configuration

Vite + Vue 3 Configuration

Option 1: Vite Plugin (Recommended)

// vite.config.ts
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import StrandsAuth from '@strands.gg/accui/vite'

export default defineConfig({
  plugins: [
    vue(),
    StrandsAuth({
      // API Configuration
      baseUrl: 'http://localhost:8000',

      // Theme Configuration
      accentColor: '#EA00A8',
      useSquircle: true,

      // Auto-import styles (default: true)
      styles: true,

      // Navigation
      onSignInUrl: '/dashboard',
      onSignOutUrl: '/',

      // Support
      supportEmail: '[email protected]',
    })
  ]
})

// main.ts
import { createApp } from 'vue'
import { createStrandsAuth } from '@strands.gg/accui/vite'
import App from './App.vue'

const app = createApp(App)
app.use(createStrandsAuth())
app.mount('#app')

Option 2: Manual Configuration

// main.ts
import { createApp } from 'vue'
import { setStrandsConfig } from '@strands.gg/accui'
import StrandsUIPlugin from '@strands.gg/accui/plugin'
import '@strands.gg/accui/style.css'
import App from './App.vue'

setStrandsConfig({
  baseUrl: 'http://localhost:8000',
  accentColor: '#EA00A8',
  useSquircle: true,
})

const app = createApp(App)
app.use(StrandsUIPlugin)
app.mount('#app')

See VITE_PLUGIN.md for full documentation.

Nuxt 3/4 Configuration

export default defineNuxtConfig({
  modules: [
    '@strands.gg/accui/nuxt',     // Supports both Nuxt 3 and 4
  ],

  strandsAuth: {
    // API endpoint (required)
    baseUrl: process.env.NODE_ENV === 'development'
      ? 'http://localhost:8000'
      : 'https://your-api.example.com',

    // Navigation
    onSignInUrl: '/dashboard',
    onSignOutUrl: '/',

    // OAuth2 configuration
    oauth2RedirectUrl: 'https://your-app.example.com/oauth2/callback', // Optional

    // Support
    supportEmail: '[email protected]', // Optional

    // Development
    devMode: process.env.NODE_ENV === 'development',

    // Styling
    accentColor: '#EA00A8',
    styles: true, // Auto-import CSS

    // Security
    autoRefresh: true,
    refreshInterval: 4, // minutes

    // Route protection
    protectedRoutes: ['/dashboard/*', '/admin/*'],
    guestOnlyRoutes: ['/auth', '/login', '/register']
  }
})

## 🧩 Components

### Authentication Components

| Component | Description | Requirements |
|-----------|-------------|--------------|
| `StrandsAuth` | Combined auth with tabs | Valid application domain |
| `StrandsSignIn` | Email + password/MFA | Registered user account |
| `StrandsSignUp` | Magic link signup | SMTP configuration |
| `StrandsUserProfile` | Profile management | Active session |
| `StrandsMFASetup` | MFA configuration | User with verified email |

### Composables

```typescript
// Auto-imported in Nuxt
const { 
  user,              // Current user from JWT
  isAuthenticated,   // Session validity
  signOut,          // Clear session
  refreshToken      // Rotate JWT token
} = useStrandsAuth()

// OAuth providers from API
const { 
  providers,         // Available OAuth providers
  fetchProviders,   // Load from API
  redirectToProvider // Initiate OAuth flow
} = useOAuthProviders()

🔐 Authentication Flow

1. Sign Up: Email → Magic Link → Complete Registration
2. Sign In: Email + Password → Optional MFA → JWT Token
3. Token Rotation: 5-minute access tokens, 30-day refresh tokens
4. OAuth: Dynamic provider discovery → Authorization → Callback

🎨 Styling

Components use Tailwind CSS with custom properties:

:root {
  --strands-primary: #EA00A8;  /* Strands brand color */
  --strands-secondary: #B8006F;
  /* Set via accentColor config */
}

To use custom styles:

strandsAuth: {
  styles: false, // Disable auto-import
  // ... other config
}

🚨 Common Issues

"Cannot connect to API"

• Verify your domain is registered with us
• Check CORS is enabled for your origin
• Ensure API is running (development: port 8000)

"Invalid client configuration"

• Application domain must match request origin
• Cannot use from localhost without registration

"MFA verification failed"

• TOTP codes expire after 30 seconds
• Email codes expire after 10 minutes
• Hardware keys require HTTPS origin

🔧 Development Setup

For local development of Strands applications, configure your Nuxt app to use the development API endpoint:

strandsAuth: {
  baseUrl: process.env.NODE_ENV === 'development' 
    ? 'http://localhost:8000' 
    : 'https://your-api.example.com',
  devMode: true
}

Contact the platform team to register your local development domain.

📋 TypeScript Types

import type {
  User,              // User model from API
  Session,           // JWT session data
  StrandsAuthConfig, // Module configuration
  MfaDevice,        // MFA device types
  AuthResponse      // API responses
} from '@strands.gg/accui'

🏗️ Requirements

• Domain Registration: Your application domain must be registered with Strands Services
• HTTPS: Required for production OAuth and hardware key authentication

📄 License

PROPRIETARY - Strands Services Limited

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.