@japikey/cloudflare 0.1.0

package/README.md

@@ -0,0 +1,179 @@
+# @japikey/cloudflare
+
+This package generates Cloudflare worker routes and middleware to fully integrate japikeys into your app. You can create api keys, view, or delete them, and validate they are valid.
+This package is part of the larger @japikey ecosystem. See @japikey/japikey for more information.
+
+# Prerequisites
+
+Have an existing Cloudflare Worker application that has some other mechanism for authentication. When a user creates an API key, we only want to grant access for that user, after all! You'll also need a D1 database to store the API key information.
+
+# Installing japikey
+
+```bash
+npm install --save "@japikey/japikey"
+npm install --save "@japikey/cloudflare"
+```
+
+# Setting up your Worker
+
+Create a standard Cloudflare Worker that handles API key routes and JWKS endpoints:
+
+```ts
+import { D1Driver, UnauthorizedError } from '@japikey/cloudflare';
+import {
+  createApiKeyRouter,
+  createJWKSRouter,
+  isJWKSPath,
+  type CreateApiKeyRouterOptions,
+  type CreateApiKeyData,
+} from '@japikey/cloudflare';
+
+interface Env {
+  DB: D1Database;
+}
+
+async function getUserId(request: Request, env: Env): Promise<string> {
+  // This should integrate with your existing auth system
+  // For example, you might check for a session cookie or JWT token
+  // Example: Check for a user session
+  const session = request.headers.get('Authorization');
+  if (!session) {
+    throw new UnauthorizedError();
+  }
+
+  // Validate the session and extract user ID
+  // This is where you'd integrate with your auth system
+  const userId = await validateSession(session);
+  if (!userId) {
+    throw new UnauthorizedError();
+  }
+
+  return userId;
+}
+
+async function parseCreateApiKeyRequest(
+  request: Request,
+  env: Env
+): Promise<CreateApiKeyData> {
+  const body = await request.json();
+  const { expiresAt, scopes } = body;
+
+  // Add extra validation as desired
+  return {
+    expiresAt: new Date(expiresAt),
+    claims: { scopes }, // Any claims you want encoded in the token
+    databaseMetadata: {}, // Any extra things you want to store in the database
+  };
+}
+
+export default {
+  async fetch(request: Request, env: Env): Promise<Response> {
+    const url = new URL(request.url);
+
+    // Handle API key routes
+    if (url.pathname.startsWith('/api-keys')) {
+      const db = new D1Driver(env.DB);
+      await db.ensureTable();
+
+      const options: CreateApiKeyRouterOptions<Env> = {
+        getUserId,
+        parseCreateApiKeyRequest,
+        issuer: new URL('https://example.com/'),
+        aud: 'api-key',
+        db,
+        routePrefix: '/api-keys',
+      };
+
+      const apiKeyRouter = createApiKeyRouter(options);
+      return apiKeyRouter.fetch(request, env);
+    }
+
+    // Handle JWKS routes
+    const baseIssuer = new URL('https://example.com/');
+    if (isJWKSPath(request, baseIssuer)) {
+      const jwksRouter = createJWKSRouter(baseIssuer, db);
+      return jwksRouter.fetch(request, env);
+    }
+
+    // Handle other routes
+    return new Response('Not found', { status: 404 });
+  },
+};
+```
+
+## Details about the configuration
+
+There are two separate endpoint banks to implement. The apiKeyRouter handles the CRUD operations to create, list, and delete an api key.
+
+The jwksRouter handles any client that wants to validate the API key. It provides the public key data via the `.well-known/jwks.json` endpoint. These two endpoints do need to be configured in a compatible way, specifically around the issuer URL.
+
+The `issuer` passed into createApiKeyRouter MUST be the full URL corresponding to the root of the jwksRouter.
+
+For example, if your domain is `https://example.com` and you use the baseIssuer as `https://example.com`, your issuer MUST be `https://example.com`. The JWKS endpoint will be available at `https://example.com/{kid}/.well-known/jwks.json`.
+
+The issuer URL does not necessarily have anything to do with the URL that the apiKeyRouter is on. Your apiKeyRoute could be `https://example.com/api-keys` or `https://example.com/my/long/subpath` and that doesn't have any impact on the JWKS endpoint.
+
+Besides the issuer, the other critical parameter passed in is the `getUserId` function. That function MUST integrate with your existing authentication system. It MUST raise an exception if the user is not authenticated.
+
+You can throw any error that you want from the method. If you throw one of the errors provided by japikeys (such as `UnauthorizedError`), the router will make sure it gets converted to the proper HTTP status code, with a JSON body for clients.
+
+Lastly, the parseCreateApiKeyRequest lets you specify what the payload is to the CREATE endpoint (`POST /api-keys`). You at least need to pass back an expiredAt parameter. (You could always hardcode this to e.g. Date.now() + one year) for example. Any other data is up to your application needs. `claims` get encoded in the token themselves, and `databaseMetadata` goes in the database for any of your business logic later.
+
+# Setting up D1 Database
+
+You'll need to create a D1 database and bind it to your worker. In your `wrangler.toml`:
+
+```toml
+[[d1_databases]]
+binding = "DB"
+database_name = "japikey-db"
+database_id = "your-database-id"
+```
+
+The D1Driver will automatically create the required table when you call `ensureTable()`. The table structure is:
+
+```sql
+CREATE TABLE IF NOT EXISTS japikeys (
+  kid TEXT PRIMARY KEY,
+  user_id TEXT NOT NULL,
+  revoked INTEGER NOT NULL,
+  jwk TEXT NOT NULL,
+  metadata TEXT NOT NULL
+)
+```
+
+# Validating an API key
+
+Whether you're in the backend, or even on the browser frontend, verifying an API key is a simple process.
+
+```ts
+import { createGetJWKS, authenticate } from '@japikey/authenticate';
+
+const issuer = new URL('https://example.com/');
+const getJWKS = createGetJWKS(issuer);
+await authenticate(my_auth_token, { getJWKS, baseIssuer: issuer });
+```
+
+# API Endpoints
+
+The API key router provides the following endpoints:
+
+- `POST /api-keys` - Create a new API key
+- `GET /api-keys/my` - List user's API keys
+- `GET /api-keys/:id` - Get specific API key details
+- `DELETE /api-keys/:id` - Revoke an API key
+
+The JWKS router provides:
+
+- `GET /{kid}/.well-known/jwks.json` - Get public key for validation
+
+# Error Handling
+
+The router automatically handles common errors and returns appropriate HTTP status codes:
+
+- `400 Bad Request` - Invalid request data
+- `401 Unauthorized` - Authentication required
+- `404 Not Found` - Resource not found
+- `500 Internal Server Error` - Server error
+
+All error responses include a JSON body with error details.

