@veducio/keja 0.2.3 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@veducio/keja",
-  "version": "0.2.3",
+  "version": "0.3.0",
   "packageManager": "bun@1.4.4",
   "description": "Veducio Keja - RESTFUL Web Server, Based on Lightweight Hono Framework, Written in TypeScript, Powered by Bun",
   "license": "MIT",

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 } });
+  });
+}

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/project/config.test.ts

@@ -100,6 +100,9 @@ describe("defineConfig", () => {
       token: "s.token",
       namespace: "apps",
       mount: "kv",
+      transit_key: null,
+      transit_mount: "transit",
+      grant_max_exp: 900,
     });
     expect(defineConfig().vault).toEqual({ enabled: false });
   });

package/src/project/config.ts

@@ -49,6 +49,9 @@ export type VaultSettings = {
   token: string;
   namespace: string | null;
   mount: string;
+  transit_key: string | null;
+  transit_mount: string;
+  grant_max_exp: number;
 };
 
 export type VaultConfigInput = {
@@ -57,6 +60,9 @@ export type VaultConfigInput = {
   token?: string;
   namespace?: string;
   mount?: string;
+  transit_key?: string;
+  transit_mount?: string;
+  grant_max_exp?: number;
 };
 
 export type VaultConfig =
@@ -289,6 +295,15 @@ function configVault(value: VaultConfigInput | undefined): VaultConfig {
     ),
     namespace: optionalText(namespace, "vault.namespace", "namespace"),
     mount: vaultMount(value.mount ?? configEnv("VAULT_KV_MOUNT") ?? "secret"),
+    transit_key:
+      value.transit_key === undefined
+        ? null
+        : vaultName(value.transit_key, "vault.transit_key"),
+    transit_mount: vaultName(
+      value.transit_mount ?? "transit",
+      "vault.transit_mount",
+    ),
+    grant_max_exp: grantMaxExp(value.grant_max_exp),
   };
 }
 
