nocal-auth-sdk 0.1.0

package/README.md

@@ -0,0 +1,325 @@
+# Nocal Auth SDK
+
+A lightweight, secure client-side TypeScript/JavaScript SDK for implementing "Login with Nocal" in third-party applications via popup flow.
+
+## Features
+
+- ✅ **Popup-based OAuth flow** - Opens authentication in a centered popup window
+- ✅ **PostMessage protocol** - Secure communication between popup and parent window
+- ✅ **Origin verification** - Validates that messages come from trusted domain
+- ✅ **Memory cleanup** - Automatically removes event listeners and closes popup
+- ✅ **Full TypeScript support** - Fully typed for better DX
+- ✅ **CSRF protection** - Support for state parameter validation
+- ✅ **Zero dependencies** - Uses native browser APIs only
+
+## Installation
+
+### From npm (when published):
+
+```bash
+npm install nocal-auth-sdk
+```
+
+### From local development:
+
+```bash
+npm install /path/to/sdk
+# or
+npm pack
+npm install nocal-auth-sdk-0.1.0.tgz
+```
+
+## Quick Start
+
+### Basic Usage (Vanilla JavaScript/TypeScript)
+
+```typescript
+import { NocalAuth } from 'nocal-auth-sdk';
+
+// Initialize the SDK
+const nocalAuth = new NocalAuth({
+  clientId: 'your_client_id',
+  redirectUri: 'https://yourapp.example.com/auth/callback',
+  scope: 'openid profile email',
+  state: 'random_state_value' // CSRF protection
+});
+
+// Trigger login in popup
+async function handleLoginClick() {
+  const result = await nocalAuth.loginWithPopup({
+    width: 520,
+    height: 700
+  });
+
+  if (result.type === 'success') {
+    console.log('✅ Login successful!', result.data);
+    // result.data may contain: { token, id_token, code, user, profile, ... }
+    // Handle token storage, redirect, etc.
+  } else if (result.type === 'error') {
+    console.error('❌ Authentication failed:', result.error);
+    // Handle error: popup_blocked, unknown_error, etc.
+  } else if (result.type === 'closed') {
+    console.warn('⚠️ User closed popup before completing auth');
+  }
+}
+```
+
+### React Example
+
+```jsx
+import { useCallback } from 'react';
+import { NocalAuth } from 'nocal-auth-sdk';
+
+export function LoginButton() {
+  const handleLogin = useCallback(async () => {
+    const sdk = new NocalAuth({
+      clientId: process.env.REACT_APP_NOCAL_CLIENT_ID!,
+      redirectUri: `${window.location.origin}/auth/callback`,
+      scope: 'openid profile email',
+      state: generateRandomState() // Use crypto.randomUUID() or similar
+    });
+
+    const result = await sdk.loginWithPopup({ width: 520, height: 700 });
+
+    switch (result.type) {
+      case 'success':
+        // Store token
+        localStorage.setItem('nocal_token', result.data.token);
+        // Redirect or update app state
+        window.location.href = '/dashboard';
+        break;
+
+      case 'error':
+        alert(`Login failed: ${result.error}`);
+        break;
+
+      case 'closed':
+        console.log('User cancelled login');
+        break;
+    }
+  }, []);
+
+  return (
+    <button onClick={handleLogin} className="btn btn-primary">
+      🔐 Login with Nocal
+    </button>
+  );
+}
+
+function generateRandomState() {
+  return crypto.randomUUID?.() || Math.random().toString(36).substr(2);
+}
+```
+
+### Vue 3 Composition API Example
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { NocalAuth } from 'nocal-auth-sdk';
+
+const isLoading = ref(false);
+const error = ref('');
+
+const handleLogin = async () => {
+  isLoading.value = true;
+  error.value = '';
+
+  const sdk = new NocalAuth({
+    clientId: import.meta.env.VITE_NOCAL_CLIENT_ID,
+    redirectUri: `${window.location.origin}/auth/callback`,
+    scope: 'openid profile email'
+  });
+
+  const result = await sdk.loginWithPopup();
+
+  if (result.type === 'success') {
+    // Store token and redirect
+    localStorage.setItem('nocal_token', result.data.token);
+    window.location.href = '/dashboard';
+  } else if (result.type === 'error') {
+    error.value = result.error;
+  }
+
+  isLoading.value = false;
+};
+</script>
+
+<template>
+  <button @click="handleLogin" :disabled="isLoading">
+    {{ isLoading ? 'Logging in...' : '🔐 Login with Nocal' }}
+  </button>
+  <p v-if="error" class="error">{{ error }}</p>
+</template>
+```
+
+## API Reference
+
+### Constructor
+
+```typescript
+new NocalAuth(options: NocalAuthOptions)
+```
+
+**Options:**
+
+| Property | Type | Required | Default | Description |
+|----------|------|----------|---------|-------------|
+| `clientId` | `string` | ✅ | - | OAuth client ID from Nocal Auth |
+| `redirectUri` | `string` | ✅ | - | Callback URL after authentication |
+| `scope` | `string` | ❌ | - | OAuth scopes (e.g., `"openid profile email"`) |
+| `state` | `string` | ❌ | - | CSRF token (you should generate this) |
+| `issuerOrigin` | `string` | ❌ | `https://auth.nocal.dev` | Authorized domain for postMessage |
+| `popupFeatures` | `string` | ❌ | - | Extra window.open features |
+| `extraParams` | `Record<string, string>` | ❌ | - | Additional query parameters |
+
+### Methods
+
+#### `loginWithPopup(options?: PopupOptions): Promise<PopupResult<T>>`
+
+Opens a centered popup for authentication.
+
+**PopupOptions:**
+
+```typescript
+interface PopupOptions {
+  width?: number;    // Default: 500
+  height?: number;   // Default: 700
+  popupName?: string; // Default: 'nocal_auth_popup'
+}
+```
+
+**PopupResult:**
+
+```typescript
+type PopupResult<T> =
+  | { type: 'success'; data: T }      // Authentication succeeded
+  | { type: 'error'; error: string }  // Error occurred
+  | { type: 'closed' }                // User closed popup
+```
+
+**Returns:** `Promise<PopupResult<Record<string, any>>>`
+
+The `data` object typically contains:
+- `token` - Access token
+- `id_token` - OpenID Connect token (if `openid` in scope)
+- `code` - Authorization code (if using code flow)
+- `user` or `profile` - User information
+- Other fields based on your server configuration
+
+## Server-Side Requirements
+
+Your Nocal Auth server must:
+
+1. Accept the authorize request at `/authorize?client_id=...&redirect_uri=...`
+2. After successful authentication, post a message back to the popup's opener:
+
+```javascript
+// In the popup (auth.nocal.dev), after auth completes:
+window.opener.postMessage(
+  {
+    type: 'nocal_auth',
+    success: true,
+    data: {
+      token: 'access_token_value',
+      id_token: 'id_token_value', // optional
+      user: { id: '123', email: 'user@example.com' }
+    }
+  },
+  'https://yourapp.example.com' // client origin
+);
+```
+
+Or on error:
+
+```javascript
+window.opener.postMessage(
+  {
+    type: 'nocal_auth',
+    success: false,
+    error: 'invalid_grant' // or other error code
+  },
+  'https://yourapp.example.com'
+);
+```
+
+3. Ensure the origin in `postMessage` matches your client app's origin for browser security
+
+## Security Considerations
+
+### 1. **Origin Verification** ✅
+- SDK automatically verifies `event.origin === issuerOrigin` before accepting messages
+- Prevents clickjacking and XSS attacks from unauthorized domains
+
+### 2. **State Parameter** 🔐
+- Always generate a random `state` value client-side
+- Pass it to the SDK constructor
+- Server should validate it matches before returning auth result
+- Example: `crypto.randomUUID()` or `Math.random().toString(36)`
+
+### 3. **HTTPS Only** 🔒
+- Both client app and Nocal server must use HTTPS in production
+- Prevents man-in-the-middle attacks
+
+### 4. **Token Storage** 💾
+- Store tokens securely:
+  - **Recommended:** Session/memory (least persistent, most secure)
+  - **Alternative:** localStorage with HttpOnly cookie for sensitive data
+  - **Avoid:** localStorage for sensitive tokens without additional encryption
+
+### 5. **PKCE for SPA** (Future Enhancement)
+- For maximum security, implement PKCE (RFC 7636)
+- Protects against authorization code interception
+
+## Building from Source
+
+```bash
+# Install dependencies
+npm install
+
+# Build TypeScript to dist/
+npm run build
+
+# Output structure:
+# dist/
+#   ├── index.d.ts (TypeScript declarations)
+#   ├── index.esm.js (ES modules)
+#   └── index.cjs.js (CommonJS)
+```
+
+## Publishing to npm
+
+1. Update version in `package.json`
+2. Build: `npm run build`
+3. Test locally: `npm pack`
+4. Publish: `npm publish`
+
+For private registry:
+```bash
+npm publish --registry=https://your-private-registry.com
+```
+
+## Troubleshooting
+
+### Popup is blocked
+- Ensure login is triggered by direct user action (click event)
+- Some browsers block popups from async operations
+- Check browser console for popup blocker warnings
+
+### Message not received
+- Verify `issuerOrigin` matches exactly (protocol, domain, port)
+- Check Network tab in DevTools for postMessage calls
+- Ensure popup is not on cross-origin without proper headers
+
+### Token not persisting
+- Check localStorage/sessionStorage permissions
+- Verify HTTPS in production
+- Check cookie policies and SameSite attributes
+
+## License
+
+MIT
+
+## Support
+
+For issues or questions, open an issue on the Nocal Auth repository.