package/eslint.config.js

@@ -0,0 +1,3 @@
+import { browserConfig } from '../../eslint.config.js';
+
+export default browserConfig;

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@japikey/cloudflare",
+  "version": "0.1.0",
+  "description": "Cloudflare worker-based endpoints for japikey",
+  "engines": {
+    "node": ">=22.5.0"
+  },
+  "keywords": [
+    "cloudflare",
+    "japikey"
+  ],
+  "homepage": "https://github.com/susu-dot-dev/japikey_js#readme",
+  "bugs": {
+    "url": "https://github.com/susu-dot-dev/japikey_js/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/susu-dot-dev/japikey_js.git"
+  },
+  "license": "MIT",
+  "author": "Anil Kulkarni",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "scripts": {
+    "test": "vitest",
+    "test:coverage": "vitest --coverage",
+    "clean": "rimraf dist",
+    "build": "npm run clean && tsc",
+    "lint": "eslint --flag v10_config_lookup_from_file .",
+    "lint:fix": "eslint . --fix",
+    "format": "prettier --write src/**/*.ts",
+    "format:check": "prettier --check src/**/*.ts"
+  },
+  "dependencies": {
+    "@japikey/japikey": "0.1.0",
+    "path-to-regexp": "^8.2.0"
+  },
+  "devDependencies": {
+    "@cloudflare/workers-types": "^4.20250806.0",
+    "@types/node": "^24.1.0",
+    "@typescript-eslint/eslint-plugin": "^8.38.0",
+    "@typescript-eslint/parser": "^8.38.0",
+    "@vitest/coverage-v8": "^3.2.4",
+    "eslint": "^9.32.0",
+    "eslint-config-prettier": "^10.1.8",
+    "globals": "^14.0.0",
+    "jose": "^6.0.12",
+    "prettier": "^3.6.2",
+    "rimraf": "^6.0.1",
+    "vitest": "^3.2.4"
+  }
+}

package/src/d1.ts

