Merge pull request #1 from runtimed/feature/api-key-provider

Set up the initial repository and implement ApiKeyProvider

Author: intentionally-left-nil

.github/workflows/ci.yml

@@ -0,0 +1,34 @@
+name: CI
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+
+    strategy:
+      matrix:
+        node-version: [22.x, 24.x]
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js ${{ matrix.node-version }}
+        uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node-version }}
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Check formatting
+        run: npm run format:check
+
+      - name: Build project
+        run: npm run build

.github/workflows/publish.yml

@@ -0,0 +1,21 @@
+name: Publish Package to npmjs
+on:
+  release:
+    types: [published]
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write
+    environment: production
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '24.x'
+          registry-url: 'https://registry.npmjs.org'
+      - run: npm ci
+      - run: npm run build
+      - name: Publish the package
+        run: npm publish --provenance --access public

.prettierignore

@@ -0,0 +1,31 @@
+# Build outputs
+dist/
+build/
+*.min.js
+
+# Dependencies
+node_modules/
+
+# Package files
+package-lock.json
+yarn.lock
+pnpm-lock.yaml
+
+# Generated files
+*.d.ts.map
+
+# Logs
+*.log
+
+# Environment files
+.env
+.env.local
+.env.*.local
+
+# IDE files
+.vscode/
+.idea/
+
+# OS files
+.DS_Store
+Thumbs.db

.prettierrc

@@ -0,0 +1,11 @@
+{
+  "semi": true,
+  "trailingComma": "es5",
+  "singleQuote": true,
+  "printWidth": 120,
+  "tabWidth": 2,
+  "useTabs": false,
+  "bracketSpacing": true,
+  "arrowParens": "avoid",
+  "endOfLine": "lf"
+}

README.md

@@ -1,2 +1,3 @@
 # extensions
+
 Interface and shared code for building extensions for the runt ecosystem

package-lock.json

@@ -0,0 +1,47 @@
+{
+  "name": "@runtimed/extensions",
+  "version": "0.1.0",
+  "description": "Interfaces and shared code for building extensions to the runt ecosystem",
+  "keywords": [
+    "runtimed",
+    "runt"
+  ],
+  "homepage": "https://github.com/runtimed/extensions#readme",
+  "bugs": {
+    "url": "https://github.com/runtimed/extensions/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/runtimed/extensions.git"
+  },
+  "license": "BSD-3-Clause",
+  "author": "Anil Kulkarni",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "build": "npx tsc"
+  },
+  "devDependencies": {
+    "jose": "^6.0.12",
+    "prettier": "^3.6.2",
+    "typescript": "^5.9.2"
+  },
+  "peerDependencies": {
+    "@cloudflare/workers-types": "^4.20250810.0"
+  }
+}

package.json

@@ -0,0 +1,6 @@
+import type { ApiKeyProvider } from './providers/api_key';
+export type * from './providers/shared';
+
+export type BackendExtension = {
+  apiKey?: ApiKeyProvider;
+};

src/index.ts

@@ -0,0 +1,34 @@
+import type { Response as WorkerResponse } from '@cloudflare/workers-types';
+import type { Passport, ProviderContext, Scope, Resource } from './shared';
+
+export enum ApiKeyCapabilities {
+  Revoke = 'revoke',
+  Delete = 'delete',
+  CreateWithResources = 'create_with_resources',
+}
+
+export type CreateApiKeyRequest = {
+  scopes: Scope[];
+  resources?: Resource[];
+  expiresAt: string;
+  name?: string;
+  userGenerated: boolean;
+};
+
+export type ApiKey = CreateApiKeyRequest & {
+  id: string;
+  userId: string;
+  revoked: boolean;
+};
+
+export type ApiKeyProvider = {
+  capabilities: Set<ApiKeyCapabilities>;
+  overrideHandler?: (context: ProviderContext) => Promise<false | WorkerResponse>; // Any routes the provider wants to fully implement. Return false for any route not handled
+  isApiKey(context: ProviderContext): boolean; // Returns true if the auth token appears to be an API key (whether or not it is valid)
+  validateApiKey(context: ProviderContext): Promise<Passport>; // Ensure the API key is valid, and returns the Passport. Raise an error otherwise
+  createApiKey: (context: ProviderContext, request: CreateApiKeyRequest) => Promise<string>;
+  getApiKey: (context: ProviderContext, id: string) => Promise<ApiKey>; // Returns the API key matching the specific api key id
+  listApiKeys: (context: ProviderContext) => Promise<ApiKey[]>; // Return a list of all API keys for a user
+  revokeApiKey: (context: ProviderContext, id: string) => Promise<void>; // set the revoked flag for an API key, such that it will no longer be valid
+  deleteApiKey: (context: ProviderContext, id: string) => Promise<void>; // Delete an API key from the database
+};

src/providers/api_key.ts

@@ -0,0 +1,48 @@
+import type { JWTPayload } from 'jose';
+import type {
+  Request as WorkerRequest,
+  IncomingRequestCfProperties,
+  D1Database,
+  ExecutionContext,
+} from '@cloudflare/workers-types';
+
+export type ProviderEnv = {
+  DB: D1Database;
+  AUTH_ISSUER: string;
+};
+
+export enum AuthType {
+  OAuth = 'oauth',
+  ApiKey = 'api_key',
+}
+
+export type Scope = 'runt:read' | 'runt:execute';
+
+export type User = {
+  id: string;
+  email: string;
+  name?: string;
+  givenName?: string;
+  familyName: string;
+};
+
+export type Resource = {
+  id: string;
+  type: string;
+};
+
+export type Passport = {
+  type: AuthType;
+  user: User;
+  claims: JWTPayload;
+  scopes: Scope[] | null;
+  resources: Resource[] | null;
+};
+
+export type ProviderContext = {
+  request: WorkerRequest<unknown, IncomingRequestCfProperties<unknown>>;
+  env: ProviderEnv;
+  ctx: ExecutionContext;
+  bearerToken: string | null;
+  passport: Passport | null;
+};