frappebun 0.0.0

package/src/permissions/index.ts

@@ -0,0 +1,265 @@
+/**
+ * frappe.perms — role-based access control with row-level scoping.
+ *
+ * Three layers applied in order:
+ *   1. Role check   — does this user's role allow this action on this DocType?
+ *   2. Scope        — for list queries: which rows can this user see?
+ *   3. Document     — for individual docs: can this user perform this action?
+ */
+
+import type { FrappeDatabase } from "../database/database"
+import { getDocTypeMeta, getController } from "../doctype/registry"
+import type { DocumentLike, PermissionDenial, PermissionRule } from "../doctype/types"
+import { PermissionError } from "../errors"
+
+// ─── PermissionDenial sentinel ────────────────────────────
+
+export function isDenial(v: unknown): v is PermissionDenial {
+  return (
+    typeof v === "object" && v !== null && (v as PermissionDenial).__type === "PermissionDenial"
+  )
+}
+
+/** Signal a contextual denial with a human-readable message. */
+export function deny(message: string): PermissionDenial {
+  return { __type: "PermissionDenial", message }
+}
+
+// ─── Role helpers (per-request cache) ────────────────────
+
+const roleCache = new WeakMap<object, Map<string, Set<string>>>()
+
+/**
+ * Get the roles for a user. Results are cached per-request
+ * (keyed by the `ctx` object reference — rotated each request).
+ */
+export function getUserRoles(user: string, db: FrappeDatabase, ctxRef: object): Set<string> {
+  let reqCache = roleCache.get(ctxRef)
+  if (!reqCache) {
+    reqCache = new Map()
+    roleCache.set(ctxRef, reqCache)
+  }
+
+  const cached = reqCache.get(user)
+  if (cached) return cached
+
+  const roles = new Set<string>(["All"])
+
+  if (user === "Administrator") {
+    roles.add("Administrator")
+    roles.add("System Manager")
+  } else {
+    try {
+      // UserRole table: columns: user, role (plus standard child fields)
+      const rows = db.raw
+        .query<{ role: string }, [string]>(`SELECT "role" FROM "UserRole" WHERE "user" = ?`)
+        .all(user)
+      for (const r of rows) roles.add(r.role)
+    } catch {
+      // UserRole table may not exist yet during migration
+    }
+  }
+
+  reqCache.set(user, roles)
+  return roles
+}
+
+// ─── Role permission check ────────────────────────────────
+
+/**
+ * Check if the user has the given action on the DocType based on role permissions.
+ * Returns true for Administrator (always) and false if the DocType has no permissions array.
+ */
+export function hasRolePermission(
+  doctype: string,
+  action: string,
+  user: string,
+  db: FrappeDatabase,
+  ctxRef: object,
+): boolean {
+  if (user === "Administrator") return true
+
+  const meta = getDocTypeMeta(doctype)
+  if (!meta) return false
+
+  const permRules: PermissionRule[] = meta.schema.permissions ?? []
+  if (permRules.length === 0) return true // no restrictions declared
+
+  const roles = getUserRoles(user, db, ctxRef)
+
+  return permRules.some((rule) => {
+    const roleMatch = rule.role === "All" || roles.has(rule.role)
+    if (!roleMatch) return false
+    return rule[action as keyof PermissionRule] === true
+  })
+}
+
+// ─── Document-level check ────────────────────────────────
+
+/**
+ * Run the controller's per-action permission method.
+ * Returns true if allowed, throws PermissionError if denied.
+ */
+export async function checkDocPermission(
+  doctype: string,
+  action: "read" | "write" | "delete" | "submit" | "cancel",
+  doc: DocumentLike,
+  user: string,
+): Promise<void> {
+  if (user === "Administrator") return
+
+  const controller = getController(doctype)
+  const permFn = controller?.permissions?.[action]
+  if (!permFn) return
+
+  const result = await (permFn as (doc: DocumentLike, user: string) => unknown)(doc, user)
+  evaluatePermResult(result, action, doctype)
+}
+
+/**
+ * Run the controller's create-permission check (no doc yet).
+ */
+export async function checkCreatePermission(doctype: string, user: string): Promise<void> {
+  if (user === "Administrator") return
+
+  const controller = getController(doctype)
+  const createFn = controller?.permissions?.create
+  if (!createFn) return
+
+  const result = await createFn(user)
+  evaluatePermResult(result, "create", doctype)
+}
+
+function evaluatePermResult(result: unknown, action: string, doctype: string): void {
+  if (result === true) return
+  if (isDenial(result)) throw new PermissionError(result.message)
+  if (result === false || result == null)
+    throw new PermissionError(`No permission to ${action} ${doctype}`)
+}
+
+// ─── frappe.perms namespace ───────────────────────────────
+
+export interface PermsNamespace {
+  /**
+   * Check if the current user has the given action on the DocType.
+   * Role check only (no doc loaded). Returns boolean, never throws.
+   */
+  can(action: string, doctype: string): boolean
+  can(action: string, doctype: string, doc: DocumentLike): Promise<boolean>
+  can(action: string, doctype: string, name: string): Promise<boolean>
+
+  /**
+   * Assert permission — throws PermissionError if denied.
+   */
+  authorize(action: string, doctype: string): void
+  authorize(action: string, doctype: string, doc: DocumentLike): Promise<void>
+  authorize(action: string, doctype: string, name: string): Promise<void>
+
+  /** Check if the current user has the role (or any of the listed roles). */
+  hasRole(role: string | string[], user?: string): boolean
+
+  /** Get all roles for the current user (or a specified user). */
+  getRoles(user?: string): string[]
+
+  /** Produce a PermissionDenial with a descriptive message. */
+  deny(message: string): PermissionDenial
+
+  /** Share a document with another user. */
+  share(
+    doctype: string,
+    name: string,
+    targetUser: string,
+    perms: { read?: boolean; write?: boolean },
+  ): Promise<void>
+  unshare(doctype: string, name: string, targetUser: string): Promise<void>
+  getShares(
+    doctype: string,
+    name: string,
+  ): Promise<{ user: string; read: boolean; write: boolean }[]>
+}
+
+export function createPermsNamespace(
+  user: string,
+  db: FrappeDatabase,
+  ctxRef: object,
+  getDoc: (doctype: string, name: string) => Promise<DocumentLike>,
+): PermsNamespace {
+  const self: PermsNamespace = {
+    can(
+      action: string,
+      doctype: string,
+      docOrName?: DocumentLike | string,
+    ): boolean | Promise<boolean> {
+      const roleOk = hasRolePermission(doctype, action, user, db, ctxRef)
+      if (!roleOk) return false
+      if (docOrName === undefined) return true
+
+      // Doc-level check
+      return (async () => {
+        const doc: DocumentLike =
+          typeof docOrName === "string" ? await getDoc(doctype, docOrName) : docOrName
+        try {
+          await checkDocPermission(doctype, action as "read", doc, user)
+          return true
+        } catch {
+          return false
+        }
+      })()
+    },
+
+    authorize(
+      action: string,
+      doctype: string,
+      docOrName?: DocumentLike | string,
+    ): void | Promise<void> {
+      const roleOk = hasRolePermission(doctype, action, user, db, ctxRef)
+      if (!roleOk) throw new PermissionError(`No permission to ${action} ${doctype}`)
+      if (docOrName === undefined) return
+
+      return (async () => {
+        const doc: DocumentLike =
+          typeof docOrName === "string" ? await getDoc(doctype, docOrName) : docOrName
+        await checkDocPermission(doctype, action as "read", doc, user)
+      })()
+    },
+
+    hasRole(roleOrRoles: string | string[], targetUser?: string): boolean {
+      const u = targetUser ?? user
+      if (u === "Administrator") return true
+      const roles = getUserRoles(u, db, ctxRef)
+      return Array.isArray(roleOrRoles)
+        ? roleOrRoles.some((r) => roles.has(r))
+        : roles.has(roleOrRoles)
+    },
+
+    getRoles(targetUser?: string): string[] {
+      return [...getUserRoles(targetUser ?? user, db, ctxRef)]
+    },
+
+    deny(message: string): PermissionDenial {
+      return deny(message)
+    },
+
+    async share(doctype, name, targetUser, perms) {
+      // Placeholder: will use DocShare DocType when implemented
+      void doctype
+      void name
+      void targetUser
+      void perms
+    },
+
+    async unshare(doctype, name, targetUser) {
+      void doctype
+      void name
+      void targetUser
+    },
+
+    async getShares(doctype, name) {
+      void doctype
+      void name
+      return []
+    },
+  }
+
+  return self
+}

