@veducio/keja 0.2.3 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@veducio/keja",
-  "version": "0.2.3",
+  "version": "0.4.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,189 @@
+import { decodeJwt, decodeProtectedHeader } from "jose";
+import { afterEach, describe, expect, it } from "vitest";
+import { connectVault, setVault } from "../vault/client.ts";
+import { grant, verifyGrant } from "./grant.ts";
+import { setGrants } from "./settings.ts";
+
+afterEach(() => {
+  setVault(null);
+  setGrants(null);
+});
+
+describe("grant", () => {
+  it("signs with a secret from grants config", async () => {
+    setGrants({
+      mode: "secret",
+      max_exp: 900,
+      secret: "test-secret",
+    });
+    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: "HS256",
+        typ: "JWT",
+      });
+      expect(decodeJwt(token)).toMatchObject({
+        sub: "tenant_01h455vb4pex5vsknk084sn02q",
+        action: "posts.read",
+        iat: 1_700_000_000,
+        exp: 1_700_000_060,
+        context: { postId: "posts_01h455vb4pex5vsknk084sn02q" },
+      });
+      await expect(
+        verifyGrant(token, { action: "posts.read" }),
+      ).resolves.toEqual({
+        subject: "tenant_01h455vb4pex5vsknk084sn02q",
+        action: "posts.read",
+        context: { postId: "posts_01h455vb4pex5vsknk084sn02q" },
+      });
+    } finally {
+      Date.now = clock;
+    }
+  });
+
+  it("signs a subject, action, expiry, and context with the transit key", async () => {
+    const calls: { url: string; body: unknown }[] = [];
+    await connectVault(
+      {
+        address: "https://vault.example",
+        token: "s.token",
+        namespace: "apps",
+        mount: "secret",
+      },
+      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: "ecdsa-p256", 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: true } });
+      },
+    );
+    setGrants({
+      mode: "transit",
+      max_exp: 900,
+      transit_key: "keja-grants",
+      transit_mount: "transit",
+    });
+    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",
+      });
+      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");
+    } finally {
+      Date.now = clock;
+    }
+  });
+
+  it("rejects a lifetime past the configured maximum", async () => {
+    setGrants({
+      mode: "secret",
+      max_exp: 900,
+      secret: "test-secret",
+    });
+    await expect(
+      grant({ subject: "tenant", action: "posts.read", exp: 901 }),
+    ).rejects.toThrow("grant exp must be at most 900 seconds");
+  });
+
+  it("requires grants to be enabled", async () => {
+    await expect(
+      grant({ subject: "tenant", action: "posts.read", exp: 60 }),
+    ).rejects.toThrow("grant requires grants");
+  });
+
+  it("rejects a signature Vault does not accept", async () => {
+    await connectVault(
+      {
+        address: "https://vault.example",
+        token: "s.token",
+        namespace: null,
+        mount: "secret",
+      },
+      async (url) => {
+        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: "rsa-2048", 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: false } });
+      },
+    );
+    setGrants({
+      mode: "transit",
+      max_exp: 900,
+      transit_key: "keja-grants",
+      transit_mount: "transit",
+    });
+    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;
+    }
+  });
+});

package/src/grant/grant.ts

@@ -0,0 +1,289 @@
+import {
+  decodeJwt,
+  decodeProtectedHeader,
+  type JWTPayload,
+  jwtVerify,
+  SignJWT,
+} from "jose";
+import { openVault, VaultError } from "../vault/client.ts";
+import { requireGrants } from "./settings.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 = requireGrants("grant");
+  const subject = requiredText(input.subject, "subject");
+  const action = requiredText(input.action, "action");
+  const lifetime = lifetimeSeconds(input.exp, settings.max_exp);
+  const context = contextObject(input.context);
+  const now = Math.floor(Date.now() / 1000);
+  const payload = {
+    sub: subject,
+    action,
+    iat: now,
+    exp: now + lifetime,
+    context,
+  };
+  if (settings.mode === "secret") {
+    return new SignJWT({ action, context })
+      .setProtectedHeader({ alg: "HS256", typ: "JWT" })
+      .setSubject(subject)
+      .setIssuedAt(now)
+      .setExpirationTime(now + lifetime)
+      .sign(secretKey(settings.secret));
+  }
+  const vault = openVault("grant");
+  const key = await readKey(vault, settings);
+  const body = base64url(JSON.stringify(payload));
+  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 = requireGrants("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");
+  }
+  if (settings.mode === "secret") {
+    try {
+      const verified = await jwtVerify(token, secretKey(settings.secret), {
+        algorithms: ["HS256"],
+        clockTolerance: 0,
+        currentDate: new Date(Date.now()),
+      });
+      return claims(verified.payload, action);
+    } catch (error) {
+      if (error instanceof VaultError) {
+        throw error;
+      }
+      throw new VaultError("grant signature was rejected");
+    }
+  }
+  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);
+}
+
+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 secretKey(secret: string) {
+  return new TextEncoder().encode(secret);
+}
+
+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/grant/settings.ts

@@ -0,0 +1,67 @@
+import { DependencyNotMet } from "../errors/framework-errors.ts";
+import { processValue } from "../process/slot.ts";
+import type { GrantsConfig } from "../project/config.ts";
+import { VaultError, vaultSecret } from "../vault/client.ts";
+
+export type ActiveGrants =
+  | {
+      mode: "transit";
+      max_exp: number;
+      transit_key: string;
+      transit_mount: string;
+    }
+  | {
+      mode: "secret";
+      max_exp: number;
+      secret: string;
+    };
+
+const state = processValue("grants", () => ({
+  active: null as ActiveGrants | null,
+}));
+
+export function setGrants(settings: ActiveGrants | null) {
+  state.active = settings;
+}
+
+export function requireGrants(feature: string) {
+  if (!state.active) {
+    throw new DependencyNotMet(feature, "grants");
+  }
+  return state.active;
+}
+
+export async function connectGrants(config: GrantsConfig) {
+  if (!config.enabled) {
+    setGrants(null);
+    return;
+  }
+  if (config.mode === "transit") {
+    setGrants({
+      mode: "transit",
+      max_exp: config.max_exp,
+      transit_key: config.transit_key,
+      transit_mount: config.transit_mount,
+    });
+    return;
+  }
+  let secret = config.secret;
+  if (config.secret_vault) {
+    const data = await vaultSecret(config.secret_vault);
+    const value = data[config.secret_field];
+    if (typeof value !== "string" || value.trim() === "") {
+      throw new VaultError(
+        `Vault secret ${config.secret_vault} field ${config.secret_field} is required`,
+      );
+    }
+    secret = value.trim();
+  }
+  if (typeof secret !== "string" || secret.trim() === "") {
+    throw new VaultError("grant secret is required");
+  }
+  setGrants({
+    mode: "secret",
+    max_exp: config.max_exp,
+    secret: secret.trim(),
+  });
+}