---
source_url: "https://github.com/hulyak/researchhub-ai"
title: "GitHub - hulyak/researchhub-ai: ResearchHub AI is an intelligent research assistant that demonstrates the full power of Auth0 for AI Agents, featuring secure authentication, fine-grained authorization, Token Vault integration, and human-in-the-loop approvals for sensitive operations. · GitHub"
mirrored_at: 2026-08-14T03:32:37.816Z
host: github.com
cited_in_42a: true
mirror_canonical: "https://index.42a.ai/github.com/hulyak/researchhub-ai"
---

> **Original source:** https://github.com/hulyak/researchhub-ai

**Secure Academic Research Assistant powered by Auth0 for AI Agents**

ResearchHub AI is an intelligent research assistant that demonstrates the full power of Auth0 for AI Agents, featuring secure authentication, fine-grained authorization, Token Vault integration, and human-in-the-loop approvals for sensitive operations.

   

## Features

### 🔐 Secure Authentication

-   **Auth0 Universal Login** with support for social, enterprise, and custom identity providers
-   OAuth 2.0 and OpenID Connect standards
-   Secure session management with Next.js

### 🔑 Token Vault Integration

-   Securely manage API credentials for third-party services (PubMed, ArXiv, Semantic Scholar, GitHub)
-   Automatic token refresh and lifecycle management
-   No hardcoded API keys in your codebase

### 📚 Fine-Grained Authorization (FGA)

-   **Document-level access control** for RAG pipeline
-   **Role-based permissions**: Undergraduate, PhD Student, Postdoc, Faculty, Principal Investigator
-   Ensures AI agents only access data users are authorized to view
-   Auth0 FGA integration for scalable authorization

### ✅ Human-in-the-Loop (CIBA) - Enterprise Feature

-   **Client-Initiated Backchannel Authentication** for sensitive operations
-   **⚠️ Requires Auth0 Enterprise Plan** to enable CIBA grant type
-   Fully implemented and ready for production use
-   User approval required for:
    -   Sharing unpublished research
    -   Submitting to preprint servers
    -   Granting external access
    -   Exporting lab data
-   Push notifications, SMS, or email approval via Auth0 Guardian

### 🔍 Multi-Source Research

-   **PubMed**: Biomedical and life sciences literature
-   **ArXiv**: Preprints across all scientific disciplines
-   **Semantic Scholar**: AI-powered paper search with citation analysis
-   Intelligent paper recommendations

### 🤖 AI-Powered RAG

-   Vector search with Pinecone
-   Claude (Anthropic) for natural language understanding
-   OpenAI embeddings for vector search
-   LangChain agent orchestration
-   Context-aware responses with citations

## Architecture

```
┌─────────────────────────────────────────────────────────────┐
│                         User Interface                        │
│              (Next.js 14 with Auth0 NextJS SDK)              │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                      Auth0 Authentication                     │
│          Universal Login │ SSO │ Social/Enterprise           │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                    ResearchHub AI Agent                       │
│          (LangChain + Claude/Anthropic + Auth0 AI SDK)       │
└─────────────────────────────────────────────────────────────┘
           │                  │                  │
           ▼                  ▼                  ▼
┌────────────────┐  ┌────────────────┐  ┌────────────────┐
│  Token Vault   │  │   Auth0 FGA    │  │      CIBA      │
│  API Tokens    │  │  Authorization │  │    Approval    │
└────────────────┘  └────────────────┘  └────────────────┘
           │                  │
           ▼                  ▼
┌────────────────────────────────────────────────────────┐
│                    Agent Tools                          │
│  PubMed │ ArXiv │ Semantic Scholar │ Document Manager  │
└────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────┐
│              RAG Pipeline (Pinecone + FGA)               │
│          Authorized Vector Search + Retrieval            │
└─────────────────────────────────────────────────────────┘
```

## Technology Stack

