@zerotal/core 1.0.0

package/src/conventions/builtinConcerns.ts

@@ -0,0 +1,131 @@
+/**
+ * The convention concerns that core itself owns (events, listeners, jobs,
+ * validators). ORM and auth contribute their own descriptors via
+ * `app.registerConcern(...)` from their providers.
+ */
+import type { ConcernDescriptor } from "./ConventionLoader.ts";
+import type { Emitter } from "../events/Emitter.ts";
+
+/**
+ * `app/events/` — event classes are plain classes that need no registration; importing them
+ * makes them available and bundled (and lets a generated manifest reference them). Runs early
+ * so any module-level side effects are in place before listeners bind.
+ */
+export const eventsConcern: ConcernDescriptor = {
+  name: "events",
+  order: 5,
+  dir: "app/events",
+  register() {
+    /* importing the file is the whole effect */
+  },
+};
+
+/**
+ * `app/services/` — service classes auto-register with the container so
+ * `App.make(MyService)` resolves them with the declared lifetime.
+ *
+ * A class opts into a non-default lifetime via a `static lifetime` flag:
+ *
+ * @example
+ * @inject(Auth)
+ * export class UsersService {
+ *   static lifetime = "singleton";   // "singleton" | "scoped" | "transient"
+ *   constructor(private auth: AuthManager) {}
+ * }
+ *
+ * - `singleton` / `scoped` → bound with a factory that auto-wires a fresh
+ *   instance via `container.build()`.
+ * - `transient` or no flag → nothing is registered; the container already
+ *   auto-wires unregistered classes on demand (so resolution still works, it is
+ *   just a new instance each time). Only classes with an explicit lifetime are
+ *   touched, so non-service exports (types, helpers) are ignored.
+ *
+ * Runs early (before listeners) so listeners and other concerns can depend on
+ * services.
+ */
+export const servicesConcern: ConcernDescriptor = {
+  name: "services",
+  order: 10,
+  dir: "app/services",
+  register(serviceModule, ctx) {
+    const container = ctx.app.container;
+    for (const exported of Object.values(serviceModule)) {
+      if (typeof exported !== "function") continue;
+      const lifetime = (exported as { lifetime?: unknown }).lifetime;
+      const ctor = exported as new (...args: unknown[]) => unknown;
+      if (lifetime === "singleton") {
+        container.singleton(ctor, (resolver) => resolver.build(ctor));
+      } else if (lifetime === "scoped") {
+        container.scoped(ctor, (resolver) => resolver.build(ctor));
+      }
+      // "transient" / undefined: rely on the container's on-demand auto-wiring.
+    }
+  },
+};
+
+/**
+ * `app/listeners/` — a listener declares the event(s) it handles via `static listens`
+ * (a single event class or an array). The loader binds it on the app emitter.
+ *
+ * @example
+ * export class SendWelcomeEmail {
+ *   static listens = UserRegistered;
+ *   async handle(e: UserRegistered) { ... }
+ * }
+ */
+export const listenersConcern: ConcernDescriptor = {
+  name: "listeners",
+  order: 40,
+  dir: "app/listeners",
+  register(listenerModule, ctx) {
+    const emitter = ctx.resolve<Emitter>("events");
+    if (!emitter) return;
+    for (const exported of Object.values(listenerModule)) {
+      if (typeof exported !== "function") continue;
+      const listens = (exported as { listens?: unknown }).listens;
+      if (!listens) continue;
+      const events = Array.isArray(listens) ? listens : [listens];
+      for (const event of events) {
+        if (typeof event === "function") {
+          emitter.on(event as never, exported as never);
+        }
+      }
+    }
+  },
+};
+
+/**
+ * `app/jobs/` — queue job classes self-register via `JobRegistry.register()` at the bottom of
+ * each file, so importing them is the whole effect (mirrors the generated jobs barrel, but for
+ * the web/test/console runtimes too — not just the worker).
+ */
+export const jobsConcern: ConcernDescriptor = {
+  name: "jobs",
+  order: 50,
+  dir: "app/jobs",
+  register() {
+    /* importing the file triggers its JobRegistry.register() side effect */
+  },
+};
+
+/**
+ * `app/validators/` — custom validation rules / FormRequest helpers. These register themselves
+ * at module load (e.g. `Validator.extend(...)`), so importing the file is the effect.
+ */
+export const validatorsConcern: ConcernDescriptor = {
+  name: "validators",
+  order: 60,
+  dir: "app/validators",
+  register() {
+    /* importing the file runs its module-level registration */
+  },
+};
+
+/** The full set of core-owned convention concerns, in registration order. */
+export const builtinConcerns: ConcernDescriptor[] = [
+  eventsConcern,
+  servicesConcern,
+  listenersConcern,
+  jobsConcern,
+  validatorsConcern,
+];

