@venn-lang/crypto 0.1.0

package/src/actions/jwt-actions.ts

@@ -0,0 +1,77 @@
+import { type ActionContext, type ActionDefinition, arg, defineAction, z } from "@venn-lang/sdk";
+import { t } from "@venn-lang/types";
+import { equals, fromHex, toBase64Url, toBytes } from "../bytes/index.js";
+import { decodeJwt } from "../jwt/index.js";
+import { CryptoEnginePort, type HashAlgorithm } from "../port/index.js";
+
+const ALGORITHMS: Record<string, HashAlgorithm> = {
+  HS256: "sha256",
+  HS384: "sha384",
+  HS512: "sha512",
+};
+
+const signParams = z.object({
+  payload: z.record(z.string(), z.unknown()),
+  secret: z.string(),
+  algorithm: z.enum(["HS256", "HS384", "HS512"]).default("HS256"),
+});
+const verifyParams = z.object({ secret: z.string() });
+
+/** The `crypto.jwt.*` verbs: read a token, mint one, check one. */
+export const jwtActions: ActionDefinition[] = [
+  defineAction({
+    name: "jwt.decode",
+    doc: "Take a token apart without verifying it: header, payload, signature.",
+    args: [arg("token", t.string, "The token to take apart. Nothing is verified.")],
+    result: t.ref("crypto.Jwt"),
+    run: (_ctx, input) => decodeJwt(String(input.args[0] ?? "")),
+  }),
+  defineAction({
+    name: "jwt.sign",
+    doc: "Mint an HMAC-signed token.",
+    params: signParams,
+    // Payload, secret and algorithm are all options, so nothing goes positionally.
+    result: t.string,
+    run: (ctx, input) => sign(ctx, input.params as z.infer<typeof signParams>),
+  }),
+  defineAction({
+    name: "jwt.verify",
+    doc: "True when the token's signature matches the secret.",
+    params: verifyParams,
+    args: [arg("token", t.string, "The token to check against the secret in the options.")],
+    result: t.bool,
+    run: (ctx, input) =>
+      verify(ctx, String(input.args[0] ?? ""), input.params as { secret: string }),
+  }),
+];
+
+async function sign(ctx: ActionContext, params: z.infer<typeof signParams>): Promise<string> {
+  const header = { alg: params.algorithm, typ: "JWT" };
+  const input = `${encode(header)}.${encode(params.payload)}`;
+  const mac = await ctx.port(CryptoEnginePort).hmac({
+    algorithm: ALGORITHMS[params.algorithm] as HashAlgorithm,
+    key: params.secret,
+    data: input,
+  });
+  return `${input}.${toBase64Url(fromHex(mac))}`;
+}
+
+async function verify(
+  ctx: ActionContext,
+  token: string,
+  params: { secret: string },
+): Promise<boolean> {
+  const decoded = decodeJwt(token);
+  const algorithm = ALGORITHMS[String(decoded.header.alg ?? "")];
+  if (!algorithm) return false;
+  const mac = await ctx.port(CryptoEnginePort).hmac({
+    algorithm,
+    key: params.secret,
+    data: decoded.signingInput,
+  });
+  return equals(toBase64Url(fromHex(mac)), decoded.signature);
+}
+
+function encode(value: unknown): string {
+  return toBase64Url(toBytes(JSON.stringify(value)));
+}

package/src/actions/password-actions.ts

