deevoauth 1.4.5

package/README.md

@@ -0,0 +1,222 @@
+# deevo-oauth
+
+Official SDK for integrating **Deevo Account** OAuth 2.0 authentication into your applications. It allows you to add a seamless "Sign in with Deevo" experience, just like Google OAuth!
+
+## Installation
+
+Install the package via npm:
+
+```bash
+npm install deevo-oauth
+```
+
+## Quick Start
+
+### 1. Get Your Credentials
+
+You must register your application on the Deevo platform to get your API keys:
+1. Visit the [Deevo Developer Console](https://deevo.tech/developers).
+2. Sign in with your Deevo account.
+3. Click **"+ New App"**.
+4. Set your application name and the allowed Callback/Redirect URI.
+5. Save the generated `clientId` and `clientSecret`. Keep the secret secure and never expose it to your frontend!
+
+### 2. Configure the SDK
+
+In your backend or server-side code (Node.js, Express, Next.js, etc.), initialize the SDK with your credentials:
+
+```javascript
+const { DeevoAuth } = require('deevo-oauth');
+// or using ES Modules: import { DeevoAuth } from 'deevo-oauth';
+
+const deevo = new DeevoAuth({
+  clientId: 'YOUR_CLIENT_ID',          // e.g. from deevo.tech/developers
+  clientSecret: 'YOUR_CLIENT_SECRET',  // e.g. from deevo.tech/developers
+  redirectUri: 'http://localhost:3000/auth/callback', // The exact URL registered in the console
+});
+```
+
+### 3. Redirect Users to Sign In
+
+When a user clicks "Sign in with Deevo", redirect them to the Deevo authorization URL.
+
+**Express.js Example:**
+```javascript
+app.get('/auth/login', (req, res) => {
+  const loginUrl = deevo.getAuthUrl();
+  res.redirect(loginUrl);
+});
+```
+
+### 4. Handle the Callback & Exchange Code
+
+After the user successfully signs in, Deevo will redirect them back to your `redirectUri` with a special authorization `code` in the query parameters. You need to exchange this code for the user's profile information.
+
+**Express.js Example:**
+```javascript
+app.get('/auth/callback', async (req, res) => {
+  try {
+    const code = req.query.code;
+    
+    // This handles both the token exchange and fetching the user profile!
+    const { accessToken, user } = await deevo.handleCallback(code);
+    
+    /* user object looks like:
+      {
+        sub: 'firebase-uid-123',
+        name: 'John Doe',
+        email: 'john@example.com',
+        picture: 'https://...'
+      }
+    */
+
+    // Save the user data to your database or session
+    req.session.user = user;
+    req.session.accessToken = accessToken;
+    
+    // Redirect to your app's dashboard
+    res.redirect('/dashboard');
+  } catch (error) {
+    console.error('Authentication failed:', error);
+    res.redirect('/login?error=auth_failed');
+  }
+});
+```
+
+---
+
+## Usage in Next.js (App Router)
+
+If you are using Next.js (App Router), here is how you can easily integrate Deevo Auth via API routes:
+
+**`app/api/auth/login/route.js`**
+```javascript
+import { DeevoAuth } from 'deevo-oauth';
+import { redirect } from 'next/navigation';
+
+const deevo = new DeevoAuth({
+  clientId: process.env.DEEVO_CLIENT_ID,
+  clientSecret: process.env.DEEVO_CLIENT_SECRET,
+  redirectUri: `${process.env.NEXT_PUBLIC_BASE_URL}/api/auth/callback`,
+});
+
+export async function GET() {
+  // Redirect to Deevo Login Screen
+  return Response.redirect(deevo.getAuthUrl());
+}
+```
+
+**`app/api/auth/callback/route.js`**
+```javascript
+import { DeevoAuth } from 'deevo-oauth';
+import { NextResponse } from 'next/server';
+import { cookies } from 'next/headers';
+
+const deevo = new DeevoAuth({
+  clientId: process.env.DEEVO_CLIENT_ID,
+  clientSecret: process.env.DEEVO_CLIENT_SECRET,
+  redirectUri: `${process.env.NEXT_PUBLIC_BASE_URL}/api/auth/callback`,
+});
+
+export async function GET(request) {
+  const code = request.nextUrl.searchParams.get('code');
+  
+  try {
+    const { accessToken, user } = await deevo.handleCallback(code);
+    
+    // Example: Set HTTP-Only Cookie with the token
+    const cookieStore = await cookies();
+    cookieStore.set('deevo_session', accessToken, {
+      httpOnly: true,
+      secure: process.env.NODE_ENV === 'production',
+      maxAge: 3600 // 1 hour
+    });
+
+    return NextResponse.redirect(new URL('/dashboard', request.url));
+  } catch (error) {
+    return NextResponse.redirect(new URL('/login?error=invalid_code', request.url));
+  }
+}
+```
+
+---
+
+## API Reference
+
+### `new DeevoAuth(config)`
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `clientId` | string | ✅ | Your registered OAuth client ID |
+| `clientSecret` | string | ✅ | Your private client secret (Do not leak this client-side!) |
+| `redirectUri` | string | ✅ | Registered callback URL where users are returned |
+| `authServerUrl` | string | ❌ | Override auth server (Default: `https://deevo.tech`) |
+| `scope` | string | ❌ | Space-separated scopes (Default: `'profile email'`) |
+
+### `deevo.getAuthUrl(options?)`
+Returns the fully-qualified login URL to redirect users to.
+```javascript
+const url = deevo.getAuthUrl({ state: 'random-csrf-token' });
+```
+
+### `deevo.exchangeCode(code)`
+Exchanges an authorization code for raw access tokens.
+```javascript
+const tokens = await deevo.exchangeCode(code);
+// => { access_token: '...', token_type: 'Bearer', expires_in: 3600 }
+```
+
+### `deevo.getUserInfo(accessToken)`
+Fetches the current user profile data using a valid Bearer token.
+```javascript
+const user = await deevo.getUserInfo(tokens.access_token);
+```
+
+### `deevo.handleCallback(code)`
+A convenience method that performs `exchangeCode` AND `getUserInfo` in one swift call.
+```javascript
+const { accessToken, user } = await deevo.handleCallback(code);
+```
+
+### `deevo.verifyToken(accessToken)`
+Verifies a token and returns user info. Ideal for protecting your internal API routes.
+```javascript
+const user = await deevo.verifyToken(req.headers.authorization.split(' ')[1]);
+```
+
+---
+
+## Express.js API Middleware
+The SDK comes with a built-in Express middleware to protect your private routes:
+
+```javascript
+const { DeevoAuth, deevoMiddleware } = require('deevo-oauth');
+
+const deevo = new DeevoAuth({ /* config */ });
+
+app.get('/api/protected-data', deevoMiddleware(deevo), (req, res) => {
+  // If the token is verified successfully, the user data will be injected into req.deevoUser
+  res.json({ message: "Welcome!", user: req.deevoUser });
+});
+```
+
+## Error Handling
+
+If an API call fails, the SDK will throw a `DeevoAuthError`. You can handle specific error codes:
+
+```javascript
+const { DeevoAuthError } = require('deevo-oauth');
+
+try {
+  const { user } = await deevo.handleCallback(code);
+} catch (error) {
+  if (error instanceof DeevoAuthError) {
+    console.error(`HTTP Status: ${error.statusCode}`);
+    console.error(`Error Code: ${error.code}`);
+    console.error(`Message: ${error.message}`);
+  }
+}
+```
+
+---
+**License**: MIT © [Deevo Systems](https://deevo.tech)

package/app/api/internal/create-user/route.js

@@ -0,0 +1,54 @@
+import { NextResponse } from 'next/server';
+import { db, auth } from '@/lib/firebase-admin';
+
+export async function POST(request) {
+  try {
+    const { idToken, fullName } = await request.json();
+
+    if (!idToken) {
+      return NextResponse.json({ error: 'missing_token' }, { status: 400 });
+    }
+
+    // Verify the Firebase ID token
+    const decodedToken = await auth.verifyIdToken(idToken);
+    const uid = decodedToken.uid;
+
+    // Get the full user record from Firebase Auth
+    const userRecord = await auth.getUser(uid);
+
+    // Build the user profile data
+    const userData = {
+      uid: uid,
+      email: userRecord.email || '',
+      fullName: fullName || userRecord.displayName || '',
+      avatarUrl: userRecord.photoURL || '',
+      emailVerified: userRecord.emailVerified || false,
+      provider: userRecord.providerData?.[0]?.providerId || 'unknown',
+      updatedAt: Date.now(),
+    };
+
+    // Check if user already exists
+    const userRef = db.collection('users').doc(uid);
+    const existingUser = await userRef.get();
+
+    if (existingUser.exists) {
+      // Update existing user (preserve createdAt)
+      const updateData = { ...userData };
+      delete updateData.uid; // Don't overwrite uid
+      await userRef.update(updateData);
+    } else {
+      // Create new user with createdAt
+      userData.createdAt = Date.now();
+      await userRef.set(userData);
+    }
+
+    return NextResponse.json({ success: true, uid });
+
+  } catch (error) {
+    console.error('Create User Error:', error);
+    return NextResponse.json(
+      { error: 'server_error', message: error.message },
+      { status: 500 }
+    );
+  }
+}

package/app/api/internal/developer/clients/route.js

@@ -0,0 +1,122 @@
+import { NextResponse } from 'next/server';
+import { db, auth } from '@/lib/firebase-admin';
+import crypto from 'crypto';
+
+// GET - List all OAuth clients for the authenticated user
+export async function GET(request) {
+  try {
+    const authHeader = request.headers.get('authorization');
+    if (!authHeader || !authHeader.startsWith('Bearer ')) {
+      return NextResponse.json({ error: 'unauthorized' }, { status: 401 });
+    }
+
+    const idToken = authHeader.split(' ')[1];
+    const decodedToken = await auth.verifyIdToken(idToken);
+    const uid = decodedToken.uid;
+
+    // Fetch clients owned by this user
+    const snapshot = await db.collection('oauth_clients')
+      .where('ownerId', '==', uid)
+      .get();
+
+    const clients = [];
+    snapshot.forEach((doc) => {
+      const data = doc.data();
+      clients.push({
+        id: doc.id,
+        name: data.name,
+        redirectUri: data.redirectUri,
+        createdAt: data.createdAt,
+      });
+    });
+
+    return NextResponse.json({ clients });
+
+  } catch (error) {
+    console.error('List Clients Error:', error);
+    return NextResponse.json({ error: 'server_error' }, { status: 500 });
+  }
+}
+
+// POST - Create a new OAuth client
+export async function POST(request) {
+  try {
+    const authHeader = request.headers.get('authorization');
+    if (!authHeader || !authHeader.startsWith('Bearer ')) {
+      return NextResponse.json({ error: 'unauthorized' }, { status: 401 });
+    }
+
+    const idToken = authHeader.split(' ')[1];
+    const decodedToken = await auth.verifyIdToken(idToken);
+    const uid = decodedToken.uid;
+
+    const { name, redirectUri } = await request.json();
+
+    if (!name || !redirectUri) {
+      return NextResponse.json({ error: 'missing_fields' }, { status: 400 });
+    }
+
+    // Generate client credentials
+    const clientId = crypto.randomBytes(16).toString('hex');
+    const clientSecret = `dv_${crypto.randomBytes(32).toString('hex')}`;
+
+    // Store in Firestore
+    await db.collection('oauth_clients').doc(clientId).set({
+      name,
+      redirectUri,
+      clientSecret,
+      ownerId: uid,
+      createdAt: Date.now(),
+    });
+
+    return NextResponse.json({
+      clientId,
+      clientSecret,
+      name,
+      redirectUri,
+    });
+
+  } catch (error) {
+    console.error('Create Client Error:', error);
+    return NextResponse.json({ error: 'server_error' }, { status: 500 });
+  }
+}
+
+// DELETE - Delete an OAuth client
+export async function DELETE(request) {
+  try {
+    const authHeader = request.headers.get('authorization');
+    if (!authHeader || !authHeader.startsWith('Bearer ')) {
+      return NextResponse.json({ error: 'unauthorized' }, { status: 401 });
+    }
+
+    const idToken = authHeader.split(' ')[1];
+    const decodedToken = await auth.verifyIdToken(idToken);
+    const uid = decodedToken.uid;
+
+    const { searchParams } = new URL(request.url);
+    const clientId = searchParams.get('clientId');
+
+    if (!clientId) {
+      return NextResponse.json({ error: 'missing_client_id' }, { status: 400 });
+    }
+
+    // Verify ownership
+    const clientDoc = await db.collection('oauth_clients').doc(clientId).get();
+    if (!clientDoc.exists) {
+      return NextResponse.json({ error: 'not_found' }, { status: 404 });
+    }
+
+    if (clientDoc.data().ownerId !== uid) {
+      return NextResponse.json({ error: 'forbidden' }, { status: 403 });
+    }
+
+    await db.collection('oauth_clients').doc(clientId).delete();
+
+    return NextResponse.json({ success: true });
+
+  } catch (error) {
+    console.error('Delete Client Error:', error);
+    return NextResponse.json({ error: 'server_error' }, { status: 500 });
+  }
+}

package/app/api/internal/generate-code/route.js

@@ -0,0 +1,41 @@
+import { NextResponse } from 'next/server';
+import { db, auth } from '@/lib/firebase-admin'; // From previous setup
+import crypto from 'crypto';
+
+export async function POST(request) {
+  try {
+    const { idToken, clientId, redirectUri } = await request.json();
+
+    // 1. Verify the Firebase user securely on the server
+    const decodedToken = await auth.verifyIdToken(idToken);
+    const uid = decodedToken.uid;
+    const email = decodedToken.email;
+
+    // 2. Validate the Client App
+    const clientRef = db.collection('oauth_clients').doc(clientId);
+    const clientDoc = await clientRef.get();
+
+    if (!clientDoc.exists) {
+      return NextResponse.json({ error: 'invalid_client' }, { status: 400 });
+    }
+
+    // 3. Generate a secure, random Authorization Code
+    const authCode = crypto.randomBytes(16).toString('hex');
+
+    // 4. Store the code in Firestore with a 5-minute expiration
+    await db.collection('oauth_codes').doc(authCode).set({
+      code: authCode,
+      clientId: clientId,
+      uid: uid,
+      email: email,
+      redirectUri: redirectUri,
+      expiresAt: Date.now() + 5 * 60 * 1000, // 5 mins from now
+    });
+
+    return NextResponse.json({ code: authCode });
+
+  } catch (error) {
+    console.error('Error generating auth code:', error);
+    return NextResponse.json({ error: 'server_error' }, { status: 500 });
+  }
+}

package/app/api/oauth/token/route.js

@@ -0,0 +1,115 @@
+import { NextResponse } from 'next/server';
+import { db, auth } from '@/lib/firebase-admin';
+import jwt from 'jsonwebtoken';
+
+export async function POST(request) {
+  try {
+    const body = await request.json();
+    const { grant_type, code, client_id, client_secret, redirect_uri } = body;
+
+    // Validate grant type
+    if (grant_type !== 'authorization_code') {
+      return NextResponse.json(
+        { error: 'unsupported_grant_type', message: 'Only authorization_code is supported' },
+        { status: 400 }
+      );
+    }
+
+    // Validate required fields
+    if (!code || !client_id || !redirect_uri) {
+      return NextResponse.json(
+        { error: 'invalid_request', message: 'Missing required fields: code, client_id, redirect_uri' },
+        { status: 400 }
+      );
+    }
+
+    // 1. Look up the auth code in Firestore
+    const codeRef = db.collection('oauth_codes').doc(code);
+    const codeDoc = await codeRef.get();
+
+    if (!codeDoc.exists) {
+      return NextResponse.json(
+        { error: 'invalid_grant', message: 'Authorization code not found or already used' },
+        { status: 400 }
+      );
+    }
+
+    const codeData = codeDoc.data();
+
+    // 2. Validate the code hasn't expired
+    if (Date.now() > codeData.expiresAt) {
+      await codeRef.delete(); // Clean up expired code
+      return NextResponse.json(
+        { error: 'invalid_grant', message: 'Authorization code has expired' },
+        { status: 400 }
+      );
+    }
+
+    // 3. Validate the client_id and redirect_uri match
+    if (codeData.clientId !== client_id) {
+      return NextResponse.json(
+        { error: 'invalid_client', message: 'Client ID mismatch' },
+        { status: 400 }
+      );
+    }
+
+    if (codeData.redirectUri !== redirect_uri) {
+      return NextResponse.json(
+        { error: 'invalid_grant', message: 'Redirect URI mismatch' },
+        { status: 400 }
+      );
+    }
+
+    // 4. Validate client_secret (if provided)
+    if (client_secret) {
+      const clientRef = db.collection('oauth_clients').doc(client_id);
+      const clientDoc = await clientRef.get();
+
+      if (!clientDoc.exists) {
+        return NextResponse.json(
+          { error: 'invalid_client', message: 'Client not found' },
+          { status: 400 }
+        );
+      }
+
+      const clientData = clientDoc.data();
+      if (clientData.clientSecret && clientData.clientSecret !== client_secret) {
+        return NextResponse.json(
+          { error: 'invalid_client', message: 'Invalid client secret' },
+          { status: 401 }
+        );
+      }
+    }
+
+    // 5. Delete the code (one-time use)
+    await codeRef.delete();
+
+    // 6. Generate a Deevo access token (JWT)
+    const accessToken = jwt.sign(
+      {
+        uid: codeData.uid,
+        email: codeData.email,
+        client_id: client_id,
+        iss: 'https://deevo.tech',
+        aud: client_id,
+      },
+      process.env.DEEVO_JWT_SECRET,
+      { expiresIn: '1h' }
+    );
+
+    // 7. Return the token response (OAuth 2.0 standard format)
+    return NextResponse.json({
+      access_token: accessToken,
+      token_type: 'Bearer',
+      expires_in: 3600,
+      scope: 'profile email',
+    });
+
+  } catch (error) {
+    console.error('Token Exchange Error:', error);
+    return NextResponse.json(
+      { error: 'server_error', message: 'Internal server error' },
+      { status: 500 }
+    );
+  }
+}

package/app/api/oauth/userinfo/route.js

@@ -0,0 +1,46 @@
+import { NextResponse } from 'next/server';
+import { db } from '@/lib/firebase-admin';
+import jwt from 'jsonwebtoken';
+
+export async function GET(request) {
+  try {
+    // Extract the Bearer token from the header
+    const authHeader = request.headers.get('authorization');
+    if (!authHeader || !authHeader.startsWith('Bearer ')) {
+      return NextResponse.json({ error: 'invalid_token' }, { status: 401 });
+    }
+
+    const token = authHeader.split(' ')[1];
+
+    // Verify the JWT was signed by Deevo
+    let decodedPayload;
+    try {
+      decodedPayload = jwt.verify(token, process.env.DEEVO_JWT_SECRET);
+    } catch (err) {
+      return NextResponse.json({ error: 'invalid_token', message: 'Token expired or malformed' }, { status: 401 });
+    }
+
+    // Fetch the canonical user profile from Firestore using the UID in the token
+    const userRef = db.collection('users').doc(decodedPayload.uid);
+    const userDoc = await userRef.get();
+
+    if (!userDoc.exists) {
+      return NextResponse.json({ error: 'user_not_found' }, { status: 404 });
+    }
+
+    const userData = userDoc.data();
+
+    // Return standard OpenID Connect / OAuth userinfo response
+    return NextResponse.json({
+      sub: decodedPayload.uid,
+      name: userData.fullName || '',
+      email: userData.email,
+      picture: userData.avatarUrl || '',
+      // Add any custom Deevo ecosystem claims here
+    });
+
+  } catch (error) {
+    console.error('UserInfo Error:', error);
+    return NextResponse.json({ error: 'server_error' }, { status: 500 });
+  }
+}