package/dist/NocalAuth.d.ts

@@ -0,0 +1,37 @@
+export type PopupResult<T = Record<string, unknown>> = {
+    type: "success";
+    data: T;
+} | {
+    type: "error";
+    error: string;
+} | {
+    type: "closed";
+};
+export interface NocalAuthOptions {
+    clientId: string;
+    redirectUri: string;
+    scope?: string;
+    state?: string;
+    issuerOrigin?: string;
+    responseType?: "code" | "token";
+    popupFeatures?: string;
+    extraParams?: Record<string, string | number | boolean | undefined>;
+}
+export interface PopupOptions {
+    width?: number;
+    height?: number;
+    popupName?: string;
+}
+export declare class NocalAuth {
+    private readonly clientId;
+    private readonly redirectUri;
+    private readonly scope?;
+    private readonly state?;
+    private readonly issuerOrigin;
+    private readonly responseType;
+    private readonly popupFeatures?;
+    private readonly extraParams?;
+    constructor(options: NocalAuthOptions);
+    private getAuthorizeUrl;
+    loginWithPopup(popupOptions?: PopupOptions): Promise<Record<string, unknown>>;
+}

package/dist/NocalAuth.js

@@ -0,0 +1,133 @@
+function buildQuery(params) {
+    const qs = Object.entries(params)
+        .filter(([, value]) => value !== undefined && value !== null && value !== "")
+        .map(([key, value]) => `${encodeURIComponent(key)}=${encodeURIComponent(String(value))}`)
+        .join("&");
+    return qs ? `?${qs}` : "";
+}
+export class NocalAuth {
+    constructor(options) {
+        if (!options.clientId) {
+            throw new Error("NocalAuth requires a clientId");
+        }
+        if (!options.redirectUri) {
+            throw new Error("NocalAuth requires a redirectUri");
+        }
+        this.clientId = options.clientId;
+        this.redirectUri = options.redirectUri;
+        this.scope = options.scope;
+        this.state = options.state;
+        this.issuerOrigin = (options.issuerOrigin ?? "https://auth.nocal.vn").replace(/\/$/, "");
+        this.responseType = options.responseType ?? "code";
+        this.popupFeatures = options.popupFeatures;
+        this.extraParams = options.extraParams;
+    }
+    getAuthorizeUrl() {
+        const baseUrl = `${this.issuerOrigin}/authorize`;
+        const query = buildQuery({
+            client_id: this.clientId,
+            redirect_uri: this.redirectUri,
+            response_type: this.responseType,
+            scope: this.scope,
+            state: this.state,
+            ...this.extraParams,
+        });
+        return `${baseUrl}${query}`;
+    }
+    async loginWithPopup(popupOptions = {}) {
+        if (typeof window === "undefined") {
+            throw new Error("loginWithPopup() can only be used in a browser environment");
+        }
+        const width = popupOptions.width ?? 500;
+        const height = popupOptions.height ?? 700;
+        const popupName = popupOptions.popupName ?? "nocal_auth_popup";
+        const dualScreenLeft = window.screenLeft ?? window.screenX ?? 0;
+        const dualScreenTop = window.screenTop ?? window.screenY ?? 0;
+        const screenWidth = window.innerWidth ??
+            document.documentElement.clientWidth ??
+            window.screen.width ??
+            1280;
+        const screenHeight = window.innerHeight ??
+            document.documentElement.clientHeight ??
+            window.screen.height ??
+            720;
+        const left = Math.round(dualScreenLeft + (screenWidth - width) / 2);
+        const top = Math.round(dualScreenTop + (screenHeight - height) / 2);
+        const features = [
+            `width=${width}`,
+            `height=${height}`,
+            `left=${left}`,
+            `top=${top}`,
+            "resizable=yes",
+            "scrollbars=yes",
+            this.popupFeatures ?? "",
+        ]
+            .filter(Boolean)
+            .join(",");
+        const popup = window.open(this.getAuthorizeUrl(), popupName, features);
+        if (!popup) {
+            throw new Error("POPUP_BLOCKED");
+        }
+        popup.focus?.();
+        return new Promise((resolve, reject) => {
+            let settled = false;
+            let checkInterval = undefined;
+            const cleanup = () => {
+                settled = true;
+                window.removeEventListener("message", handleMessage);
+                if (checkInterval) {
+                    clearInterval(checkInterval);
+                }
+            };
+            const rejectWith = (message) => {
+                if (settled)
+                    return;
+                cleanup();
+                reject(new Error(message));
+            };
+            const handleMessage = (event) => {
+                if (settled)
+                    return;
+                if (event.origin !== this.issuerOrigin) {
+                    return;
+                }
+                const payload = event.data;
+                if (!payload || typeof payload !== "object") {
+                    return;
+                }
+                const isValidPayload = payload.type === "nocal_auth" ||
+                    payload.source === "nocal_auth" ||
+                    Boolean(payload.code ||
+                        payload.token ||
+                        payload.access_token ||
+                        payload.id_token ||
+                        payload.error);
+                if (!isValidPayload) {
+                    return;
+                }
+                cleanup();
+                if (payload.success === false || payload.error) {
+                    rejectWith(typeof payload.error === "string" ? payload.error : "AUTH_FAILED");
+                    return;
+                }
+                const data = payload.data ?? {
+                    code: payload.code,
+                    token: payload.token ?? payload.access_token,
+                    id_token: payload.id_token,
+                    state: payload.state,
+                };
+                if (!data || Object.keys(data).length === 0) {
+                    rejectWith("AUTH_DATA_MISSING");
+                    return;
+                }
+                resolve(data);
+            };
+            window.addEventListener("message", handleMessage, false);
+            checkInterval = window.setInterval(() => {
+                if (popup.closed) {
+                    rejectWith("POPUP_CLOSED");
+                }
+            }, 500);
+        });
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { NocalAuth } from './NocalAuth';
+export type { NocalAuthOptions, PopupOptions, PopupResult } from './NocalAuth';

package/dist/index.js

@@ -0,0 +1 @@
+export { NocalAuth } from './NocalAuth';

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "nocal-auth-sdk",
+  "version": "0.1.0",
+  "description": "Nocal Auth - client-side SDK for Login with Nocal (popup flow)",
+  "type": "module",
+  "main": "dist/index.js",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "prepare": "npm run build"
+  },
+  "files": [
+    "dist"
+  ],
+  "keywords": [
+    "nocal",
+    "oauth",
+    "popup",
+    "auth",
+    "supabase"
+  ],
+  "author": "",
+  "license": "MIT",
+  "devDependencies": {
+    "typescript": "^5.0.0"
+  }
+}