cobras-auth-nuxt 1.0.0

package/README.md

@@ -0,0 +1,302 @@
+# @cobras/auth-nuxt
+
+Nuxt 3/4 module for integrating with the Cobras Auth service. Supports two modes:
+
+- **Internal Mode**: Full SSO authentication for internal tools
+- **Public Mode**: Public-facing sites with optional auth for dev tools/special features
+
+## Installation
+
+```bash
+npm install @cobras/auth-nuxt
+# or
+pnpm add @cobras/auth-nuxt
+```
+
+## Setup
+
+Add to your `nuxt.config.ts`:
+
+```typescript
+export default defineNuxtConfig({
+  modules: ['@cobras/auth-nuxt'],
+
+  cobrasAuth: {
+    // Required: URL of your Cobras Auth service
+    authServiceUrl: 'https://cobras-auth-app-production.up.railway.app',
+
+    // 'internal' = SSO for internal tools (blocks until auth checked)
+    // 'public' = public site with optional auth (non-blocking)
+    mode: 'public',
+
+    // Optional: Register your site in cobras-auth admin
+    siteId: 'your-site-id',
+    // or
+    siteDomain: 'your-site.com',
+
+    // Enable global auth middleware (internal mode typically)
+    globalMiddleware: false,
+
+    // Routes that don't require auth (internal mode)
+    publicRoutes: ['/', '/about', '/public/*'],
+
+    // Enable dev tools for authenticated users
+    enableDevTools: true,
+    devToolsKey: 'ctrl+shift+d',
+
+    // Debug logging
+    debug: false,
+  },
+})
+```
+
+## Modes
+
+### Public Mode (default)
+
+For public-facing websites. Auth is checked on the client-side without blocking SSR.
+
+```typescript
+// nuxt.config.ts
+cobrasAuth: {
+  mode: 'public',
+  enableDevTools: true, // Show dev panel for logged-in team members
+}
+```
+
+Use cases:
+- Marketing sites where team members can toggle feature flags
+- Public apps where authenticated users get extra features
+- Sites where you want to show dev tools to internal users
+
+### Internal Mode
+
+For internal tools requiring SSO. Auth is checked on the server before rendering.
+
+```typescript
+// nuxt.config.ts
+cobrasAuth: {
+  mode: 'internal',
+  globalMiddleware: true,
+  publicRoutes: ['/'], // Landing page is public
+}
+```
+
+Use cases:
+- Admin dashboards
+- Internal tools
+- Apps that require authentication for all routes
+
+## Usage
+
+### Composables
+
+#### `useCobrasAuth()`
+
+Main composable for auth state and actions.
+
+```vue
+<script setup>
+const {
+  user,           // Ref<CobrasUser | null>
+  isAuthenticated, // ComputedRef<boolean>
+  isInternalUser,  // ComputedRef<boolean> - alias for isAuthenticated
+  isAdmin,        // ComputedRef<boolean>
+  mode,           // 'internal' | 'public'
+  checkAuth,      // () => Promise<void>
+  login,          // (redirect?: string) => void
+  logout,         // () => Promise<void>
+} = useCobrasAuth()
+</script>
+
+<template>
+  <div v-if="isAuthenticated">
+    Welcome, {{ user?.name }}!
+    <button @click="logout">Logout</button>
+  </div>
+  <div v-else>
+    <button @click="login()">Login</button>
+  </div>
+</template>
+```
+
+#### `useCobrasMode()`
+
+Check current mode and feature visibility.
+
+```vue
+<script setup>
+const {
+  mode,                // 'internal' | 'public'
+  isInternalMode,      // boolean
+  isPublicMode,        // boolean
+  showInternalFeatures, // boolean - true if user is authenticated
+  showAdminFeatures,   // boolean - true if user is admin
+  devToolsEnabled,     // boolean
+} = useCobrasMode()
+</script>
+
+<template>
+  <AdminPanel v-if="showAdminFeatures" />
+  <InternalTools v-if="showInternalFeatures" />
+</template>
+```
+
+#### `useCobrasDevTools()`
+
+Control dev tools panel and feature flags.
+
+```vue
+<script setup>
+const {
+  state,          // Ref<DevToolsState>
+  isAvailable,    // ComputedRef<boolean>
+  toggle,         // () => void
+  open,           // () => void
+  close,          // () => void
+  setFeatureFlag, // (key: string, value: boolean) => void
+  getFeatureFlag, // (key: string) => boolean
+  toggleDebugMode, // () => void
+} = useCobrasDevTools()
+
+// Check a feature flag anywhere in your app
+const showNewFeature = computed(() => getFeatureFlag('new-checkout-flow'))
+</script>
+```
+
+### Global `$cobrasAuth`
+
+Available via `useNuxtApp()` or in templates:
+
+```vue
+<template>
+  <span v-if="$cobrasAuth.isAuthenticated">
+    {{ $cobrasAuth.user?.name }}
+  </span>
+</template>
+```
+
+### Middleware
+
+#### Global Middleware
+
+Enable in config to protect all routes:
+
+```typescript
+cobrasAuth: {
+  globalMiddleware: true,
+  publicRoutes: ['/', '/login', '/public/*'],
+}
+```
+
+#### Per-Route Protection
+
+Use `cobras-internal` middleware on specific pages:
+
+```vue
+<!-- pages/admin.vue -->
+<script setup>
+definePageMeta({
+  middleware: 'cobras-internal'
+})
+</script>
+```
+
+### Dev Tools Component
+
+Add the dev tools panel to your app (only shows for authenticated users):
+
+```vue
+<!-- app.vue or layouts/default.vue -->
+<template>
+  <div>
+    <NuxtPage />
+    <CobrasDevTools />
+  </div>
+</template>
+```
+
+Toggle with keyboard shortcut (default: `Ctrl+Shift+D`).
+
+## API Reference
+
+### Module Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `authServiceUrl` | `string` | Railway URL | Cobras Auth service URL |
+| `mode` | `'internal' \| 'public'` | `'public'` | Authentication mode |
+| `siteId` | `string` | - | Site ID for permissions |
+| `siteDomain` | `string` | - | Site domain for permissions |
+| `globalMiddleware` | `boolean` | `false` | Enable auth on all routes |
+| `publicRoutes` | `string[]` | `['/']` | Routes that don't require auth |
+| `loginPath` | `string` | `'/login'` | Custom login page path |
+| `enableDevTools` | `boolean` | `true` | Enable dev tools panel |
+| `devToolsKey` | `string` | `'ctrl+shift+d'` | Keyboard shortcut |
+| `cookieDomain` | `string` | - | Cookie domain override |
+| `debug` | `boolean` | `false` | Enable debug logging |
+
+### CobrasUser Type
+
+```typescript
+interface CobrasUser {
+  id: string
+  email: string
+  name: string
+  role: 'admin' | 'user'
+  canAccessAdmin?: boolean
+  isAutoAuth?: boolean
+}
+```
+
+## Examples
+
+### Conditional Feature Based on Auth
+
+```vue
+<script setup>
+const { isAuthenticated, isAdmin } = useCobrasAuth()
+const { getFeatureFlag } = useCobrasDevTools()
+
+const showBetaFeature = computed(() => {
+  // Show to admins, or authenticated users with flag enabled
+  return isAdmin.value || (isAuthenticated.value && getFeatureFlag('beta-feature'))
+})
+</script>
+```
+
+### Protected API Route
+
+```typescript
+// server/api/admin/stats.get.ts
+export default defineEventHandler(async (event) => {
+  // Verify auth via the proxy endpoint
+  const auth = await $fetch('/api/_cobras/verify', {
+    headers: { cookie: getHeader(event, 'cookie') || '' }
+  }).catch(() => null)
+
+  if (!auth?.valid || auth.user?.role !== 'admin') {
+    throw createError({ statusCode: 403, message: 'Admin access required' })
+  }
+
+  return { stats: '...' }
+})
+```
+
+## Development
+
+```bash
+# Install dependencies
+pnpm install
+
+# Build the module
+pnpm prepack
+
+# Dev with playground
+pnpm dev:prepare
+pnpm dev
+```
+
+## License
+
+MIT

