@veducio/keja 0.0.0-stage → 0.2.3

package/LICENSE

@@ -0,0 +1,7 @@
+Copyright © 2026 Veducio
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -1,3 +1,40 @@
-# Temporary Holding Version
+# keja
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Hono server framework for Bun.
+
+Copy `.env.example` to `.env` and set `HOST`, `HTTP_PORT`, and `HTTP_SERVICE_PORT` before starting. `OPENAPI_SERVER` and `OPENAPI_SERVICE_SERVER` are optional absolute http or https URLs written into each OpenAPI document. The names and validators live in `src/env/required-env.ts`.
+
+A project keeps `keja.versioning.ts` at its root. Public routes live in `src/public` and service routes live in `src/service`, one `defineRoute` module per file. `bun run dev` and `bun run start` load that project from the current directory and listen on both ports. Each server exposes `/_health`, `/_openapi.json`, and `/docs`.
+
+## Commands
+
+- `examples/example-app` is its own package. From that directory, `bun install` then `bun dev` starts it. The app defines `v1` and `v2`, serves users and posts on the public port, and creates jobs on the service port.
+- `bun run dev` runs the self-test, then starts the development server with Bun watch. Run it from a Keja project. In this repository it fails until `keja.versioning.ts` exists in the current directory.
+- `bun run start` runs the self-test, then starts the server once.
+- `bun run self-test` checks that the process is Bun, checks the machine, then checks required environment variables.
+- `keja dev` and `keja start` are the same commands through the CLI. `keja build` and `keja init` are reserved for a later specification.
+- `bun run typecheck` typechecks the project with TypeScript.
+- `bun run test` runs the Vitest suite once.
+- `bun run test:watch` runs Vitest in watch mode.
+- `bun run lint` lints the project with Biome.
+- `bun run format` formats the project with Biome.
+- `bun run check` runs the Biome formatter and linter without writing.
+
+## Git hooks
+
+Husky installs the hooks in `.husky` on `bun install`.
+
+- Commits and pushes directly to `production` are rejected.
+- Commit messages must use Conventional Commits, such as `feat: add a route` or `fix(api): handle a missing host`.
+- Staged files are checked with Biome before a commit is created.
+
+## Versioning
+
+A push to `production` or `main` runs the test suite, then chooses a version bump from the commit messages in that push:
+
+- `type!:` or a `BREAKING CHANGE:` footer bumps the major version.
+- `feat:` bumps the minor version.
+- `fix:` bumps the patch version.
+- Any other message does not bump the version.
+
+When several commits are pushed together, the highest bump wins. The workflow commits `chore: release <version>` and pushes that commit plus the git tag.

package/examples/starter/.env.example

@@ -0,0 +1,6 @@
+HOST=127.0.0.1
+HTTP_PORT=3000
+HTTP_SERVICE_PORT=3001
+OPENAPI_SERVER=http://127.0.0.1:3000
+OPENAPI_SERVICE_SERVER=http://127.0.0.1:3001
+DATABASE_URL=postgres://postgres:postgres@127.0.0.1:5432/keja

package/examples/starter/keja.config.ts

@@ -0,0 +1,7 @@
+import { defineConfig } from "@veducio/keja";
+
+export default defineConfig({
+  public_path: "src/public",
+  service_path: "src/service",
+  db: { enabled: true },
+});

package/examples/starter/keja.versioning.ts

@@ -0,0 +1,5 @@
+import { defineVersions } from "@veducio/keja";
+
+export default defineVersions({
+  v1: { releasedAt: "2026-01-01" },
+});

package/examples/starter/migrations/0001_init.sql

@@ -0,0 +1 @@
+select 1;

package/examples/starter/package.json

@@ -0,0 +1,14 @@
+{
+  "name": "my-app",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "keja dev",
+    "start": "keja start"
+  },
+  "dependencies": {
+    "@veducio/keja": "^0.1.0",
+    "zod": "^4.6.7"
+  }
+}

package/examples/starter/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "paths": {
+      "@veducio/keja": ["../../src/server/index.ts"]
+    }
+  },
+  "include": ["**/*.ts"]
+}

package/package.json

