feat: scaffold control plane API with EffectTS and BetterAuth

Author: richiemcilroy

apps/api/package.json

@@ -7,13 +7,19 @@
     "build": "tsc",
     "typecheck": "tsc --noEmit",
     "lint": "eslint src/",
-    "test": "echo 'no tests yet'"
+    "test": "bun test",
+    "dev": "bun run src/index.ts"
   },
   "dependencies": {
+    "@effect/platform": "^0.94.5",
+    "@effect/platform-node": "^0.104.1",
+    "@effect/schema": "^0.75.5",
     "better-auth": "^1.4.18",
+    "effect": "^3.19.18",
     "mysql2": "^3.17.4"
   },
   "devDependencies": {
+    "@types/bun": "^1.3.9",
     "@types/node": "^25.3.0"
   }
 }

apps/api/src/context.ts

@@ -0,0 +1,8 @@
+import { Context } from 'effect'
+
+export interface AuthInfo {
+  readonly userId: string
+  readonly orgId: string
+}
+
+export class AuthContext extends Context.Tag('AuthContext')<AuthContext, AuthInfo>() {}

apps/api/src/errors.ts

@@ -0,0 +1,102 @@
+import { Data } from 'effect'
+import { HttpServerResponse } from '@effect/platform'
+
+export class NotFoundError extends Data.TaggedError('NotFoundError')<{
+  readonly message: string
+}> {}
+
+export class UnauthorizedError extends Data.TaggedError('UnauthorizedError')<{
+  readonly message: string
+}> {}
+
+export class ForbiddenError extends Data.TaggedError('ForbiddenError')<{
+  readonly message: string
+}> {}
+
+export class ValidationError extends Data.TaggedError('ValidationError')<{
+  readonly message: string
+}> {}
+
+export class ConflictError extends Data.TaggedError('ConflictError')<{
+  readonly message: string
+}> {}
+
+export class RateLimitedError extends Data.TaggedError('RateLimitedError')<{
+  readonly message: string
+  readonly retryAfter: number
+}> {}
+
+export class SandboxNotRunningError extends Data.TaggedError('SandboxNotRunningError')<{
+  readonly message: string
+}> {}
+
+export class NotImplementedError extends Data.TaggedError('NotImplementedError')<{
+  readonly message: string
+}> {}
+
+export type ApiError =
+  | NotFoundError
+  | UnauthorizedError
+  | ForbiddenError
+  | ValidationError
+  | ConflictError
+  | RateLimitedError
+  | SandboxNotRunningError
+  | NotImplementedError
+
+const STATUS_MAP: Record<ApiError['_tag'], number> = {
+  NotFoundError: 404,
+  UnauthorizedError: 401,
+  ForbiddenError: 403,
+  ValidationError: 400,
+  ConflictError: 409,
+  RateLimitedError: 429,
+  SandboxNotRunningError: 409,
+  NotImplementedError: 501,
+}
+
+const CODE_MAP: Record<ApiError['_tag'], string> = {
+  NotFoundError: 'not_found',
+  UnauthorizedError: 'unauthorized',
+  ForbiddenError: 'forbidden',
+  ValidationError: 'validation_error',
+  ConflictError: 'conflict',
+  RateLimitedError: 'rate_limited',
+  SandboxNotRunningError: 'sandbox_not_running',
+  NotImplementedError: 'not_implemented',
+}
+
+export function errorToResponse(error: ApiError, requestId: string) {
+  return HttpServerResponse.unsafeJson(
+    {
+      error: CODE_MAP[error._tag],
+      message: error.message,
+      request_id: requestId,
+      retry_after: error._tag === 'RateLimitedError' ? error.retryAfter : null,
+    },
+    {
+      status: STATUS_MAP[error._tag],
+      headers: { 'content-type': 'application/json' },
+    },
+  )
+}
+
+/** Formats any error as an API error response. Handles both ApiError and unknown errors. */
+export function formatApiError(error: unknown, requestId: string = '') {
+  const tag =
+    typeof error === 'object' && error !== null && '_tag' in error
+      ? (error as { _tag: string })._tag
+      : null
+  if (tag !== null && tag in STATUS_MAP) {
+    return errorToResponse(error as ApiError, requestId)
+  }
+  return HttpServerResponse.unsafeJson(
+    {
+      error: 'internal_error',
+      message: 'An unexpected error occurred',
+      request_id: requestId,
+      retry_after: null,
+    },
+    { status: 500, headers: { 'content-type': 'application/json' } },
+  )
+}

