Change pkg to auth0 api (#1)

* allow more versions of partyserver

* 2.2.1

* minor change of impl

* 2.3.0

* remove the static getCredentials - not needed

* 3.0.0

* add experimental withownership mixin class

* 3.1.0

* second attempt to fix types

* 3.1.1

* add onAuthorizedConnect and onAuthorizedRequest

* 3.2.0

* improve readme

* 3.2.1

* fix on authorized request

* 3.2.2

* feat: add aliases

* 3.3.0

* fix issue with recreating server instance

* 3.3.1

* convert package to auth0 sdk

* convert package to auth0 sdk

Author: jfromaniello

README.md

@@ -1,6 +1,6 @@
 # Agents OAuth2 JWT Bearer
 
-A PartyServer mixin for adding OAuth 2.0 JWT Bearer Token authentication to your PartyServer applications.
+A PartyServer mixin for adding OAuth 2.0 JWT Bearer Token authentication to your PartyServer applications, with Auth0 support.
 
 It should work with:
 
@@ -9,16 +9,16 @@ It should work with:
 
 ## Overview
 
-This package provides a mixin that adds authentication functionality to a PartyServer server using [JSON Web Token (JWT) Profile for OAuth 2.0 Access Tokens](https://datatracker.ietf.org/doc/html/rfc9068). It allows you to secure your PartyServer applications by validating access tokens from requests and connections.
+This package provides a mixin that adds authentication functionality to a PartyServer server using [JSON Web Token (JWT) Profile for OAuth 2.0 Access Tokens](https://datatracker.ietf.org/doc/html/rfc9068). It allows you to secure your PartyServer applications by validating access tokens from requests and connections, with built-in support for Auth0.
 
 ## Installation
 
 ```bash
-npm install agents-oauth2-jwt-bearer
+npm install @auth0/auth0-cloudflare-agent-api
 # or
-yarn add agents-oauth2-jwt-bearer
+yarn add @auth0/auth0-cloudflare-agent-api
 # or
-pnpm add agents-oauth2-jwt-bearer
+pnpm add @auth0/auth0-cloudflare-agent-api
 ```
 
 ## Usage
@@ -27,12 +27,12 @@ pnpm add agents-oauth2-jwt-bearer
 
 ```typescript
 import { Server } from "partyserver";
-import { WithAuth } from "agents-oauth2-jwt-bearer";
+import { WithAuth } from "@auth0/auth0-cloudflare-agent-api";
 
 // Define your environment type
 type MyEnv = {
-  OIDC_ISSUER_URL: string;
-  OIDC_AUDIENCE: string;
+  AUTH0_DOMAIN: string;
+  AUTH0_AUDIENCE: string;
   // ... other environment variables
 };
 
@@ -41,21 +41,21 @@ class MyAuthenticatedServer extends WithAuth(Server<MyEnv>) {
   // Your server implementation
 }
 
-// Pass verify options as parameters to the mixin function
+// Pass options as parameters to the mixin function
 class MyAuthenticatedServer extends WithAuth(Server, {
-  // Optional: specify the audience and issuer, etc
-  verify: verifyOptions,
-  // Optional: allow unauthenticated requests and connections
+  // Optional: make authentication optional
   authRequired: false,
+  // Optional: provide a debug function
+  debug: (message, ctx) => console.log(message, ctx),
 }) {
   // Your server implementation
 }
 
 // Start the server
 const server = new MyAuthenticatedServer({
   env: {
-    OIDC_ISSUER_URL: "https://your-identity-provider.com",
-    OIDC_AUDIENCE: "your-api-audience",
+    AUTH0_DOMAIN: "your-tenant.auth0.com",
+    AUTH0_AUDIENCE: "your-api-audience",
     // ... other environment variables
   },
 });
@@ -73,7 +73,7 @@ class MyAuthenticatedServer extends WithAuth(Server<MyEnv>) {
   onAuthenticatedRequest(req: Request) {
     // Get the JWT claims from the token
     const claims = this.getClaims();
-    if (claims.sub !== expectedUserId) {
+    if (claims?.sub !== expectedUserId) {
       return new Response("You are not welcome", { status: 401 });
     }
   }
@@ -86,7 +86,19 @@ class MyAuthenticatedServer extends WithAuth(Server<MyEnv>) {
     const claims = this.getClaims();
 
     // Now you can use the claims to identify the user
-    console.log(`User ID: ${claims.sub}`);
+    console.log(`User ID: ${claims?.sub}`);
+
+    // You can also require specific scopes for certain operations
+    try {
+      await this.requireAuth({ scopes: "read:data" });
+      // The user has the required scope
+    } catch (error) {
+      if (error instanceof UnauthorizedError) {
+        return error.toResponse();
+      }
+      // Handle other errors
+      return new Response("Unknown error", { status: 500 });
+    }
 
     // Continue processing the request...
     return new Response("Hello authenticated user!");
@@ -109,7 +121,19 @@ class MyAuthenticatedServer extends WithAuth(Server<MyEnv>) {
     const claims = this.getClaims();
 
     // Use the claims in your connection handling logic
-    console.log(`Connected user: ${claims.sub}`);
+    console.log(`Connected user: ${claims?.sub}`);
+
+    // You can also require specific scopes for certain operations
+    try {
+      await this.requireAuth({ scopes: ["read:data", "write:data"] });
+      // The user has both required scopes
+    } catch (error) {
+      if (error instanceof UnauthorizedError) {
+        return error.terminateConnection(connection);
+      }
+      // Handle other errors
+      throw error;
+    }
   }
 
   onMessage(connection: Connection, message: unknown) {
@@ -120,7 +144,7 @@ class MyAuthenticatedServer extends WithAuth(Server<MyEnv>) {
     const claims = this.getClaims();
 
     // Use the claims in your message handling logic
-    console.log(`Message from user: ${claims.sub}`);
+    console.log(`Message from user: ${claims?.sub}`);
 
     // Process the message...
   }
@@ -132,8 +156,8 @@ class MyAuthenticatedServer extends WithAuth(Server<MyEnv>) {
 1. When a client makes a request or connection:
 
    - The mixin extracts the bearer token from the Authorization header or the `access_token` query parameter
-   - It validates the token using the JWKS from your identity provider
-   - It verifies the token's issuer and audience
+   - It validates the token using Auth0's token verification API
+   - It verifies the token's issuer and audience claims
 
 2. If validation succeeds:
 
@@ -148,26 +172,40 @@ class MyAuthenticatedServer extends WithAuth(Server<MyEnv>) {
 
 The `WithAuth` mixin requires the following environment variables:
 
-- `OIDC_ISSUER_URL`: The URL of the OpenID Connect issuer (your identity provider)
-- `OIDC_AUDIENCE`: The audience for the JWT, typically your API identifier
+- `AUTH0_DOMAIN`: Your Auth0 tenant domain (e.g., "your-tenant.auth0.com")
+- `AUTH0_AUDIENCE`: The audience for the JWT, typically your API identifier
+
+You can also configure the mixin with options:
+
+```typescript
+WithAuth(Server, {
+  // Make authentication optional (default: true)
+  authRequired: false,
+  // Optional debug function
+  debug: (message, context) => console.log(message, context),
+});
+```
 
 ## API Reference
 
-### `WithAuth(BaseClass)`
+### `WithAuth(BaseClass, options?)`
 
 A mixin factory function that adds authentication functionality to a PartyServer class.
 
 **Parameters:**
 
 - `BaseClass`: The base class to extend from. This should be a class that extends `Server`.
+- `options`: Optional configuration object:
+  - `authRequired`: Boolean indicating whether authentication is required (default: true)
+  - `debug`: Function for debugging (default: noop)
 
 **Returns:**
 
 - A new class that extends the base class with authentication capabilities.
 
 ### Methods
 
-#### `getCredentials(): TokenSet | void`
+#### `getCredentials(): TokenSet | undefined`
 
 Gets the token set associated with the current context.
 
@@ -178,13 +216,32 @@ Gets the token set associated with the current context.
   - `id_token`: Optional ID token (from `x-id-token` header)
   - `refresh_token`: Optional refresh token (from `x-refresh-token` header)
 
-#### `getClaims(reqOrConnection: Request | Connection): Record<string, unknown>`
+#### `getClaims(): Token | undefined`
 
 Gets the decoded JWT claims from the access token.
 
 **Returns:**
 
-- An object containing the JWT claims
+- An object containing the JWT claims or undefined if no token is available
+
+#### `requireAuth(options?: { scopes?: string | string[] }): Promise<TokenSet>`
+
+Requires authentication with optional scope checking.
+
+**Parameters:**
+
+- `options`: Optional configuration object:
+  - `scopes`: String or array of strings representing required scopes
+
+**Returns:**
+
+- A promise that resolves to the token set if authentication is successful
+
+**Throws:**
+
+- `UnauthorizedError`: If no valid token is present
+- `InvalidTokenError`: If the token is invalid
+- `InsufficientScopeError`: If the token doesn't have the required scopes
 
 ## Token Format
 
@@ -193,8 +250,106 @@ The mixin accepts tokens in the following formats:
 1. Authorization header: `Authorization: Bearer <token>`
 2. Query parameter: `?access_token=<token>`
 
+## Advanced Usage: WithOwnership Mixin
+
+### Overview
+
+The `WithOwnership` mixin adds ownership capabilities to a PartyServer that already has authentication provided by the `WithAuth` mixin. This is particularly useful for scenarios where you need to restrict access to resources based on ownership, such as private chats or user-specific data.
+
+### Key Features
+
+- Owner-based access control for connections and requests
+- Integration with Durable Objects for persistent ownership data
+- Automatic rejection of non-owner access attempts
+
+### Usage Example
+
+```typescript
+// Then add ownership with WithOwnership
+class MyServer extends WithOwnership(WithAuth(Server<MyEnv>), {
+  // Optional: provide a debug function
+  debug: (message, ctx) => console.log(message, ctx),
+}) {
+  // Your server implementation
+
+  // Optionally override authorization methods
+  async onAuthorizedConnect(connection, ctx) {
+    console.log("Owner connected:", this.getClaims()?.sub);
+    // Handle authorized connection
+  }
+
+  async onAuthorizedRequest(req) {
+    console.log("Owner made a request:", this.getClaims()?.sub);
+    // Handle authorized request
+  }
+}
+```
+
+### Ownership Methods
+
+#### `setOwner(owner: string, overwrite: boolean = false): Promise<void>`
+
+Sets the owner of the object. By default, it will throw an error if the owner is already set to a different user unless `overwrite` is set to `true`.
+
+**Parameters:**
+
+- `owner`: The user ID (sub from JWT claims) to set as the owner
+- `overwrite`: Optional boolean to allow overwriting an existing owner
+
+**Example:**
+
+```typescript
+// When initializing a new chat or resource
+async onCreate() {
+  const claims = this.getClaims();
+  if (claims?.sub) {
+    await this.setOwner(claims.sub);
+  }
+}
+```
+
+#### `getOwner(): Promise<string | undefined>`
+
+Gets the current owner of the object.
+
+**Returns:**
+
+- The user ID (sub) of the owner, or undefined if no owner is set
+
+**Example:**
+
+```typescript
+async checkOwnership() {
+  const owner = await this.getOwner();
+  console.log(`This resource is owned by: ${owner}`);
+}
+```
+
+### Authorization Flow
+
+1. When a client makes a request or connection:
+
+   - First, the authentication checks are performed by the `WithAuth` mixin
+   - Then, the ownership check verifies if the authenticated user is the owner
+
+2. If the ownership check succeeds:
+
+   - The `onAuthorizedConnect` or `onAuthorizedRequest` method is called
+   - The connection or request is allowed to proceed
+
+3. If the ownership check fails:
+   - For WebSocket connections: Connection is closed with code 1008 and message "This chat is not yours."
+   - For HTTP requests: A 403 Forbidden response is returned with message "This chat is not yours."
+
+### DurableObject Integration
+
+The `WithOwnership` mixin is designed to work with Cloudflare DurableObjects for storing ownership data. The mixin uses the DurableObject's storage API to persist ownership information.
+
+**Note:** If you're not using DurableObjects, you'll need to override the `setOwner` and `getOwner` methods to implement your own storage mechanism.
+
 ## References
 
+- This project uses the Auth0 API Client to verify access tokens: [@auth0/auth0-api-js](https://github.com/auth0/auth0-api-js)
 - This project is similar to other Auth0 middlewares like [node-oauth2-jwt-bearer](https://github.com/auth0/node-oauth2-jwt-bearer).
 - [Authentication on PartyKit](https://docs.partykit.io/guides/authentication/).
 

package.json

@@ -1,8 +1,7 @@
 {
-  "name": "@auth0/agents-oauth2-jwt-bearer",
-  "version": "2.2.0",
-  "private": true,
-  "description": "A PartyServer mixin for adding OAuth 2.0 JWT Bearer Token authentication to your PartyServer applications.",
+  "name": "@auth0/auth0-cloudflare-agent-api",
+  "version": "3.3.1",
+  "description": "A PartyServer mixin for adding Auth0 API authentication to your PartyServer applications.",
   "author": {
     "name": "Auth0 Inc.",
     "url": "https://auth0.com"
@@ -42,10 +41,10 @@
     "typescript-eslint": "^8.30.1",
     "vitest": "^3.1.1"
   },
-  "dependencies": {
-    "jose": "^6.0.10"
-  },
   "peerDependencies": {
-    "partyserver": "^0.0.67 || ^0.0.68"
+    "partyserver": ">=0.0.67 <0.0.72"
+  },
+  "dependencies": {
+    "@auth0/auth0-api-js": "^1.0.1"
   }
 }

src/bearer/errors.ts

@@ -2,6 +2,8 @@
  * Errors per https://tools.ietf.org/html/rfc6750#section-3.1
  */
 
+import { Connection } from "partyserver";
+
 /**
  * If the request lacks any authentication information,
  * the resource server SHOULD NOT include an error code or
@@ -16,6 +18,27 @@ export class UnauthorizedError extends Error {
     super(message);
     this.name = this.constructor.name;
   }
+
+  /**
+   * Respond with a 401 Unauthorized error.
+   * This is used for HTTP requests.
+   * @returns
+   */
+  toResponse() {
+    return new Response(null, {
+      status: this.statusCode,
+      headers: this.headers,
+    });
+  }
+
+  /**
+   * Terminate a websocket connection
+   * due an authorization error.
+   * @param connection -
+   */
+  terminateConnection(connection: Connection) {
+    connection.close(1008, this.message);
+  }
 }
 
 /**