1tube 0.1.5 → 0.1.7

package/README.md

@@ -35,9 +35,30 @@ Deno does not run npm `postinstall` / build scripts unless you allow them. `deno
 
 | Path | Description |
 |---|---|
+| `GET /` | Liveness probe (`{"status":"ok"}`) — intentionally minimal so unauthenticated callers don't see the function map. |
 | `POST /functions/v1/:name` | Invoke an edge function |
-| `GET /health` | Health check + loaded function list |
-| `GET /metrics` | Prometheus-compatible metrics |
+| `GET /health` | Auth-gated health (`Authorization: Bearer $INTERNAL_KEY`); without auth returns the same minimal `{"status":"ok"}`. |
+| `GET /metrics` | Auth-gated Prometheus exposition (same scheme). |
+
+## Configuration
+
+All knobs default to safe-but-backwards-compatible values. The TS gateway (`src/server.ts`) reads:
+
+| Env / flag | Default | Notes |
+|---|---|---|
+| `--port` / `PORT` | `3100` | Listen port |
+| `--host` / `1TUBE_HOST` | `127.0.0.1` | Loopback by default — pass `--host 0.0.0.0` to expose. |
+| `--functions` / `FUNCTIONS_PATH` | `./supabase/functions` | Functions root |
+| `--timeout` / `FUNCTION_TIMEOUT_MS` | `150000` | Per-request wall-clock cap (also overridable per function) |
+| `--dev` / `1TUBE_DEV` | off | Applies the well-known local Supabase JWT/secrets. **Refuses to start in prod when JWT_SECRET / SUPABASE_SERVICE_ROLE_KEY are missing or are the public dev defaults.** |
+| `--hmr` / `1TUBE_HMR` | off | File-watch + per-function reload (dev only). |
+| `1TUBE_BODY_LIMIT_MB` | `30` | Hono `bodyLimit`; matches Supabase. Returns 413 before the handler runs. |
+| `1TUBE_BODY_READ_MS` | `30000` | Slow-loris guard. Max idle gap (ms) between body chunks before the request is aborted with **408**. NOT a total body-read deadline — large but fast uploads pass through. Set `0` to disable. |
+| `1TUBE_CORS_ORIGIN` | `*` (dev only) | Comma-separated allowlist or `*`. In prod, leaving unset disables CORS. |
+| `1TUBE_TRUSTED_PROXIES` | empty | Comma-separated list of remote IPs whose `X-Forwarded-For` is honored. Anything else uses the raw socket address — XFF spoofing no longer mints fresh rate-limit buckets. |
+| `1TUBE_SHUTDOWN_GRACE_MS` | `10000` | SIGINT/SIGTERM drain budget. |
+| `INTERNAL_KEY` | unset | Required to read detailed `/health` and `/metrics`. Header-only: `Authorization: Bearer $INTERNAL_KEY`. |
+```
 
 ## .NET integration
 

package/deno.json

@@ -5,10 +5,13 @@
   },
   "tasks": {
     "dev": "deno run --allow-all --watch src/server.ts",
-    "serve": "deno run --allow-all src/server.ts"
+    "serve": "deno run --allow-all src/server.ts",
+    "play": "deno run --allow-all --watch src/server.ts --dev --hmr --functions ./playground --port 3199",
+    "test": "deno test --allow-all tests/"
   },
   "imports": {
     "@std/path": "jsr:@std/path@^1",
+    "@std/assert": "jsr:@std/assert@^1",
     "hono": "npm:hono@4"
   },
   "nodeModulesDir": "auto",

package/deno.lock