package/dist/module.cjs

@@ -0,0 +1,5 @@
+module.exports = function(...args) {
+  return import('./module.mjs').then(m => m.default.call(this, ...args))
+}
+const _meta = module.exports.meta = require('./module.json')
+module.exports.getMeta = () => Promise.resolve(_meta)

package/dist/module.d.mts

@@ -0,0 +1,134 @@
+import * as _nuxt_schema from '@nuxt/schema';
+import { Ref, ComputedRef } from 'vue';
+
+interface CobrasUser {
+    id: string;
+    email: string;
+    name: string;
+    role: 'admin' | 'user';
+    canAccessAdmin?: boolean;
+    isAutoAuth?: boolean;
+}
+interface CobrasAuthState {
+    /** Current authenticated user, null if not logged in */
+    user: CobrasUser | null;
+    /** Whether auth state has been checked */
+    initialized: boolean;
+    /** Whether a check is in progress */
+    loading: boolean;
+    /** Last error if any */
+    error: string | null;
+}
+type AuthMode = 'internal' | 'public';
+interface ModuleOptions {
+    /**
+     * URL of the Cobras auth service
+     * @default 'https://cobras-auth-app-production.up.railway.app'
+     */
+    authServiceUrl: string;
+    /**
+     * Authentication mode:
+     * - 'internal': Full SSO - all protected routes require authentication
+     * - 'public': Public site with optional auth for special features/dev tools
+     * @default 'public'
+     */
+    mode: AuthMode;
+    /**
+     * Site ID registered in cobras-auth (for site-specific permissions)
+     */
+    siteId?: string;
+    /**
+     * Site domain registered in cobras-auth (alternative to siteId)
+     */
+    siteDomain?: string;
+    /**
+     * Enable auth middleware on all routes by default
+     * In 'internal' mode, this protects all routes
+     * In 'public' mode, this just checks auth status silently
+     * @default false
+     */
+    globalMiddleware: boolean;
+    /**
+     * Routes that don't require authentication (only applies in 'internal' mode)
+     * @default ['/']
+     */
+    publicRoutes: string[];
+    /**
+     * Custom login page path (if you have one locally)
+     * Otherwise redirects to auth service
+     * @default '/login'
+     */
+    loginPath: string;
+    /**
+     * Enable dev tools panel for authenticated users (public mode)
+     * @default true
+     */
+    enableDevTools: boolean;
+    /**
+     * Keyboard shortcut to toggle dev tools
+     * @default 'ctrl+shift+d'
+     */
+    devToolsKey: string;
+    /**
+     * Cookie domain for auth cookies (usually set automatically)
+     */
+    cookieDomain?: string;
+    /**
+     * Enable debug logging
+     * @default false
+     */
+    debug: boolean;
+}
+declare module '@nuxt/schema' {
+    interface RuntimeConfig {
+        cobrasAuth: {
+            cookieDomain?: string;
+        };
+    }
+    interface PublicRuntimeConfig {
+        cobrasAuth: {
+            authServiceUrl: string;
+            mode: AuthMode;
+            siteId?: string;
+            siteDomain?: string;
+            publicRoutes: string[];
+            loginPath: string;
+            enableDevTools: boolean;
+            devToolsKey: string;
+            debug: boolean;
+        };
+    }
+}
+declare module '#app' {
+    interface NuxtApp {
+        $cobrasAuth: {
+            user: Ref<CobrasUser | null>;
+            isAuthenticated: ComputedRef<boolean>;
+            isInternalUser: ComputedRef<boolean>;
+            isAdmin: ComputedRef<boolean>;
+            mode: AuthMode;
+            checkAuth: () => Promise<void>;
+            login: (redirect?: string) => void;
+            logout: () => Promise<void>;
+        };
+    }
+}
+declare module 'vue' {
+    interface ComponentCustomProperties {
+        $cobrasAuth: {
+            user: Ref<CobrasUser | null>;
+            isAuthenticated: ComputedRef<boolean>;
+            isInternalUser: ComputedRef<boolean>;
+            isAdmin: ComputedRef<boolean>;
+            mode: AuthMode;
+            checkAuth: () => Promise<void>;
+            login: (redirect?: string) => void;
+            logout: () => Promise<void>;
+        };
+    }
+}
+
+declare const _default: _nuxt_schema.NuxtModule<ModuleOptions, ModuleOptions, false>;
+
+export { _default as default };
+export type { CobrasAuthState, CobrasUser, ModuleOptions };