-   **Frontend**: Next.js 14, React, TypeScript, Tailwind CSS
-   **Authentication**: Auth0 for AI Agents SDK, @auth0/nextjs-auth0
-   **AI/ML**: Claude (Anthropic) for chat, OpenAI for embeddings, LangChain
-   **Vector Database**: Pinecone
-   **Database**: PostgreSQL with Prisma ORM
-   **Authorization**: Auth0 FGA (Fine-Grained Authorization)
-   **APIs**: PubMed, ArXiv, Semantic Scholar

## Prerequisites

-   Node.js 18+ and npm
-   PostgreSQL database
-   Auth0 account with AI Agents enabled
-   Anthropic API key (for Claude)
-   OpenAI API key (for embeddings)
-   Pinecone account

## Setup Instructions

### 1\. Clone the Repository

git clone https://github.com/hulyak/researchhub-ai.git
cd researchhub-ai
npm install

### 2\. Set Up Auth0

#### Create Auth0 Application

1.  Go to [Auth0 Dashboard](https://manage.auth0.com/)
2.  Create a new **Regular Web Application**
3.  Configure the following settings:
    -   **Allowed Callback URLs**: `http://localhost:3000/api/auth/callback`
    -   **Allowed Logout URLs**: `http://localhost:3000`
    -   **Allowed Web Origins**: `http://localhost:3000`

#### Enable Auth0 for AI Agents

1.  Navigate to **Auth0 for AI Agents** in the dashboard
2.  Enable AI Agents for your tenant
3.  Create a new AI Agent application
4.  Note your Client ID and Client Secret

#### Set Up Auth0 FGA

1.  Go to **Auth0 FGA** in the dashboard
2.  Create a new store
3.  Define the authorization model:

```
model
  schema 1.1

type user

type document
  relations
    define owner: [user]
    define writer: [user] or owner
    define reader: [user] or writer
    define viewer: [user] or reader

type role
  relations
    define member: [user]
```

4.  Note your Store ID

### 3\. Configure Environment Variables

Copy `.env.example` to `.env` and fill in your credentials:

cp .env.example .env

Edit `.env`:

# Auth0 Configuration
AUTH0\_SECRET\='use \[openssl rand -hex 32\] to generate'
AUTH0\_BASE\_URL\=http://localhost:3000
AUTH0\_ISSUER\_BASE\_URL\=https://YOUR\_TENANT.auth0.com
AUTH0\_CLIENT\_ID\=your\_client\_id
AUTH0\_CLIENT\_SECRET\=your\_client\_secret
AUTH0\_AUDIENCE\=your\_api\_audience

# Auth0 for AI Agents
AUTH0\_AI\_ISSUER\=https://YOUR\_TENANT.auth0.com
AUTH0\_AI\_CLIENT\_ID\=your\_ai\_client\_id
AUTH0\_AI\_CLIENT\_SECRET\=your\_ai\_client\_secret

# Auth0 FGA
AUTH0\_FGA\_STORE\_ID\=your\_fga\_store\_id
AUTH0\_FGA\_API\_URL\=https://api.us.fga.dev

# Anthropic (Claude for main chat)
ANTHROPIC\_API\_KEY\=your\_anthropic\_key

# OpenAI (for embeddings only)
OPENAI\_API\_KEY\=your\_openai\_key

# Pinecone
PINECONE\_API\_KEY\=your\_pinecone\_key
PINECONE\_ENVIRONMENT\=your\_environment
PINECONE\_INDEX\=researchhub-documents

# Database
DATABASE\_URL\=postgresql://user:password@localhost:5432/researchhub

### 4\. Set Up Database

# Create database
createdb researchhub

# Run migrations
npx prisma migrate dev --name init

# Generate Prisma client
npx prisma generate

### 5\. Set Up Pinecone

1.  Go to [Pinecone Console](https://app.pinecone.io/)
2.  Create a new index:
    -   **Name**: `researchhub-documents`
    -   **Dimensions**: `1536` (OpenAI ada-002)
    -   **Metric**: `cosine`

### 6\. Run the Application

npm run dev

Open [http://localhost:3000](http://localhost:3000/) in your browser.

## Usage Guide

### Authentication

1.  Click **Sign In** on the homepage
2.  Complete Auth0 Universal Login
3.  You'll be redirected to the chat interface

### Role Selection

On first login, your role defaults to **PhD Student**. To test different access levels with a single account:

1.  Go to **Settings** in the sidebar
2.  Scroll to **Role Management** section
3.  Click any role to switch instantly (page reloads with new role)

**Available Roles:**

1.  **UNDERGRADUATE** - Limited access to public materials
    
    -   Can view public research papers and preprints
    -   Cannot access lab documents or drafts
    -   Read-only access to shared public documents
2.  **PHD\_STUDENT** - Access to lab documents and research
    
    -   All undergraduate permissions
    -   Access to lab notes and shared research
    -   Can view datasets
    -   Access to lab's collaborative documents
3.  **POSTDOC** - Access to peer reviews and drafts
    
    -   All PhD student permissions
    -   Access to peer reviews
    -   Can view draft manuscripts
    -   Can collaborate across research groups
4.  **FACULTY** - Full access including grants
    
    -   All postdoc permissions
    -   Access to all document types including grant proposals
    -   Can view peer reviews and confidential materials
    -   Can share documents with others (requires CIBA approval)
    -   Can manage document access permissions
5.  **PRINCIPAL\_INVESTIGATOR** - Administrative access to all lab materials
    
    -   Full administrative access
    -   Access to all lab documents and materials
    -   Access to grant proposals and funding documents
    -   Can manage lab member permissions
    -   Oversees all lab research activities

**Important Note on Document Ownership:**

The system enforces role-based access control where users can always access their own documents, and role restrictions apply to viewing other researchers' documents. In a real lab, an undergraduate student would only see public papers from other researchers, while faculty members have full access to all lab documents. This ownership model ensures researchers maintain access to their own work regardless of role changes, while properly restricting access to others' sensitive materials.

### Using the Research Assistant

#### Search Research Databases

```
"Find recent papers on CRISPR gene editing"
"Search ArXiv for quantum computing papers from 2024"
"What are the most cited papers on neural networks?"
```

#### Manage Documents

```
"List my recent documents"
"Search my documents for machine learning"
"Get details of document abc123"
```

#### Advanced Features

```
"Recommend papers related to this one: [paper-id]"
"Share document xyz789 with user@example.com with read permission"
```

### Document Upload

1.  Navigate to **My Documents**
2.  Click **Upload Document**
3.  Fill in:
    -   Title
    -   Content
    -   Document Type (Research Paper, Grant Proposal, Lab Note, etc.)
    -   Visibility (Private, Lab Only, Public)
4.  Document is automatically:
    -   Stored in database
    -   Indexed in vector store
    -   Protected by FGA rules

### CIBA Approval Flow (Enterprise Feature)

**Note**: CIBA requires Auth0 Enterprise plan. The implementation is complete and can be activated by:

1.  Enabling CIBA grant type in Auth0 Dashboard
2.  Configuring Auth0 Guardian for push notifications
3.  Contacting Auth0 support for enterprise access

For sensitive actions (e.g., sharing unpublished research):

1.  Agent initiates CIBA request via `lib/auth0/ciba.ts`
2.  User receives approval notification (push/SMS/email)
3.  User approves or denies the action
4.  Agent proceeds based on decision
5.  Action logged in audit trail

## Security Features

### 1\. User Authentication

-   Secure OAuth 2.0 / OIDC flow
-   No passwords stored in application
-   Support for MFA via Auth0

### 2\. Token Management

-   API credentials stored securely in Token Vault
-   Automatic token refresh
-   No credentials in environment or code

### 3\. Authorization

-   Fine-grained access control with Auth0 FGA
-   Document-level permissions
-   Role-based access (5 levels)

### 4\. RAG Security

-   Vector search filtered by FGA rules
-   Users only see authorized documents
-   Real-time permission checks

### 5\. Audit Trail

-   All sensitive actions logged
-   CIBA approval records
-   User activity tracking

## Project Structure

```
researchhub-ai/
├── app/
│   ├── api/
│   │   ├── auth/[auth0]/    # Auth0 routes
│   │   ├── chat/            # Chat endpoint
│   │   ├── documents/       # Document management
│   │   └── user/            # User profile
│   ├── chat/                # Chat UI
│   ├── layout.tsx
│   ├── page.tsx             # Homepage
│   └── globals.css
├── lib/
│   ├── auth0/
│   │   ├── config.ts        # Auth0 configuration
│   │   ├── fga.ts           # FGA client
│   │   ├── token-vault.ts   # Token Vault client
│   │   └── ciba.ts          # CIBA implementation
│   ├── rag/
│   │   └── vector-store.ts  # Authorized vector search
│   ├── tools/
│   │   ├── pubmed.ts        # PubMed tool
│   │   ├── arxiv.ts         # ArXiv tool
│   │   ├── semantic-scholar.ts
│   │   └── document-manager.ts
│   ├── agent/
│   │   └── research-agent.ts # Main AI agent
│   └── db.ts                # Prisma client
├── prisma/
│   └── schema.prisma        # Database schema
├── package.json
├── tsconfig.json
└── README.md
```

## Auth0 for AI Agents Integration

This project demonstrates all three pillars of Auth0 for AI Agents:

### 1\. Authenticate the User

-   **Implementation**: `lib/auth0/config.ts`, `app/api/auth/[auth0]/route.ts`
-   **Features**: Universal Login, session management, user profile

### 2\. Control the Tools

-   **Implementation**: `lib/auth0/token-vault.ts`
-   **Features**: Secure API credential storage for PubMed, ArXiv, Semantic Scholar

### 3\. Limit Knowledge

-   **Implementation**: `lib/auth0/fga.ts`, `lib/rag/vector-store.ts`
-   **Features**: Document-level access control, role-based RAG filtering

### Bonus: CIBA (Enterprise Feature)

-   **Implementation**: `lib/auth0/ciba.ts`
-   **Features**: Human-in-the-loop approval for sensitive operations
-   **Note**: Fully implemented and production-ready. Requires Auth0 Enterprise plan to enable CIBA grant type. See code at `lib/auth0/ciba.ts` for integration with document sharing tool.

## API Endpoints

### Authentication

-   `GET /api/auth/login` - Initiate login
-   `GET /api/auth/logout` - Logout
-   `GET /api/auth/callback` - OAuth callback

### Chat

-   `POST /api/chat` - Send message to agent

### Documents

-   `POST /api/documents/upload` - Upload document
-   `GET /api/documents` - List documents

### User

-   `GET /api/user/profile` - Get user profile
-   `PATCH /api/user/profile` - Update profile

## Contributing

This is a demo project for the Auth0 for AI Agents Challenge. Feel free to fork and customize for your needs!

## Deployment

### Vercel (Recommended)

npm install -g vercel
vercel

Update Auth0 URLs to your production domain.

### Docker

FROM node:18-alpine
WORKDIR /app
COPY package\*.json ./
RUN npm ci --only=production
COPY . .
RUN npx prisma generate
RUN npm run build
CMD \["npm", "start"\]

## Troubleshooting

### Common Issues

**Issue**: `Invalid state` error during login

**Solution**: Clear browser cookies and ensure `AUTH0_SECRET` is set

**Issue**: FGA authorization fails

**Solution**: Verify FGA store ID and authorization model

**Issue**: Pinecone connection errors

**Solution**: Check API key and index name match configuration

**Issue**: Agent doesn't respond

**Solution**: Verify Anthropic API key and check rate limits

## License

MIT License - see LICENSE file for details

## Acknowledgments

-   Built for the **Auth0 for AI Agents Challenge**
-   Powered by Auth0, Anthropic (Claude), OpenAI (embeddings), LangChain, and Pinecone
-   Demonstrates secure AI agent architecture

## Links

-   [Auth0 for AI Agents Documentation](https://auth0.com/ai/docs)
-   [Auth0 Dashboard](https://manage.auth0.com/)

* * *

**ResearchHub AI** - Secure, intelligent research assistance with Auth0 for AI Agents