canopycms 0.0.0

package/src/api/guards.ts

@@ -0,0 +1,271 @@
+/**
+ * Declarative guard system for API endpoints.
+ *
+ * Guards run before the handler and either:
+ * - Return an error response (404, 403, 500) to short-circuit
+ * - Produce a guard context (e.g., branch context with schema) for the handler
+ *
+ * Usage in defineEndpoint:
+ * ```ts
+ * defineEndpoint({
+ *   guards: ['branchAccessWithSchema'] as const,
+ *   handler: async (gc, ctx, req, params) => {
+ *     // gc.branchContext is guaranteed non-null with flatSchema
+ *   }
+ * })
+ * ```
+ */
+
+import type { BranchContext, BranchContextWithSchema } from '../types'
+import type { ApiContext, ApiRequest, ApiResponse } from './types'
+import { isAdmin, isReviewer, isPrivileged } from '../authorization/helpers'
+
+// ============================================================================
+// Guard IDs and Context Map
+// ============================================================================
+
+/** All available guard identifiers */
+export type GuardId =
+  | 'branch'
+  | 'branchAccess'
+  | 'schema'
+  | 'branchAccessWithSchema'
+  | 'admin'
+  | 'reviewer'
+  | 'privileged'
+
+/** Maps each guard ID to the context it contributes */
+export interface GuardContextMap {
+  branch: { branchContext: BranchContext }
+  branchAccess: { branchContext: BranchContext }
+  schema: { branchContext: BranchContextWithSchema }
+  branchAccessWithSchema: { branchContext: BranchContextWithSchema }
+  admin: Record<string, never>
+  reviewer: Record<string, never>
+  privileged: Record<string, never>
+}
+
+// ============================================================================
+// Type-level computation of guard context
+// ============================================================================
+
+/** Helper: convert union to intersection */
+type UnionToIntersection<U> = (U extends unknown ? (k: U) => void : never) extends (
+  k: infer I,
+) => void
+  ? I
+  : never
+
+/** Compute the guard context type from a tuple of guard IDs */
+export type ComputeGuardContext<T extends readonly GuardId[]> = UnionToIntersection<
+  GuardContextMap[T[number]]
+>
+
+// ============================================================================
+// Guard runner types
+// ============================================================================
+
+/** Result of a single guard execution */
+type GuardRunnerResult =
+  | { ok: true; context: Partial<GuardContext> }
+  | { ok: false; response: ApiResponse<never> }
+
+/** Accumulated guard context (runtime shape) */
+interface GuardContext {
+  branchContext?: BranchContext | BranchContextWithSchema
+}
+
+/** A guard runner function */
+type GuardRunner = (
+  ctx: ApiContext,
+  req: ApiRequest,
+  params: Record<string, unknown>,
+  accumulated: GuardContext,
+) => Promise<GuardRunnerResult>
+
+// ============================================================================
+// Guard runner implementations
+// ============================================================================
+
+/** Extracts branch name from params, returning error response if missing */
+function extractBranchName(params: Record<string, unknown>): string | ApiResponse<never> {
+  const branch = params.branch
+  if (typeof branch !== 'string' || !branch) {
+    return { ok: false, status: 400, error: 'Branch parameter required' }
+  }
+  return branch
+}
+
+/** Resolve branch context, reusing from accumulated if available */
+async function resolveBranchContext(
+  ctx: ApiContext,
+  params: Record<string, unknown>,
+  accumulated: GuardContext,
+  options?: { loadSchema?: boolean },
+): Promise<BranchContext | null> {
+  // Reuse accumulated context if it has everything we need
+  if (accumulated.branchContext) {
+    if (!options?.loadSchema || accumulated.branchContext.flatSchema) {
+      return accumulated.branchContext
+    }
+    // Need schema but accumulated doesn't have it — re-fetch with schema
+  }
+
+  const branch = extractBranchName(params)
+  if (typeof branch !== 'string') return null
+  return ctx.getBranchContext(branch, options)
+}
+
+const runBranchGuard: GuardRunner = async (ctx, _req, params, accumulated) => {
+  const branch = extractBranchName(params)
+  if (typeof branch !== 'string') return { ok: false, response: branch }
+
+  const context = accumulated.branchContext ?? (await ctx.getBranchContext(branch))
+  if (!context) {
+    return { ok: false, response: { ok: false, status: 404, error: 'Branch not found' } }
+  }
+  return { ok: true, context: { branchContext: context } }
+}
+
+const runBranchAccessGuard: GuardRunner = async (ctx, req, params, accumulated) => {
+  const branch = extractBranchName(params)
+  if (typeof branch !== 'string') return { ok: false, response: branch }
+
+  const context = accumulated.branchContext ?? (await ctx.getBranchContext(branch))
+  if (!context) {
+    return { ok: false, response: { ok: false, status: 404, error: 'Branch not found' } }
+  }
+
+  const access = ctx.services.checkBranchAccess(context, req.user)
+  if (!access.allowed) {
+    return {
+      ok: false,
+      response: { ok: false, status: 403, error: access.reason || 'Forbidden' },
+    }
+  }
+
+  return { ok: true, context: { branchContext: context } }
+}
+
+const runSchemaGuard: GuardRunner = async (ctx, _req, params, accumulated) => {
+  const branch = extractBranchName(params)
+  if (typeof branch !== 'string') return { ok: false, response: branch }
+
+  const context = await resolveBranchContext(ctx, params, accumulated, { loadSchema: true })
+  if (!context) {
+    return { ok: false, response: { ok: false, status: 404, error: 'Branch not found' } }
+  }
+  if (!context.flatSchema) {
+    return {
+      ok: false,
+      response: { ok: false, status: 500, error: 'Schema not loaded for branch' },
+    }
+  }
+
+  return { ok: true, context: { branchContext: context as BranchContextWithSchema } }
+}
+
+const runBranchAccessWithSchemaGuard: GuardRunner = async (ctx, req, params, accumulated) => {
+  const branch = extractBranchName(params)
+  if (typeof branch !== 'string') return { ok: false, response: branch }
+
+  const context = await resolveBranchContext(ctx, params, accumulated, { loadSchema: true })
+  if (!context) {
+    return { ok: false, response: { ok: false, status: 404, error: 'Branch not found' } }
+  }
+
+  const access = ctx.services.checkBranchAccess(context, req.user)
+  if (!access.allowed) {
+    return {
+      ok: false,
+      response: { ok: false, status: 403, error: access.reason || 'Forbidden' },
+    }
+  }
+
+  if (!context.flatSchema) {
+    return {
+      ok: false,
+      response: { ok: false, status: 500, error: 'Schema not loaded for branch' },
+    }
+  }
+
+  return { ok: true, context: { branchContext: context as BranchContextWithSchema } }
+}
+
+const runAdminGuard: GuardRunner = async (_ctx, req) => {
+  if (!isAdmin(req.user.groups)) {
+    return {
+      ok: false,
+      response: { ok: false, status: 403, error: 'Admin access required' },
+    }
+  }
+  return { ok: true, context: {} }
+}
+
+const runReviewerGuard: GuardRunner = async (_ctx, req) => {
+  if (!isReviewer(req.user.groups)) {
+    return {
+      ok: false,
+      response: { ok: false, status: 403, error: 'Reviewer access required' },
+    }
+  }
+  return { ok: true, context: {} }
+}
+
+const runPrivilegedGuard: GuardRunner = async (_ctx, req) => {
+  if (!isPrivileged(req.user.groups)) {
+    return {
+      ok: false,
+      response: { ok: false, status: 403, error: 'Privileged access required' },
+    }
+  }
+  return { ok: true, context: {} }
+}
+
+// ============================================================================
+// Guard registry
+// ============================================================================
+
+const GUARD_RUNNERS: Record<GuardId, GuardRunner> = {
+  branch: runBranchGuard,
+  branchAccess: runBranchAccessGuard,
+  schema: runSchemaGuard,
+  branchAccessWithSchema: runBranchAccessWithSchemaGuard,
+  admin: runAdminGuard,
+  reviewer: runReviewerGuard,
+  privileged: runPrivilegedGuard,
+}
+
+// ============================================================================
+// Guard execution
+// ============================================================================
+
+/** Result of executeGuards */
+export type ExecuteGuardsResult<T extends readonly GuardId[]> =
+  | { ok: true; guardContext: ComputeGuardContext<T> }
+  | { ok: false; response: ApiResponse<never> }
+
+/**
+ * Execute a chain of guards in order.
+ * Returns the accumulated guard context on success, or the first error response on failure.
+ */
+export async function executeGuards<T extends readonly GuardId[]>(
+  guards: T,
+  ctx: ApiContext,
+  req: ApiRequest,
+  params: Record<string, unknown>,
+): Promise<ExecuteGuardsResult<T>> {
+  const accumulated: GuardContext = {}
+
+  for (const guardId of guards) {
+    const runner = GUARD_RUNNERS[guardId]
+    const result = await runner(ctx, req, params, accumulated)
+    if (!result.ok) {
+      return { ok: false, response: result.response }
+    }
+    // Merge context contributions
+    Object.assign(accumulated, result.context)
+  }
+
+  return { ok: true, guardContext: accumulated as ComputeGuardContext<T> }
+}