@@ -1,6 +1,64 @@
 {
   "name": "@veducio/keja",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.3",
+  "packageManager": "bun@1.4.4",
+  "description": "Veducio Keja - RESTFUL Web Server, Based on Lightweight Hono Framework, Written in TypeScript, Powered by Bun",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/veducio/keja.git"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "files": [
+    "src",
+    "examples/starter",
+    "README.md",
+    "LICENSE"
+  ],
+  "type": "module",
+  "bin": {
+    "keja": "./src/cli/index.ts"
+  },
+  "main": "src/server/index.ts",
+  "exports": {
+    ".": "./src/server/index.ts",
+    "./cli": "./src/cli/index.ts"
+  },
+  "scripts": {
+    "dev": "bun src/cli/index.ts dev",
+    "start": "bun src/cli/index.ts start",
+    "self-test": "bun src/self-test/run.ts",
+    "typecheck": "tsc --noEmit && tsc --noEmit -p examples/example-app && tsc --noEmit -p examples/starter",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "biome lint .",
+    "format": "biome format --write .",
+    "check": "biome check .",
+    "docs": "cd docs && mint dev",
+    "prepare": "husky"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "2.6.6",
+    "@types/bun": "^1.4.4",
+    "husky": "^9.1.7",
+    "mint": "^4.3.6",
+    "typescript": "^7.0.2",
+    "vitest": "^5.1.0"
+  },
+  "dependencies": {
+    "@hono/zod-openapi": "^1.6.3",
+    "@scalar/hono-api-reference": "^0.12.18",
+    "chalk": "^6.0.1",
+    "citty": "^0.2.2",
+    "hono": "^4.13.17",
+    "jose": "^6.2.16",
+    "typeid-js": "^1.2.0",
+    "zod": "^4.6.7"
+  }
+}

package/src/access/cloudflare.test.ts

@@ -0,0 +1,131 @@
+import { generateKeyPair, SignJWT } from "jose";
+import { describe, expect, it } from "vitest";
+import { frameworkErrors } from "../errors/framework-errors.ts";
+import {
+  accessToken,
+  cloudflareAccess,
+  verifyAccessJwt,
+} from "./cloudflare.ts";
+
+const issuer = "https://veducio.cloudflareaccess.com";
+const audience = "app-aud";
+
+describe("accessToken", () => {
+  it("reads the assertion header before the cookie", () => {
+    const request = new Request("https://app.test", {
+      headers: {
+        "Cf-Access-Jwt-Assertion": "header-token",
+        cookie: "CF_Authorization=cookie-token",
+      },
+    });
+    expect(accessToken(request)).toBe("header-token");
+    expect(
+      accessToken(
+        new Request("https://app.test", {
+          headers: { cookie: "theme=light; CF_Authorization=cookie-token" },
+        }),
+      ),
+    ).toBe("cookie-token");
+  });
+});
+
+describe("verifyAccessJwt", () => {
+  it("accepts a token signed for the team audience", async () => {
+    const { publicKey, privateKey } = await generateKeyPair("ES256");
+    const token = await new SignJWT({
+      email: "ada@veducio.com",
+      country: "PL",
+    })
+      .setProtectedHeader({ alg: "ES256" })
+      .setIssuer(issuer)
+      .setAudience(audience)
+      .setSubject("ada")
+      .setIssuedAt()
+      .setExpirationTime("2m")
+      .sign(privateKey);
+
+    await expect(
+      verifyAccessJwt(token, {
+        team: "veducio.cloudflareaccess.com",
+        audience,
+        getKey: async () => publicKey,
+      }),
+    ).resolves.toMatchObject({
+      sub: "ada",
+      iss: issuer,
+      aud: [audience],
+      email: "ada@veducio.com",
+      country: "PL",
+    });
+  });
+
+  it("rejects a token for a different audience", async () => {
+    const { publicKey, privateKey } = await generateKeyPair("ES256");
+    const token = await new SignJWT({})
+      .setProtectedHeader({ alg: "ES256" })
+      .setIssuer(issuer)
+      .setAudience("other-app")
+      .setSubject("ada")
+      .setIssuedAt()
+      .setExpirationTime("2m")
+      .sign(privateKey);
+
+    await expect(
+      verifyAccessJwt(token, {
+        team: issuer,
+        audience,
+        getKey: async () => publicKey,
+      }),
+    ).rejects.toThrow("Cloudflare Access token was rejected");
+  });
+});
+
+describe("cloudflareAccess", () => {
+  it("passes the identity to the route and denies a missing token", async () => {
+    const { publicKey, privateKey } = await generateKeyPair("ES256");
+    const token = await new SignJWT({ email: "ada@veducio.com" })
+      .setProtectedHeader({ alg: "ES256" })
+      .setIssuer(issuer)
+      .setAudience(audience)
+      .setSubject("ada")
+      .setIssuedAt()
+      .setExpirationTime("2m")
+      .sign(privateKey);
+    const middleware = cloudflareAccess({
+      team: issuer,
+      audience,
+      getKey: async () => publicKey,
+    });
+    const accepted = await middleware.handle({
+      request: new Request("https://app.test/v1/jobs", {
+        headers: { "Cf-Access-Jwt-Assertion": token },
+      }),
+      version: "v1",
+      params: {},
+      next: async (fields) => Response.json(fields ?? null),
+    });
+    expect(accepted.status).toBe(200);
+    await expect(accepted.json()).resolves.toMatchObject({
+      access: { email: "ada@veducio.com", sub: "ada" },
+    });
+
+    const denied = await middleware.handle({
+      request: new Request("https://app.test/v1/jobs"),
+      version: "v1",
+      params: {},
+      next: async () => Response.json({ ok: true }),
+    });
+    expect(denied.status).toBe(401);
+    await expect(denied.json()).resolves.toMatchObject(
+      frameworkErrors.accessDenied,
+    );
+  });
+
+  it("requires a team domain and audience tag", () => {
+    delete process.env.CF_ACCESS_TEAM_DOMAIN;
+    delete process.env.CF_ACCESS_AUD;
+    expect(() => cloudflareAccess()).toThrow(
+      "Missing CF_ACCESS_TEAM_DOMAIN and CF_ACCESS_AUD",
+    );
+  });
+});