@@ -0,0 +1,66 @@
+import { type ActionContext, type ActionDefinition, arg, defineAction, z } from "@venn-lang/sdk";
+import { t } from "@venn-lang/types";
+import { equals } from "../bytes/index.js";
+import { CryptoEnginePort, type HashAlgorithm } from "../port/index.js";
+
+const SCHEME = "pbkdf2";
+const DEFAULT_ITERATIONS = 100_000;
+
+const hashParams = z
+  .object({
+    iterations: z.number().int().positive().default(DEFAULT_ITERATIONS),
+    algorithm: z.enum(["sha256", "sha512"]).default("sha256"),
+  })
+  .optional();
+const verifyParams = z.object({ hash: z.string() });
+
+/**
+ * The `crypto.password.hash` and `crypto.password.verify` verbs.
+ *
+ * PBKDF2 rather than bcrypt, because WebCrypto offers PBKDF2 and so the package
+ * needs no native module. The encoded form carries its own cost parameters,
+ * `pbkdf2$sha256$iterations$salt$derived`, so a stored hash stays verifiable
+ * after the defaults here change.
+ */
+export const passwordActions: ActionDefinition[] = [
+  defineAction({
+    name: "password.hash",
+    doc: "Hash a password with PBKDF2, returning a self-describing string.",
+    params: hashParams,
+    args: [arg("password", t.string, "The password in the clear.")],
+    result: t.string,
+    run: (ctx, input) => hash(ctx, String(input.args[0] ?? ""), input.params),
+  }),
+  defineAction({
+    name: "password.verify",
+    doc: "True when the password matches a hash produced by `password.hash`.",
+    params: verifyParams,
+    args: [arg("password", t.string, "The password in the clear, to check against the hash.")],
+    result: t.bool,
+    run: (ctx, input) =>
+      verify(ctx, String(input.args[0] ?? ""), (input.params as { hash: string }).hash),
+  }),
+];
+
+async function hash(ctx: ActionContext, password: string, params: unknown): Promise<string> {
+  const options = (params ?? {}) as { iterations?: number; algorithm?: HashAlgorithm };
+  const iterations = options.iterations ?? DEFAULT_ITERATIONS;
+  const algorithm = options.algorithm ?? "sha256";
+  const salt = ctx.port(CryptoEnginePort).randomBytes(16);
+  const derived = await ctx
+    .port(CryptoEnginePort)
+    .derive({ password, salt, iterations, algorithm });
+  return [SCHEME, algorithm, iterations, salt, derived].join("$");
+}
+
+async function verify(ctx: ActionContext, password: string, encoded: string): Promise<boolean> {
+  const [scheme, algorithm, iterations, salt, derived] = encoded.split("$");
+  if (scheme !== SCHEME || !algorithm || !salt || !derived) return false;
+  const again = await ctx.port(CryptoEnginePort).derive({
+    password,
+    salt,
+    iterations: Number(iterations),
+    algorithm: algorithm as HashAlgorithm,
+  });
+  return equals(again, derived);
+}

package/src/bytes/bytes.ts

