npm package: @strands.gg/accui
Description: Strands Authentication UI Components
Author: Strands Services Limited
Latest version: 2.19.1

# @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)

```bash
npm install @strands.gg/accui
```

## 🎯 Configuration

### Vite + Vue 3 Configuration

**Option 1: Vite Plugin (Recommended)**

```typescript
// 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 (optional - if not set, app handles its own redirects)
      // onSignInUrl: '/dashboard',
      onSignOutUrl: '/',

      // Support
      supportEmail: 'support@your-app.example.com',
    })
  ]
})
```

```typescript
// 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**

```typescript
// 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](./VITE_PLUGIN.md) for full documentation.

### Nuxt 3/4 Configuration

```typescript
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 (optional - if not set, app handles its own redirects)
    // onSignInUrl: '/dashboard',
    onSignOutUrl: '/',

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

    // Support
    supportEmail: 'support@your-app.example.com', // 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:

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

To use custom styles:
```typescript
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:

```typescript
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

```typescript
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.

---