Setup the initial repository and implement ApiKeyProvider

This sets up tsc, prettier, and github actions for the project
In addition, the ApiKeyProvider methods are all defined
This provider is used for creating, and validating a user via api key

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;
+};