@veducio/keja 0.0.0-stage → 0.3.0

package/src/env/required-env.ts

@@ -0,0 +1,120 @@
+export type EnvSource = {
+  readonly [key: string]: string | undefined;
+};
+
+export type RequiredEnv = {
+  host: string;
+  httpPort: number;
+  httpServicePort: number;
+};
+
+type EnvRequirement<Key extends keyof RequiredEnv> = {
+  key: Key;
+  name: string;
+  validate(value: string | undefined): string | null;
+  parse(value: string): RequiredEnv[Key];
+};
+
+function portValidator(name: string) {
+  return (value: string | undefined): string | null => {
+    if (typeof value !== "string" || !/^\d+$/.test(value)) {
+      return `${name} must be an integer from 1 to 65535`;
+    }
+    const port = Number(value);
+    if (port < 1 || port > 65535) {
+      return `${name} must be an integer from 1 to 65535`;
+    }
+    return null;
+  };
+}
+
+function portParser(value: string) {
+  return Number(value);
+}
+
+export const requiredEnv: [
+  EnvRequirement<"host">,
+  EnvRequirement<"httpPort">,
+  EnvRequirement<"httpServicePort">,
+] = [
+  {
+    key: "host",
+    name: "HOST",
+    validate(value: string | undefined): string | null {
+      if (typeof value !== "string" || value.trim() === "") {
+        return "HOST is required";
+      }
+      return null;
+    },
+    parse(value: string): string {
+      return value;
+    },
+  },
+  {
+    key: "httpPort",
+    name: "HTTP_PORT",
+    validate: portValidator("HTTP_PORT"),
+    parse: portParser,
+  },
+  {
+    key: "httpServicePort",
+    name: "HTTP_SERVICE_PORT",
+    validate: portValidator("HTTP_SERVICE_PORT"),
+    parse: portParser,
+  },
+];
+
+export function readRequiredEnv(env: EnvSource): RequiredEnv {
+  return {
+    host: requiredEnv[0].parse(env.HOST ?? ""),
+    httpPort: requiredEnv[1].parse(env.HTTP_PORT ?? ""),
+    httpServicePort: requiredEnv[2].parse(env.HTTP_SERVICE_PORT ?? ""),
+  };
+}
+
+export const openApiServerEnv = [
+  { key: "openapiServer", name: "OPENAPI_SERVER" },
+  { key: "openapiServiceServer", name: "OPENAPI_SERVICE_SERVER" },
+] as const;
+
+export function validateOpenApiServer(
+  name: string,
+  value: string | undefined,
+): string | null {
+  if (typeof value !== "string" || value.trim() === "") {
+    return null;
+  }
+  try {
+    const url = new URL(value.trim());
+    if (url.protocol === "http:" || url.protocol === "https:") {
+      return null;
+    }
+  } catch {
+    return `${name} must be an absolute http or https URL`;
+  }
+  return `${name} must be an absolute http or https URL`;
+}
+
+export function readOpenApiServers(env: EnvSource): {
+  openapiServer: string | null;
+  openapiServiceServer: string | null;
+} {
+  return {
+    openapiServer: readOpenApiServer("OPENAPI_SERVER", env.OPENAPI_SERVER),
+    openapiServiceServer: readOpenApiServer(
+      "OPENAPI_SERVICE_SERVER",
+      env.OPENAPI_SERVICE_SERVER,
+    ),
+  };
+}
+
+function readOpenApiServer(name: string, value: string | undefined) {
+  const error = validateOpenApiServer(name, value);
+  if (error) {
+    throw new Error(error);
+  }
+  if (typeof value !== "string" || value.trim() === "") {
+    return null;
+  }
+  return value.trim();
+}

package/src/errors/framework-errors.ts