@@ -0,0 +1,185 @@
+import type { ApiKeyRow, DatabaseDriver } from '@japikey/shared';
+import {
+  IncorrectUsageError,
+  DatabaseError,
+  InvalidInputError,
+  TRUNCATE_TABLE_ONLY_USE_FOR_UNIT_TESTS,
+} from '@japikey/shared';
+import type {
+  D1Database,
+  D1PreparedStatement,
+  D1Result,
+} from '@cloudflare/workers-types';
+
+type Queries = {
+  insert: D1PreparedStatement;
+  get: D1PreparedStatement;
+  find: D1PreparedStatement;
+  revoke: D1PreparedStatement;
+};
+
+function toSqlite(apiKey: ApiKeyRow): Record<keyof ApiKeyRow, unknown> {
+  try {
+    return {
+      kid: apiKey.kid,
+      user_id: apiKey.user_id,
+      revoked: apiKey.revoked ? 1 : 0,
+      jwk: JSON.stringify(apiKey.jwk),
+      metadata: JSON.stringify(apiKey.metadata),
+    };
+  } catch (err) {
+    throw new InvalidInputError('Failed to serialize the metadata', {
+      cause: err,
+    });
+  }
+}
+
+function fromSqlite(result: Record<keyof ApiKeyRow, unknown>): ApiKeyRow {
+  try {
+    return {
+      kid: result.kid as string,
+      user_id: result.user_id as string,
+      revoked: result.revoked === 1,
+      jwk: JSON.parse(result.jwk as string),
+      metadata: JSON.parse(result.metadata as string),
+    };
+  } catch (err) {
+    throw new DatabaseError('Failed to deserialize an ApiKeyRow', {
+      cause: err,
+    });
+  }
+}
+
+export default class D1Driver implements DatabaseDriver {
+  private _queries?: Queries;
+  private tableName: string;
+
+  constructor(
+    private db: D1Database,
+    tableName: string = 'japikeys'
+  ) {
+    if (!/^[a-zA-Z0-9_]+$/.test(tableName)) {
+      throw new IncorrectUsageError('Invalid table name');
+    }
+    this.tableName = tableName;
+  }
+
+  private getQuery(name: keyof Queries): D1PreparedStatement {
+    if (!this._queries) {
+      throw new IncorrectUsageError(
+        'Database not initialized. Call ensureTable() first.'
+      );
+    }
+    return this._queries[name];
+  }
+
+  private prepareStatements(): void {
+    try {
+      this._queries = {
+        insert: this.db.prepare(
+          `INSERT INTO ${this.tableName} (kid, user_id, revoked, jwk, metadata) VALUES (?1, ?2, ?3, ?4, ?5)`
+        ),
+        get: this.db.prepare(`SELECT * FROM ${this.tableName} WHERE kid = ?1`),
+        find: this.db.prepare(
+          `SELECT * FROM ${this.tableName} WHERE user_id = ?1 LIMIT ?2 OFFSET ?3`
+        ),
+        revoke: this.db.prepare(
+          `UPDATE ${this.tableName} SET revoked = 1 WHERE user_id = ?1 AND kid = ?2`
+        ),
+      };
+    } catch (err) {
+      throw new DatabaseError('Failed to generate sql prepared statements', {
+        cause: err,
+      });
+    }
+  }
+
+  async ensureTable(): Promise<void> {
+    try {
+      await this.db.exec(`
+      CREATE TABLE IF NOT EXISTS ${this.tableName} (
+        kid TEXT PRIMARY KEY,
+        user_id TEXT NOT NULL,
+        revoked INTEGER NOT NULL,
+        jwk TEXT NOT NULL,
+        metadata TEXT NOT NULL
+      )
+    `);
+    } catch (err) {
+      throw new DatabaseError('Failed to create the table', {
+        cause: err,
+      });
+    }
+    this.prepareStatements();
+  }
+
+  async insertApiKey(apiKey: ApiKeyRow): Promise<void> {
+    const params = toSqlite(apiKey);
+    const query = this.getQuery('insert');
+    try {
+      await query
+        .bind(
+          params.kid,
+          params.user_id,
+          params.revoked,
+          params.jwk,
+          params.metadata
+        )
+        .run();
+    } catch (err) {
+      throw new DatabaseError('Failed to insert api key', {
+        cause: err,
+      });
+    }
+  }
+
+  async getApiKey(kid: string): Promise<ApiKeyRow | null> {
+    let result: Record<string, unknown> | undefined | null;
+    const query = this.getQuery('get');
+    try {
+      result = await query.bind(kid).first();
+    } catch (err) {
+      throw new DatabaseError('Failed to query for the api key', {
+        cause: err,
+      });
+    }
+    if (!result) {
+      return null;
+    }
+    return fromSqlite(result);
+  }
+
+  async findApiKeys(
+    user_id: string,
+    limit?: number,
+    offset?: number
+  ): Promise<ApiKeyRow[]> {
+    let response: D1Result<Record<string, unknown>>;
+    const query = this.getQuery('find');
+    try {
+      response = await query.bind(user_id, limit ?? -1, offset ?? 0).all();
+    } catch (err) {
+      throw new DatabaseError('Failed to query for the api keys', {
+        cause: err,
+      });
+    }
+    return response.results.map(row => fromSqlite(row));
+  }
+
+  async revokeApiKey(filter: { user_id: string; kid: string }): Promise<void> {
+    const query = this.getQuery('revoke');
+    try {
+      await query.bind(filter.user_id, filter.kid).run();
+    } catch (err) {
+      throw new DatabaseError('Failed to revoke the api key', {
+        cause: err,
+      });
+    }
+  }
+
+  async close(): Promise<void> {}
+
+  async [TRUNCATE_TABLE_ONLY_USE_FOR_UNIT_TESTS](): Promise<void> {
+    await this.db.exec(`DELETE FROM ${this.tableName}`);
+  }
+}

package/src/index.ts

@@ -0,0 +1,12 @@
+import type { CreateApiKeyRouterOptions, CreateApiKeyData } from './router.ts';
+import { createApiKeyRouter, createJWKSRouter, isJWKSPath } from './router.ts';
+import D1Driver from './d1.ts';
+
+export {
+  createApiKeyRouter,
+  createJWKSRouter,
+  isJWKSPath,
+  D1Driver,
+  type CreateApiKeyRouterOptions,
+  type CreateApiKeyData,
+};