package/src/crypt/Crypt.ts

@@ -0,0 +1,141 @@
+/**
+ * Symmetric encryption keyed by `APP_KEY`.
+ *
+ * Uses AES-256-GCM (authenticated encryption): tampered or truncated payloads
+ * fail to decrypt with a `DecryptionError` rather than returning garbage. The
+ * key is derived from `APP_KEY` (raw or `base64:` prefixed) via SHA-256, so any
+ * key length works; generate one with `zerotal key:generate`.
+ *
+ * @example
+ * import { Crypt } from '@zerotal/core';
+ * const token = Crypt.encryptString('secret');   // opaque base64
+ * Crypt.decryptString(token);                     // 'secret'
+ * const blob  = Crypt.encrypt({ userId: 7 });     // any JSON-serializable value
+ * Crypt.decrypt<{ userId: number }>(blob).userId; // 7
+ */
+import { createCipheriv, createDecipheriv, randomBytes } from "node:crypto";
+import { ZerotalError } from "../errors/ZerotalError.ts";
+
+/** Raised when `Crypt` is used without an `APP_KEY` configured. */
+export class CryptKeyMissingError extends ZerotalError {
+  constructor() {
+    super(
+      "[Zerotal] Crypt requires APP_KEY. Generate one with `zerotal key:generate`.",
+      "E_CRYPT_NO_KEY",
+      500,
+    );
+  }
+}
+
+/** Raised when a payload cannot be decrypted — wrong key or tampered data. */
+export class DecryptionError extends ZerotalError {
+  constructor() {
+    super(
+      "[Zerotal] Could not decrypt the payload — wrong key or tampered data.",
+      "E_DECRYPT",
+      500,
+    );
+  }
+}
+
+const IV_BYTES = 12;
+const TAG_BYTES = 16;
+
+class CryptManager {
+  private _key: Buffer | null = null;
+
+  /** Override the key explicitly (otherwise derived from `APP_KEY`). */
+  setKey(key: string): void {
+    this._key = this._derive(key);
+  }
+
+  private _derive(key: string): Buffer {
+    const raw = key.startsWith("base64:")
+      ? Buffer.from(key.slice(7), "base64")
+      : Buffer.from(key, "utf8");
+    return new Bun.CryptoHasher("sha256").update(raw).digest(); // exactly 32 bytes
+  }
+
+  private _resolveKey(): Buffer {
+    if (this._key) return this._key;
+    const appKey = Bun.env["APP_KEY"];
+    if (!appKey) throw new CryptKeyMissingError();
+    this._key = this._derive(appKey);
+    return this._key;
+  }
+
+  /**
+   * Encrypt a UTF-8 string. Returns an opaque base64 payload (iv+tag+ciphertext).
+   *
+   * @throws {CryptKeyMissingError} When no key is set and `APP_KEY` is absent.
+   */
+  encryptString(plain: string): string {
+    const iv = randomBytes(IV_BYTES);
+    const cipher = createCipheriv("aes-256-gcm", this._resolveKey(), iv);
+    const ciphertext = Buffer.concat([cipher.update(plain, "utf8"), cipher.final()]);
+    return Buffer.concat([iv, cipher.getAuthTag(), ciphertext]).toString("base64");
+  }
+
+  /**
+   * Decrypt a payload produced by {@link encryptString}.
+   *
+   * @throws {DecryptionError} When the payload is malformed, truncated, tampered
+   *   with, or decrypted with the wrong key.
+   * @throws {CryptKeyMissingError} When no key is set and `APP_KEY` is absent.
+   */
+  decryptString(payload: string): string {
+    let data: Buffer;
+    try {
+      data = Buffer.from(payload, "base64");
+    } catch {
+      throw new DecryptionError();
+    }
+    if (data.length < IV_BYTES + TAG_BYTES) throw new DecryptionError();
+    const iv = data.subarray(0, IV_BYTES);
+    const tag = data.subarray(IV_BYTES, IV_BYTES + TAG_BYTES);
+    const ciphertext = data.subarray(IV_BYTES + TAG_BYTES);
+    try {
+      const decipher = createDecipheriv("aes-256-gcm", this._resolveKey(), iv);
+      decipher.setAuthTag(tag);
+      return Buffer.concat([decipher.update(ciphertext), decipher.final()]).toString("utf8");
+    } catch {
+      throw new DecryptionError();
+    }
+  }
+
+  /**
+   * Encrypt any JSON-serializable value (serialized with `JSON.stringify`).
+   *
+   * @throws {CryptKeyMissingError} When no key is set and `APP_KEY` is absent.
+   */
+  encrypt(value: unknown): string {
+    return this.encryptString(JSON.stringify(value));
+  }
+
+  /**
+   * Decrypt a value produced by {@link encrypt}, parsing it back with `JSON.parse`.
+   *
+   * @typeParam T - Expected shape of the decrypted value.
+   * @throws {DecryptionError} When the payload cannot be decrypted.
+   * @throws {CryptKeyMissingError} When no key is set and `APP_KEY` is absent.
+   */
+  decrypt<T = unknown>(payload: string): T {
+    return JSON.parse(this.decryptString(payload)) as T;
+  }
+}
+
+/**
+ * App-key symmetric encryption facade (AES-256-GCM).
+ *
+ * @example
+ * ```ts
+ * import { Crypt } from "@zerotal/core/security";
+ *
+ * const token = Crypt.encryptString("secret");
+ * Crypt.decryptString(token); // "secret"
+ *
+ * const blob = Crypt.encrypt({ userId: 7 });
+ * Crypt.decrypt<{ userId: number }>(blob).userId; // 7
+ * ```
+ */
+export const Crypt = new CryptManager();

