{"id":29998948,"url":"https://github.com/auth0-lab/cloudflare-agents-starter","last_synced_at":"2025-08-05T04:39:20.398Z","repository":{"id":306100950,"uuid":"1000968688","full_name":"auth0-lab/cloudflare-agents-starter","owner":"auth0-lab","description":"A starter kit for building secure ai agents on Cloudflare with Auth0","archived":false,"fork":false,"pushed_at":"2025-07-23T15:51:03.000Z","size":2579,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-07-23T17:44:02.766Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/auth0-lab.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":"CODE-OF-CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-06-12T15:46:18.000Z","updated_at":"2025-07-23T15:51:07.000Z","dependencies_parsed_at":"2025-07-23T17:44:11.304Z","dependency_job_id":"aba1e1e3-ad32-43cc-abfa-b5ceada15abb","html_url":"https://github.com/auth0-lab/cloudflare-agents-starter","commit_stats":null,"previous_names":["auth0-lab/cloudflare-agents-starter"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/auth0-lab/cloudflare-agents-starter","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/auth0-lab%2Fcloudflare-agents-starter","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/auth0-lab%2Fcloudflare-agents-starter/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/auth0-lab%2Fcloudflare-agents-starter/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/auth0-lab%2Fcloudflare-agents-starter/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/auth0-lab","download_url":"https://codeload.github.com/auth0-lab/cloudflare-agents-starter/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/auth0-lab%2Fcloudflare-agents-starter/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":268836799,"owners_count":24314961,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-05T02:00:12.334Z","response_time":2576,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-08-05T04:39:19.547Z","updated_at":"2025-08-05T04:39:20.388Z","avatar_url":"https://github.com/auth0-lab.png","language":"TypeScript","funding_links":[],"categories":["Labs"],"sub_categories":[],"readme":"# 🤖 Chat Agent Starter Kit with Auth0 Authentication\n\n![agents-header](./public/cloudflare-agents-auth0-sm.png)\n\nA starter template for building AI-powered chat agents using Cloudflare's Agent platform, powered by [`agents`](https://www.npmjs.com/package/agents) and secured with Auth0 authentication. This project provides a foundation for creating interactive chat experiences with AI, complete with a modern UI, tool integration capabilities, and user authentication.\n\n## Features\n\n- 💬 Interactive chat interface with AI\n- 🔐 Auth0 authentication and authorization\n- 📜 Securely get access tokens for Federated Connections using [Auth0 Token Vault](https://auth0.com/docs/secure/tokens/token-vault/configure-token-vault)\n- 🙆‍♂️ Backchannel Authentication for **human-in-the-loop** interactions using [Auth0 CIBA](https://auth0.com/docs/get-started/authentication-and-authorization-flow/client-initiated-backchannel-authentication-flow/user-authentication-with-ciba)\n- 👤 User-specific chat history and management\n- 🛠️ Built-in tool system with human-in-the-loop confirmation\n- 📅 Advanced task scheduling (one-time, delayed, and recurring via cron)\n- 🌓 Dark/Light theme support\n- ⚡️ Real-time streaming responses\n- 🔄 State management and chat history\n- 🎨 Modern, responsive UI\n\n## Prerequisites\n\n- Cloudflare account with Workers \u0026 Workers AI enabled\n- OpenAI API key\n- Auth0 account with a configured:\n  - Web Application\n  - API (resource server)\n\n## Auth0 Configuration\n\n### Step 1: Create an Auth0 API\n\n1. Log in to your Auth0 dashboard\n2. Navigate to \"Applications \u003e APIs\" and click \"Create API\"\n3. Provide a name and identifier (audience)\n4. Note the API Identifier (audience) for later use\n\n### Step 2: Create an Auth0 Application\n\nNote: you can also use the default app.\n\n1. In your Auth0 dashboard, go to \"Applications\" and click \"Create Application\"\n2. Select \"Web Application\" as the application type\n3. Configure the following settings:\n   - Allowed Callback URLs: `http://localhost:3000/auth/callback` (development) and your production URL\n   - Allowed Logout URLs: `http://localhost:3000` (development) and your production URL\n4. Note your Domain, Client ID, and Client Secret for later use\n\n## Quick Start\n\n1. Create a new Cloudflare Workers project using the Auth0 starter template:\n\n```bash\nnpx create-cloudflare@latest --template auth0-lab/cloudflare-agents-starter\n```\n\n3. Set up your environment:\n\nCreate a `.dev.vars` file based on the example:\n\n```env\n# OpenAI API key\nOPENAI_API_KEY=sk-your-openai-api-key\n\n# Auth0 Configuration\n# trailing slash in ISSUER is important:\nAUTH0_DOMAIN=\"your-tenant.us.auth0.com/\"\nAUTH0_CLIENT_ID=\"your-auth0-client-id\"\nAUTH0_CLIENT_SECRET=\"your-auth0-client-secret\"\nAUTH0_SESSION_ENCRYPTION_KEY=\"generate-a-random-key-at-least-32-characters-long\"\nAUTH0_AUDIENCE=\"https://your-auth0-api-identifier\"\n\n# Application base URL\nBASE_URL=http://localhost:3000\n```\n\n4. Run locally:\n\n```bash\nnpm start\n```\n\n5. Deploy:\n\n```bash\nnpm run deploy\n```\n\n## Project Structure\n\n```\n├── src/\n│   ├── server.ts                # Main worker with auth configuration\n│   ├── chats.ts                 # Chat management functions using Cloudflare KV\n│   ├── agent/                   # Agent-related code\n│   │   ├── index.ts             # Chat agent implementation with Auth0 integration\n│   │   ├── tools.ts             # Tool definitions and implementations\n│   │   ├── utils.ts             # Agent utility functions\n│   │   ├── auth0-ai.ts          # Auth0 AI initialization and configuration\n│   │   └── shared.ts            # Shared constants and types\n│   ├── client/                  # Frontend client application\n│   │   ├── app.tsx              # Chat UI implementation\n│   │   ├── home.tsx             # Home page component\n│   │   ├── index.tsx            # Entry point for React app\n│   │   ├── Layout.tsx           # Layout component\n│   │   └── styles.css           # UI styling\n│   ├── components/              # UI components\n│   │   ├── auth0/               # Auth0-specific components\n│   │   ├── auth0-ai/            # Auth0-specific components\n│   │   ├── chatList/            # Chat list components\n│   │   └── ...                  # Other UI components\n│   └── hooks/                   # React hooks\n│       ├── useUser.tsx          # User authentication hook\n│       └── ...                  # Other custom hooks\n```\n\n## Authentication Flow\n\nThis starter kit uses Auth0 for authentication and authorization:\n\n1. Users log in using Auth0 credentials\n2. Auth0 provides JWT tokens for API authentication\n3. The Agent use the `WithAuth` mixin from the `agents-oauth2-jwt-bearer` package to validate the JWT token\n4. API requests and WebSocket connections are secured with the JWT token\n5. Each chat is associated with its owner (user ID) to ensure data isolation\n\n### Authentication Packages\n\nThis project utilizes two key npm packages for authentication:\n\n- [`@auth0/auth0-hono`](https://github.com/auth0-lab/auth0-hono) - Handles browser-based authentication flows, session management, and token handling for the web interface.\n- [`@auth0/auth0-cloudflare-agents-api`](https://github.com/auth0-lab/auth0-cloudflare-agents-api/) - Secures WebSocket connections and API endpoints for the agent, providing token validation and authorization for all agent interactions.\n- [`@auth0/ai`](https://github.com/auth0-lab/auth0-ai-js/) - Provides AI capabilities for the agent. Token Vault for Federated Connections, Backchannel Authorization, and more.\n\nThese packages work together to provide a comprehensive authentication solution that secures both the web interface and the underlying agent communication.\n\n## Auth0 AI Powerful Integrations\n\nThe example contains two powerful integrations with Auth0 AI:\n\n- **Token Vault**: Securely store and retrieve access tokens for Federated Connections, allowing the agent to access third-party APIs on behalf of the user.\n- **Backchannel Authentication**: Implement human-in-the-loop interactions using Client-Initiated Backchannel Authentication (CIBA) flow, allowing the agent to request user confirmation for actions that require human input.\n\nPrompts:\n\n- `Am I available next monday 9am?` - This messsage will call the [check-user-calendar](src/agent/auth0-ai-sample-tools/check-user-calendar.ts) which is wrapped by the `@auth0/ai` Authorizer. If the application can't access the user's calendar it will fire a popup window with the Authorization process. Once completed, the agent will be able to access the user's calendar and answer the question.\n- `Buy 100 shares of MSFT` - This message will call the [buy-stock](src/agent/auth0-ai-sample-tools/buy-stock.ts) tool which is wrapped by the `@auth0/ai` Backchannel Authorizer. The agent fires an authorization request to the user, who will receive a push notification on their device. The user can then approve or deny the request. If approved, the agent will execute the tool and \"buy the stock\".\n\nAnother interesting scenario is triggering the buy stock tool on a schedule. For example, you can ask the agent to \"buy 100 shares in 5 minutes\". The agent will schedule the tool execution using the Cloudflare agent Task Scheduler, which supports one-time, delayed, and recurring tasks via cron expressions. Once it executes the task, it will again fire the authorization request to the user, who can approve or deny the request.\n\n## Customization Guide\n\n### Adding New Tools\n\nAdd new tools in `src/agent/tools.ts` using the tool builder:\n\n```typescript\n// Example of a tool that requires confirmation\nconst searchDatabase = tool({\n  description: \"Search the database for user records\",\n  parameters: z.object({\n    query: z.string(),\n    limit: z.number().optional(),\n  }),\n  // No execute function = requires confirmation\n});\n\n// Example of an auto-executing tool\nconst getCurrentTime = tool({\n  description: \"Get current server time\",\n  parameters: z.object({}),\n  execute: async () =\u003e new Date().toISOString(),\n});\n```\n\nTo handle tool confirmations, add execution functions to the `executions` object:\n\n```typescript\nexport const executions = {\n  searchDatabase: async ({\n    query,\n    limit,\n  }: {\n    query: string;\n    limit?: number;\n  }) =\u003e {\n    // Implementation for when the tool is confirmed\n    const results = await db.search(query, limit);\n    return results;\n  },\n  // Add more execution handlers for other tools that require confirmation\n};\n```\n\n### Extending Auth0 Integration\n\nThe integration uses Hono's OpenID Connect middleware for authentication and session management. You can customize the authentication behavior in `src/server.ts`.\n\nThe agent uses the `WithAuth` mixin from `agents-oauth2-jwt-bearer` package to secure API endpoints and WebSocket connections. Each chat is associated with its owner through the `setOwner` method to ensure users can only access their own chats.\n\n## Learn More\n\n- [`@auth0/auth0-hono`](https://github.com/auth0-lab/auth0-hono)\n- [`@auth0/auth0-cloudflare-agents-api`](https://github.com/auth0-lab/auth0-cloudflare-agents-api/)\n- [`@auth0/ai`](https://github.com/auth0-lab/auth0-ai-js/)\n- [`agents`](https://github.com/cloudflare/agents/blob/main/packages/agents/README.md)\n- [Cloudflare Agents Documentation](https://developers.cloudflare.com/agents/)\n- [Cloudflare Workers Documentation](https://developers.cloudflare.com/workers/)\n- [Auth0 Documentation](https://auth0.com/docs/)\n\n## Feedback\n\n### Contributing\n\nWe appreciate feedback and contribution to this repo! Before you get started, please see the following:\n\n- [Auth0's general contribution guidelines](https://github.com/auth0/open-source-template/blob/master/GENERAL-CONTRIBUTING.md)\n- [Auth0's code of conduct guidelines](https://github.com/auth0/open-source-template/blob/master/CODE-OF-CONDUCT.md)\n\n### Raise an issue\n\nTo provide feedback or report a bug, please [raise an issue on our issue tracker](https://github.com/auth0-lab/cloudflare-agents-starter/issues).\n\n### Vulnerability Reporting\n\nPlease do not report security vulnerabilities on the public GitHub issue tracker. The [Responsible Disclosure Program](https://auth0.com/responsible-disclosure-policy) details the procedure for disclosing security issues.\n\n---\n\n\u003cp align=\"center\"\u003e\n  \u003cpicture\u003e\n    \u003csource media=\"(prefers-color-scheme: light)\" srcset=\"https://cdn.auth0.com/website/sdks/logos/auth0_light_mode.png\"   width=\"150\"\u003e\n    \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"https://cdn.auth0.com/website/sdks/logos/auth0_dark_mode.png\" width=\"150\"\u003e\n    \u003cimg alt=\"Auth0 Logo\" src=\"https://cdn.auth0.com/website/sdks/logos/auth0_light_mode.png\" width=\"150\"\u003e\n  \u003c/picture\u003e\n\u003c/p\u003e\n\u003cp align=\"center\"\u003eAuth0 is an easy to implement, adaptable authentication and authorization platform. To learn more checkout \u003ca href=\"https://auth0.com/why-auth0\"\u003eWhy Auth0?\u003c/a\u003e\u003c/p\u003e\n\u003cp align=\"center\"\u003e\nThis project is licensed under the Apache 2.0 license. See the \u003ca href=\"/LICENSE\"\u003e LICENSE\u003c/a\u003e file for more info.\u003c/p\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fauth0-lab%2Fcloudflare-agents-starter","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fauth0-lab%2Fcloudflare-agents-starter","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fauth0-lab%2Fcloudflare-agents-starter/lists"}