package/src/api/index.ts

@@ -0,0 +1,87 @@
+// Re-export all response types
+export type { ApiResponse, ApiRequest, ApiContext } from './types'
+export type {
+  BranchResponse,
+  BranchListResponse,
+  BranchDeleteResponse,
+  CreateBranchBody,
+  UpdateBranchAccessBody,
+} from './branch'
+export type { BranchMergeResponse } from './branch-merge'
+export type {
+  CommentsResponse,
+  AddCommentResponse,
+  ResolveCommentResponse,
+  ListCommentsResponse,
+} from './comments'
+export type {
+  EntriesResponse,
+  ListEntriesResponse,
+  CollectionItem,
+  ListEntriesParams,
+  DeleteEntryResponse,
+} from './entries'
+export type {
+  PermissionsResponse,
+  UpdatePermissionsBody,
+  SearchUsersParams,
+  GetUserMetadataResponse,
+  GetUserMetadataParams,
+} from './permissions'
+export type { UserInfoResponse } from './user'
+export type {
+  AssetsListResponse,
+  AssetUploadResponse,
+  UploadAssetBody,
+  DeleteAssetBody,
+  ListAssetsParams,
+} from './assets'
+export type {
+  InternalGroupsResponse,
+  ExternalGroupsResponse,
+  UpdateInternalGroupsBody,
+  SearchExternalGroupsParams,
+  ExternalGroup,
+} from './groups'
+export type { ReferenceOptionsResponse } from './reference-options'
+export type { ResolveReferencesResponse } from './resolve-references'
+export type {
+  SchemaResponse,
+  WireEntryType,
+  WireCollectionConfig,
+  WireFlatSchemaItem,
+  CollectionResponse,
+  CreateCollectionResponse,
+  UpdateCollectionResponse,
+  DeleteCollectionResponse,
+  AddEntryTypeResponse,
+  UpdateEntryTypeResponse,
+  RemoveEntryTypeResponse,
+  UpdateOrderResponse,
+  GetSchemaApiResponse,
+  GetCollectionApiResponse,
+  CreateCollectionApiResponse,
+  UpdateCollectionApiResponse,
+  DeleteCollectionApiResponse,
+  AddEntryTypeApiResponse,
+  UpdateEntryTypeApiResponse,
+  RemoveEntryTypeApiResponse,
+  UpdateOrderApiResponse,
+} from './schema'
+export type {
+  CreateCollectionInput,
+  UpdateCollectionInput,
+  CreateEntryTypeInput,
+  UpdateEntryTypeInput,
+} from '../schema/schema-store-types'
+export type { EntryTypeSummary } from './entries'
+// Content API uses path-based routing now - no separate params/body types exported
+
+// Export route definitions
+export { USER_ROUTES } from './user'
+// Note: SCHEMA_ROUTES is not exported here because it imports server-only code (fs module).
+// Import it directly from './schema' in server-side code when needed.
+
+// Export client
+export { CanopyApiClient, createApiClient } from './client'
+export type { ApiClientOptions } from './client'