@@ -1,6 +1,7 @@
 {
   "version": "5",
   "specifiers": {
+    "jsr:@std/assert@1": "1.0.19",
     "jsr:@std/internal@^1.0.12": "1.0.12",
     "jsr:@std/path@1": "1.1.4",
     "npm:@ai-sdk/mcp@0": "0.0.15_zod@3.25.76",
@@ -12,6 +13,12 @@
     "npm:zod@3": "3.25.76"
   },
   "jsr": {
+    "@std/assert@1.0.19": {
+      "integrity": "eaada96ee120cb980bc47e040f82814d786fe8162ecc53c91d8df60b8755991e",
+      "dependencies": [
+        "jsr:@std/internal"
+      ]
+    },
     "@std/internal@1.0.12": {
       "integrity": "972a634fd5bc34b242024402972cd5143eac68d8dffaca5eaa4dba30ce17b027"
     },
@@ -494,6 +501,7 @@
   },
   "workspace": {
     "dependencies": [
+      "jsr:@std/assert@1",
       "jsr:@std/path@1",
       "npm:hono@4"
     ],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "1tube",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "private": false,
   "description": "Self-hosted Supabase Edge Functions gateway for Deno, plus an ESLint plugin for consumers",
   "license": "MIT",

package/src/discovery.ts

@@ -3,72 +3,194 @@
  *
  * Scans `functionsDir` for subdirectories containing an `index.ts`.
  * Skips directories starting with `_` or ending with `_shared`.
- * Each discovered module is dynamically imported — the top-level `serve()` call
- * in the module registers the handler via the global FunctionRegistry.
+ * Each discovered module is dynamically imported in parallel — the top-level
+ * `serve()` call in the module registers the handler via the global
+ * FunctionRegistry. Concurrent imports are kept registration-safe via the
+ * registry's async-context binding.
  */
 
-import { join, toFileUrl } from "jsr:@std/path@^1";
+// node: specifiers so this module loads cleanly from node_modules in any
+// host Deno project (no shared import-map entry required).
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
 import type { FunctionRegistry } from "./registry.ts";
+import { loadManifest } from "./manifest.ts";
+
+export interface DiscoveryProgress {
+  name: string;
+  index: number;
+  total: number;
+  durationMs: number;
+  ok: boolean;
+  error?: string;
+}
+
+export interface DiscoveryOptions {
+  /** When set, appended as `?v=` to module URLs to force re-transpilation. */
+  cacheBust?: string;
+  /** Restrict loading to this set of function names (others are skipped entirely). */
+  only?: ReadonlySet<string>;
+  /** Max number of concurrent dynamic imports. Defaults to 8. */
+  concurrency?: number;
+  /** Invoked once per function as it finishes (success or failure). */
+  onProgress?: (p: DiscoveryProgress) => void;
+  /**
+   * When true, candidates are registered for lazy import on first dispatch.
+   * Functions whose manifest sets `warm: true` are still imported eagerly
+   * (in parallel, alongside other warm functions). Significantly cuts
+   * startup wall-clock and resident memory when many functions exist.
+   */
+  lazy?: boolean;
+}
+
+export interface DiscoveryResult {
+  loaded: string[];
+  skipped: string[];
+  errors: Array<{ name: string; error: string }>;
+  /** Function names whose `index.ts` no longer exists (caller should evict from registry). */
+  removed: string[];
+  /** Names registered as lazy candidates (only populated when `options.lazy` is true). */
+  deferred: string[];
+}
 
 export async function discoverAndLoad(
   functionsDir: string,
   registry: FunctionRegistry,
-  options?: { cacheBust?: string },
-): Promise<{ loaded: string[]; skipped: string[]; errors: Array<{ name: string; error: string }> }> {
+  options?: DiscoveryOptions,
+): Promise<DiscoveryResult> {
   const loaded: string[] = [];
   const skipped: string[] = [];
+  const removed: string[] = [];
+  const deferred: string[] = [];
   const errors: Array<{ name: string; error: string }> = [];
 
   const resolvedDir = await Deno.realPath(functionsDir);
 
-  const entries: string[] = [];
+  const candidates: string[] = [];
   for await (const entry of Deno.readDir(resolvedDir)) {
     if (!entry.isDirectory) continue;
     if (entry.name.startsWith("_") || entry.name.endsWith("_shared")) {
       skipped.push(entry.name);
       continue;
     }
-    entries.push(entry.name);
+    candidates.push(entry.name);
   }
+  candidates.sort();
 
-  entries.sort();
+  // Build the work list: exists check + `only` filter.
+  const work: string[] = [];
+  for (const name of candidates) {
+    if (options?.only && !options.only.has(name)) continue;
 
-  for (const name of entries) {
     const indexPath = join(resolvedDir, name, "index.ts");
-
     try {
       await Deno.stat(indexPath);
+      work.push(name);
     } catch {
-      skipped.push(name);
-      continue;
+      // No index.ts. If we were asked to reload this name explicitly, treat as
+      // a deletion so the caller can evict it. Otherwise just skip.
+      if (options?.only?.has(name)) {
+        removed.push(name);
+      } else {
+        skipped.push(name);
+      }
+    }
+  }
+
+  // Also detect deletions from `only` that didn't appear as candidates at all
+  // (e.g. the whole directory was removed).
+  if (options?.only) {
+    const present = new Set(candidates);
+    for (const name of options.only) {
+      if (!present.has(name) && !removed.includes(name)) {
+        removed.push(name);
+      }
     }
+  }
 
-    registry.setCurrentFunction(name);
+  const total = work.length;
+  let completed = 0;
 
+  const loadOne = async (name: string): Promise<void> => {
+    const indexPath = join(resolvedDir, name, "index.ts");
+    // pathToFileURL is the node:url equivalent of std/path's toFileUrl;
+    // both produce a `file://` URL whose searchParams we mutate below for
+    // HMR cache-busting.
+    const moduleUrl = pathToFileURL(indexPath);
+    if (options?.cacheBust) {
+      moduleUrl.searchParams.set("v", options.cacheBust);
+    }
+
+    const start = performance.now();
     try {
-      const moduleUrl = toFileUrl(indexPath);
-      if (options?.cacheBust) {
-        moduleUrl.searchParams.set("v", options.cacheBust);
+      // Load the manifest first so it is attached to the registry before the
+      // module's top-level `serve()` call captures the handler. Manifest
+      // failures degrade to defaults inside loadManifest().
+      const manifest = await loadManifest(resolvedDir, name);
+
+      // Lazy mode: skip the dynamic import unless the manifest opts in via
+      // `warm: true`. Register a candidate so the first dispatch can import
+      // on demand. This is the single biggest startup-time win for sites
+      // with many rarely-called functions.
+      if (options?.lazy && !manifest.warm) {
+        registry.registerCandidate({ name, moduleUrl: moduleUrl.href, manifest });
+        deferred.push(name);
+        const durationMs = performance.now() - start;
+        options?.onProgress?.({
+          name,
+          index: ++completed,
+          total,
+          durationMs,
+          ok: true,
+        });
+        return;
       }
-      await import(moduleUrl.href);
+
+      registry.attachManifest(name, manifest);
+      // Even in lazy mode, eagerly-warm functions still register a candidate
+      // so HMR reloads can re-import via the same URL.
+      if (options?.lazy && manifest.warm) {
+        registry.registerCandidate({ name, moduleUrl: moduleUrl.href, manifest });
+      }
+      await registry.runWithCurrentFunction(name, async () => {
+        await import(moduleUrl.href);
+      });
       loaded.push(name);
+      const durationMs = performance.now() - start;
+      options?.onProgress?.({
+        name,
+        index: ++completed,
+        total,
+        durationMs,
+        ok: true,
+      });
     } catch (err) {
       const msg = err instanceof Error ? err.message : String(err);
       errors.push({ name, error: msg });
+      const durationMs = performance.now() - start;
+      options?.onProgress?.({
+        name,
+        index: ++completed,
+        total,
+        durationMs,
+        ok: false,
+        error: msg,
+      });
+    }
+  };
 
-      const isEnvIssue =
-        msg.includes("is required") ||
-        msg.includes("must be set") ||
-        msg.includes("API key") ||
-        msg.includes("undefined");
-
-      if (isEnvIssue) {
-        console.error(`[1tube] Failed to load "${name}" (missing env var): ${msg}`);
-      } else {
-        console.error(`[1tube] Failed to load "${name}": ${msg}`);
-      }
+  // Bounded parallel loader. Deno's module loader serializes some FS work
+  // internally, but we still benefit from overlapping transpile + JSR fetches.
+  const concurrency = Math.max(1, options?.concurrency ?? 8);
+  let cursor = 0;
+  const workers = Array.from({ length: Math.min(concurrency, work.length) }, async () => {
+    while (true) {
+      const i = cursor++;
+      if (i >= work.length) return;
+      await loadOne(work[i]);
     }
-  }
+  });
+  await Promise.all(workers);
 
-  return { loaded, skipped, errors };
+  return { loaded, skipped, errors, removed, deferred };
 }

package/src/env-scope.ts

@@ -0,0 +1,120 @@
+/**
+ * Per-function env-var scoping.
+ *
+ * When `1TUBE_ENFORCE_MANIFEST=1`, `installEnvScope()` replaces `Deno.env` with
+ * a wrapper that filters reads (`get`, `has`, `toObject`) against the active
+ * function's manifest `permissions.env` allowlist, using AsyncLocalStorage to
+ * know which function is currently executing. Outside any function context
+ * (e.g. server bootstrap, gateway middleware) all env access passes through
+ * unchanged so the gateway itself never gets sandboxed.
+ *
+ * Writes (`set`, `delete`) are always rejected from inside a function context
+ * — functions should not be able to mutate process env on each other.
+ *
+ * `1TUBE_ALLOW_ALL=1` short-circuits the scope and is the documented escape
+ * hatch for legacy functions whose env usage hasn't been audited yet.
+ *
+ * This is opt-in, monitored on bootstrap, and idempotent.
+ */
+
+import { AsyncLocalStorage } from "node:async_hooks";
+
+export interface EnvScopeContext {
+  functionName: string;
+  /** Allowlisted env var names (manifest.permissions.env). */
+  allow: ReadonlySet<string>;
+}
+
+export const envScopeStorage = new AsyncLocalStorage<EnvScopeContext>();
+
+let _installed = false;
+
+/**
+ * Replace Deno.env with a filtering wrapper. Safe to call multiple times;
+ * only the first call has an effect.
+ */
+export function installEnvScope(): void {
+  if (_installed) return;
+  _installed = true;
+
+  const original = Deno.env;
+  const allowAll = (Deno.env.get("1TUBE_ALLOW_ALL") ?? "") === "1";
+
+  const wrap: typeof Deno.env = {
+    get(key: string) {
+      const ctx = envScopeStorage.getStore();
+      if (!ctx || allowAll) return original.get(key);
+      if (ctx.allow.has(key)) return original.get(key);
+      return undefined;
+    },
+    has(key: string) {
+      const ctx = envScopeStorage.getStore();
+      if (!ctx || allowAll) return original.has(key);
+      if (!ctx.allow.has(key)) return false;
+      return original.has(key);
+    },
+    set(key: string, value: string) {
+      const ctx = envScopeStorage.getStore();
+      if (ctx && !allowAll) {
+        throw new Deno.errors.PermissionDenied(
+          `Function "${ctx.functionName}" attempted Deno.env.set(${JSON.stringify(key)}); ` +
+            `env writes are not permitted from function code.`,
+        );
+      }
+      original.set(key, value);
+    },
+    delete(key: string) {
+      const ctx = envScopeStorage.getStore();
+      if (ctx && !allowAll) {
+        throw new Deno.errors.PermissionDenied(
+          `Function "${ctx.functionName}" attempted Deno.env.delete(${JSON.stringify(key)}); ` +
+            `env writes are not permitted from function code.`,
+        );
+      }
+      original.delete(key);
+    },
+    toObject() {
+      const ctx = envScopeStorage.getStore();
+      if (!ctx || allowAll) return original.toObject();
+      const all = original.toObject();
+      const filtered: Record<string, string> = {};
+      for (const k of ctx.allow) {
+        if (k in all) filtered[k] = all[k];
+      }
+      return filtered;
+    },
+  };
+
+  try {
+    Object.defineProperty(Deno, "env", {
+      value: wrap,
+      writable: false,
+      configurable: true,
+    });
+  } catch {
+    // Deno.env property is locked down on this runtime — patch the methods on
+    // the existing object instead. This still gives us the same scoping
+    // behaviour because the wrapper closes over `original`.
+    (original as { get: typeof wrap.get }).get = wrap.get;
+    (original as { has: typeof wrap.has }).has = wrap.has;
+    (original as { set: typeof wrap.set }).set = wrap.set;
+    (original as { delete: typeof wrap.delete }).delete = wrap.delete;
+    (original as { toObject: typeof wrap.toObject }).toObject = wrap.toObject;
+  }
+}
+
+/**
+ * Run `fn` with the env-scope context bound to `name` + `allow`. Any nested
+ * `Deno.env.*` call sees only the allowlisted variables.
+ */
+export function runWithEnvScope<T>(
+  ctx: EnvScopeContext,
+  fn: () => T | Promise<T>,
+): T | Promise<T> {
+  return envScopeStorage.run(ctx, fn);
+}
+
+/** Test-only: allow re-installation in unit tests. */
+export function _resetEnvScopeForTests(): void {
+  _installed = false;
+}

package/src/gateway/auth.ts

@@ -3,25 +3,71 @@
  *
  * Validates HMAC-SHA256 JWTs using the same secret as Supabase,
  * producing tokens fully compatible with Supabase RLS policies.
+ *
+ * The JWT secret is read lazily on first use so that env defaults applied
+ * by the server bootstrap (e.g. dev mode) take effect even though this
+ * module is imported transitively before bootstrap runs.
+ *
+ * Verified payloads are cached in a bounded LRU keyed by the raw token
+ * string. Cache hits skip the SubtleCrypto verify (~50–200µs each on a
+ * realistic workload) and the JSON.parse, which is the single biggest
+ * single-process throughput win on the hot path.
+ *
+ *   - Cache is invalidated implicitly when JWT_SECRET rotates
+ *     (see `getSecret()`), so a stale entry can never validate against
+ *     a new key.
+ *   - Each entry stores the token's `exp` so we never serve a payload
+ *     past its TTL.
+ *   - The map is bounded; oldest insertions are evicted first
+ *     (insertion-order LRU; bumped on each hit).
  */
 
 import type { AuthContext, JWTPayload } from "../registry.ts";
 
-const JWT_SECRET = Deno.env.get("JWT_SECRET") || "";
-if (!JWT_SECRET) {
-  console.warn("[1tube] JWT_SECRET not set — authenticated endpoints will reject all requests");
-}
-
 const encoder = new TextEncoder();
 const decoder = new TextDecoder();
 
 let _cachedKey: CryptoKey | null = null;
+let _cachedSecret: string | null = null;
+let _warnedNoSecret = false;
+
+const VERIFY_CACHE_DEFAULT_MAX = 5_000;
+let _verifyCacheMax = VERIFY_CACHE_DEFAULT_MAX;
+
+interface VerifiedEntry {
+  payload: JWTPayload;
+  expiresAtMs: number;
+}
 
-async function getKey(): Promise<CryptoKey> {
+const verifyCache = new Map<string, VerifiedEntry>();
+let _verifyCacheHits = 0;
+let _verifyCacheMisses = 0;
+
+function getSecret(): string {
+  const current = Deno.env.get("JWT_SECRET") || "";
+  if (current !== _cachedSecret) {
+    _cachedSecret = current;
+    _cachedKey = null;
+    // Any cached verifications were authorised against the previous key;
+    // drop them so a rotated secret cannot accidentally accept old tokens.
+    verifyCache.clear();
+    if (!current && !_warnedNoSecret) {
+      console.warn(
+        "[1tube] JWT_SECRET not set — authenticated endpoints will reject all requests",
+      );
+      _warnedNoSecret = true;
+    }
+  }
+  return current;
+}
+
+async function getKey(): Promise<CryptoKey | null> {
+  const secret = getSecret();
+  if (!secret) return null;
   if (_cachedKey) return _cachedKey;
   _cachedKey = await crypto.subtle.importKey(
     "raw",
-    encoder.encode(JWT_SECRET),
+    encoder.encode(secret),
     { name: "HMAC", hash: "SHA-256" },
     false,
     ["verify"],
@@ -42,13 +88,54 @@ function parseBearer(header: string | null): string | null {
   return match ? match[1] : null;
 }
 
+function cacheGet(token: string, nowMs: number): JWTPayload | null {
+  const hit = verifyCache.get(token);
+  if (!hit) return null;
+  if (hit.expiresAtMs <= nowMs) {
+    verifyCache.delete(token);
+    return null;
+  }
+  // LRU bump: re-insert so this entry becomes the most recently used.
+  verifyCache.delete(token);
+  verifyCache.set(token, hit);
+  _verifyCacheHits++;
+  return hit.payload;
+}
+
+function cacheSet(token: string, payload: JWTPayload): void {
+  // Evict insertion-oldest while we're over capacity. Loop because the cap
+  // can be lowered at runtime via `_setVerifyCacheMaxForTests()`.
+  while (verifyCache.size >= _verifyCacheMax) {
+    const oldest = verifyCache.keys().next().value;
+    if (oldest === undefined) break;
+    verifyCache.delete(oldest);
+  }
+  verifyCache.set(token, {
+    payload,
+    expiresAtMs: payload.exp * 1000,
+  });
+}
+
 async function verifyToken(token: string): Promise<JWTPayload | null> {
+  // Resolve the secret BEFORE consulting the cache. getSecret() detects
+  // rotation and clears stale entries; if we read the cache first, a token
+  // signed with the previous key would be returned to the caller before the
+  // rotation took effect.
+  const secret = getSecret();
+  if (!secret) return null;
+
+  const nowMs = Date.now();
+  const cached = cacheGet(token, nowMs);
+  if (cached) return cached;
+
+  _verifyCacheMisses++;
   try {
     const parts = token.split(".");
     if (parts.length !== 3) return null;
 
     const [headerB64, payloadB64, signatureB64] = parts;
     const key = await getKey();
+    if (!key) return null;
     const sigBytes = base64UrlDecode(signatureB64);
 
     const isValid = await crypto.subtle.verify(
@@ -61,8 +148,15 @@ async function verifyToken(token: string): Promise<JWTPayload | null> {
 
     const payload = JSON.parse(decoder.decode(base64UrlDecode(payloadB64))) as JWTPayload;
 
-    if (payload.exp < Math.floor(Date.now() / 1000)) return null;
+    // `exp` is a NumericDate (seconds since epoch). Per RFC 7519 the token
+    // MUST NOT be accepted past `exp`; we treat the second the token expires
+    // as "past" so a 1-second TTL token can't be replayed within the same
+    // wall-clock second.
+    if (typeof payload.exp !== "number" || payload.exp * 1000 <= nowMs) {
+      return null;
+    }
 
+    cacheSet(token, payload);
     return payload;
   } catch {
     return null;
@@ -86,3 +180,44 @@ export async function validateRequest(req: Request): Promise<AuthContext | null>
     rawToken: token,
   };
 }
+
+// ---------------------------------------------------------------------------
+// Diagnostics & test hooks
+// ---------------------------------------------------------------------------
+
+export interface JwtVerifyCacheStats {
+  size: number;
+  capacity: number;
+  hits: number;
+  misses: number;
+}
+
+export function getVerifyCacheStats(): JwtVerifyCacheStats {
+  return {
+    size: verifyCache.size,
+    capacity: _verifyCacheMax,
+    hits: _verifyCacheHits,
+    misses: _verifyCacheMisses,
+  };
+}
+
+/** Test-only: clear the cache + counters and reset key/secret memoisation. */
+export function _resetAuthForTests(): void {
+  verifyCache.clear();
+  _verifyCacheHits = 0;
+  _verifyCacheMisses = 0;
+  _cachedKey = null;
+  _cachedSecret = null;
+  _warnedNoSecret = false;
+  _verifyCacheMax = VERIFY_CACHE_DEFAULT_MAX;
+}
+
+/** Test-only: shrink the cache so eviction is observable in unit tests. */
+export function _setVerifyCacheMaxForTests(max: number): void {
+  _verifyCacheMax = Math.max(1, Math.floor(max));
+  while (verifyCache.size > _verifyCacheMax) {
+    const oldest = verifyCache.keys().next().value;
+    if (oldest === undefined) break;
+    verifyCache.delete(oldest);
+  }
+}