package/src/access/cloudflare.ts

@@ -0,0 +1,193 @@
+import {
+  createRemoteJWKSet,
+  type JWTPayload,
+  type JWTVerifyGetKey,
+  jwtVerify,
+} from "jose";
+import { frameworkError, projectError } from "../errors/framework-errors.ts";
+import { defineMiddleware } from "../route/middleware.ts";
+
+const assertionHeader = "Cf-Access-Jwt-Assertion";
+const authorizationCookie = "CF_Authorization";
+
+export type AccessIdentity = {
+  sub: string;
+  iss: string;
+  aud: string[];
+  exp: number;
+  iat: number;
+  email?: string;
+  country?: string;
+  type?: string;
+};
+
+export type CloudflareAccessOptions = {
+  team?: string;
+  audience?: string | string[];
+  getKey?: JWTVerifyGetKey;
+};
+
+const jwksByIssuer = new Map<string, JWTVerifyGetKey>();
+
+export function cloudflareAccess(options: CloudflareAccessOptions = {}) {
+  const settings = accessSettings(options);
+  return defineMiddleware(async ({ request, next }) => {
+    const token = accessToken(request);
+    if (!token) {
+      return denied();
+    }
+    try {
+      const access = await verifyAccessJwt(token, settings);
+      return next({ access });
+    } catch {
+      return denied();
+    }
+  });
+}
+
+export async function verifyAccessJwt(
+  token: string,
+  options: {
+    team: string;
+    audience: string | string[];
+    getKey?: JWTVerifyGetKey;
+  },
+) {
+  const issuer = teamIssuer(options.team);
+  const audience = audienceList(options.audience);
+  try {
+    const verified = await jwtVerify(token, options.getKey ?? jwks(issuer), {
+      issuer,
+      audience,
+    });
+    return accessIdentity(verified.payload);
+  } catch (error) {
+    if (error instanceof Error && error.message === rejected) {
+      throw error;
+    }
+    throw new Error(rejected);
+  }
+}
+
+export function accessToken(request: Request) {
+  const header = request.headers.get(assertionHeader)?.trim();
+  if (header) {
+    return header;
+  }
+  return cookie(request, authorizationCookie);
+}
+
+function accessSettings(options: CloudflareAccessOptions) {
+  const team = options.team?.trim() || envValue("CF_ACCESS_TEAM_DOMAIN");
+  const audience = options.audience ?? envValue("CF_ACCESS_AUD");
+  const missing = [
+    team ? null : "CF_ACCESS_TEAM_DOMAIN",
+    audience ? null : "CF_ACCESS_AUD",
+  ].filter((item) => item !== null);
+  if (missing.length > 0 || !team || !audience) {
+    throw projectError("accessConfig", `Missing ${missing.join(" and ")}`);
+  }
+  return { team, audience, getKey: options.getKey };
+}
+
+function accessIdentity(payload: JWTPayload): AccessIdentity {
+  const aud = payload.aud;
+  const audiences =
+    typeof aud === "string"
+      ? [aud]
+      : Array.isArray(aud)
+        ? aud.filter((item): item is string => typeof item === "string")
+        : [];
+  if (
+    typeof payload.sub !== "string" ||
+    typeof payload.iss !== "string" ||
+    typeof payload.exp !== "number" ||
+    typeof payload.iat !== "number" ||
+    audiences.length === 0
+  ) {
+    throw new Error(rejected);
+  }
+  return {
+    sub: payload.sub,
+    iss: payload.iss,
+    aud: audiences,
+    exp: payload.exp,
+    iat: payload.iat,
+    ...(typeof payload.email === "string" ? { email: payload.email } : {}),
+    ...(typeof payload.country === "string"
+      ? { country: payload.country }
+      : {}),
+    ...(typeof payload.type === "string" ? { type: payload.type } : {}),
+  };
+}
+
+function teamIssuer(team: string) {
+  const trimmed = team.trim().replace(/\/+$/, "");
+  if (trimmed.startsWith("https://")) {
+    const url = new URL(trimmed);
+    if (url.origin !== trimmed) {
+      throw projectError(
+        "accessConfig",
+        "Cloudflare Access team must be a hostname or https origin",
+      );
+    }
+    return url.origin;
+  }
+  if (!/^[A-Za-z0-9.-]+$/.test(trimmed)) {
+    throw projectError(
+      "accessConfig",
+      "Cloudflare Access team must be a hostname or https origin",
+    );
+  }
+  return `https://${trimmed}`;
+}
+
+function audienceList(audience: string | string[]) {
+  const values = (Array.isArray(audience) ? audience : audience.split(","))
+    .map((item) => item.trim())
+    .filter((item) => item.length > 0);
+  if (values.length === 0) {
+    throw projectError("accessConfig", "Missing CF_ACCESS_AUD");
+  }
+  return values;
+}
+
+function jwks(issuer: string) {
+  const existing = jwksByIssuer.get(issuer);
+  if (existing) {
+    return existing;
+  }
+  const created = createRemoteJWKSet(new URL(`${issuer}/cdn-cgi/access/certs`));
+  jwksByIssuer.set(issuer, created);
+  return created;
+}
+
+function cookie(request: Request, name: string) {
+  const header = request.headers.get("cookie");
+  if (!header) {
+    return null;
+  }
+  for (const part of header.split(";")) {
+    const [key, ...rest] = part.trim().split("=");
+    if (key === name) {
+      const value = rest.join("=").trim();
+      return value ? decodeURIComponent(value) : null;
+    }
+  }
+  return null;
+}
+
+function envValue(name: string) {
+  const runtime = globalThis as {
+    Bun?: { env?: Record<string, string | undefined> };
+  };
+  const value = runtime.Bun?.env?.[name] ?? process.env[name];
+  const trimmed = value?.trim();
+  return trimmed ? trimmed : null;
+}
+
+function denied() {
+  return Response.json(frameworkError("accessDenied"), { status: 401 });
+}
+
+const rejected = "Cloudflare Access token was rejected";