@@ -0,0 +1,70 @@
+// Conversions between the shapes crypto work needs: text, bytes, hex, base64.
+// All pure, all platform-neutral.
+
+/** Bytes backed by a plain `ArrayBuffer`, the only shape WebCrypto accepts. */
+export type Bytes = Uint8Array<ArrayBuffer>;
+
+/** UTF-8 encode a string. */
+export function toBytes(text: string): Bytes {
+  return new TextEncoder().encode(text) as Bytes;
+}
+
+/** UTF-8 decode bytes back to a string. Invalid sequences become the replacement character. */
+export function fromBytes(bytes: Uint8Array): string {
+  return new TextDecoder().decode(bytes);
+}
+
+/** Lowercase hex, two characters per byte. */
+export function toHex(bytes: Uint8Array): string {
+  return [...bytes].map((byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+
+/** Read a hex string back into bytes. A trailing odd character is dropped. */
+export function fromHex(hex: string): Bytes {
+  const pairs = hex.match(/../g) ?? [];
+  return Uint8Array.from(pairs.map((pair) => Number.parseInt(pair, 16))) as Bytes;
+}
+
+/** Standard base64, padded. */
+export function toBase64(bytes: Uint8Array): string {
+  return btoa(String.fromCharCode(...bytes));
+}
+
+/**
+ * Read standard base64 back into bytes.
+ *
+ * @throws DOMException when the text is not valid base64.
+ */
+export function fromBase64(text: string): Bytes {
+  return Uint8Array.from(atob(text), (char) => char.charCodeAt(0)) as Bytes;
+}
+
+/** Base64url, the flavour JWT uses: `+/` become `-_` and padding is dropped. */
+export function toBase64Url(bytes: Uint8Array): string {
+  return toBase64(bytes).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+
+/**
+ * Read base64url back into bytes, restoring the padding first.
+ *
+ * @throws DOMException when the text is not valid base64url.
+ */
+export function fromBase64Url(text: string): Bytes {
+  const padded = text.replace(/-/g, "+").replace(/_/g, "/");
+  return fromBase64(padded.padEnd(Math.ceil(padded.length / 4) * 4, "="));
+}
+
+/**
+ * Compare two strings in time that does not depend on where they differ.
+ *
+ * Use this for every signature and digest check: `===` returns early on the
+ * first mismatched byte, which leaks the correct prefix to a patient attacker.
+ */
+export function equals(left: string, right: string): boolean {
+  if (left.length !== right.length) return false;
+  let diff = 0;
+  for (let index = 0; index < left.length; index++) {
+    diff |= left.charCodeAt(index) ^ right.charCodeAt(index);
+  }
+  return diff === 0;
+}

package/src/bytes/index.ts

@@ -0,0 +1,12 @@
+export type { Bytes } from "./bytes.js";
+export {
+  equals,
+  fromBase64,
+  fromBase64Url,
+  fromBytes,
+  fromHex,
+  toBase64,
+  toBase64Url,
+  toBytes,
+  toHex,
+} from "./bytes.js";

package/src/engines/fake-engine.ts

@@ -0,0 +1,43 @@
+import type { CryptoEngine } from "../port/index.js";
+
+/**
+ * A deterministic stand-in for tests: same input, same output, no platform crypto.
+ *
+ * Not secure and not meant to be. It exists so assertions over a digest, an HMAC
+ * or a random token stay reproducible from run to run.
+ */
+export function createFakeCryptoEngine(): CryptoEngine {
+  let counter = 0;
+  return {
+    digest: ({ algorithm, data }) => Promise.resolve(stable(`${algorithm}|${data}`)),
+    hmac: ({ algorithm, key, data }) => Promise.resolve(stable(`${algorithm}|${key}|${data}`)),
+    derive: (args) =>
+      Promise.resolve(stable(`${args.algorithm}|${args.password}|${args.salt}|${args.iterations}`)),
+    randomBytes: (size) => {
+      counter += 1;
+      return sized(stable(`bytes|${counter}`), size);
+    },
+  };
+}
+
+// FNV-1a, run over the seed with a changing suffix until 64 hex digits are filled.
+function stable(seed: string): string {
+  let out = "";
+  for (let round = 0; out.length < 64; round++) {
+    out += fnv1a(`${seed}|${round}`).toString(16).padStart(8, "0");
+  }
+  return out.slice(0, 64);
+}
+
+function fnv1a(text: string): number {
+  let hash = 0x811c9dc5;
+  for (let index = 0; index < text.length; index++) {
+    hash ^= text.charCodeAt(index);
+    hash = Math.imul(hash, 0x01000193) >>> 0;
+  }
+  return hash >>> 0;
+}
+
+function sized(hex: string, size: number): string {
+  return hex.repeat(Math.ceil((size * 2) / hex.length)).slice(0, size * 2);
+}

package/src/engines/index.ts

@@ -0,0 +1,2 @@
+export { createFakeCryptoEngine } from "./fake-engine.js";
+export { createWebCryptoEngine } from "./web-crypto-engine.js";

package/src/engines/web-crypto-engine.ts

@@ -0,0 +1,45 @@
+import { toBytes, toHex } from "../bytes/index.js";
+import type { CryptoEngine, DeriveArgs, HashAlgorithm } from "../port/index.js";
+
+const NAMES: Record<HashAlgorithm, string> = {
+  sha1: "SHA-1",
+  sha256: "SHA-256",
+  sha384: "SHA-384",
+  sha512: "SHA-512",
+};
+
+/**
+ * The real engine, backed by the platform's global WebCrypto.
+ *
+ * WebCrypto exists in Node 24 and in browsers alike, so nothing here imports
+ * `node:crypto` and the package stays platform-neutral.
+ */
+export function createWebCryptoEngine(): CryptoEngine {
+  return {
+    digest: async ({ algorithm, data }) =>
+      toHex(new Uint8Array(await crypto.subtle.digest(NAMES[algorithm], toBytes(data)))),
+    hmac: async ({ algorithm, key, data }) =>
+      toHex(new Uint8Array(await sign(algorithm, key, data))),
+    derive: async (args) => toHex(new Uint8Array(await deriveBits(args))),
+    randomBytes: (size) => toHex(crypto.getRandomValues(new Uint8Array(size))),
+  };
+}
+
+async function sign(algorithm: HashAlgorithm, key: string, data: string): Promise<ArrayBuffer> {
+  const spec = { name: "HMAC", hash: NAMES[algorithm] };
+  const material = await crypto.subtle.importKey("raw", toBytes(key), spec, false, ["sign"]);
+  return crypto.subtle.sign("HMAC", material, toBytes(data));
+}
+
+async function deriveBits(args: DeriveArgs): Promise<ArrayBuffer> {
+  const material = await crypto.subtle.importKey("raw", toBytes(args.password), "PBKDF2", false, [
+    "deriveBits",
+  ]);
+  const params = {
+    name: "PBKDF2",
+    salt: toBytes(args.salt),
+    iterations: args.iterations,
+    hash: NAMES[args.algorithm],
+  };
+  return crypto.subtle.deriveBits(params, material, 256);
+}

package/src/index.ts

@@ -0,0 +1,20 @@
+// @venn-lang/crypto: hashes, HMACs, base64, PBKDF2 password hashing and JSON Web
+// Tokens, all reached through the CryptoEngine port.
+
+export {
+  equals,
+  fromBase64,
+  fromBase64Url,
+  fromBytes,
+  fromHex,
+  toBase64,
+  toBase64Url,
+  toBytes,
+  toHex,
+} from "./bytes/index.js";
+export { createFakeCryptoEngine, createWebCryptoEngine } from "./engines/index.js";
+export type { DecodedJwt } from "./jwt/index.js";
+export { decodeJwt } from "./jwt/index.js";
+export { cryptoPlugin } from "./plugin.js";
+export type { CryptoEngine, DeriveArgs, HashAlgorithm } from "./port/index.js";
+export { CryptoEnginePort } from "./port/index.js";

package/src/jwt/decode.ts

@@ -0,0 +1,37 @@
+import { VennError } from "@venn-lang/contracts";
+import { fromBase64Url, fromBytes } from "../bytes/index.js";
+import type { DecodedJwt } from "./jwt.types.js";
+
+/**
+ * Split a token and decode its header and payload, without verifying anything.
+ *
+ * Reading a token's claims and trusting them are separate acts. This is the
+ * first; `crypto.jwt.verify` is the second.
+ *
+ * @param token A compact JWS, `header.payload.signature`.
+ * @returns The decoded sections plus the `signingInput` a signature covers.
+ * @throws VennError `VN7003` when the token has fewer than two sections, or when
+ * a section is not base64url-encoded JSON.
+ */
+export function decodeJwt(token: string): DecodedJwt {
+  const parts = token.split(".");
+  if (parts.length < 2) throw malformed("expected header.payload.signature");
+  return {
+    header: section(parts[0], "header"),
+    payload: section(parts[1], "payload"),
+    signature: parts[2] ?? "",
+    signingInput: `${parts[0]}.${parts[1]}`,
+  };
+}
+
+function section(part: string | undefined, what: string): Record<string, unknown> {
+  try {
+    return JSON.parse(fromBytes(fromBase64Url(part ?? "")));
+  } catch {
+    throw malformed(`its ${what} is not base64url-encoded JSON`);
+  }
+}
+
+function malformed(detail: string): VennError {
+  return new VennError({ code: "VN7003", message: `Not a JWT — ${detail}.` });
+}

package/src/jwt/index.ts

@@ -0,0 +1,2 @@
+export { decodeJwt } from "./decode.js";
+export type { DecodedJwt } from "./jwt.types.js";

package/src/jwt/jwt.types.ts

@@ -0,0 +1,9 @@
+/** A JWT taken apart, verified or not. */
+export interface DecodedJwt {
+  header: Record<string, unknown>;
+  payload: Record<string, unknown>;
+  /** The third section, still base64url. Empty when the token carries none. */
+  signature: string;
+  /** `header.payload`, exactly the bytes the signature covers. */
+  signingInput: string;
+}

package/src/plugin.ts

@@ -0,0 +1,18 @@
+import { definePlugin, type PluginDefinition } from "@venn-lang/sdk";
+import { cryptoActions } from "./actions/index.js";
+import { cryptoTypeDefs } from "./types.js";
+
+/**
+ * The `crypto` plugin: digests, encodings, password hashing and JSON Web Tokens.
+ *
+ * Every primitive comes from `CryptoEnginePort`, so a host can swap WebCrypto for
+ * the deterministic fake and keep assertions reproducible. No capability is
+ * required: WebCrypto is present in Node and in the browser alike.
+ */
+export const cryptoPlugin: PluginDefinition = definePlugin({
+  name: "venn/crypto",
+  version: "0.1.0",
+  namespace: "crypto",
+  actions: cryptoActions,
+  typeDefs: cryptoTypeDefs,
+});

package/src/port/crypto-engine.port.ts

@@ -0,0 +1,15 @@
+import type { Port } from "@venn-lang/contracts";
+import type { CryptoEngine } from "./crypto-engine.types.js";
+
+/**
+ * The port every `crypto` verb reaches its primitives through.
+ *
+ * Bound by the host to `createWebCryptoEngine` or `createFakeCryptoEngine`.
+ * Requires no capability, because WebCrypto is present on every target.
+ */
+export const CryptoEnginePort: Port<CryptoEngine> = {
+  id: "venn.port.crypto-engine",
+  version: 1,
+  requires: [],
+  methods: ["digest", "hmac", "derive", "randomBytes"],
+};

package/src/port/crypto-engine.types.ts

@@ -0,0 +1,23 @@
+/** The digests every engine supports. */
+export type HashAlgorithm = "sha1" | "sha256" | "sha384" | "sha512";
+
+/** Arguments for {@link CryptoEngine.derive}: a password plus its PBKDF2 cost parameters. */
+export interface DeriveArgs {
+  password: string;
+  salt: string;
+  iterations: number;
+  algorithm: HashAlgorithm;
+}
+
+/**
+ * The primitives every `crypto` verb is built from.
+ *
+ * Each method answers in lowercase hex. That single shape is what the actions
+ * convert from, so an engine that returned bytes would break every caller.
+ */
+export interface CryptoEngine {
+  digest(args: { algorithm: HashAlgorithm; data: string }): Promise<string>;
+  hmac(args: { algorithm: HashAlgorithm; key: string; data: string }): Promise<string>;
+  derive(args: DeriveArgs): Promise<string>;
+  randomBytes(size: number): string;
+}

package/src/port/index.ts

@@ -0,0 +1,2 @@
+export { CryptoEnginePort } from "./crypto-engine.port.js";
+export type { CryptoEngine, DeriveArgs, HashAlgorithm } from "./crypto-engine.types.js";

package/src/types.ts

@@ -0,0 +1,21 @@
+import { type TypeSpec, t } from "@venn-lang/types";
+
+/**
+ * The named types `@venn-lang/crypto` publishes to scripts, keyed by their bare name.
+ *
+ * One name is enough: every other verb answers with a string or a boolean, which
+ * reads better inline than behind a name that adds nothing. Hand-mirrored from
+ * `DecodedJwt` in `jwt/jwt.types.ts`, so change the two together.
+ */
+export const cryptoTypeDefs: Readonly<Record<string, TypeSpec>> = {
+  /**
+   * A token taken apart. The claims are whatever the issuer put there, so both
+   * sections are maps of dynamic rather than a shape nobody can promise.
+   */
+  Jwt: t.record({
+    header: t.map(t.dynamic),
+    payload: t.map(t.dynamic),
+    signature: t.string,
+    signingInput: t.string,
+  }),
+};