@veducio/keja 0.0.0-stage → 0.3.0

package/src/grant/grant.ts

@@ -0,0 +1,268 @@
+import { decodeJwt, decodeProtectedHeader, type JWTPayload } from "jose";
+import {
+  openVault,
+  requireVaultSettings,
+  VaultError,
+} from "../vault/client.ts";
+
+export type Grant = {
+  subject: string;
+  action: string;
+  context: Record<string, unknown>;
+};
+
+type GrantInput = {
+  subject: string;
+  action: string;
+  exp: number;
+  context?: Record<string, unknown>;
+};
+
+type KeySpec = {
+  alg: string;
+  hash?: string;
+  marshaling?: string;
+  signature?: string;
+};
+
+const keySpecs: Record<string, KeySpec> = {
+  "rsa-2048": { alg: "RS256", hash: "sha2-256", signature: "pkcs1v15" },
+  "rsa-3072": { alg: "RS256", hash: "sha2-256", signature: "pkcs1v15" },
+  "rsa-4096": { alg: "RS256", hash: "sha2-256", signature: "pkcs1v15" },
+  "ecdsa-p256": { alg: "ES256", hash: "sha2-256", marshaling: "jws" },
+  "ecdsa-p384": { alg: "ES384", hash: "sha2-384", marshaling: "jws" },
+  "ecdsa-p521": { alg: "ES512", hash: "sha2-512", marshaling: "jws" },
+  ed25519: { alg: "EdDSA" },
+};
+
+export async function grant(input: GrantInput) {
+  const settings = grantSettings("grant");
+  const subject = requiredText(input.subject, "subject");
+  const action = requiredText(input.action, "action");
+  const lifetime = lifetimeSeconds(input.exp, settings.grant_max_exp);
+  const context = contextObject(input.context);
+  const vault = openVault("grant");
+  const key = await readKey(vault, settings);
+  const now = Math.floor(Date.now() / 1000);
+  const body = base64url(
+    JSON.stringify({
+      sub: subject,
+      action,
+      iat: now,
+      exp: now + lifetime,
+      context,
+    }),
+  );
+  const header = base64url(
+    JSON.stringify({ alg: key.alg, typ: "JWT", kid: String(key.version) }),
+  );
+  const signingInput = `${header}.${body}`;
+  const signed = await vault.transitSign(
+    settings.transit_mount,
+    settings.transit_key,
+    signBody(key, base64(signingInput)),
+  );
+  const signature = vaultSignature(signed.signature);
+  if (signature.version !== String(key.version)) {
+    throw new VaultError("Vault signed the grant with a different key version");
+  }
+  return `${signingInput}.${signature.segment}`;
+}
+
+export async function verifyGrant(token: string, options: { action: string }) {
+  const settings = grantSettings("verifyGrant");
+  const action = requiredText(options.action, "action");
+  const parts = token.split(".");
+  if (parts.length !== 3 || parts.some((part) => part.length === 0)) {
+    throw new VaultError("grant token is unreadable");
+  }
+  const header = decodeProtectedHeader(token);
+  const payload = decodeJwt(token);
+  const vault = openVault("verifyGrant");
+  const key = await readKey(vault, settings);
+  if (
+    header.alg !== key.alg ||
+    typeof header.kid !== "string" ||
+    !/^\d+$/.test(header.kid)
+  ) {
+    throw new VaultError("grant token is unreadable");
+  }
+  const verified = await vault.transitVerify(
+    settings.transit_mount,
+    settings.transit_key,
+    {
+      ...signBody(key, base64(`${parts[0]}.${parts[1]}`)),
+      signature: `vault:v${header.kid}:${Buffer.from(parts[2], "base64url").toString("base64")}`,
+    },
+  );
+  if (verified.valid !== true) {
+    throw new VaultError("grant signature was rejected");
+  }
+  return claims(payload, action);
+}
+
+function grantSettings(feature: "grant" | "verifyGrant") {
+  const settings = requireVaultSettings(feature);
+  if (!settings.transit_key) {
+    throw new VaultError("vault transit key is required");
+  }
+  return settings as typeof settings & { transit_key: string };
+}
+
+async function readKey(
+  vault: ReturnType<typeof openVault>,
+  settings: { transit_mount: string; transit_key: string },
+) {
+  const data = await vault.transitKey(
+    settings.transit_mount,
+    settings.transit_key,
+  );
+  if (typeof data.type !== "string" || !(data.type in keySpecs)) {
+    throw new VaultError("Vault transit key type cannot sign a grant");
+  }
+  const version = data.latest_version;
+  if (
+    typeof version !== "number" ||
+    !Number.isInteger(version) ||
+    version < 1
+  ) {
+    throw new VaultError("Vault transit key has no version");
+  }
+  return { ...keySpecs[data.type], version };
+}
+
+function signBody(
+  key: KeySpec,
+  input: string,
+): {
+  input: string;
+  hash_algorithm?: string;
+  marshaling_algorithm?: string;
+  signature_algorithm?: string;
+} {
+  return {
+    input,
+    ...(key.hash ? { hash_algorithm: key.hash } : {}),
+    ...(key.marshaling ? { marshaling_algorithm: key.marshaling } : {}),
+    ...(key.signature ? { signature_algorithm: key.signature } : {}),
+  };
+}
+
+function vaultSignature(value: unknown) {
+  if (typeof value !== "string") {
+    throw new VaultError("Vault returned an unreadable signature");
+  }
+  const match = /^vault:v(\d+):([A-Za-z0-9+/=_-]+)$/.exec(value);
+  if (!match) {
+    throw new VaultError("Vault returned an unreadable signature");
+  }
+  return {
+    version: match[1],
+    segment: Buffer.from(match[2], "base64").toString("base64url"),
+  };
+}
+
+function claims(payload: JWTPayload, action: string): Grant {
+  const now = Math.floor(Date.now() / 1000);
+  if (
+    typeof payload.exp !== "number" ||
+    !Number.isInteger(payload.exp) ||
+    payload.exp <= now
+  ) {
+    throw new VaultError("grant is expired");
+  }
+  if (
+    typeof payload.iat !== "number" ||
+    !Number.isInteger(payload.iat) ||
+    payload.iat > now ||
+    payload.iat >= payload.exp
+  ) {
+    throw new VaultError("grant token is unreadable");
+  }
+  if (typeof payload.sub !== "string" || payload.sub.trim() === "") {
+    throw new VaultError("grant token is unreadable");
+  }
+  if (payload.action !== action) {
+    throw new VaultError("grant action does not match");
+  }
+  if (!isContext(payload.context)) {
+    throw new VaultError("grant context must be a plain object");
+  }
+  return {
+    subject: payload.sub,
+    action,
+    context: payload.context,
+  };
+}
+
+function requiredText(value: unknown, field: string) {
+  if (
+    typeof value !== "string" ||
+    value.trim() === "" ||
+    value.trim() !== value
+  ) {
+    throw new VaultError(`grant ${field} must be a non-empty string`);
+  }
+  return value;
+}
+
+function lifetimeSeconds(value: unknown, max: number) {
+  if (typeof value !== "number" || !Number.isInteger(value) || value < 1) {
+    throw new VaultError("grant exp must be a whole number of seconds");
+  }
+  if (value > max) {
+    throw new VaultError(`grant exp must be at most ${max} seconds`);
+  }
+  return value;
+}
+
+function contextObject(value: unknown) {
+  if (value === undefined) {
+    return {};
+  }
+  if (!isContext(value)) {
+    throw new VaultError("grant context must be a plain object");
+  }
+  return value;
+}
+
+function isContext(value: unknown): value is Record<string, unknown> {
+  if (!isPlain(value)) {
+    return false;
+  }
+  return Object.values(value).every((item) => isJson(item));
+}
+
+function isJson(value: unknown): boolean {
+  if (
+    value === null ||
+    typeof value === "string" ||
+    typeof value === "boolean" ||
+    (typeof value === "number" && Number.isFinite(value))
+  ) {
+    return true;
+  }
+  if (Array.isArray(value)) {
+    return value.every((item) => isJson(item));
+  }
+  if (!isPlain(value)) {
+    return false;
+  }
+  return Object.values(value).every((item) => isJson(item));
+}
+
+function isPlain(value: unknown): value is Record<string, unknown> {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    return false;
+  }
+  const proto = Object.getPrototypeOf(value);
+  return proto === Object.prototype || proto === null;
+}
+
+function base64url(value: string) {
+  return Buffer.from(value).toString("base64url");
+}
+
+function base64(value: string) {
+  return Buffer.from(value).toString("base64");
+}