apps/api/src/index.ts

@@ -1,2 +1,12 @@
-export { auth } from './auth.js'
-export { authClient } from './auth-client.js'
+import { NodeHttpServer, NodeRuntime } from '@effect/platform-node'
+import { Layer } from 'effect'
+import { createServer } from 'node:http'
+import { AppLive } from './server.js'
+
+const PORT = Number(process.env.PORT ?? 3000)
+
+const ServerLive = AppLive.pipe(
+  Layer.provide(NodeHttpServer.layer(() => createServer(), { port: PORT })),
+)
+
+NodeRuntime.runMain(Layer.launch(ServerLive))

apps/api/src/middleware.ts

@@ -0,0 +1,70 @@
+import { HttpMiddleware, HttpServerRequest, HttpServerResponse } from '@effect/platform'
+import { Effect } from 'effect'
+import { UnauthorizedError } from './errors.js'
+import { AuthContext } from './context.js'
+import { auth } from './auth.js'
+
+/**
+ * Generates a request ID (or propagates from X-Request-Id header)
+ * and attaches it to the response.
+ */
+export const withRequestId = HttpMiddleware.make((app) =>
+  Effect.gen(function* () {
+    const request = yield* HttpServerRequest.HttpServerRequest
+    const incoming = request.headers['x-request-id']
+    const requestId = incoming ?? crypto.randomUUID()
+    const response = yield* app
+    return response.pipe(HttpServerResponse.setHeader('x-request-id', requestId))
+  }),
+)
+
+/**
+ * Validates API key or session cookie and provides AuthContext.
+ * Skips auth for /health and /api/auth/* routes.
+ */
+export const withAuth = HttpMiddleware.make((app) =>
+  Effect.gen(function* () {
+    const request = yield* HttpServerRequest.HttpServerRequest
+
+    if (request.url.startsWith('/health') || request.url.startsWith('/api/auth')) {
+      return yield* Effect.provideService(app, AuthContext, { userId: '', orgId: '' })
+    }
+
+    const authHeader = request.headers['authorization']
+    if (authHeader?.startsWith('Bearer ')) {
+      const key = authHeader.slice(7)
+      const result = yield* Effect.tryPromise({
+        try: () => auth.api.verifyApiKey({ body: { key } }),
+        catch: () => new UnauthorizedError({ message: 'Invalid API key' }),
+      })
+
+      if (!result?.valid) {
+        return yield* Effect.fail(new UnauthorizedError({ message: 'Invalid API key' }))
+      }
+
+      const metadata = (result as { metadata?: { orgId?: string } }).metadata
+      return yield* Effect.provideService(app, AuthContext, {
+        userId: (result as { userId?: string }).userId ?? '',
+        orgId: metadata?.orgId ?? '',
+      })
+    }
+
+    const sessionResult = yield* Effect.tryPromise({
+      try: () =>
+        auth.api.getSession({
+          headers: new Headers(request.headers as Record<string, string>),
+        }),
+      catch: () => new UnauthorizedError({ message: 'Invalid session' }),
+    })
+
+    if (!sessionResult?.session) {
+      return yield* Effect.fail(new UnauthorizedError({ message: 'Authentication required' }))
+    }
+
+    return yield* Effect.provideService(app, AuthContext, {
+      userId: sessionResult.session.userId,
+      orgId:
+        (sessionResult.session as { activeOrganizationId?: string }).activeOrganizationId ?? '',
+    })
+  }),
+)