package/dist/module.d.ts

@@ -0,0 +1,134 @@
+import * as _nuxt_schema from '@nuxt/schema';
+import { Ref, ComputedRef } from 'vue';
+
+interface CobrasUser {
+    id: string;
+    email: string;
+    name: string;
+    role: 'admin' | 'user';
+    canAccessAdmin?: boolean;
+    isAutoAuth?: boolean;
+}
+interface CobrasAuthState {
+    /** Current authenticated user, null if not logged in */
+    user: CobrasUser | null;
+    /** Whether auth state has been checked */
+    initialized: boolean;
+    /** Whether a check is in progress */
+    loading: boolean;
+    /** Last error if any */
+    error: string | null;
+}
+type AuthMode = 'internal' | 'public';
+interface ModuleOptions {
+    /**
+     * URL of the Cobras auth service
+     * @default 'https://cobras-auth-app-production.up.railway.app'
+     */
+    authServiceUrl: string;
+    /**
+     * Authentication mode:
+     * - 'internal': Full SSO - all protected routes require authentication
+     * - 'public': Public site with optional auth for special features/dev tools
+     * @default 'public'
+     */
+    mode: AuthMode;
+    /**
+     * Site ID registered in cobras-auth (for site-specific permissions)
+     */
+    siteId?: string;
+    /**
+     * Site domain registered in cobras-auth (alternative to siteId)
+     */
+    siteDomain?: string;
+    /**
+     * Enable auth middleware on all routes by default
+     * In 'internal' mode, this protects all routes
+     * In 'public' mode, this just checks auth status silently
+     * @default false
+     */
+    globalMiddleware: boolean;
+    /**
+     * Routes that don't require authentication (only applies in 'internal' mode)
+     * @default ['/']
+     */
+    publicRoutes: string[];
+    /**
+     * Custom login page path (if you have one locally)
+     * Otherwise redirects to auth service
+     * @default '/login'
+     */
+    loginPath: string;
+    /**
+     * Enable dev tools panel for authenticated users (public mode)
+     * @default true
+     */
+    enableDevTools: boolean;
+    /**
+     * Keyboard shortcut to toggle dev tools
+     * @default 'ctrl+shift+d'
+     */
+    devToolsKey: string;
+    /**
+     * Cookie domain for auth cookies (usually set automatically)
+     */
+    cookieDomain?: string;
+    /**
+     * Enable debug logging
+     * @default false
+     */
+    debug: boolean;
+}
+declare module '@nuxt/schema' {
+    interface RuntimeConfig {
+        cobrasAuth: {
+            cookieDomain?: string;
+        };
+    }
+    interface PublicRuntimeConfig {
+        cobrasAuth: {
+            authServiceUrl: string;
+            mode: AuthMode;
+            siteId?: string;
+            siteDomain?: string;
+            publicRoutes: string[];
+            loginPath: string;
+            enableDevTools: boolean;
+            devToolsKey: string;
+            debug: boolean;
+        };
+    }
+}
+declare module '#app' {
+    interface NuxtApp {
+        $cobrasAuth: {
+            user: Ref<CobrasUser | null>;
+            isAuthenticated: ComputedRef<boolean>;
+            isInternalUser: ComputedRef<boolean>;
+            isAdmin: ComputedRef<boolean>;
+            mode: AuthMode;
+            checkAuth: () => Promise<void>;
+            login: (redirect?: string) => void;
+            logout: () => Promise<void>;
+        };
+    }
+}
+declare module 'vue' {
+    interface ComponentCustomProperties {
+        $cobrasAuth: {
+            user: Ref<CobrasUser | null>;
+            isAuthenticated: ComputedRef<boolean>;
+            isInternalUser: ComputedRef<boolean>;
+            isAdmin: ComputedRef<boolean>;
+            mode: AuthMode;
+            checkAuth: () => Promise<void>;
+            login: (redirect?: string) => void;
+            logout: () => Promise<void>;
+        };
+    }
+}
+
+declare const _default: _nuxt_schema.NuxtModule<ModuleOptions, ModuleOptions, false>;
+
+export { _default as default };
+export type { CobrasAuthState, CobrasUser, ModuleOptions };

