- + ⭐ Live Demo
-bknd simplifies app development by providing a fully functional backend for database management, authentication, media and workflows. Being lightweight and built on Web Standards, it can be deployed nearly anywhere, including running inside your framework of choice. No more deploying multiple separate services! +bknd simplifies app development by providing a fully functional visual backend for database management, authentication, media and workflows. Being lightweight and built on Web Standards, it can be deployed nearly anywhere, including running inside your framework of choice. No more deploying multiple separate services! + +It's designed to avoid vendor lock-in and architectural limitations. Built exclusively on [WinterTC Minimum Common Web Platform API](https://min-common-api.proposal.wintertc.org/) for universal compatibility, all functionality (data, auth, media, flows) is modular and opt-in, and infrastructure access is adapter-based with direct access to underlying drivers giving you full control without abstractions getting in your way. + * **Runtimes**: Node.js 22+, Bun 1.0+, Deno, Browser, Cloudflare Workers/Pages, Vercel, Netlify, AWS Lambda, etc. * **Databases**: * SQLite: LibSQL, Node SQLite, Bun SQLite, Cloudflare D1, Cloudflare Durable Objects SQLite, SQLocal * Postgres: Vanilla Postgres, Supabase, Neon, Xata * **Frameworks**: React, Next.js, React Router, Astro, Vite, Waku * **Storage**: AWS S3, S3-compatible (Tigris, R2, Minio, etc.), Cloudflare R2 (binding), Cloudinary, Filesystem +* **Deployment**: Standalone, Docker, Cloudflare Workers, Vercel, Netlify, Deno Deploy, AWS Lambda, Valtown etc. **For documentation and examples, please visit https://docs.bknd.io.** > [!WARNING] -> This project requires Node.js 22 or higher (because of `node:sqlite`). +> This project requires Node.js 22.13 or higher (because of `node:sqlite`). > > Please keep in mind that **bknd** is still under active development > and therefore full backward compatibility is not guaranteed before reaching v1.0.0. +## Use Cases + +bknd is a general purpose backend system that implements the primitives almost any backend needs. This way, you can use it for any backend use case, including but not limited to: + +- **Content Management System (CMS)** as Wordpress alternative, hosted separately or embedded in your frontend +- **AI Agent Backends** for managing agent state with built-in data persistence, regardless where it is hosted. Optionally communicate over the integrated MCP server. +- **SaaS Products** with multi-tenant data isolation (RLS) and user management, with freedom to choose your own database and storage provider +- **Prototypes & MVPs** to validate ideas quickly without infrastructure overhead +- **API-First Applications** where you need a reliable, type-safe backend without vendor lock-in either with the integrated TypeScript SDK or REST API using OpenAPI +- **IoT & Embedded Devices** where minimal footprint matters + + ## Size   - - + + The size on npm is misleading, as the `bknd` package includes the backend, the ui components as well as the whole backend bundled into the cli including static assets. @@ -46,6 +62,7 @@ Creating digital products always requires developing both the backend (the logic * **Media**: Effortlessly manage and serve all your media files. * **Flows**: Design and run workflows with seamless automation. (UI integration coming soon!) * 🌐 Built on Web Standards for maximum compatibility +* 🛠️ MCP server, client and UI built-in to control your backend * 🏃♂️ Multiple run modes * standalone using the CLI * using a JavaScript runtime (Node, Bun, workerd) diff --git a/app/__test__/App.spec.ts b/app/__test__/App.spec.ts index 0b456e1..7213216 100644 --- a/app/__test__/App.spec.ts +++ b/app/__test__/App.spec.ts @@ -1,12 +1,15 @@ -import { afterEach, describe, test, expect } from "bun:test"; +import { afterEach, describe, test, expect, beforeAll, afterAll } from "bun:test"; import { App, createApp } from "core/test/utils"; import { getDummyConnection } from "./helper"; import { Hono } from "hono"; import * as proto from "../src/data/prototype"; import { pick } from "lodash-es"; +import { disableConsoleLog, enableConsoleLog } from "core/utils/test"; + +beforeAll(() => disableConsoleLog()); const { dummyConnection, afterAllCleanup } = getDummyConnection(); -afterEach(afterAllCleanup); +afterEach(async () => (await afterAllCleanup()) && enableConsoleLog()); describe("App tests", async () => { test("boots and pongs", async () => { @@ -19,7 +22,7 @@ describe("App tests", async () => { test("plugins", async () => { const called: string[] = []; const app = createApp({ - initialConfig: { + config: { auth: { enabled: true, }, diff --git a/app/__test__/_assets/test.mp3 b/app/__test__/_assets/test.mp3 new file mode 100644 index 0000000..ab94045 Binary files /dev/null and b/app/__test__/_assets/test.mp3 differ diff --git a/app/__test__/_assets/test.txt b/app/__test__/_assets/test.txt new file mode 100644 index 0000000..b6fc4c6 --- /dev/null +++ b/app/__test__/_assets/test.txt @@ -0,0 +1 @@ +hello \ No newline at end of file diff --git a/app/__test__/adapter/adapter.test.ts b/app/__test__/adapter/adapter.test.ts index f7d623c..8527b5d 100644 --- a/app/__test__/adapter/adapter.test.ts +++ b/app/__test__/adapter/adapter.test.ts @@ -1,4 +1,4 @@ -import { expect, describe, it, beforeAll, afterAll } from "bun:test"; +import { expect, describe, it, beforeAll, afterAll, mock } from "bun:test"; import * as adapter from "adapter"; import { disableConsoleLog, enableConsoleLog } from "core/utils"; import { adapterTestSuite } from "adapter/adapter-test-suite"; @@ -9,60 +9,49 @@ beforeAll(disableConsoleLog); afterAll(enableConsoleLog); describe("adapter", () => { - it("makes config", () => { - expect(omitKeys(adapter.makeConfig({}), ["connection"])).toEqual({}); - expect(omitKeys(adapter.makeConfig({}, { env: { TEST: "test" } }), ["connection"])).toEqual( - {}, - ); + it("makes config", async () => { + expect(omitKeys(await adapter.makeConfig({}), ["connection"])).toEqual({}); + expect( + omitKeys(await adapter.makeConfig({}, { env: { TEST: "test" } }), ["connection"]), + ).toEqual({}); // merges everything returned from `app` with the config expect( omitKeys( - adapter.makeConfig( - { app: (a) => ({ initialConfig: { server: { cors: { origin: a.env.TEST } } } }) }, + await adapter.makeConfig( + { app: (a) => ({ config: { server: { cors: { origin: a.env.TEST } } } }) }, { env: { TEST: "test" } }, ), ["connection"], ), ).toEqual({ - initialConfig: { server: { cors: { origin: "test" } } }, + config: { server: { cors: { origin: "test" } } }, }); }); - /* it.only("...", async () => { - const app = await adapter.createAdapterApp(); - }); */ - - it("reuses apps correctly", async () => { - const id = crypto.randomUUID(); - - const first = await adapter.createAdapterApp( + it("allows all properties in app function", async () => { + const called = mock(() => null); + const config = await adapter.makeConfig( { - initialConfig: { server: { cors: { origin: "random" } } }, + app: (env) => ({ + connection: { url: "test" }, + config: { server: { cors: { origin: "test" } } }, + options: { + mode: "db", + }, + onBuilt: () => { + called(); + expect(env).toEqual({ foo: "bar" }); + }, + }), }, - undefined, - { id }, + { foo: "bar" }, ); - const second = await adapter.createAdapterApp(); - const third = await adapter.createAdapterApp(undefined, undefined, { id }); - - await first.build(); - await second.build(); - await third.build(); - - expect(first.toJSON().server.cors.origin).toEqual("random"); - expect(first).toBe(third); - expect(first).not.toBe(second); - expect(second).not.toBe(third); - expect(second.toJSON().server.cors.origin).toEqual("*"); - - // recreate the first one - const first2 = await adapter.createAdapterApp(undefined, undefined, { id, force: true }); - await first2.build(); - expect(first2).not.toBe(first); - expect(first2).not.toBe(third); - expect(first2).not.toBe(second); - expect(first2.toJSON().server.cors.origin).toEqual("*"); + expect(config.connection).toEqual({ url: "test" }); + expect(config.config).toEqual({ server: { cors: { origin: "test" } } }); + expect(config.options).toEqual({ mode: "db" }); + await config.onBuilt?.(null as any); + expect(called).toHaveBeenCalled(); }); adapterTestSuite(bunTestRunner, { diff --git a/app/__test__/api/Api.spec.ts b/app/__test__/api/Api.spec.ts index dee1e14..4384928 100644 --- a/app/__test__/api/Api.spec.ts +++ b/app/__test__/api/Api.spec.ts @@ -6,13 +6,16 @@ describe("Api", async () => { it("should construct without options", () => { const api = new Api(); expect(api.baseUrl).toBe("http://localhost"); - expect(api.isAuthVerified()).toBe(false); + + // verified is true, because no token, user, headers or request given + // therefore nothing to check, auth state is verified + expect(api.isAuthVerified()).toBe(true); }); it("should ignore force verify if no claims given", () => { const api = new Api({ verified: true }); expect(api.baseUrl).toBe("http://localhost"); - expect(api.isAuthVerified()).toBe(false); + expect(api.isAuthVerified()).toBe(true); }); it("should construct from request (token)", async () => { @@ -42,7 +45,6 @@ describe("Api", async () => { expect(api.isAuthVerified()).toBe(false); const params = api.getParams(); - console.log(params); expect(params.token).toBe(token); expect(params.token_transport).toBe("cookie"); expect(params.host).toBe("http://example.com"); diff --git a/app/__test__/app/App.spec.ts b/app/__test__/app/App.spec.ts index 361bbef..5bbee56 100644 --- a/app/__test__/app/App.spec.ts +++ b/app/__test__/app/App.spec.ts @@ -1,9 +1,23 @@ -import { describe, expect, mock, test } from "bun:test"; +import { afterAll, beforeAll, describe, expect, mock, test } from "bun:test"; import type { ModuleBuildContext } from "../../src"; import { App, createApp } from "core/test/utils"; -import * as proto from "../../src/data/prototype"; +import * as proto from "data/prototype"; +import { DbModuleManager } from "modules/db/DbModuleManager"; +import { disableConsoleLog, enableConsoleLog } from "core/utils/test"; + +beforeAll(disableConsoleLog); +afterAll(enableConsoleLog); describe("App", () => { + test("use db mode by default", async () => { + const app = createApp(); + await app.build(); + + expect(app.mode).toBe("db"); + expect(app.isReadOnly()).toBe(false); + expect(app.modules instanceof DbModuleManager).toBe(true); + }); + test("seed includes ctx and app", async () => { const called = mock(() => null); await createApp({ @@ -20,6 +34,7 @@ describe("App", () => { "guard", "flags", "logger", + "mcp", "helper", ]); }, @@ -28,7 +43,7 @@ describe("App", () => { expect(called).toHaveBeenCalled(); const app = createApp({ - initialConfig: { + config: { data: proto .em({ todos: proto.entity("todos", { @@ -135,4 +150,21 @@ describe("App", () => { // expect async listeners to be executed sync after request expect(called).toHaveBeenCalled(); }); + + test("getMcpClient", async () => { + const app = createApp({ + config: { + server: { + mcp: { + enabled: true, + }, + }, + }, + }); + await app.build(); + const client = app.getMcpClient(); + const res = await client.listTools(); + expect(res).toBeDefined(); + expect(res?.tools.length).toBeGreaterThan(0); + }); }); diff --git a/app/__test__/app/AppServer.spec.ts b/app/__test__/app/AppServer.spec.ts index 40ea414..1933787 100644 --- a/app/__test__/app/AppServer.spec.ts +++ b/app/__test__/app/AppServer.spec.ts @@ -13,6 +13,11 @@ describe("AppServer", () => { allow_methods: ["GET", "POST", "PATCH", "PUT", "DELETE"], allow_headers: ["Content-Type", "Content-Length", "Authorization", "Accept"], }, + mcp: { + enabled: false, + path: "/api/system/mcp", + logLevel: "warning", + }, }); } @@ -31,6 +36,11 @@ describe("AppServer", () => { allow_methods: ["GET", "POST"], allow_headers: ["Content-Type", "Content-Length", "Authorization", "Accept"], }, + mcp: { + enabled: false, + path: "/api/system/mcp", + logLevel: "warning", + }, }); } }); diff --git a/app/__test__/app/code-only.test.ts b/app/__test__/app/code-only.test.ts new file mode 100644 index 0000000..26fb8e9 --- /dev/null +++ b/app/__test__/app/code-only.test.ts @@ -0,0 +1,127 @@ +import { describe, expect, mock, test } from "bun:test"; +import { createApp as internalCreateApp, type CreateAppConfig } from "bknd"; +import { getDummyConnection } from "../../__test__/helper"; +import { ModuleManager } from "modules/ModuleManager"; +import { em, entity, text } from "data/prototype"; + +async function createApp(config: CreateAppConfig = {}) { + const app = internalCreateApp({ + connection: getDummyConnection().dummyConnection, + ...config, + options: { + ...config.options, + mode: "code", + }, + }); + await app.build(); + return app; +} + +describe("code-only", () => { + test("should create app with correct manager", async () => { + const app = await createApp(); + await app.build(); + + expect(app.version()).toBeDefined(); + expect(app.modules).toBeInstanceOf(ModuleManager); + }); + + test("should not perform database syncs", async () => { + const app = await createApp({ + config: { + data: em({ + test: entity("test", { + name: text(), + }), + }).toJSON(), + }, + }); + expect(app.em.entities.map((e) => e.name)).toEqual(["test"]); + expect( + await app.em.connection.kysely + .selectFrom("sqlite_master") + .where("type", "=", "table") + .selectAll() + .execute(), + ).toEqual([]); + + // only perform when explicitly forced + await app.em.schema().sync({ force: true }); + expect( + await app.em.connection.kysely + .selectFrom("sqlite_master") + .where("type", "=", "table") + .selectAll() + .execute() + .then((r) => r.map((r) => r.name)), + ).toEqual(["test", "sqlite_sequence"]); + }); + + test("should not perform seeding", async () => { + const called = mock(() => null); + const app = await createApp({ + config: { + data: em({ + test: entity("test", { + name: text(), + }), + }).toJSON(), + }, + options: { + seed: async (ctx) => { + called(); + await ctx.em.mutator("test").insertOne({ name: "test" }); + }, + }, + }); + await app.em.schema().sync({ force: true }); + expect(called).not.toHaveBeenCalled(); + expect( + await app.em + .repo("test") + .findMany({}) + .then((r) => r.data), + ).toEqual([]); + }); + + test("should sync and perform seeding", async () => { + const called = mock(() => null); + const app = await createApp({ + config: { + data: em({ + test: entity("test", { + name: text(), + }), + }).toJSON(), + }, + options: { + seed: async (ctx) => { + called(); + await ctx.em.mutator("test").insertOne({ name: "test" }); + }, + }, + }); + + await app.em.schema().sync({ force: true }); + await app.options?.seed?.({ + ...app.modules.ctx(), + app: app, + }); + expect(called).toHaveBeenCalled(); + expect( + await app.em + .repo("test") + .findMany({}) + .then((r) => r.data), + ).toEqual([{ id: 1, name: "test" }]); + }); + + test("should not allow to modify config", async () => { + const app = await createApp(); + // biome-ignore lint/suspicious/noPrototypeBuiltins:>( + permission: P, + c: GuardContext, + context: PermissionContext
, + ): void; + granted
>(permission: P, c: GuardContext): void; + granted
>( + permission: P, + c: GuardContext, + context?: PermissionContext
, + ): void { + if (!this.isEnabled()) { + return; + } + const { ctx: _ctx, exists, role, rolePermission } = this.collect(permission, c, context); + + // validate context + let ctx = Object.assign({}, _ctx); + if (permission.context) { + ctx = permission.parseContext(ctx); + } + + $console.debug("guard: checking permission", { + name: permission.name, + context: ctx, + }); + if (!exists) { + throw new GuardPermissionsException( + permission, + undefined, + `Permission ${permission.name} does not exist`, ); } + + if (!role) { + throw new GuardPermissionsException(permission, undefined, "User has no role"); + } + + if (!rolePermission) { + if (role.implicit_allow === true) { + $console.debug(`guard: role "${role.name}" has implicit allow, allowing`); + return; + } + + throw new GuardPermissionsException( + permission, + undefined, + `Role "${role.name}" does not have required permission`, + ); + } + + if (rolePermission?.policies.length > 0) { + $console.debug("guard: rolePermission has policies, checking"); + + // set the default effect of the role permission + let allowed = rolePermission.effect === "allow"; + for (const policy of rolePermission.policies) { + $console.debug("guard: checking policy", { policy: policy.toJSON(), ctx }); + // skip filter policies + if (policy.content.effect === "filter") continue; + + // if condition is met, check the effect + const meets = policy.meetsCondition(ctx); + if (meets) { + $console.debug("guard: policy meets condition"); + // if deny, then break early + if (policy.content.effect === "deny") { + $console.debug("guard: policy is deny, setting allowed to false"); + allowed = false; + break; + + // if allow, set allow but continue checking + } else if (policy.content.effect === "allow") { + allowed = true; + } + } else { + $console.debug("guard: policy does not meet condition"); + } + } + + if (!allowed) { + throw new GuardPermissionsException(permission, undefined, "Policy condition unmet"); + } + } + + $console.debug("guard allowing", { + permission: permission.name, + role: role.name, + }); + } + + filters
>( + permission: P, + c: GuardContext, + context: PermissionContext
, + ); + filters
>(permission: P, c: GuardContext); + filters
>( + permission: P, + c: GuardContext, + context?: PermissionContext
,
+ ) {
+ if (!permission.isFilterable()) {
+ throw new GuardPermissionsException(permission, undefined, "Permission is not filterable");
+ }
+
+ const {
+ ctx: _ctx,
+ exists,
+ role,
+ user,
+ rolePermission,
+ } = this.collect(permission, c, context);
+
+ // validate context
+ let ctx = Object.assign(
+ {
+ user,
+ },
+ _ctx,
+ );
+
+ if (permission.context) {
+ ctx = permission.parseContext(ctx, {
+ coerceDropUnknown: false,
+ });
+ }
+
+ const filters: PolicySchema["filter"][] = [];
+ const policies: Policy[] = [];
+ if (exists && role && rolePermission && rolePermission.policies.length > 0) {
+ for (const policy of rolePermission.policies) {
+ if (policy.content.effect === "filter") {
+ const meets = policy.meetsCondition(ctx);
+ if (meets) {
+ policies.push(policy);
+ filters.push(policy.getReplacedFilter(ctx));
+ }
+ }
+ }
+ }
+
+ const filter = filters.length > 0 ? mergeObject({}, ...filters) : undefined;
+ return {
+ filters,
+ filter,
+ policies,
+ merge: (givenFilter: object | undefined) => {
+ return mergeFilters(givenFilter ?? {}, filter ?? {});
+ },
+ matches: (subject: object | object[], opts?: { throwOnError?: boolean }) => {
+ const subjects = Array.isArray(subject) ? subject : [subject];
+ if (policies.length > 0) {
+ for (const policy of policies) {
+ for (const subject of subjects) {
+ if (!policy.meetsFilter(subject, ctx)) {
+ if (opts?.throwOnError) {
+ throw new GuardPermissionsException(
+ permission,
+ policy,
+ "Policy filter not met",
+ );
+ }
+ return false;
+ }
+ }
+ }
+ }
+ return true;
+ },
+ };
}
}
+
+export function mergeFilters(base: ObjectQuery, priority: ObjectQuery) {
+ const base_converted = convert(base);
+ const priority_converted = convert(priority);
+ const merged = mergeObject(base_converted, priority_converted);
+
+ // in case priority filter is also contained in base's $and, merge priority in
+ if ("$or" in base_converted && base_converted.$or) {
+ const $ors = base_converted.$or as ObjectQuery;
+ const priority_keys = Object.keys(priority_converted);
+ for (const key of priority_keys) {
+ if (key in $ors) {
+ merged.$or[key] = mergeObject($ors[key], priority_converted[key]);
+ }
+ }
+ }
+
+ return merged;
+}
diff --git a/app/src/auth/authorize/Permission.ts b/app/src/auth/authorize/Permission.ts
new file mode 100644
index 0000000..cfd5963
--- /dev/null
+++ b/app/src/auth/authorize/Permission.ts
@@ -0,0 +1,77 @@
+import { s, type ParseOptions, parse, InvalidSchemaError, HttpStatus } from "bknd/utils";
+
+export const permissionOptionsSchema = s
+ .strictObject({
+ description: s.string(),
+ filterable: s.boolean(),
+ })
+ .partial();
+
+export type TPermission = {
+ name: string;
+ description?: string;
+ filterable?: boolean;
+ context?: any;
+};
+
+export type PermissionOptions = s.Static > = P extends Permission<
+ any,
+ any,
+ infer Context,
+ any
+>
+ ? Context extends s.ObjectSchema
+ ? s.Static > = {
+ onGranted?: (c: Context >(
+ permission: P,
+ options: PermissionMiddlewareOptions ,
+) {
+ // @ts-ignore (middlewares do not always return)
+ const handler = createMiddleware