@@ -0,0 +1,295 @@
+export const frameworkErrors = {
+  notFound: {
+    code: 1001,
+    name: "NotFound",
+    description: "No route matched this request.",
+    tip: "Check the method, path, and version token.",
+  },
+  unknownVersion: {
+    code: 1002,
+    name: "UnknownVersion",
+    description: "The version token does not match a published version.",
+    tip: "Use a version such as v1, a release date, latest, or current.",
+  },
+  invalidRequest: {
+    code: 1003,
+    name: "InvalidRequest",
+    description: "The request did not match the route schema.",
+    tip: "Compare the path parameters, query, and JSON body with the route definition.",
+  },
+  invalidResponse: {
+    code: 1004,
+    name: "InvalidResponse",
+    description:
+      "The handler result did not match the declared response schema.",
+    tip: "Return one of the named responses with the fields its schema requires.",
+  },
+  accessDenied: {
+    code: 1005,
+    name: "AccessDenied",
+    description: "Cloudflare Access did not accept this request.",
+    tip: "Send a valid Cf-Access-Jwt-Assertion header or CF_Authorization cookie.",
+  },
+  methodNotAllowed: {
+    code: 1006,
+    name: "MethodNotAllowed",
+    description: "The service server only accepts POST.",
+    tip: "Send the service request as POST.",
+  },
+} as const;
+
+export function frameworkError<Extra extends Record<string, unknown>>(
+  key: keyof typeof frameworkErrors,
+  extra?: Extra,
+) {
+  return { ...frameworkErrors[key], ...extra };
+}
+
+const projectScope = "Project";
+
+export const projectErrors = {
+  unknownRouteVersion: {
+    scope: projectScope,
+    code: 2001,
+    name: "UnknownRouteVersion",
+    description: "A route uses a version this project does not define.",
+    tip: "Add the version to keja.versioning.ts, or change the route version.",
+  },
+  duplicateRoute: {
+    scope: projectScope,
+    code: 2002,
+    name: "DuplicateRoute",
+    description: "Two routes use the same method, path, and version.",
+    tip: "Keep one route for that method, path, and version.",
+  },
+  missingVersionFile: {
+    scope: projectScope,
+    code: 2003,
+    name: "MissingVersionFile",
+    description: "The project has no keja.versioning.ts file.",
+    tip: "Add keja.versioning.ts that default-exports defineVersions(...).",
+  },
+  invalidVersionFile: {
+    scope: projectScope,
+    code: 2004,
+    name: "InvalidVersionFile",
+    description: "keja.versioning.ts does not export the version catalog.",
+    tip: "Default-export the result of defineVersions(...).",
+  },
+  missingRouteDirectory: {
+    scope: projectScope,
+    code: 2005,
+    name: "MissingRouteDirectory",
+    description: "A route directory is missing.",
+    tip: "Create src/public and src/service.",
+  },
+  invalidRouteFile: {
+    scope: projectScope,
+    code: 2006,
+    name: "InvalidRouteFile",
+    description: "A route file does not export a route.",
+    tip: "Export defineRoute(...) by name, or as the default export.",
+  },
+  invalidMiddlewareFile: {
+    scope: projectScope,
+    code: 2007,
+    name: "InvalidMiddlewareFile",
+    description: "A server middleware file does not export middleware.",
+    tip: "Default-export defineMiddleware(...) or an array of them.",
+  },
+  invalidVersionId: {
+    scope: projectScope,
+    code: 2008,
+    name: "InvalidVersionId",
+    description: "A version id is not v followed by a whole number.",
+    tip: "Use a version such as v1, v2, or v10.",
+  },
+  invalidReleaseDate: {
+    scope: projectScope,
+    code: 2009,
+    name: "InvalidReleaseDate",
+    description: "A version has a release date Keja cannot read.",
+    tip: "Use YYYY-MM-DD, DD-MM-YYYY, or a unix timestamp.",
+  },
+  invalidStatusCode: {
+    scope: projectScope,
+    code: 2010,
+    name: "InvalidStatusCode",
+    description: "A response status code is outside the HTTP range.",
+    tip: "Use an integer from 100 to 599.",
+  },
+  invalidRouteMiddleware: {
+    scope: projectScope,
+    code: 2011,
+    name: "InvalidRouteMiddleware",
+    description: "A route lists middleware Keja did not create.",
+    tip: "Pass functions created with defineMiddleware(...).",
+  },
+  invalidRoute: {
+    scope: projectScope,
+    code: 2030,
+    name: "InvalidRoute",
+    description:
+      "A route definition has a method, path, or schema Keja cannot use.",
+    tip: "Use get, post, put, patch, or delete, a path that starts with /, and Zod schemas.",
+  },
+  invalidConfigFile: {
+    scope: projectScope,
+    code: 2012,
+    name: "InvalidConfigFile",
+    description: "keja.config.ts does not export a Keja config.",
+    tip: "Default-export the result of defineConfig(...).",
+  },
+  databaseUrl: {
+    scope: projectScope,
+    code: 2013,
+    name: "DatabaseUrl",
+    description:
+      "The database is enabled and DATABASE_URL is missing or not a postgres URL.",
+    tip: "Set DATABASE_URL to a postgres connection string, or set db.enabled to false.",
+  },
+  missingMigrations: {
+    scope: projectScope,
+    code: 2014,
+    name: "MissingMigrations",
+    description: "The migrations folder is missing.",
+    tip: "Create the folder and add files named 0001_name.sql.",
+  },
+  invalidMigrationFile: {
+    scope: projectScope,
+    code: 2015,
+    name: "InvalidMigrationFile",
+    description: "A migration file does not use the 0001_name.sql form.",
+    tip: "Rename the file to 0001_name.sql.",
+  },
+  duplicateMigration: {
+    scope: projectScope,
+    code: 2016,
+    name: "DuplicateMigration",
+    description: "Two migration files use the same number.",
+    tip: "Keep one file for each migration number.",
+  },
+  migrationChanged: {
+    scope: projectScope,
+    code: 2017,
+    name: "MigrationChanged",
+    description: "An applied migration file changed.",
+    tip: "Add a new migration instead of editing an applied file.",
+  },
+  migrationFailed: {
+    scope: projectScope,
+    code: 2018,
+    name: "MigrationFailed",
+    description: "Postgres rejected a migration.",
+    tip: "Fix the SQL in that migration file.",
+  },
+  ownedObjects: {
+    scope: projectScope,
+    code: 2021,
+    name: "OwnedObjects",
+    description: "A table does not match the OwnedObjects shape.",
+    tip: "Add _id, _object, _tenant, _archived, _createdAt, and _updatedAt with the Keja checks.",
+  },
+  serviceMethod: {
+    scope: projectScope,
+    code: 2020,
+    name: "ServiceMethod",
+    description: "A service route uses a method other than POST.",
+    tip: "Change the service route method to post.",
+  },
+  databaseInit: {
+    scope: projectScope,
+    code: 2022,
+    name: "DatabaseInit",
+    description: "The database is enabled and Postgres could not be reached.",
+    tip: "Check DATABASE_URL and that Postgres is running.",
+  },
+  argusInit: {
+    scope: projectScope,
+    code: 2023,
+    name: "ArgusInit",
+    description: "Argus is enabled and the first registration failed.",
+    tip: "Check the Argus URL, credentials, and catalog service names.",
+  },
+  vaultInit: {
+    scope: projectScope,
+    code: 2024,
+    name: "VaultInit",
+    description: "Vault is enabled and the token lookup failed.",
+    tip: "Check the Vault address, token, and namespace.",
+  },
+  dependencyNotMet: {
+    scope: projectScope,
+    code: 2025,
+    name: "DependencyNotMet",
+    description: "A feature was used while a feature it requires is disabled.",
+    tip: "Enable the required feature in keja.config.ts.",
+  },
+  invalidSeeder: {
+    scope: projectScope,
+    code: 2026,
+    name: "InvalidSeeder",
+    description: "A seeder does not describe a table and OwnedObjects rows.",
+    tip: "Pass a table name and objects with _id, _object, _tenant, _archived, _createdAt, and _updatedAt.",
+  },
+  invalidSeederFile: {
+    scope: projectScope,
+    code: 2027,
+    name: "InvalidSeederFile",
+    description: "A seed file does not export a seeder.",
+    tip: "Export defineSeeder(...) by name, or as the default export.",
+  },
+  invalidRepositorySql: {
+    scope: projectScope,
+    code: 2028,
+    name: "InvalidRepositorySql",
+    description: "A migration cannot be read as a repository table.",
+    tip: "Use CREATE TABLE or ALTER TABLE ... ADD COLUMN with a mapped column type and the OwnedObjects columns.",
+  },
+  invalidRepositoryFile: {
+    scope: projectScope,
+    code: 2029,
+    name: "InvalidRepositoryFile",
+    description: "keja.repositories.ts does not export repository flags.",
+    tip: "Default-export defineRepositories(...), and name tables that the migrations create.",
+  },
+  accessConfig: {
+    scope: projectScope,
+    code: 2019,
+    name: "AccessConfig",
+    description:
+      "Cloudflare Access is missing its team domain or audience tag.",
+    tip: "Set CF_ACCESS_TEAM_DOMAIN and CF_ACCESS_AUD, or pass team and audience to cloudflareAccess().",
+  },
+} as const;
+
+export type ProjectErrorEntry =
+  (typeof projectErrors)[keyof typeof projectErrors];
+
+export class ProjectError extends Error {
+  readonly scope: string;
+  readonly code: number;
+  readonly errorName: string;
+  readonly description: string;
+  readonly tip: string;
+
+  constructor(entry: ProjectErrorEntry, detail: string) {
+    super(detail);
+    this.scope = entry.scope;
+    this.code = entry.code;
+    this.errorName = entry.name;
+    this.description = entry.description;
+    this.tip = entry.tip;
+  }
+}
+
+export function projectError(key: keyof typeof projectErrors, detail: string) {
+  return new ProjectError(projectErrors[key], detail);
+}
+
+export class DependencyNotMet extends ProjectError {
+  constructor(feature: string, requires: string) {
+    super(projectErrors.dependencyNotMet, `${feature} requires ${requires}`);
+    this.name = "DependencyNotMet";
+  }
+}