package/dist/module.json

@@ -0,0 +1,12 @@
+{
+  "name": "@cobras/auth-nuxt",
+  "configKey": "cobrasAuth",
+  "compatibility": {
+    "nuxt": ">=3.0.0"
+  },
+  "version": "1.0.0",
+  "builder": {
+    "@nuxt/module-builder": "0.8.4",
+    "unbuild": "unknown"
+  }
+}

package/dist/module.mjs

@@ -0,0 +1,112 @@
+import { defineNuxtModule, createResolver, addPlugin, addImports, addRouteMiddleware, addServerHandler, addComponent } from '@nuxt/kit';
+import { defu } from 'defu';
+
+const module = defineNuxtModule({
+  meta: {
+    name: "@cobras/auth-nuxt",
+    configKey: "cobrasAuth",
+    compatibility: {
+      nuxt: ">=3.0.0"
+    }
+  },
+  defaults: {
+    authServiceUrl: "https://cobras-auth-app-production.up.railway.app",
+    mode: "public",
+    siteId: void 0,
+    siteDomain: void 0,
+    globalMiddleware: false,
+    publicRoutes: [],
+    // Empty by default - user must explicitly set public routes
+    loginPath: "/login",
+    enableDevTools: true,
+    devToolsKey: "ctrl+shift+d",
+    cookieDomain: void 0,
+    debug: false
+  },
+  setup(options, nuxt) {
+    const resolver = createResolver(import.meta.url);
+    nuxt.options.runtimeConfig.public.cobrasAuth = defu(
+      nuxt.options.runtimeConfig.public.cobrasAuth || {},
+      {
+        authServiceUrl: options.authServiceUrl,
+        mode: options.mode,
+        siteId: options.siteId,
+        siteDomain: options.siteDomain,
+        publicRoutes: options.publicRoutes,
+        loginPath: options.loginPath,
+        enableDevTools: options.enableDevTools,
+        devToolsKey: options.devToolsKey,
+        debug: options.debug
+      }
+    );
+    nuxt.options.runtimeConfig.cobrasAuth = defu(
+      nuxt.options.runtimeConfig.cobrasAuth || {},
+      {
+        cookieDomain: options.cookieDomain
+      }
+    );
+    addPlugin({
+      src: resolver.resolve("./runtime/plugins/auth.client"),
+      mode: "client"
+    });
+    addPlugin({
+      src: resolver.resolve("./runtime/plugins/auth.server"),
+      mode: "server"
+    });
+    addImports([
+      {
+        name: "useCobrasAuth",
+        from: resolver.resolve("./runtime/composables/useCobrasAuth")
+      },
+      {
+        name: "useCobrasDevTools",
+        from: resolver.resolve("./runtime/composables/useCobrasDevTools")
+      },
+      {
+        name: "useCobrasMode",
+        from: resolver.resolve("./runtime/composables/useCobrasMode")
+      }
+    ]);
+    addRouteMiddleware({
+      name: "cobras-auth",
+      path: resolver.resolve("./runtime/middleware/auth"),
+      global: options.globalMiddleware
+    });
+    addRouteMiddleware({
+      name: "cobras-internal",
+      path: resolver.resolve("./runtime/middleware/internal"),
+      global: false
+    });
+    addServerHandler({
+      route: "/api/_cobras/verify",
+      handler: resolver.resolve("./runtime/server/api/verify.get")
+    });
+    addServerHandler({
+      route: "/api/_cobras/refresh",
+      handler: resolver.resolve("./runtime/server/api/refresh.post")
+    });
+    addServerHandler({
+      route: "/api/_cobras/logout",
+      handler: resolver.resolve("./runtime/server/api/logout.post")
+    });
+    addServerHandler({
+      route: "/api/_cobras/exchange",
+      handler: resolver.resolve("./runtime/server/api/exchange.post")
+    });
+    if (options.enableDevTools) {
+      addComponent({
+        name: "CobrasDevTools",
+        filePath: resolver.resolve("./runtime/components/CobrasDevTools.vue")
+      });
+    }
+    if (options.debug) {
+      console.log("[@cobras/auth-nuxt] Module configured:", {
+        mode: options.mode,
+        authServiceUrl: options.authServiceUrl,
+        globalMiddleware: options.globalMiddleware
+      });
+    }
+  }
+});
+
+export { module as default };