package/src/crypt/URLSigner.ts

@@ -0,0 +1,96 @@
+import { safeEqual, hmacHex } from "../support/crypto.ts";
+
+/**
+ * URLSigner — generate and verify HMAC-signed URLs.
+ *
+ * Signed URLs carry a `signature` and `expires` query parameter.  The
+ * signature is HMAC-SHA256(secret, canonicalPayload) where the payload is
+ * the full URL (without the signature param) sorted by key so that the
+ * order of other query parameters doesn't matter.
+ *
+ * For app-key-keyed signing without managing a secret, prefer the {@link Url}
+ * facade (`Url.sign` / `Url.verify`), which derives the secret from `APP_KEY`.
+ *
+ * @example
+ * ```ts
+ * const signer = new URLSigner(process.env.APP_KEY!);
+ *
+ * // Generate a link that expires in 15 minutes:
+ * const url = signer.sign("https://app.example.com/auth/verify", {
+ *   email: "user@example.com",
+ * }, 15);
+ *
+ * // Verify later:
+ * const ok = signer.verify(url); // true while unexpired and untampered
+ * ```
+ */
+export class URLSigner {
+  /**
+   * @param secret - HMAC signing secret (e.g. `APP_KEY`); must be non-empty.
+   * @throws {Error} When `secret` is empty.
+   */
+  constructor(private readonly secret: string) {
+    if (!secret) throw new Error("[URLSigner] secret must be a non-empty string");
+  }
+
+  /**
+   * Build a signed URL.
+   *
+   * @param base  The base URL (scheme + host + path).
+   * @param params  Extra query parameters to include (will be encoded).
+   * @param expiresInMinutes  Minutes until the link expires. Default 60.
+   * @returns The URL with `expires` and `signature` query parameters appended.
+   */
+  sign(base: string, params: Record<string, string> = {}, expiresInMinutes: number = 60): string {
+    const expiresAt = Math.floor(Date.now() / 1000) + expiresInMinutes * 60;
+
+    const url = new URL(base);
+    for (const [k, v] of Object.entries(params)) url.searchParams.set(k, v);
+    url.searchParams.set("expires", String(expiresAt));
+
+    const signature = this._hmac(this._canonical(url));
+    url.searchParams.set("signature", signature);
+    return url.toString();
+  }
+
+  /**
+   * Verify a signed URL.
+   * Returns `true` if the signature is valid and the link has not expired.
+   */
+  verify(signedUrl: string): boolean {
+    try {
+      const url = new URL(signedUrl);
+
+      const signature = url.searchParams.get("signature");
+      const expires = url.searchParams.get("expires");
+      if (!signature || !expires) return false;
+
+      // Check expiry first (cheap)
+      if (Math.floor(Date.now() / 1000) > Number(expires)) return false;
+
+      // Rebuild the URL without the signature to get the canonical payload
+      const clone = new URL(signedUrl);
+      clone.searchParams.delete("signature");
+      const expected = this._hmac(this._canonical(clone));
+
+      return safeEqual(signature, expected);
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * Canonical form: sort all params alphabetically so order doesn't matter.
+   */
+  private _canonical(url: URL): string {
+    const clone = new URL(url.toString());
+    const sorted = [...clone.searchParams.entries()].sort(([a], [b]) => a.localeCompare(b));
+    clone.search = "";
+    for (const [k, v] of sorted) clone.searchParams.append(k, v);
+    return clone.toString();
+  }
+
+  private _hmac(payload: string): string {
+    return hmacHex(payload, this.secret);
+  }
+}