package/src/argus/call.test.ts

@@ -0,0 +1,98 @@
+import { afterEach, describe, expect, it } from "vitest";
+import type { ArgusSettings } from "../project/config.ts";
+import { callService, ServiceCallError, setArgus } from "./call.ts";
+
+const argus: ArgusSettings = {
+  url: "https://argus.example",
+  env: "staging",
+  username: "argus",
+  password: "secret",
+  public: null,
+  service: null,
+};
+
+describe("callService", () => {
+  afterEach(() => {
+    setArgus(null);
+  });
+
+  it("discovers a healthy instance and posts the body", async () => {
+    setArgus(argus);
+    const calls: {
+      url: string;
+      method?: string;
+      authorization: string | null;
+      body?: string;
+    }[] = [];
+    const result = await callService(
+      "billing-service",
+      "v1/invoices",
+      { amount: 10 },
+      {
+        random: () => 0.9,
+        fetchImpl: async (url, init) => {
+          calls.push({
+            url,
+            method: init?.method,
+            authorization: init?.headers?.get("authorization") ?? null,
+            body: init?.body,
+          });
+          if (url.includes("/v1/services/")) {
+            return Response.json({
+              instances: [
+                {
+                  base_url: "http://10.0.0.4:3001",
+                  weight: 1,
+                  status: "healthy",
+                },
+                {
+                  base_url: "http://10.0.0.5:3001",
+                  weight: 3,
+                  status: "healthy",
+                },
+                {
+                  base_url: "http://10.0.0.9:3001",
+                  weight: 100,
+                  status: "unhealthy",
+                },
+              ],
+            });
+          }
+          return Response.json({ id: "inv_1" });
+        },
+      },
+    );
+    expect(result).toEqual({ id: "inv_1" });
+    expect(calls).toEqual([
+      {
+        url: "https://argus.example/v1/services/billing-service?env=staging",
+        method: undefined,
+        authorization: `Basic ${Buffer.from("argus:secret").toString("base64")}`,
+        body: undefined,
+      },
+      {
+        url: "http://10.0.0.5:3001/v1/invoices",
+        method: "POST",
+        authorization: null,
+        body: JSON.stringify({ amount: 10 }),
+      },
+    ]);
+  });
+
+  it("requires an active Argus config and a registered instance", async () => {
+    await expect(callService("billing", "/v1/invoices", {})).rejects.toThrow(
+      "service call requires argus",
+    );
+    setArgus(argus);
+    await expect(
+      callService(
+        "billing",
+        "/v1/invoices",
+        {},
+        {
+          fetchImpl: async () => Response.json({ instances: [] }),
+        },
+      ),
+    ).rejects.toBeInstanceOf(ServiceCallError);
+  });
+});