apps/api/src/routes/artifacts.ts

@@ -0,0 +1,10 @@
+import { HttpRouter } from '@effect/platform'
+import { Effect } from 'effect'
+import { NotImplementedError } from '../errors.js'
+
+const stub = (name: string) => Effect.fail(new NotImplementedError({ message: `${name} not yet implemented` }))
+
+export const ArtifactRouter = HttpRouter.empty.pipe(
+  HttpRouter.post('/v1/sandboxes/:id/artifacts', stub('Register artifacts')),
+  HttpRouter.get('/v1/sandboxes/:id/artifacts', stub('List artifacts')),
+)

apps/api/src/routes/execs.ts

@@ -0,0 +1,12 @@
+import { HttpRouter } from '@effect/platform'
+import { Effect } from 'effect'
+import { NotImplementedError } from '../errors.js'
+
+const stub = (name: string) => Effect.fail(new NotImplementedError({ message: `${name} not yet implemented` }))
+
+export const ExecRouter = HttpRouter.empty.pipe(
+  HttpRouter.post('/v1/sandboxes/:id/exec', stub('Execute command')),
+  HttpRouter.get('/v1/sandboxes/:id/exec/:execId', stub('Get exec')),
+  HttpRouter.get('/v1/sandboxes/:id/execs', stub('List execs')),
+  HttpRouter.get('/v1/sandboxes/:id/exec/:execId/stream', stub('Stream exec output')),
+)

apps/api/src/routes/files.ts

@@ -0,0 +1,11 @@
+import { HttpRouter } from '@effect/platform'
+import { Effect } from 'effect'
+import { NotImplementedError } from '../errors.js'
+
+const stub = (name: string) => Effect.fail(new NotImplementedError({ message: `${name} not yet implemented` }))
+
+export const FileRouter = HttpRouter.empty.pipe(
+  HttpRouter.put('/v1/sandboxes/:id/files', stub('Upload file')),
+  HttpRouter.get('/v1/sandboxes/:id/files', stub('Download or list files')),
+  HttpRouter.del('/v1/sandboxes/:id/files', stub('Delete file')),
+)

apps/api/src/routes/health.ts

@@ -0,0 +1,9 @@
+import { HttpRouter, HttpServerResponse } from '@effect/platform'
+import { Effect } from 'effect'
+
+export const HealthRouter = HttpRouter.empty.pipe(
+  HttpRouter.get(
+    '/health',
+    Effect.succeed(HttpServerResponse.unsafeJson({ status: 'ok' })),
+  ),
+)

apps/api/src/routes/sandboxes.ts

@@ -0,0 +1,16 @@
+import { HttpRouter } from '@effect/platform'
+import { Effect } from 'effect'
+import { NotImplementedError } from '../errors.js'
+
+const stub = (name: string) => Effect.fail(new NotImplementedError({ message: `${name} not yet implemented` }))
+
+export const SandboxRouter = HttpRouter.empty.pipe(
+  HttpRouter.post('/v1/sandboxes', stub('Create sandbox')),
+  HttpRouter.get('/v1/sandboxes', stub('List sandboxes')),
+  HttpRouter.get('/v1/sandboxes/:id', stub('Get sandbox')),
+  HttpRouter.post('/v1/sandboxes/:id/fork', stub('Fork sandbox')),
+  HttpRouter.get('/v1/sandboxes/:id/forks', stub('Get fork tree')),
+  HttpRouter.post('/v1/sandboxes/:id/stop', stub('Stop sandbox')),
+  HttpRouter.del('/v1/sandboxes/:id', stub('Delete sandbox')),
+  HttpRouter.get('/v1/sandboxes/:id/replay', stub('Get replay')),
+)