package/src/response.ts

@@ -0,0 +1,100 @@
+/**
+ * frappe.response — HTTP Response factory helpers.
+ *
+ * Available on every request context as `frappe.response.*` and importable
+ * directly for use in framework internals.
+ *
+ * Handlers returning a plain value are wrapped automatically by invokeRoute().
+ * Use these helpers when you need explicit control over status codes or headers.
+ *
+ * Examples:
+ *   return frappe.response.ok({ name: "INV-001" })
+ *   return frappe.response.created(doc.asDict())
+ *   return frappe.response.error("Not enough stock", 409)
+ */
+
+// ─── Standard envelope shapes ─────────────────────────────
+
+export interface DataEnvelope {
+  data: unknown
+}
+export interface ErrorEnvelope {
+  error: string
+}
+
+// ─── Response helpers ─────────────────────────────────────
+
+/** `{ data }` with 200 OK. */
+function ok(data: unknown): Response {
+  return build({ data }, 200)
+}
+
+/**
+ * Alias for `ok()` — matches the natural instinct to call
+ * `frappe.response.json(...)`. Returns `{ data }` with 200.
+ */
+const json = ok
+
+/** `{ data }` with 201 Created. */
+function created(data: unknown): Response {
+  return build({ data }, 201)
+}
+
+/**
+ * `{ data }` with a custom status code.
+ * Use for 2xx codes where `ok` and `created` don't fit (e.g. 202 Accepted).
+ */
+function success(data: unknown, status = 200): Response {
+  return build({ data }, status)
+}
+
+/** `{ error: message }` with an explicit HTTP status. */
+function error(message: string, status = 400): Response {
+  return build({ error: message }, status)
+}
+
+/** 401 Unauthorized. */
+function unauthorized(message = "Authentication required"): Response {
+  return error(message, 401)
+}
+
+/** 403 Forbidden. */
+function forbidden(message = "Permission denied"): Response {
+  return error(message, 403)
+}
+
+/** 404 Not Found. */
+function notFound(message = "Not found"): Response {
+  return error(message, 404)
+}
+
+/** 405 Method Not Allowed. */
+function methodNotAllowed(message = "Method not allowed"): Response {
+  return error(message, 405)
+}
+
+// ─── Namespace export ─────────────────────────────────────
+
+/** frappe.response — HTTP Response factory helpers. */
+export const response = {
+  ok,
+  json,
+  created,
+  success,
+  error,
+  unauthorized,
+  forbidden,
+  notFound,
+  methodNotAllowed,
+} as const
+
+export type FrappeResponse = typeof response
+
+// ─── Internal helper ──────────────────────────────────────
+
+function build(body: object, status: number): Response {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { "Content-Type": "application/json" },
+  })
+}