package/src/grant/grant.test.ts

@@ -0,0 +1,130 @@
+import { decodeJwt, decodeProtectedHeader } from "jose";
+import { afterEach, describe, expect, it } from "vitest";
+import { connectVault, setVault, VaultError } from "../vault/client.ts";
+import { grant, verifyGrant } from "./grant.ts";
+
+const settings = {
+  address: "https://vault.example",
+  token: "s.token",
+  namespace: "apps" as string | null,
+  mount: "secret",
+  transit_key: "keja-grants" as string | null,
+  transit_mount: "transit",
+  grant_max_exp: 900,
+};
+
+afterEach(() => {
+  setVault(null);
+});
+
+describe("grant", () => {
+  it("signs a subject, action, expiry, and context with the transit key", async () => {
+    const calls: { url: string; body: unknown }[] = [];
+    await connect(calls, { type: "ecdsa-p256", valid: true });
+    const now = 1_700_000_000_000;
+    const clock = Date.now;
+    Date.now = () => now;
+    try {
+      const token = await grant({
+        subject: "tenant_01h455vb4pex5vsknk084sn02q",
+        action: "posts.read",
+        exp: 60,
+        context: { postId: "posts_01h455vb4pex5vsknk084sn02q" },
+      });
+      expect(decodeProtectedHeader(token)).toEqual({
+        alg: "ES256",
+        typ: "JWT",
+        kid: "1",
+      });
+      expect(decodeJwt(token)).toMatchObject({
+        sub: "tenant_01h455vb4pex5vsknk084sn02q",
+        action: "posts.read",
+        iat: 1_700_000_000,
+        exp: 1_700_000_060,
+        context: { postId: "posts_01h455vb4pex5vsknk084sn02q" },
+      });
+      const sign = calls.find((call) => call.url.endsWith("/sign/keja-grants"));
+      expect(sign?.body).toMatchObject({
+        hash_algorithm: "sha2-256",
+        marshaling_algorithm: "jws",
+      });
+      await expect(
+        verifyGrant(token, { action: "posts.read" }),
+      ).resolves.toEqual({
+        subject: "tenant_01h455vb4pex5vsknk084sn02q",
+        action: "posts.read",
+        context: { postId: "posts_01h455vb4pex5vsknk084sn02q" },
+      });
+      Date.now = () => now + 120_000;
+      await expect(
+        verifyGrant(token, { action: "posts.read" }),
+      ).rejects.toThrow("grant is expired");
+      Date.now = () => now;
+      await expect(
+        verifyGrant(token, { action: "posts.write" }),
+      ).rejects.toThrow("grant action does not match");
+    } finally {
+      Date.now = clock;
+    }
+  });
+
+  it("rejects a lifetime past the configured maximum", async () => {
+    await connect([], { type: "rsa-2048", valid: true });
+    await expect(
+      grant({ subject: "tenant", action: "posts.read", exp: 901 }),
+    ).rejects.toThrow("grant exp must be at most 900 seconds");
+  });
+
+  it("rejects a signature Vault does not accept", async () => {
+    await connect([], { type: "rsa-2048", valid: false });
+    const now = Date.now;
+    Date.now = () => 1_700_000_000_000;
+    try {
+      const token = await grant({
+        subject: "tenant",
+        action: "posts.read",
+        exp: 60,
+      });
+      await expect(
+        verifyGrant(token, { action: "posts.read" }),
+      ).rejects.toThrow("grant signature was rejected");
+    } finally {
+      Date.now = now;
+    }
+  });
+
+  it("requires vault and a transit key", async () => {
+    await expect(
+      grant({ subject: "tenant", action: "posts.read", exp: 60 }),
+    ).rejects.toThrow("grant requires vault");
+    await connect([], { type: "rsa-2048", valid: true });
+    setVault({ ...settings, transit_key: null });
+    await expect(
+      grant({ subject: "tenant", action: "posts.read", exp: 60 }),
+    ).rejects.toBeInstanceOf(VaultError);
+  });
+});
+
+async function connect(
+  calls: { url: string; body: unknown }[],
+  result: { type: string; valid: boolean },
+) {
+  await connectVault(settings, async (url, init) => {
+    const body = init?.body ? JSON.parse(String(init.body)) : null;
+    calls.push({ url, body });
+    if (url.endsWith("/v1/auth/token/lookup-self")) {
+      return Response.json({ data: { id: "s.token" } });
+    }
+    if (url.endsWith("/keys/keja-grants")) {
+      return Response.json({ data: { type: result.type, latest_version: 1 } });
+    }
+    if (url.endsWith("/sign/keja-grants")) {
+      return Response.json({
+        data: {
+          signature: `vault:v1:${Buffer.from("signed").toString("base64")}`,
+        },
+      });
+    }
+    return Response.json({ data: { valid: result.valid } });
+  });
+}