@gzl10/nexus-plugin-google-auth 0.1.0

package/README.md

@@ -0,0 +1,102 @@
+# @gzl10/nexus-plugin-google-auth
+
+Google authentication plugin for [Nexus BaaS](https://gitlab.gzl10.com/oss/nexus). Adds login via Google using OpenID Connect.
+
+## Features
+
+- OIDC Authorization Code Flow
+- Auto-registration or manual account linking
+- Google Workspace domain restriction (hd parameter)
+- Email domain allowlist
+
+## Requirements
+
+- `@gzl10/nexus-backend` >= 0.13.0
+- `@gzl10/nexus-sdk` >= 0.13.0
+- A Google Cloud project with OAuth 2.0 credentials
+
+## Installation
+
+```bash
+pnpm add @gzl10/nexus-plugin-google-auth
+```
+
+## 1. Configure Google Cloud
+
+In the [Google Auth Platform](https://console.cloud.google.com/auth/clients):
+
+1. Go to **Clients** > **Create Client** > **OAuth client ID**
+2. Set **Application type**: Web application
+3. Add **Authorized redirect URI**: `https://your-backend.com/api/v1/google_auth/callback`
+4. Download or copy the **Client ID** and **Client Secret** immediately
+
+> **Important:** Since June 2025, client secrets are masked after creation and cannot be retrieved later. Save them when you create the client.
+>
+> The redirect URI must point to your Nexus backend's callback endpoint, not the frontend.
+
+## 2. Configure Nexus
+
+Add environment variables:
+
+```env
+GOOGLE_CLIENT_ID=your-client-id
+GOOGLE_CLIENT_SECRET=your-client-secret
+```
+
+Register the plugin in your backend:
+
+```typescript
+import { start } from '@gzl10/nexus-backend'
+import { googleAuthPlugin } from '@gzl10/nexus-plugin-google-auth'
+
+await start({ plugins: [googleAuthPlugin] })
+```
+
+On first start, the plugin auto-seeds its configuration from the environment variables.
+
+## 3. Frontend
+
+The plugin registers an auth provider that nexus-ui picks up automatically. A "Sign in with Google" button appears on the login page.
+
+For custom frontends, redirect users to:
+
+```
+GET /api/v1/google_auth/authorize?redirect_uri=https://your-frontend.com/login
+```
+
+After authentication, the backend redirects back with tokens in the URL fragment:
+
+```
+https://your-frontend.com/login#accessToken=...&refreshToken=...
+```
+
+On error:
+
+```
+https://your-frontend.com/login#error=Your+account+does+not+exist
+```
+
+## Configuration
+
+The plugin creates a `google_auth_config` table on first run. Options:
+
+| Field | Default | Description |
+|-------|---------|-------------|
+| `enabled` | `true` | Enable/disable Google login |
+| `hosted_domain` | `null` | Restrict to a Google Workspace domain |
+| `default_role` | `VIEWER` | Role assigned to new users |
+| `allowed_domains` | `null` | JSON array of allowed email domains (null = all) |
+| `scopes` | `openid profile email` | OIDC scopes |
+
+## API Endpoints
+
+| Method | Endpoint | Auth | Description |
+|--------|----------|------|-------------|
+| GET | `/api/v1/google_auth/authorize` | No | Start OIDC flow |
+| GET | `/api/v1/google_auth/callback` | No | Handle OIDC callback |
+| GET | `/api/v1/google_auth/link` | Yes | Link existing account |
+| GET | `/api/v1/google_auth/status` | Yes | Check if Google is linked |
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,205 @@
+import { ConfigEntityDefinition, ModuleManifest, OidcState, ActionEntityDefinition, PluginManifest } from '@gzl10/nexus-sdk';
+export { IdTokenClaims, OidcClient, OidcDiscoveryDocument, OidcTokens, OidcUserInfo, createOidcClient, getOidcClient } from '@gzl10/nexus-sdk';
+
+/**
+ * Google Auth Configuration Types
+ */
+/**
+ * Google Auth config stored in database
+ */
+interface GoogleAuthConfig {
+    /** Enable/disable Google authentication */
+    enabled: boolean;
+    /** OIDC Client ID from Google Cloud Console */
+    client_id: string;
+    /** OIDC Client Secret (encrypted) */
+    client_secret: string;
+    /** Scopes to request (default: openid profile email) */
+    scopes: string;
+    /** Allowed email domains (JSON array, optional) */
+    allowed_domains: string | null;
+    /** Google Workspace hosted domain (hd parameter) */
+    hosted_domain: string | null;
+    /** Default role for new users */
+    default_role: string | null;
+}
+/**
+ * Config service interface
+ */
+interface ConfigService {
+    /** Get current config */
+    getConfig(): Promise<GoogleAuthConfig | null>;
+    /** Check if Google Auth is enabled */
+    isEnabled(): Promise<boolean>;
+}
+
+/**
+ * Google Auth Config Entity
+ *
+ * Stores OIDC configuration for Google authentication.
+ * Note: Google OIDC issuer is always https://accounts.google.com
+ */
+declare const googleAuthConfigEntity: ConfigEntityDefinition;
+
+declare function getConfigService(): ConfigService;
+declare function setConfigService(service: ConfigService): void;
+/**
+ * Google Auth Config Module
+ */
+declare const configModule: ModuleManifest;
+
+/**
+ * Google Auth Types
+ */
+
+/**
+ * Session result after successful authentication
+ */
+interface SessionResult {
+    accessToken: string;
+    refreshToken: string;
+    expiresIn: number;
+    user: {
+        id: string;
+        email: string;
+        name?: string;
+    };
+    /** Frontend URL to redirect user after auth (server-side flow) */
+    returnUrl?: string;
+}
+/**
+ * Google-specific OIDC state (extends base)
+ */
+interface GoogleAuthState extends OidcState {
+    /** User ID if linking account */
+    linkUserId?: string;
+    /** Frontend URL to redirect user after auth completes */
+    returnUrl?: string;
+}
+/**
+ * Subset of core AuthService used by this plugin.
+ * Registered as ctx.services.get('auth') by nexus-backend.
+ */
+interface CoreAuthService {
+    findUserById(id: string): Promise<{
+        id: string;
+        email: string;
+        name?: string;
+    } | null>;
+    findUserByEmail(email: string): Promise<{
+        id: string;
+        email: string;
+        name?: string;
+    } | null>;
+    createUser(data: {
+        email: string;
+        name?: string;
+        role?: string;
+    }): Promise<{
+        id: string;
+        email: string;
+        name?: string;
+    }>;
+    createTokens(user: {
+        id: string;
+    }): Promise<{
+        accessToken: string;
+        refreshToken: string;
+        expiresIn: number;
+    }>;
+    findIdentity(provider: string, providerUserId: string): Promise<AuthIdentity | undefined>;
+    findIdentitiesByUser(userId: string, provider?: string): Promise<AuthIdentity[]>;
+    linkIdentity(input: LinkIdentityInput): Promise<AuthIdentity>;
+    unlinkIdentity(provider: string, providerUserId: string): Promise<boolean>;
+    updateIdentityLogin(provider: string, providerUserId: string): Promise<void>;
+}
+/**
+ * External auth identity (mirrors core auth_identities table)
+ */
+interface AuthIdentity {
+    id: string;
+    user_id: string;
+    provider: string;
+    provider_user_id: string;
+    provider_email: string | null;
+    metadata: Record<string, unknown> | null;
+    linked_at: string;
+    last_login_at: string | null;
+}
+/**
+ * Input for linking an external identity
+ */
+interface LinkIdentityInput {
+    userId: string;
+    provider: string;
+    providerUserId: string;
+    providerEmail?: string | null;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Auth service interface
+ */
+interface GoogleAuthService {
+    /** Generate authorization URL and state */
+    getAuthorizationUrl(redirectUri: string, linkUserId?: string, returnUrl?: string): Promise<{
+        url: string;
+        state: string;
+    }>;
+    /** Handle callback from Google */
+    handleCallback(code: string, state: string): Promise<SessionResult>;
+    /** Verify state is valid */
+    verifyState(state: string): Promise<GoogleAuthState | null>;
+    /** Clear state after use */
+    clearState(state: string): Promise<void>;
+}
+
+declare function getAuthService(): GoogleAuthService;
+declare function setAuthService(service: GoogleAuthService): void;
+
+/**
+ * Google Auth Controller
+ *
+ * Handles OIDC endpoints:
+ * - GET /google_auth/authorize - Start OIDC flow
+ * - GET /google_auth/callback - Handle OIDC callback (from Google redirect)
+ * - GET /google_auth/link - Link existing account (requires auth)
+ * - GET /google_auth/status - Check if Google is linked
+ */
+
+declare const authActions: ActionEntityDefinition[];
+
+/**
+ * Google Auth Module
+ *
+ * Provides OIDC authentication endpoints:
+ * - GET /google_auth/authorize - Start auth flow
+ * - GET /google_auth/callback - Handle callback
+ * - GET /google_auth/link - Link existing account
+ * - GET /google_auth/status - Check link status
+ */
+declare const authModule: ModuleManifest;
+
+/**
+ * Google Auth Plugin for Nexus.
+ *
+ * Provides OIDC authentication with Google for OAuth login.
+ *
+ * Features:
+ * - OIDC Authorization Code Flow
+ * - User auto-registration or linking
+ * - Google Workspace domain restriction (hd parameter)
+ * - Domain allowlist support
+ *
+ * @example
+ * ```typescript
+ * import { createNexus } from '@gzl10/nexus-backend'
+ * import { googleAuthPlugin } from '@gzl10/nexus-plugin-google-auth'
+ *
+ * const nexus = createNexus({
+ *   plugins: [googleAuthPlugin]
+ * })
+ * ```
+ */
+declare const googleAuthPlugin: PluginManifest;
+
+export { type AuthIdentity, type ConfigService, type CoreAuthService, type GoogleAuthConfig, type GoogleAuthService, type GoogleAuthState, type LinkIdentityInput, type SessionResult, authActions, authModule, configModule, googleAuthPlugin as default, getAuthService, getConfigService, googleAuthConfigEntity, googleAuthPlugin, setAuthService, setConfigService };