package/src/server.ts

@@ -0,0 +1,210 @@
+/**
+ * Bun HTTP server — site resolution, per-request context, and dispatch.
+ *
+ * Built-in endpoint modules live in src/api/ and follow the same route()
+ * convention as user app endpoints.  They are registered as fixed (system)
+ * routes at startup so they survive routeRegistry.clear() in tests.
+ *
+ * Dispatch order:
+ *   1. api/method  — built-in debug/test helpers
+ *   2. routeRegistry — framework routes first (fixed), then user routes (dynamic)
+ */
+
+import type { Server } from "bun"
+import { existsSync, readdirSync, statSync } from "node:fs"
+import { join } from "node:path"
+type AnyServer = Server<undefined>
+import { isRouteDefinition, invokeRoute, routeRegistry } from "./api/route"
+import { resolveAuth, verifyCsrf } from "./auth/auth"
+import { contextStore, createContext } from "./context"
+import { registerCoreDocTypes } from "./core/doctypes"
+import { FrappeDatabase } from "./database/database"
+import { FrappeError, ValidationError } from "./errors"
+import { response } from "./response"
+import { resolveSite, loadSiteConfig } from "./site"
+import { handlePageRequest, type PageMatcher } from "./ssr/handler"
+
+export interface ServerOptions {
+  port?: number
+  sitesDir: string
+  /** Static-route page matcher from the SSR subsystem. If provided, GET requests
+   * are tried against it before falling through to route/404 handling. */
+  pageMatcher?: PageMatcher
+  /** HTML document title for SSR'd pages. */
+  pageTitle?: string
+}
+
+// ─── Site DB cache ─────────────────────────────────────────
+
+const siteDbCache = new Map<string, FrappeDatabase>()
+
+function getOrCreateDb(site: string, sitesDir: string): FrappeDatabase {
+  const cached = siteDbCache.get(site)
+  if (cached) return cached
+
+  const siteConfig = loadSiteConfig(site, sitesDir)
+  const dbPath = join(sitesDir, site, "site.db")
+  const db = new FrappeDatabase(dbPath, { debug: Boolean(siteConfig["developer_mode"]) })
+  siteDbCache.set(site, db)
+  return db
+}
+
+/**
+ * Initialize a site's database: register core DocTypes and migrate schema.
+ * Safe to call multiple times — re-uses cached DB after first call.
+ */
+export async function initSiteDb(site: string, sitesDir: string): Promise<FrappeDatabase> {
+  await registerCoreDocTypes()
+  const db = getOrCreateDb(site, sitesDir)
+  db.migrate()
+  return db
+}
+
+/** Close and remove all cached site databases. Useful for test cleanup. */
+export function closeAllDbs(): void {
+  for (const db of siteDbCache.values()) db.close()
+  siteDbCache.clear()
+}
+
+// ─── Framework route registration ─────────────────────────
+
+let frameworkRoutesRegistered = false
+
+/**
+ * Register all framework routes (auth, resource) as system routes.
+ * System routes survive routeRegistry.clear() — they're registered once
+ * at server startup and never need to be re-registered.
+ */
+async function registerFrameworkRoutes(): Promise<void> {
+  if (frameworkRoutesRegistered) return
+  frameworkRoutesRegistered = true
+
+  const [authModule, resourceModule] = await Promise.all([
+    import("./api/auth") as Promise<Record<string, unknown>>,
+    import("./api/resource") as Promise<Record<string, unknown>>,
+  ])
+
+  for (const [name, def] of Object.entries({ ...authModule, ...resourceModule })) {
+    if (isRouteDefinition(def) && def.config.path) {
+      // path: on framework routes is the full absolute server path
+      routeRegistry.registerSystem(def.config.path, def, name)
+    }
+  }
+}
+
+// ─── Built-in debug/test methods ──────────────────────────
+
+type BuiltinHandler = (req: Request) => unknown
+
+const builtinMethods: Record<string, BuiltinHandler> = {
+  ping: () => "pong",
+
+  __test_error: () => {
+    throw new ValidationError("test error")
+  },
+
+  __test_context: () => {
+    const ctx = contextStore.getStore()
+    if (!ctx) throw new Error("No context")
+    return { user: ctx.user, site: ctx.site, env: ctx.env }
+  },
+}
+
+// ─── Server ────────────────────────────────────────────────
+
+export async function createServer(opts: ServerOptions): Promise<AnyServer> {
+  const { sitesDir, pageMatcher, pageTitle } = opts
+
+  await registerFrameworkRoutes()
+
+  if (existsSync(sitesDir)) {
+    for (const entry of readdirSync(sitesDir)) {
+      if (entry.startsWith(".") || entry === "common_site_config.json") continue
+      const entryPath = join(sitesDir, entry)
+      if (statSync(entryPath).isDirectory() && existsSync(join(entryPath, "site_config.json"))) {
+        await initSiteDb(entry, sitesDir)
+      }
+    }
+  }
+
+  return Bun.serve({
+    port: opts.port ?? 8000,
+
+    async fetch(req) {
+      const url = new URL(req.url)
+
+      let site: string
+      try {
+        site = resolveSite(req, sitesDir)
+      } catch (e) {
+        return jsonResponse({ error: (e as Error).message }, 400)
+      }
+
+      const db = getOrCreateDb(site, sitesDir)
+      const auth = await resolveAuth(req, db)
+
+      const ctx = createContext({
+        user: auth.user,
+        site,
+        db,
+        sid: auth.sid,
+        csrfToken: auth.csrfToken,
+        request: req,
+      })
+
+      return contextStore.run(ctx, async () => {
+        try {
+          if (auth.sid && !verifyCsrf(req, auth.csrfToken)) {
+            return response.forbidden("CSRF token mismatch")
+          }
+          if (pageMatcher) {
+            const page = await handlePageRequest(req, url, pageMatcher, { title: pageTitle })
+            if (page) return page
+          }
+          return await dispatch(req, url)
+        } catch (error) {
+          return handleError(error)
+        }
+      })
+    },
+  })
+}
+
+// ─── Dispatcher ────────────────────────────────────────────
+
+async function dispatch(req: Request, url: URL): Promise<Response> {
+  const { pathname } = url
+
+  // api/method — built-in debug/test endpoints
+  const methodMatch = pathname.match(/^\/api\/method\/(.+)$/)
+  if (methodMatch) {
+    const name = methodMatch[1]!
+    const handler = builtinMethods[name]
+    if (!handler) return response.notFound(`Method "${name}" not found`)
+    // Built-in methods use { message } envelope (legacy shape)
+    const result = await handler(req)
+    return new Response(JSON.stringify({ message: result }), {
+      status: 200,
+      headers: { "Content-Type": "application/json" },
+    })
+  }
+
+  // All other routes — framework (fixed) and user (dynamic) via registry
+  const matched = routeRegistry.match(pathname, req.method)
+  if (matched) return invokeRoute(matched.def, matched.params)
+
+  return response.notFound()
+}
+
+// ─── Utilities ─────────────────────────────────────────────
+
+function handleError(error: unknown): Response {
+  if (error instanceof FrappeError) {
+    return new Response(
+      JSON.stringify({ exc_type: error.name, message: error.message, title: error.title }),
+      { status: error.httpStatus, headers: { "Content-Type": "application/json" } },
+    )
+  }
+  console.error("Unhandled error:", error)
+  return response.error("Internal Server Error", 500)
+}

