@pelican-identity/auth-core 1.2.0 → 1.2.2

package/README.md

@@ -0,0 +1,570 @@
+# Pelican Auth SDK
+
+A modern, event-driven JavaScript/TypeScript SDK for integrating Pelican Vault authentication into your web applications.
+
+## Features
+
+- 🎯 **Event-Driven Architecture** - Subscribe to authentication lifecycle events
+- 🔄 **Continuous Mode** - Automatic session restart for repeated authentication
+- 📱 **Multi-Platform** - Supports both QR code (desktop) and deep linking (mobile)
+- 🔐 **Secure** - End-to-end encrypted authentication using TweetNaCl
+- 🔌 **WebSocket Transport** - Real-time communication with Pelican Vault
+- 🎨 **Framework Agnostic** - Works with React, Vue, Svelte, or vanilla JS
+- 📦 **Type-Safe** - Full TypeScript support with comprehensive type definitions
+
+## Installation
+
+```bash
+npm @pelican-identity/sdk
+# or
+yarn add @pelican-identity/sdk
+# or
+pnpm add @pelican-identity/sdk
+```
+
+## Quick Start
+
+### Basic Usage
+
+```typescript
+import { PelicanAuth } from "@pelican-identity/sdk";
+
+// Initialize the SDK
+const auth = new PelicanAuth({
+  publicKey: "your-public-key",
+  projectId: "your-project-id",
+  authType: "login", // 'login' | 'signup' | 'id-verification'
+});
+
+// Listen for authentication success
+auth.on("success", (identity) => {
+  console.log("User authenticated:", identity);
+  // Handle successful authentication
+});
+
+// Listen for errors
+auth.on("error", (error) => {
+  console.error("Authentication failed:", error);
+});
+
+// Listen for QR code (desktop) or deep link (mobile)
+auth.on("qr", (qrDataUrl) => {
+  // Display QR code image
+  document.getElementById("qr").src = qrDataUrl;
+});
+
+auth.on("deeplink", (url) => {
+  // Redirect to Pelican Vault app
+  window.location.href = url;
+});
+
+// Start authentication
+auth.start();
+```
+
+## API Reference
+
+### Constructor
+
+```typescript
+new PelicanAuth(config: PelicanAuthConfig)
+```
+
+#### Configuration Options
+
+| Option           | Type                                       | Required | Default | Description                          |
+| ---------------- | ------------------------------------------ | -------- | ------- | ------------------------------------ |
+| `publicKey`      | `string`                                   | ✅ Yes   | -       | Your Pelican Vault public key        |
+| `projectId`      | `string`                                   | ✅ Yes   | -       | Your project identifier              |
+| `authType`       | `'login' \| 'signup' \| 'id-verification'` | ✅ Yes   | -       | Type of authentication flow          |
+| `continuousMode` | `boolean`                                  | ❌ No    | `false` | Auto-restart after successful auth   |
+| `forceQRCode`    | `boolean`                                  | ❌ No    | `false` | Force QR code even on mobile devices |
+
+### Methods
+
+#### `start(): Promise<void>`
+
+Initiates the authentication flow.
+
+```typescript
+await auth.start();
+```
+
+#### `stop(): void`
+
+Stops the authentication flow and cleans up resources.
+
+```typescript
+auth.stop();
+```
+
+#### `on<K>(event: K, callback: Listener<K>): () => void`
+
+Subscribe to authentication events. Returns an unsubscribe function.
+
+```typescript
+const unsubscribe = auth.on("success", (identity) => {
+  console.log(identity);
+});
+
+// Later: unsubscribe
+unsubscribe();
+```
+
+#### `destroy(): void`
+
+Completely destroys the SDK instance, removing all listeners and cleanup.
+
+```typescript
+auth.destroy();
+```
+
+### Events
+
+The SDK emits the following events:
+
+#### `state`
+
+Emitted when the authentication state changes.
+
+```typescript
+auth.on("state", (state) => {
+  console.log("Current state:", state);
+});
+```
+
+**States:**
+
+- `idle` - Initial state
+- `initializing` - Fetching relay server
+- `awaiting-pair` - Waiting for mobile device to scan
+- `paired` - Device connected
+- `authenticated` - User authenticated
+- `confirmed` - Authentication confirmed
+- `terminated` - Session ended
+- `error` - Error occurred
+
+#### `success`
+
+Emitted when authentication succeeds.
+
+```typescript
+auth.on("success", (identity: IdentityResult) => {
+  console.log("User ID:", identity.user_id);
+  console.log("Email:", identity.user_data.email.value);
+  console.log("Phone:", identity.user_data.phone.number);
+  console.log("First Name:", identity.user_data.first_name);
+
+  console.log("ID Verification:", identity.id_verification);
+});
+```
+
+**IdentityResult:**
+
+```typescript
+interface IdentityResult {
+  user_id: string;
+  user_data: IUserData;
+  id_verification: IKycData;
+  id_downloadurls?: { front_of_card?: string; back_of_card?: string };
+}
+```
+
+#### `error`
+
+Emitted when an error occurs.
+
+```typescript
+auth.on("error", (error: Error) => {
+  console.error("Error:", error.message);
+});
+```
+
+#### `qr`
+
+Emitted on desktop with QR code data URL.
+
+```typescript
+auth.on("qr", (dataUrl: string) => {
+  // Display in an <img> tag
+  document.getElementById("qr").src = dataUrl;
+});
+```
+
+#### `deeplink`
+
+Emitted on mobile with deep link URL.
+
+```typescript
+auth.on("deeplink", (url: string) => {
+  // Open Pelican Vault app
+  window.location.href = url;
+  // Or use as href in a button
+  document.getElementById("login-btn").href = url;
+});
+```
+
+## Usage Examples
+
+### React Hook
+
+```typescript
+import { useEffect, useState } from "react";
+import { PelicanAuth } from "@pelican-identity/sdk";
+
+function usePelicanAuth(config) {
+  const [state, setState] = useState("idle");
+  const [qrCode, setQrCode] = useState(null);
+  const [deepLink, setDeepLink] = useState(null);
+  const [error, setError] = useState(null);
+
+  useEffect(() => {
+    const auth = new PelicanAuth(config);
+
+    auth.on("state", setState);
+    auth.on("qr", setQrCode);
+    auth.on("deeplink", setDeepLink);
+    auth.on("error", setError);
+
+    auth.on("success", (identity) => {
+      console.log("Authenticated:", identity);
+      config.onSuccess?.(identity);
+    });
+
+    return () => auth.destroy();
+  }, []);
+
+  return { state, qrCode, deepLink, error };
+}
+
+// Usage
+function LoginButton() {
+  const { state, qrCode, deepLink } = usePelicanAuth({
+    publicKey: "your-key",
+    projectId: "your-project",
+    authType: "login",
+    onSuccess: (identity) => {
+      // Handle login
+    },
+  });
+
+  if (qrCode) {
+    return <img src={qrCode} alt="Scan to login" />;
+  }
+
+  if (deepLink) {
+    return <a href={deepLink}>Open Pelican App</a>;
+  }
+
+  return <button onClick={() => auth.start()}>Login</button>;
+}
+```
+
+### Vue Composition API
+
+```vue
+<script setup>
+import { ref, onMounted, onUnmounted } from "vue";
+import { PelicanAuth } from "@pelican-identity/pelican-sdk";
+
+const props = defineProps(["publicKey", "projectId", "authType"]);
+const emit = defineEmits(["success", "error"]);
+
+const state = ref("idle");
+const qrCode = ref(null);
+const deepLink = ref(null);
+
+let auth;
+
+onMounted(() => {
+  auth = new PelicanAuth({
+    publicKey: props.publicKey,
+    projectId: props.projectId,
+    authType: props.authType,
+  });
+
+  auth.on("state", (s) => (state.value = s));
+  auth.on("qr", (qr) => (qrCode.value = qr));
+  auth.on("deeplink", (link) => (deepLink.value = link));
+  auth.on("success", (identity) => emit("success", identity));
+  auth.on("error", (err) => emit("error", err));
+
+  auth.start();
+});
+
+onUnmounted(() => {
+  auth?.destroy();
+});
+</script>
+
+<template>
+  <div>
+    <img v-if="qrCode" :src="qrCode" alt="QR Code" />
+    <a v-else-if="deepLink" :href="deepLink">Open App</a>
+    <p v-else>{{ state }}</p>
+  </div>
+</template>
+```
+
+### Vanilla JavaScript
+
+```javascript
+import { PelicanAuth } from "@pelican-identity/sdk";
+
+// Create container
+const container = document.getElementById("auth-container");
+
+// Initialize
+const auth = new PelicanAuth({
+  publicKey: "your-key",
+  projectId: "your-project",
+  authType: "login",
+});
+
+// Handle QR code
+auth.on("qr", (dataUrl) => {
+  container.innerHTML = `
+    <img src="${dataUrl}" alt="Scan to login" />
+    <p>Scan with Pelican Vault app</p>
+  `;
+});
+
+// Handle deep link
+auth.on("deeplink", (url) => {
+  container.innerHTML = `
+    <a href="${url}" class="btn">Open Pelican App</a>
+  `;
+});
+
+// Handle success
+auth.on("success", (identity) => {
+  console.log("Logged in as:", identity.user_id);
+  // Redirect or update UI
+  window.location.href = "/dashboard";
+});
+
+// Handle errors
+auth.on("error", (error) => {
+  container.innerHTML = `
+    <p class="error">${error.message}</p>
+    <button onclick="auth.start()">Retry</button>
+  `;
+});
+
+// Start authentication
+auth.start();
+
+// Cleanup on page unload
+window.addEventListener("beforeunload", () => {
+  auth.destroy();
+});
+```
+
+## Advanced Features
+
+### Continuous Mode
+
+Automatically restart authentication sessions after completion. Useful for kiosks or multi-user scenarios.
+
+```typescript
+const auth = new PelicanAuth({
+  publicKey: "your-key",
+  projectId: "your-project",
+  authType: "login",
+  continuousMode: true, // Enable continuous mode
+});
+
+auth.on("success", (identity) => {
+  // Process user
+  console.log("User authenticated:", identity);
+  // Session will automatically restart after ~300ms
+});
+
+auth.start();
+```
+
+### Force QR Code on Mobile
+
+By default, mobile devices use deep links. Force QR code display instead:
+
+```typescript
+const auth = new PelicanAuth({
+  publicKey: "your-key",
+  projectId: "your-project",
+  authType: "login",
+  forceQRCode: true, // Show QR even on mobile
+});
+```
+
+### Session Recovery
+
+The SDK automatically handles session recovery when users return from the Pelican Vault app:
+
+```typescript
+// Session is automatically cached when deep link is opened
+auth.on("deeplink", (url) => {
+  // User clicks and goes to Pelican app
+  window.location.href = url;
+});
+
+// When user returns (visibility change), session is recovered automatically
+// Success event will fire if authentication completed
+auth.on("success", (identity) => {
+  console.log("Recovered session:", identity);
+});
+```
+
+### State Machine Tracking
+
+Track the complete authentication lifecycle:
+
+```typescript
+auth.on("state", (state) => {
+  switch (state) {
+    case "idle":
+      console.log("Ready to start");
+      break;
+    case "initializing":
+      console.log("Connecting to server...");
+      break;
+    case "awaiting-pair":
+      console.log("Waiting for device...");
+      break;
+    case "paired":
+      console.log("Device connected!");
+      break;
+    case "authenticated":
+      console.log("User authenticated!");
+      break;
+    case "confirmed":
+      console.log("Session confirmed");
+      break;
+    case "error":
+      console.log("Error occurred");
+      break;
+  }
+});
+```
+
+## Error Handling
+
+The SDK provides detailed error information:
+
+```typescript
+auth.on("error", (error) => {
+  console.error("Error type:", error.message);
+
+  // Common errors:
+  // - "Failed to fetch relay URL" - Server connection issue
+  // - "WebSocket connection failed" - Network issue
+  // - "Invalid authentication payload" - Data corruption
+  // - "Failed to decrypt authentication data" - Crypto error
+  // - "Authenticating device terminated the connection" - User cancelled
+  // - "Session recovery failed" - Invalid cached session
+});
+```
+
+## Security Considerations
+
+1. **Public Key and Project ID**: It is recommended to use environment variables or fetch from a secure server for production.
+2. **HTTPS Required**: Always use HTTPS in production
+3. **Session Expiry**: Sessions expire after 5 minutes by default
+4. **End-to-End Encryption**: All data is encrypted using TweetNaCl (NaCl crypto)
+5. **No Password Storage**: Authentication happens entirely through the Pelican Vault app
+
+## Browser Support
+
+- Chrome/Edge 90+
+- Firefox 88+
+- Safari 14+
+- Opera 76+
+
+**Required APIs:**
+
+- WebSocket
+- Crypto API (`crypto.randomUUID()`)
+- sessionStorage
+- Visibility API
+
+## Troubleshooting
+
+### QR Code Not Displaying
+
+```typescript
+auth.on("qr", (dataUrl) => {
+  if (!dataUrl) {
+    console.error("QR code generation failed");
+  }
+});
+```
+
+### WebSocket Connection Issues
+
+```typescript
+// Check network connectivity
+auth.on("error", (error) => {
+  if (error.message.includes("WebSocket")) {
+    console.log("Check network connection");
+    // Retry logic
+    setTimeout(() => auth.start(), 5000);
+  }
+});
+```
+
+### Session Recovery Not Working
+
+Ensure visibility change detection is working:
+
+```typescript
+document.addEventListener("visibilitychange", () => {
+  console.log("Visibility changed:", document.visibilityState);
+});
+```
+
+## TypeScript Support
+
+Full TypeScript definitions included:
+
+```typescript
+import type {
+  IEmail,
+  IKycData,
+  IPhone,
+  IUserData,
+  IdentityResult,
+  IdCardTypes,
+} from "@pelican-identity/sdk";
+import {
+  AuthType,
+  ISocketMessage,
+  PelicanAuthConfig,
+  PelicanAuthEventMap,
+  PelicanAuthState,
+} from "@pelican-identity/sdk";
+
+const config: PelicanAuthConfig = {
+  publicKey: "your-key",
+  projectId: "your-project",
+  authType: "login",
+};
+
+const auth = new PelicanAuth(config);
+
+auth.on("success", (identity: IdentityResult) => {
+  const userId: string = identity.user_id;
+});
+```
+
+## License
+
+MIT
+
+## Support
+
+- Documentation: https://docs.pelicanidentity.com
+- Issues: https://github.com/pelican-identity/sdk/issues
+- Email: support@pelicanidentity.com
+
+## Changelog
+
+See [CHANGELOG.md](CHANGELOG.md) for release history.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pelican-identity/auth-core",
-  "version": "1.2.0",
+  "version": "1.2.2",
   "description": "Framework-agnostic authentication SDK for Pelican Identity",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",