@@ -325,14 +340,36 @@ function absoluteHttpUrl(value: unknown, field: string) {
 }
 
 function vaultMount(value: string) {
-  const mount = value.trim().replace(/^\/+|\/+$/g, "");
-  if (!/^[A-Za-z0-9_-]+$/.test(mount)) {
+  return vaultName(value, "vault.mount");
+}
+
+function vaultName(value: string, field: string) {
+  const name = value.trim().replace(/^\/+|\/+$/g, "");
+  if (!/^[A-Za-z0-9_-]+$/.test(name)) {
+    throw projectError(
+      "invalidConfigFile",
+      `keja.config.ts ${field} must be a name`,
+    );
+  }
+  return name;
+}
+
+function grantMaxExp(value: number | undefined) {
+  if (value === undefined) {
+    return 900;
+  }
+  if (
+    typeof value !== "number" ||
+    !Number.isInteger(value) ||
+    value < 1 ||
+    value > 86400
+  ) {
     throw projectError(
       "invalidConfigFile",
-      `keja.config.ts vault.mount must be a mount name`,
+      "keja.config.ts vault.grant_max_exp must be a whole number of seconds from 1 to 86400",
     );
   }
-  return mount;
+  return value;
 }
 
 function configEnv(name: string) {

package/src/server/index.ts

@@ -24,6 +24,8 @@ export {
   DependencyNotMet,
   frameworkErrors,
 } from "../errors/framework-errors.ts";
+export type { Grant } from "../grant/grant.ts";
+export { grant, verifyGrant } from "../grant/grant.ts";
 export { defineConfig } from "../project/config.ts";
 export { defineRepositories } from "../repository/define.ts";
 export { repository } from "../repository/runtime.ts";

package/src/vault/client.test.ts

@@ -85,6 +85,9 @@ describe("createVault", () => {
         token: "s.token",
         namespace: null,
         mount: "secret",
+        transit_key: null,
+        transit_mount: "transit",
+        grant_max_exp: 900,
       },
       async (url) => {
         urls.push(url);
@@ -108,6 +111,9 @@ describe("createVault", () => {
           token: "s.token",
           namespace: null,
           mount: "secret",
+          transit_key: null,
+          transit_mount: "transit",
+          grant_max_exp: 900,
         },
         async () =>
           Response.json({ errors: ["permission denied"] }, { status: 403 }),

package/src/vault/client.ts

@@ -62,6 +62,7 @@ export function createVault(options: VaultClientOptions = {}) {
     options.mount ?? envValue("VAULT_KV_MOUNT") ?? "secret",
   );
   const fetchImpl = options.fetch ?? fetch;
+  const headers = () => vaultHeaders(token, namespace);
   return {
     async secret<
       Data extends Record<string, unknown> = Record<string, unknown>,
@@ -70,7 +71,7 @@ export function createVault(options: VaultClientOptions = {}) {
       const response = await fetchImpl(
         `${address}/v1/${mount}/data/${secretPath}`,
         {
-          headers: vaultHeaders(token, namespace),
+          headers: headers(),
         },
       );
       if (!response.ok) {
@@ -84,9 +85,76 @@ export function createVault(options: VaultClientOptions = {}) {
       }
       return body.data.data;
     },
+    transitKey(mountName: string, key: string) {
+      const transit = secretMount(mountName);
+      const name = secretMount(key);
+      return vaultSend<{ type?: unknown; latest_version?: unknown }>(
+        fetchImpl,
+        `${address}/v1/${transit}/keys/${name}`,
+        { headers: headers() },
+        `${transit}/keys/${name}`,
+      );
+    },
+    transitSign(mountName: string, key: string, body: TransitSignBody) {
+      const transit = secretMount(mountName);
+      const name = secretMount(key);
+      return vaultSend<{ signature?: unknown }>(
+        fetchImpl,
+        `${address}/v1/${transit}/sign/${name}`,
+        {
+          method: "POST",
+          headers: jsonHeaders(headers()),
+          body: JSON.stringify(body),
+        },
+        `${transit}/sign/${name}`,
+      );
+    },
+    transitVerify(mountName: string, key: string, body: TransitVerifyBody) {
+      const transit = secretMount(mountName);
+      const name = secretMount(key);
+      return vaultSend<{ valid?: unknown }>(
+        fetchImpl,
+        `${address}/v1/${transit}/verify/${name}`,
+        {
+          method: "POST",
+          headers: jsonHeaders(headers()),
+          body: JSON.stringify(body),
+        },
+        `${transit}/verify/${name}`,
+      );
+    },
   };
 }
 
+export function openVault(feature: string) {
+  const settings = requireVaultSettings(feature);
+  return createVault({
+    address: settings.address,
+    token: settings.token,
+    namespace: settings.namespace ?? undefined,
+    mount: settings.mount,
+    fetch: state.fetch,
+  });
+}
+
+export function requireVaultSettings(feature: string) {
+  if (!state.active) {
+    throw new DependencyNotMet(feature, "vault");
+  }
+  return state.active;
+}
+
+type TransitSignBody = {
+  input: string;
+  hash_algorithm?: string;
+  marshaling_algorithm?: string;
+  signature_algorithm?: string;
+};
+
+type TransitVerifyBody = TransitSignBody & {
+  signature: string;
+};
+
 export function vaultSecret<
   Data extends Record<string, unknown> = Record<string, unknown>,
 >(path: string, options?: VaultClientOptions) {
@@ -141,6 +209,29 @@ function normalizePath(path: string) {
   return parts.map((part) => encodeURIComponent(part)).join("/");
 }
 
+async function vaultSend<Data>(
+  fetchImpl: VaultClientOptions["fetch"],
+  url: string,
+  init: RequestInit,
+  path: string,
+) {
+  const fetch = fetchImpl ?? globalThis.fetch;
+  const response = await fetch(url, init);
+  if (!response.ok) {
+    throw await vaultFailure(response, path);
+  }
+  const body = (await response.json()) as { data?: Data };
+  if (!body.data || typeof body.data !== "object") {
+    throw new VaultError(`Vault ${path} has no data`);
+  }
+  return body.data;
+}
+
+function jsonHeaders(headers: Headers) {
+  headers.set("Content-Type", "application/json");
+  return headers;
+}
+
 function vaultHeaders(token: string, namespace: string | null) {
   const headers = new Headers({ "X-Vault-Token": token });
   if (namespace) {