package/src/http/create-app.test.ts

@@ -0,0 +1,340 @@
+import { describe, expect, it } from "vitest";
+import { z } from "zod";
+import { frameworkErrors } from "../errors/framework-errors.ts";
+import { defineRoute, response } from "../route/define.ts";
+import { defineMiddleware } from "../route/middleware.ts";
+import { defineVersions } from "../versioning/define.ts";
+import { createHttpApp } from "./create-app.ts";
+
+const versions = defineVersions({
+  v1: { releasedAt: "2020-01-15" },
+  v2: { releasedAt: "2024-06-01" },
+}).versions;
+
+const userResponse = z.object({
+  id: z.string(),
+});
+
+const publicRoutes = [
+  defineRoute({
+    method: "get",
+    path: "/users/:id",
+    version: "v1",
+    request: {
+      params: z.object({ id: z.string().min(1) }),
+    },
+    responses: {
+      User: response({ code: 200, json: userResponse }),
+    },
+    handler: ({ params, respond }) => respond.User({ id: params.id }),
+  }),
+];
+
+const serviceRoutes = [
+  defineRoute({
+    method: "post",
+    path: "/jobs",
+    version: "v2",
+    request: {
+      body: z.object({ name: z.string() }),
+    },
+    responses: {
+      Created: response({ code: 201, json: z.object({ name: z.string() }) }),
+    },
+    handler: ({ body, respond }) => respond.Created(body),
+  }),
+];
+
+describe("createHttpApp", () => {
+  const publicApp = createHttpApp({
+    title: "Public",
+    versions,
+    routes: publicRoutes,
+    server: "http://127.0.0.1:3500",
+  });
+  const serviceApp = createHttpApp({
+    title: "Service",
+    versions,
+    routes: serviceRoutes,
+    server: "https://service.example",
+    postOnly: true,
+  });
+
+  it("serves health, OpenAPI, and Scalar docs on both servers", async () => {
+    for (const app of [publicApp, serviceApp]) {
+      const health = await app.request("/_health");
+      expect(health.status).toBe(200);
+      await expect(health.json()).resolves.toEqual({ status: "ok" });
+
+      const docs = await app.request("/docs");
+      expect(docs.status).toBe(200);
+      expect(docs.headers.get("content-type")).toContain("text/html");
+      const html = await docs.text();
+      expect(html).toContain('"hideClientButton": true');
+      expect(html).toContain('"showDeveloperTools": "never"');
+    }
+
+    const identified = createHttpApp({
+      title: "Public",
+      versions,
+      routes: publicRoutes,
+      identity: {
+        name: "billing",
+        public: ["http://192.168.1.10:3000"],
+        service: ["http://192.168.1.10:3001"],
+      },
+    });
+    const identity = await identified.request("/_identity");
+    expect(identity.status).toBe(200);
+    await expect(identity.json()).resolves.toEqual({
+      name: "billing",
+      public: ["http://192.168.1.10:3000"],
+      service: ["http://192.168.1.10:3001"],
+    });
+
+    const spec = await publicApp.request("/_openapi.json");
+    const document = (await spec.json()) as {
+      openapi: string;
+      paths: Record<string, unknown>;
+      servers?: { url: string }[];
+    };
+    expect(document.openapi).toMatch(/^3\./);
+    expect(document.paths["/v1/users/{id}"]).toBeDefined();
+    expect(document.servers).toEqual([{ url: "http://127.0.0.1:3500" }]);
+
+    const serviceSpec = await serviceApp.request("/_openapi.json");
+    const serviceDocument = (await serviceSpec.json()) as {
+      servers?: { url: string }[];
+    };
+    expect(serviceDocument.servers).toEqual([
+      { url: "https://service.example" },
+    ]);
+  });
+
+  it("runs the newest available handler and validates the request", async () => {
+    const found = await publicApp.request("/v2/users/ada");
+    expect(found.status).toBe(200);
+    await expect(found.json()).resolves.toEqual({ id: "ada" });
+
+    const dated = await publicApp.request("/2020-09-20/users/ada");
+    expect(dated.status).toBe(200);
+
+    const invalid = await publicApp.request("/latest/users/");
+    expect(invalid.status).toBe(404);
+    await expect(invalid.json()).resolves.toEqual(frameworkErrors.notFound);
+
+    const missing = await publicApp.request("/2019-01-01/users/ada");
+    expect(missing.status).toBe(404);
+    await expect(missing.json()).resolves.toEqual(
+      frameworkErrors.unknownVersion,
+    );
+
+    const service = await serviceApp.request("/v1/jobs", {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ name: "sync" }),
+    });
+    expect(service.status).toBe(404);
+    await expect(service.json()).resolves.toEqual(frameworkErrors.notFound);
+
+    const getJob = await serviceApp.request("/v2/jobs");
+    expect(getJob.status).toBe(405);
+    await expect(getJob.json()).resolves.toEqual(
+      frameworkErrors.methodNotAllowed,
+    );
+
+    const created = await serviceApp.request("/current/jobs", {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ name: "sync" }),
+    });
+    expect(created.status).toBe(201);
+
+    const rejected = await serviceApp.request("/v2/jobs", {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({}),
+    });
+    expect(rejected.status).toBe(400);
+    await expect(rejected.json()).resolves.toMatchObject(
+      frameworkErrors.invalidRequest,
+    );
+  });
+
+  it("rejects a service route that is not POST", () => {
+    expect(() =>
+      createHttpApp({
+        title: "Service",
+        versions,
+        routes: publicRoutes,
+        postOnly: true,
+      }),
+    ).toThrow("GET /users/:id must use POST");
+  });
+
+  it("fills constant response fields that are not handler arguments", async () => {
+    const app = createHttpApp({
+      title: "Public",
+      versions,
+      routes: [
+        defineRoute({
+          method: "get",
+          path: "/missing/:id",
+          version: "v1",
+          request: { params: z.object({ id: z.string() }) },
+          responses: {
+            IdDoesNotExist: response({
+              code: 404,
+              json: z.object({
+                id: z.string(),
+                error: z.literal("ID_DOES_NOT_EXIST"),
+              }),
+              const: { error: "ID_DOES_NOT_EXIST" },
+            }),
+            Gone: response({
+              code: 410,
+              json: z.object({ error: z.literal("GONE") }),
+              const: { error: "GONE" },
+            }),
+          },
+          handler: ({ params, respond }) =>
+            params.id === "gone"
+              ? respond.Gone()
+              : respond.IdDoesNotExist(params),
+        }),
+      ],
+    });
+
+    const missing = await app.request("/v1/missing/ada");
+    expect(missing.status).toBe(404);
+    await expect(missing.json()).resolves.toEqual({
+      id: "ada",
+      error: "ID_DOES_NOT_EXIST",
+    });
+
+    const gone = await app.request("/v1/missing/gone");
+    expect(gone.status).toBe(410);
+    await expect(gone.json()).resolves.toEqual({ error: "GONE" });
+  });
+
+  it("runs code around next and passes values into the handler", async () => {
+    const events: string[] = [];
+    const server = defineMiddleware(async ({ next }) => {
+      events.push("server-before");
+      const response = await next();
+      events.push("server-after");
+      response.headers.set("x-server", "yes");
+      return response;
+    });
+    const route = defineMiddleware(async ({ version, params, next }) => {
+      events.push("route-before");
+      const response = await next({ seen: `${version}:${params.id}` });
+      events.push("route-after");
+      response.headers.set("x-route", "yes");
+      return response;
+    });
+    const app = createHttpApp({
+      title: "Public",
+      versions,
+      middleware: [server],
+      routes: [
+        defineRoute({
+          method: "get",
+          path: "/items/:id",
+          version: "v1",
+          request: { params: z.object({ id: z.string() }) },
+          middleware: [route],
+          responses: {
+            Ok: response({
+              code: 200,
+              json: z.object({ seen: z.string() }),
+            }),
+          },
+          handler: ({ seen, respond }) => {
+            events.push("handler");
+            return respond.Ok({ seen });
+          },
+        }),
+      ],
+    });
+
+    const health = await app.request("/_health");
+    expect(health.status).toBe(200);
+    expect(events).toEqual([]);
+
+    const result = await app.request("/v2/items/ada");
+    expect(result.status).toBe(200);
+    expect(result.headers.get("x-server")).toBe("yes");
+    expect(result.headers.get("x-route")).toBe("yes");
+    await expect(result.json()).resolves.toEqual({ seen: "v2:ada" });
+    expect(events).toEqual([
+      "server-before",
+      "route-before",
+      "handler",
+      "route-after",
+      "server-after",
+    ]);
+  });
+
+  it("stops the chain when middleware returns its own response", async () => {
+    let handled = false;
+    const app = createHttpApp({
+      title: "Public",
+      versions,
+      routes: [
+        defineRoute({
+          method: "get",
+          path: "/items/:id",
+          version: "v1",
+          middleware: [
+            defineMiddleware(async () =>
+              Response.json({ message: "Unauthorized" }, { status: 401 }),
+            ),
+          ],
+          responses: {
+            Ok: response({ code: 200, json: z.object({}) }),
+          },
+          handler: ({ respond }) => {
+            handled = true;
+            return respond.Ok({});
+          },
+        }),
+      ],
+    });
+
+    const result = await app.request("/v1/items/ada");
+    expect(result.status).toBe(401);
+    await expect(result.json()).resolves.toEqual({
+      message: "Unauthorized",
+    });
+    expect(handled).toBe(false);
+  });
+
+  it("returns the framework error when a response misses its schema", async () => {
+    const app = createHttpApp({
+      title: "Public",
+      versions,
+      routes: [
+        defineRoute({
+          method: "get",
+          path: "/items/:id",
+          version: "v1",
+          request: { params: z.object({ id: z.string() }) },
+          responses: {
+            Ok: response({
+              code: 200,
+              json: z.object({ id: z.string() }),
+            }),
+          },
+          handler: ({ respond }) => respond.Ok({ id: 1 } as never),
+        }),
+      ],
+    });
+
+    const result = await app.request("/v1/items/ada");
+    expect(result.status).toBe(500);
+    await expect(result.json()).resolves.toMatchObject(
+      frameworkErrors.invalidResponse,
+    );
+  });
+});