nocal-auth-sdk 0.1.5 → 0.1.6

package/dist/NocalAuth.js

@@ -112,6 +112,7 @@ export class NocalAuth {
                     token: rawData.accessToken ?? rawData.token ?? rawData.access_token,
                     refreshToken: rawData.refreshToken,
                     user: rawData.user,
+                    state: rawData.state,
                 };
                 if (!data || Object.keys(data).length === 0) {
                     rejectWith("AUTH_DATA_MISSING");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nocal-auth-sdk",
-  "version": "0.1.5",
+  "version": "0.1.6",
   "description": "Nocal Auth - client-side SDK for Login with Nocal (popup flow)",
   "type": "module",
   "main": "dist/index.js",

package/README.md

@@ -1,325 +0,0 @@
-# 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.