@q32/core 0.1.4 → 0.1.6

package/src/r2-json.ts

@@ -0,0 +1,32 @@
+import { sha256Hex } from "./ids.js";
+
+export type R2JsonPutOptions = {
+  contentType?: string;
+  customMetadata?: Record<string, string>;
+};
+
+export async function putR2Json(
+  bucket: R2Bucket,
+  key: string,
+  value: unknown,
+  options: R2JsonPutOptions = {},
+): Promise<R2Object> {
+  return bucket.put(key, JSON.stringify(value), {
+    httpMetadata: { contentType: options.contentType ?? "application/json; charset=utf-8" },
+    customMetadata: options.customMetadata,
+  });
+}
+
+export async function getR2Json<T>(bucket: R2Bucket, key: string): Promise<T | null> {
+  const object = await bucket.get(key);
+  if (!object) return null;
+  return (await object.json()) as T;
+}
+
+export async function digestR2Key(prefix: string, value: string | Uint8Array, extension = "json"): Promise<string> {
+  const input = typeof value === "string" ? value : [...value].map((byte) => String.fromCharCode(byte)).join("");
+  const digest = await sha256Hex(input);
+  const cleanPrefix = prefix.replace(/^\/+|\/+$/g, "");
+  const cleanExtension = extension.replace(/^\./, "");
+  return `${cleanPrefix}/${digest.slice(0, 2)}/${digest}.${cleanExtension}`;
+}

package/src/rate-limit.ts

@@ -0,0 +1,77 @@
+import type { D1DatabaseLike } from "./d1.js";
+import { sha256Hex } from "./ids.js";
+
+export type RateLimitDecision = {
+  allowed: boolean;
+  keyHash: string;
+  count: number;
+  limit: number;
+  resetAt: string;
+};
+
+export type FixedWindowRateLimitInput = {
+  namespace: string;
+  key: string;
+  limit: number;
+  windowSeconds: number;
+  now?: Date;
+};
+
+export async function checkD1FixedWindowRateLimit(
+  db: D1DatabaseLike,
+  input: FixedWindowRateLimitInput,
+): Promise<RateLimitDecision> {
+  const now = input.now ?? new Date();
+  const windowSeconds = Math.max(1, Math.floor(input.windowSeconds));
+  const limit = Math.max(1, Math.floor(input.limit));
+  const bucketStartMs = Math.floor(now.getTime() / (windowSeconds * 1000)) * windowSeconds * 1000;
+  const bucket = new Date(bucketStartMs).toISOString();
+  const resetAt = new Date(bucketStartMs + windowSeconds * 1000).toISOString();
+  const keyHash = await sha256Hex(`${input.namespace}:${input.key}`);
+
+  await db
+    .prepare(
+      `INSERT INTO rate_limits (namespace, key_hash, bucket, count, reset_at)
+       VALUES (?, ?, ?, 1, ?)
+       ON CONFLICT(namespace, key_hash, bucket)
+       DO UPDATE SET count = count + 1, reset_at = excluded.reset_at`,
+    )
+    .bind(input.namespace, keyHash, bucket, resetAt)
+    .run();
+
+  const row = await db
+    .prepare(
+      `SELECT count, reset_at AS resetAt
+       FROM rate_limits
+       WHERE namespace = ? AND key_hash = ? AND bucket = ?
+       LIMIT 1`,
+    )
+    .bind(input.namespace, keyHash, bucket)
+    .first<{ count: number; resetAt: string }>();
+
+  const count = Number(row?.count ?? 1);
+  return {
+    allowed: count <= limit,
+    keyHash,
+    count,
+    limit,
+    resetAt: row?.resetAt ?? resetAt,
+  };
+}
+
+export async function deleteExpiredD1RateLimitBuckets(db: D1DatabaseLike, now = new Date()): Promise<number> {
+  const result = await db.prepare("DELETE FROM rate_limits WHERE reset_at < ?").bind(now.toISOString()).run();
+  return Number(result.meta.changes ?? 0);
+}
+
+export const D1_RATE_LIMITS_SCHEMA = `
+CREATE TABLE IF NOT EXISTS rate_limits (
+  namespace TEXT NOT NULL,
+  key_hash TEXT NOT NULL,
+  bucket TEXT NOT NULL,
+  count INTEGER NOT NULL DEFAULT 0,
+  reset_at TEXT NOT NULL,
+  PRIMARY KEY (namespace, key_hash, bucket)
+);
+CREATE INDEX IF NOT EXISTS rate_limits_reset_at_idx ON rate_limits(reset_at);
+`;