package/src/site.ts

@@ -0,0 +1,126 @@
+/**
+ * Site resolution and config loading for multi-tenancy.
+ */
+
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs"
+import { join } from "node:path"
+
+export interface SiteConfig {
+  [key: string]: unknown
+}
+
+/**
+ * Resolve which site a request is for.
+ *
+ * Resolution order:
+ * 1. X-Frappe-Site header
+ * 2. Host header (without port)
+ * 3. default_site from common_site_config.json
+ * 4. The only site (if exactly one exists)
+ */
+export function resolveSite(req: Request, sitesDir: string): string {
+  // 1. X-Frappe-Site header takes precedence
+  const xSite = req.headers.get("x-frappe-site")
+  if (xSite) {
+    validateSiteExists(xSite, sitesDir)
+    return xSite
+  }
+
+  // 2. Host header
+  const host = req.headers.get("host")
+  if (host) {
+    const hostname = host.split(":")[0]!
+    if (siteExists(hostname, sitesDir)) {
+      return hostname
+    }
+  }
+
+  // 3. default_site from common config
+  const commonConfig = loadCommonConfig(sitesDir)
+  if (commonConfig.default_site) {
+    validateSiteExists(commonConfig.default_site, sitesDir)
+    return commonConfig.default_site
+  }
+
+  // 4. Only site
+  const sites = listSites(sitesDir)
+  if (sites.length === 1) {
+    return sites[0]!
+  }
+
+  if (sites.length === 0) {
+    throw new Error("No sites found in " + sitesDir)
+  }
+
+  throw new Error(
+    `Could not resolve site. Multiple sites exist (${sites.join(", ")}). ` +
+      `Set default_site in common_site_config.json or pass X-Frappe-Site header.`,
+  )
+}
+
+/**
+ * Load merged site config.
+ * Priority: env vars > site_config.json > common_site_config.json
+ */
+export function loadSiteConfig(site: string, sitesDir: string): SiteConfig {
+  const common = loadCommonConfig(sitesDir)
+  const siteConfigPath = join(sitesDir, site, "site_config.json")
+  const siteConf = existsSync(siteConfigPath)
+    ? JSON.parse(readFileSync(siteConfigPath, "utf-8"))
+    : {}
+
+  // Merge: common < site < env
+  const merged: SiteConfig = { ...common, ...siteConf }
+
+  // Apply FRAPPE_* environment variables
+  const envMapping: Record<string, string> = {
+    FRAPPE_DB_HOST: "db_host",
+    FRAPPE_DB_PORT: "db_port",
+    FRAPPE_DB_NAME: "db_name",
+    FRAPPE_DB_USER: "db_user",
+    FRAPPE_DB_PASSWORD: "db_password",
+    FRAPPE_DB_TYPE: "db_type",
+    FRAPPE_REDIS_URL: "redis_url",
+  }
+
+  for (const [envKey, configKey] of Object.entries(envMapping)) {
+    if (process.env[envKey]) {
+      merged[configKey] = process.env[envKey]
+    }
+  }
+
+  return merged
+}
+
+/** Read the `default_site` from `common_site_config.json`, or undefined. */
+export function getDefaultSite(sitesDir: string): string | undefined {
+  const config = loadCommonConfig(sitesDir)
+  return config.default_site as string | undefined
+}
+
+function loadCommonConfig(sitesDir: string): SiteConfig {
+  const commonPath = join(sitesDir, "common_site_config.json")
+  if (existsSync(commonPath)) {
+    return JSON.parse(readFileSync(commonPath, "utf-8"))
+  }
+  return {}
+}
+
+function listSites(sitesDir: string): string[] {
+  if (!existsSync(sitesDir)) return []
+  return readdirSync(sitesDir).filter((entry) => {
+    if (entry.startsWith(".") || entry === "common_site_config.json") return false
+    const entryPath = join(sitesDir, entry)
+    return statSync(entryPath).isDirectory() && existsSync(join(entryPath, "site_config.json"))
+  })
+}
+
+function siteExists(site: string, sitesDir: string): boolean {
+  return existsSync(join(sitesDir, site, "site_config.json"))
+}
+
+function validateSiteExists(site: string, sitesDir: string): void {
+  if (!siteExists(site, sitesDir)) {
+    throw new Error(`Site "${site}" does not exist in ${sitesDir}`)
+  }
+}