package/src/seo.ts

@@ -0,0 +1,73 @@
+export type SitemapUrl = {
+  loc: string;
+  lastmod?: string;
+  changefreq?: "always" | "hourly" | "daily" | "weekly" | "monthly" | "yearly" | "never";
+  priority?: number;
+};
+
+export type PageMeta = {
+  title: string;
+  description?: string;
+  canonical?: string;
+  image?: string;
+  type?: string;
+  noindex?: boolean;
+};
+
+export function xmlEscape(value: string): string {
+  return value
+    .replace(/&/g, "&")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;")
+    .replace(/'/g, "&apos;");
+}
+
+export function renderSitemapXml(urls: SitemapUrl[]): string {
+  const body = urls
+    .map((url) => {
+      const fields = [
+        `<loc>${xmlEscape(url.loc)}</loc>`,
+        url.lastmod ? `<lastmod>${xmlEscape(url.lastmod)}</lastmod>` : "",
+        url.changefreq ? `<changefreq>${url.changefreq}</changefreq>` : "",
+        url.priority === undefined ? "" : `<priority>${clampPriority(url.priority).toFixed(1)}</priority>`,
+      ].filter(Boolean);
+      return `  <url>\n    ${fields.join("\n    ")}\n  </url>`;
+    })
+    .join("\n");
+  return `<?xml version="1.0" encoding="UTF-8"?>\n<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">\n${body}\n</urlset>\n`;
+}
+
+export function renderRobotsTxt(options: { allow?: string[]; disallow?: string[]; sitemap?: string | string[] } = {}): string {
+  const lines = ["User-agent: *"];
+  for (const path of options.allow ?? []) lines.push(`Allow: ${path}`);
+  for (const path of options.disallow ?? []) lines.push(`Disallow: ${path}`);
+  for (const sitemap of Array.isArray(options.sitemap) ? options.sitemap : options.sitemap ? [options.sitemap] : []) {
+    lines.push(`Sitemap: ${sitemap}`);
+  }
+  return `${lines.join("\n")}\n`;
+}
+
+export function metaTags(meta: PageMeta): Record<string, string> {
+  const tags: Record<string, string> = {
+    title: meta.title,
+    "og:title": meta.title,
+  };
+  if (meta.description) {
+    tags.description = meta.description;
+    tags["og:description"] = meta.description;
+  }
+  if (meta.canonical) {
+    tags.canonical = meta.canonical;
+    tags["og:url"] = meta.canonical;
+  }
+  if (meta.image) tags["og:image"] = meta.image;
+  if (meta.type) tags["og:type"] = meta.type;
+  if (meta.noindex) tags.robots = "noindex,nofollow";
+  return tags;
+}
+
+function clampPriority(priority: number): number {
+  if (!Number.isFinite(priority)) return 0.5;
+  return Math.max(0, Math.min(1, priority));
+}

package/src/session.ts

@@ -0,0 +1,81 @@
+import { fromBase64Url, toBase64Url } from "./ids.js";
+import { epochSeconds } from "./time.js";
+
+export type SignedSessionOptions = {
+  expiresInSeconds?: number;
+};
+
+type SessionEnvelope<T> = {
+  payload: T;
+  iat: number;
+  exp: number;
+};
+
+export async function signSession<T>(payload: T, secret: string, options: SignedSessionOptions = {}): Promise<string> {
+  if (!secret) throw new Error("Session secret is required.");
+  const now = epochSeconds();
+  const envelope: SessionEnvelope<T> = {
+    payload,
+    iat: now,
+    exp: now + (options.expiresInSeconds ?? 30 * 24 * 60 * 60),
+  };
+  const encoded = toBase64Url(JSON.stringify(envelope));
+  const signature = await hmacSha256(encoded, secret);
+  return `${encoded}.${signature}`;
+}
+
+export async function createSignedPayload(payload: string, secret: string): Promise<string> {
+  const encodedPayload = toBase64Url(payload);
+  const signature = await hmacSha256(encodedPayload, secret);
+  return `${encodedPayload}.${signature}`;
+}
+
+export async function verifySignedPayload(
+  token: string | null | undefined,
+  secret: string,
+): Promise<string | null> {
+  if (!token) return null;
+  const [encodedPayload, providedSignature] = token.split(".");
+  if (!encodedPayload || !providedSignature) return null;
+  const expectedSignature = await hmacSha256(encodedPayload, secret);
+  if (!constantTimeEqual(expectedSignature, providedSignature)) return null;
+  return new TextDecoder().decode(fromBase64Url(encodedPayload));
+}
+
+export async function verifySession<T>(token: string | null | undefined, secret: string): Promise<T | null> {
+  if (!token || !secret) return null;
+  const [encoded, signature] = token.split(".");
+  if (!encoded || !signature) return null;
+  const expected = await hmacSha256(encoded, secret);
+  if (!constantTimeEqual(signature, expected)) return null;
+
+  try {
+    const envelope = JSON.parse(new TextDecoder().decode(fromBase64Url(encoded))) as SessionEnvelope<T>;
+    if (!envelope || typeof envelope.exp !== "number" || envelope.exp < epochSeconds()) return null;
+    return envelope.payload;
+  } catch {
+    return null;
+  }
+}
+
+export function sessionCookie(name: string, value: string, options: { maxAgeSeconds?: number; secure?: boolean } = {}): string {
+  const secure = options.secure ? "; Secure" : "";
+  return `${name}=${value}; Path=/; HttpOnly; SameSite=Lax; Max-Age=${options.maxAgeSeconds ?? 30 * 24 * 60 * 60}${secure}`;
+}
+
+export function expiredSessionCookie(name: string, secure = false): string {
+  return `${name}=; Path=/; HttpOnly; SameSite=Lax; Max-Age=0${secure ? "; Secure" : ""}`;
+}
+
+async function hmacSha256(input: string, secret: string): Promise<string> {
+  const key = await crypto.subtle.importKey("raw", new TextEncoder().encode(secret), { name: "HMAC", hash: "SHA-256" }, false, ["sign"]);
+  const signature = await crypto.subtle.sign("HMAC", key, new TextEncoder().encode(input));
+  return toBase64Url(new Uint8Array(signature));
+}
+
+function constantTimeEqual(a: string, b: string): boolean {
+  if (a.length !== b.length) return false;
+  let diff = 0;
+  for (let i = 0; i < a.length; i += 1) diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
+  return diff === 0;
+}

package/src/testing.ts

@@ -0,0 +1,119 @@
+export type SentQueueMessage<T> = {
+  body: T;
+  options?: QueueSendOptions;
+};
+
+export type MemoryQueue<T = unknown> = Pick<Queue<T>, "send" | "sendBatch"> & {
+  sent: SentQueueMessage<T>[];
+  clear(): void;
+};
+
+export function createMemoryQueue<T = unknown>(): MemoryQueue<T> {
+  const sent: SentQueueMessage<T>[] = [];
+  return {
+    sent,
+    async send(body: T, options?: QueueSendOptions): Promise<QueueSendResponse> {
+      sent.push({ body, options });
+      return queueSendResponse();
+    },
+    async sendBatch(messages: Iterable<MessageSendRequest<T>>): Promise<QueueSendBatchResponse> {
+      for (const message of messages) sent.push({ body: message.body, options: message });
+      return queueSendBatchResponse();
+    },
+    clear(): void {
+      sent.length = 0;
+    },
+  };
+}
+
+export type MemoryR2Object = {
+  key: string;
+  body: Uint8Array;
+  httpMetadata?: R2HTTPMetadata;
+  customMetadata?: Record<string, string>;
+  text(): Promise<string>;
+  json<T = unknown>(): Promise<T>;
+  arrayBuffer(): Promise<ArrayBuffer>;
+};
+
+export type MemoryR2Bucket = Pick<R2Bucket, "put" | "get" | "delete"> & {
+  objects: Map<string, MemoryR2Object>;
+  clear(): void;
+};
+
+export function createMemoryR2Bucket(): MemoryR2Bucket {
+  const objects = new Map<string, MemoryR2Object>();
+  return {
+    objects,
+    async put(key: string, value: ReadableStream | ArrayBuffer | ArrayBufferView | string | null | Blob, options?: R2PutOptions): Promise<R2Object> {
+      const body = await toBytes(value);
+      const object = memoryR2Object(key, body, normalizeR2HttpMetadata(options?.httpMetadata), options?.customMetadata);
+      objects.set(key, object);
+      return object as unknown as R2Object;
+    },
+    async get(key: string): Promise<R2ObjectBody | null> {
+      return (objects.get(key) as unknown as R2ObjectBody | undefined) ?? null;
+    },
+    async delete(keys: string | string[]): Promise<void> {
+      for (const key of Array.isArray(keys) ? keys : [keys]) objects.delete(key);
+    },
+    clear(): void {
+      objects.clear();
+    },
+  };
+}
+
+export async function expectJsonResponse<T = unknown>(response: Response, status = 200): Promise<T> {
+  if (response.status !== status) throw new Error(`Expected response status ${status}, got ${response.status}.`);
+  const contentType = response.headers.get("content-type") ?? "";
+  if (!contentType.includes("application/json")) throw new Error(`Expected JSON response, got ${contentType || "no content-type"}.`);
+  return (await response.json()) as T;
+}
+
+async function toBytes(value: ReadableStream | ArrayBuffer | ArrayBufferView | string | null | Blob): Promise<Uint8Array> {
+  if (value === null) return new Uint8Array();
+  if (typeof value === "string") return new TextEncoder().encode(value);
+  if (value instanceof ArrayBuffer) return new Uint8Array(value);
+  if (ArrayBuffer.isView(value)) return new Uint8Array(value.buffer.slice(value.byteOffset, value.byteOffset + value.byteLength));
+  if (value instanceof Blob) return new Uint8Array(await value.arrayBuffer());
+  return new Uint8Array(await new Response(value).arrayBuffer());
+}
+
+function queueSendResponse(): QueueSendResponse {
+  return { metadata: { metrics: { backlogCount: 0, backlogBytes: 0 } } };
+}
+
+function queueSendBatchResponse(): QueueSendBatchResponse {
+  return { metadata: { metrics: { backlogCount: 0, backlogBytes: 0 } } };
+}
+
+function normalizeR2HttpMetadata(value: R2HTTPMetadata | Headers | undefined): R2HTTPMetadata | undefined {
+  if (!value) return undefined;
+  if (!(value instanceof Headers)) return value;
+  const contentType = value.get("content-type") ?? undefined;
+  const cacheControl = value.get("cache-control") ?? undefined;
+  return { contentType, cacheControl };
+}
+
+function memoryR2Object(
+  key: string,
+  body: Uint8Array,
+  httpMetadata?: R2HTTPMetadata,
+  customMetadata?: Record<string, string>,
+): MemoryR2Object {
+  return {
+    key,
+    body,
+    httpMetadata,
+    customMetadata,
+    async text(): Promise<string> {
+      return new TextDecoder().decode(body);
+    },
+    async json<T = unknown>(): Promise<T> {
+      return JSON.parse(await this.text()) as T;
+    },
+    async arrayBuffer(): Promise<ArrayBuffer> {
+      return body.buffer.slice(body.byteOffset, body.byteOffset + body.byteLength) as ArrayBuffer;
+    },
+  };
+}

package/src/time.ts

@@ -0,0 +1,18 @@
+export function nowIso(date = new Date()): string {
+  return date.toISOString();
+}
+
+export function epochSeconds(date = new Date()): number {
+  return Math.floor(date.getTime() / 1000);
+}
+
+export function addSeconds(date: Date | string, seconds: number): string {
+  const base = typeof date === "string" ? new Date(date) : date;
+  return new Date(base.getTime() + seconds * 1000).toISOString();
+}
+
+export function isFutureIso(value: string | null | undefined, now = new Date()): boolean {
+  if (!value) return false;
+  const timestamp = Date.parse(value);
+  return Number.isFinite(timestamp) && timestamp > now.getTime();
+}