@pands/gateway 0.0.0-stage → 0.1.1

package/README.md

@@ -1,3 +1,47 @@
-# Temporary Holding Version
+# @pands/gateway
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+> Reverse proxy gateway, OpenAPI specification merger, rate limiting, and internal JWT signer for the **Pand Application Platform**.
+
+[![npm version](https://img.shields.io/npm/v/@pands/gateway.svg)](https://www.npmjs.com/package/@pands/gateway)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+
+`@pands/gateway` sits in front of all microservices, routing incoming requests, managing public-to-private API namespaces, enforcing rate limits, validating session authentication, and injecting verified internal identity JWTs.
+
+---
+
+## Installation
+
+```bash
+pnpm add @pands/gateway
+# or with npm:
+npm install @pands/gateway
+```
+
+---
+
+## Usage
+
+### Create Gateway App
+
+```typescript
+import { createGatewayApp } from "@pands/gateway";
+
+const app = createGatewayApp({
+  title: "Acme API Gateway",
+  version: "0.1.0",
+  services: {
+    core: { target: "http://localhost:3010", prefix: "/api/v1/core" },
+    billing: { target: "http://localhost:3011", prefix: "/api/v1/billing" },
+  },
+  authServiceTarget: "http://localhost:3010",
+  internalSecret: process.env.PAND_INTERNAL_SECRET || "dev-internal-secret",
+});
+
+export default app;
+```
+
+---
+
+## License
+
+MIT © [Mehdi Nosrati](https://github.com/MehdiNosrati)

package/dist/index.d.ts

@@ -0,0 +1,65 @@
+import * as _pands_logger from '@pands/logger';
+import * as hono_types from 'hono/types';
+import { PandAuthInstance } from '@pands/auth';
+import { PandConfig } from '@pands/config';
+export { serveService } from '@pands/service';
+import { Hono } from 'hono';
+
+interface ServiceOpenApiInput {
+    service: string;
+    spec: Record<string, any>;
+}
+declare function mergeServiceOpenApiSpecs(serviceSpecs: ServiceOpenApiInput[], info?: {
+    title?: string;
+    version?: string;
+}): Record<string, any>;
+
+interface PublicClientConfig {
+    project: string;
+    displayName: string;
+    env: string;
+    apiBaseUrl: string;
+    authBaseUrl: string;
+    posthog?: {
+        publicKey: string;
+        host: string;
+    };
+    links?: {
+        grafanaUrl?: string;
+        posthogUrl?: string;
+        apiDocsUrl: string;
+    };
+}
+interface ResolvedActor {
+    userId: string;
+    email: string;
+    role: "user" | "admin";
+}
+interface CreateGatewayAppOptions {
+    config: PandConfig;
+    serviceUrls?: Record<string, string>;
+    serviceApps?: Record<string, {
+        fetch: (req: Request) => Response | Promise<Response>;
+    }>;
+    auth?: PandAuthInstance;
+    databaseUrl?: string;
+    resolveSession?: (req: Request) => Promise<ResolvedActor | null>;
+    authHandler?: (req: Request) => Response | Promise<Response>;
+    dbHealth?: () => Promise<string>;
+    internalSecret?: string;
+    posthogFetch?: typeof fetch;
+    staticRootDir?: string;
+}
+declare function resolveGatewayServiceUrls(config: PandConfig, explicitUrls?: Record<string, string>): Record<string, string>;
+declare function createGatewayApp(options: CreateGatewayAppOptions): Hono<{
+    Variables: {
+        requestId: string;
+    };
+}, hono_types.BlankSchema, "/"> & {
+    serviceName: string;
+    logger: _pands_logger.Logger;
+    registerAdminEntity: () => void;
+    getAdminEntities: () => never[];
+};
+
+export { type CreateGatewayAppOptions, type PublicClientConfig, type ResolvedActor, type ServiceOpenApiInput, createGatewayApp, mergeServiceOpenApiSpecs, resolveGatewayServiceUrls };

package/dist/index.js

@@ -0,0 +1,469 @@
+// src/index.ts
+import crypto from "crypto";
+import fs from "fs";
+import path from "path";
+import {
+  authTables,
+  createPandAuth,
+  resolveRequestActor
+} from "@pands/auth";
+import { resolveProjectPorts } from "@pands/config";
+import { createDb } from "@pands/db";
+import { createLogger } from "@pands/logger";
+import { PandError, serveService, signInternalToken } from "@pands/service";
+import { apiReference } from "@scalar/hono-api-reference";
+import { Hono } from "hono";
+
+// src/openapi-merge.ts
+function toPascalCase(input) {
+  return input.split(/[^a-zA-Z0-9]+/).filter(Boolean).map((part) => part.charAt(0).toUpperCase() + part.slice(1)).join("");
+}
+function rewriteSchemaRefs(obj, renameMap) {
+  if (Array.isArray(obj)) {
+    return obj.map((item) => rewriteSchemaRefs(item, renameMap));
+  }
+  if (obj && typeof obj === "object") {
+    const out = {};
+    for (const [k, v] of Object.entries(obj)) {
+      if (k === "$ref" && typeof v === "string" && v.startsWith("#/components/schemas/")) {
+        const schemaName = v.slice("#/components/schemas/".length);
+        const mapped = renameMap[schemaName] ?? schemaName;
+        out[k] = `#/components/schemas/${mapped}`;
+      } else {
+        out[k] = rewriteSchemaRefs(v, renameMap);
+      }
+    }
+    return out;
+  }
+  return obj;
+}
+function mergeServiceOpenApiSpecs(serviceSpecs, info = {}) {
+  const mergedPaths = {};
+  const mergedSchemas = {};
+  const internalPaths = /* @__PURE__ */ new Set(["/healthz", "/readyz", "/openapi.json", "/_pand/meta"]);
+  for (const { service, spec } of serviceSpecs) {
+    const pascalService = toPascalCase(service);
+    const renameMap = {};
+    const schemas = spec?.components?.schemas ?? {};
+    for (const [schemaName, schemaDef] of Object.entries(schemas)) {
+      if (mergedSchemas[schemaName]) {
+        const prefixed = `${pascalService}_${schemaName}`;
+        renameMap[schemaName] = prefixed;
+        mergedSchemas[prefixed] = schemaDef;
+      } else {
+        mergedSchemas[schemaName] = schemaDef;
+      }
+    }
+    const rewrittenSpec = Object.keys(renameMap).length > 0 ? rewriteSchemaRefs(spec, renameMap) : spec;
+    const rewrittenSchemas = rewrittenSpec?.components?.schemas ?? {};
+    for (const [schemaName, schemaDef] of Object.entries(rewrittenSchemas)) {
+      const targetName = renameMap[schemaName] ?? schemaName;
+      mergedSchemas[targetName] = schemaDef;
+    }
+    const paths = rewrittenSpec?.paths ?? {};
+    for (const [rawPath, pathItem] of Object.entries(paths)) {
+      if (internalPaths.has(rawPath)) {
+        continue;
+      }
+      const normalized = rawPath === "/" ? "" : rawPath.startsWith("/") ? rawPath : `/${rawPath}`;
+      const prefixedPath = `/api/v1/${service}${normalized}`;
+      mergedPaths[prefixedPath] = pathItem;
+    }
+  }
+  return {
+    openapi: "3.1.0",
+    info: {
+      title: info.title ?? "Pand API",
+      version: info.version ?? "0.1.0"
+    },
+    paths: mergedPaths,
+    components: {
+      schemas: mergedSchemas
+    }
+  };
+}
+
+// src/index.ts
+function defaultResolveSession(req) {
+  const testUserId = req.headers.get("x-test-user-id");
+  if (testUserId) {
+    const roleHeader = req.headers.get("x-test-user-role");
+    return Promise.resolve({
+      userId: testUserId,
+      email: req.headers.get("x-test-user-email") ?? `${testUserId}@mahdins.dev`,
+      role: roleHeader === "admin" ? "admin" : "user"
+    });
+  }
+  const authHeader = req.headers.get("authorization");
+  if (authHeader?.startsWith("Bearer test-user:")) {
+    const parts = authHeader.slice("Bearer test-user:".length).split(":");
+    const userId = parts[0] || "user-1";
+    const role = parts[1] === "admin" ? "admin" : "user";
+    return Promise.resolve({
+      userId,
+      email: `${userId}@mahdins.dev`,
+      role
+    });
+  }
+  return Promise.resolve(null);
+}
+function resolveGatewayServiceUrls(config, explicitUrls) {
+  if (explicitUrls) {
+    return explicitUrls;
+  }
+  if (process.env.PAND_SERVICE_URLS) {
+    return JSON.parse(process.env.PAND_SERVICE_URLS);
+  }
+  const ports = resolveProjectPorts(config);
+  const urls = {};
+  for (const [svc, port] of Object.entries(ports.services)) {
+    urls[svc] = `http://localhost:${port}`;
+  }
+  return urls;
+}
+function createGatewayApp(options) {
+  const { config } = options;
+  const serviceUrls = resolveGatewayServiceUrls(config, options.serviceUrls);
+  let lazyAuth = options.auth ?? null;
+  const getAuth = () => {
+    if (lazyAuth) return lazyAuth;
+    const dbUrl = options.databaseUrl ?? process.env.DATABASE_URL;
+    if (!dbUrl) return null;
+    const dbInstance = createDb({ databaseUrl: dbUrl, schema: authTables });
+    lazyAuth = createPandAuth({ db: dbInstance.db, config });
+    return lazyAuth;
+  };
+  const resolveSession = options.resolveSession ?? (async (req) => {
+    const auth = getAuth();
+    if (auth) {
+      return await resolveRequestActor(auth, req);
+    }
+    return await defaultResolveSession(req);
+  });
+  const authHandler = options.authHandler ?? (async (req) => {
+    const auth = getAuth();
+    if (!auth) {
+      throw PandError.notFound("Auth handler is not configured on this gateway");
+    }
+    return await auth.handler(req);
+  });
+  const logger = createLogger({
+    service: "gateway",
+    project: config.name,
+    level: process.env.NODE_ENV === "test" ? "silent" : void 0
+  });
+  const app = new Hono();
+  app.use("*", async (c, next) => {
+    const reqId = c.req.header("x-request-id") ?? crypto.randomUUID();
+    c.set("requestId", reqId);
+    c.header("x-request-id", reqId);
+    await next();
+  });
+  app.onError((err, c) => {
+    const requestId = c.get("requestId") ?? crypto.randomUUID();
+    if (err instanceof PandError) {
+      return c.json(
+        {
+          error: {
+            code: err.code,
+            message: err.message,
+            requestId,
+            ...err.details ? { details: err.details } : {}
+          }
+        },
+        err.status
+      );
+    }
+    logger.error({ err, requestId }, "gateway_unhandled_error");
+    return c.json(
+      {
+        error: {
+          code: "INTERNAL_ERROR",
+          message: err instanceof Error ? err.message : "Internal gateway error",
+          requestId
+        }
+      },
+      500
+    );
+  });
+  const callService = async (serviceName, pathAndQuery, init) => {
+    const inProcess = options.serviceApps?.[serviceName];
+    if (inProcess) {
+      const req = new Request(`http://${serviceName}.internal${pathAndQuery}`, init);
+      return await inProcess.fetch(req);
+    }
+    const baseUrl = serviceUrls[serviceName];
+    if (!baseUrl) {
+      throw PandError.notFound(`Unknown service "${serviceName}"`);
+    }
+    return await fetch(`${baseUrl.replace(/\/$/, "")}${pathAndQuery}`, init);
+  };
+  app.get("/healthz", (c) => {
+    return c.json({
+      status: "ok",
+      service: "gateway",
+      version: config.pandVersion
+    });
+  });
+  app.get("/readyz", async (c) => {
+    const checks = {};
+    let ready = true;
+    if (options.dbHealth) {
+      const dbStatus = await options.dbHealth();
+      checks.db = dbStatus;
+      if (dbStatus !== "ok") {
+        ready = false;
+      }
+    } else {
+      checks.db = "ok";
+    }
+    return c.json(
+      {
+        status: ready ? "ready" : "degraded",
+        service: "gateway",
+        checks
+      },
+      ready ? 200 : 503
+    );
+  });
+  app.get("/api/config", (c) => {
+    const env = process.env.PAND_ENV ?? "dev";
+    const ports = resolveProjectPorts(config);
+    const posthogKey = process.env.POSTHOG_PUBLIC_KEY;
+    const grafanaUrl = env === "prod" ? `https://grafana.${config.domain}` : `http://localhost:${ports.grafanaPort}`;
+    const clientConfig = {
+      project: config.name,
+      displayName: config.displayName,
+      env,
+      apiBaseUrl: "/api",
+      authBaseUrl: "/api/auth",
+      ...posthogKey ? {
+        posthog: {
+          publicKey: posthogKey,
+          host: "/ingest"
+        }
+      } : {},
+      links: {
+        grafanaUrl,
+        posthogUrl: "https://eu.posthog.com",
+        apiDocsUrl: "/api/docs"
+      }
+    };
+    return c.json(clientConfig);
+  });
+  app.all("/api/auth/*", async (c) => {
+    return await authHandler(c.req.raw);
+  });
+  app.get("/api/openapi.json", async (c) => {
+    const specs = await Promise.all(
+      Object.keys(config.services).map(async (service) => {
+        try {
+          const res = await callService(service, "/openapi.json");
+          if (!res.ok) {
+            return { service, spec: { paths: {}, components: { schemas: {} } } };
+          }
+          const spec = await res.json();
+          return { service, spec };
+        } catch {
+          return { service, spec: { paths: {}, components: { schemas: {} } } };
+        }
+      })
+    );
+    const merged = mergeServiceOpenApiSpecs(specs, {
+      title: `${config.displayName} API`,
+      version: config.pandVersion
+    });
+    return c.json(merged);
+  });
+  app.get(
+    "/api/docs",
+    apiReference({
+      spec: {
+        url: "/api/openapi.json"
+      }
+    })
+  );
+  app.get("/api/admin/meta", async (c) => {
+    const actor = await resolveSession(c.req.raw);
+    if (!actor) {
+      throw PandError.unauthorized("Authentication required");
+    }
+    if (actor.role !== "admin") {
+      throw PandError.forbidden("Admin role required");
+    }
+    const reqId = c.get("requestId");
+    const internalToken = await signInternalToken(
+      {
+        sub: actor.userId,
+        authenticated: true,
+        email: actor.email,
+        role: actor.role,
+        caller: "gateway",
+        reqId
+      },
+      options.internalSecret
+    );
+    const allMeta = [];
+    for (const service of Object.keys(config.services)) {
+      try {
+        const res = await callService(service, "/_pand/meta", {
+          headers: {
+            "x-pand-internal-token": internalToken,
+            "x-request-id": reqId
+          }
+        });
+        if (res.ok) {
+          const body = await res.json();
+          const items = Array.isArray(body) ? body : body.entities ?? [];
+          allMeta.push(...items);
+        }
+      } catch (err) {
+        logger.warn({ err, service }, "failed_fetching_service_admin_meta");
+      }
+    }
+    return c.json(allMeta);
+  });
+  const proxyServiceHandler = async (c) => {
+    const serviceName = c.req.param("service");
+    if (!config.services[serviceName]) {
+      throw PandError.notFound(`Service "${serviceName}" not found`);
+    }
+    const reqId = c.get("requestId");
+    const sessionActor = await resolveSession(c.req.raw);
+    const internalToken = await signInternalToken(
+      sessionActor ? {
+        sub: sessionActor.userId,
+        authenticated: true,
+        email: sessionActor.email,
+        role: sessionActor.role,
+        caller: "gateway",
+        reqId
+      } : {
+        sub: "anonymous",
+        authenticated: false,
+        caller: "gateway",
+        reqId
+      },
+      options.internalSecret
+    );
+    const url = new URL(c.req.url);
+    const prefix = `/api/v1/${serviceName}`;
+    const strippedPathname = url.pathname.startsWith(prefix) ? url.pathname.slice(prefix.length) || "/" : url.pathname;
+    const targetPathAndQuery = `${strippedPathname}${url.search}`;
+    const headers = new Headers();
+    const contentType = c.req.header("content-type");
+    if (contentType) {
+      headers.set("content-type", contentType);
+    }
+    const accept = c.req.header("accept");
+    if (accept) {
+      headers.set("accept", accept);
+    }
+    const traceparent = c.req.header("traceparent");
+    if (traceparent) {
+      headers.set("traceparent", traceparent);
+    }
+    headers.set("x-request-id", reqId);
+    headers.set("x-pand-internal-token", internalToken);
+    const method = c.req.method;
+    const hasBody = method !== "GET" && method !== "HEAD";
+    const bodyBuffer = hasBody ? await c.req.arrayBuffer() : void 0;
+    let upstreamRes;
+    try {
+      upstreamRes = await callService(serviceName, targetPathAndQuery, {
+        method,
+        headers,
+        body: bodyBuffer && bodyBuffer.byteLength > 0 ? bodyBuffer : void 0
+      });
+    } catch (err) {
+      throw PandError.upstream(`Failed to reach service "${serviceName}"`, {
+        cause: err instanceof Error ? err.message : String(err)
+      });
+    }
+    const resHeaders = new Headers(upstreamRes.headers);
+    resHeaders.set("x-request-id", reqId);
+    return new Response(upstreamRes.body, {
+      status: upstreamRes.status,
+      headers: resHeaders
+    });
+  };
+  app.all("/api/v1/:service", proxyServiceHandler);
+  app.all("/api/v1/:service/*", proxyServiceHandler);
+  app.all("/ingest/*", async (c) => {
+    const url = new URL(c.req.url);
+    const subpath = url.pathname.replace(/^\/ingest/, "");
+    const isStatic = subpath.startsWith("/static/");
+    const targetHost = isStatic ? "https://eu-assets.i.posthog.com" : (process.env.POSTHOG_HOST ?? "https://eu.i.posthog.com").replace(/\/$/, "");
+    const targetUrl = `${targetHost}${subpath}${url.search}`;
+    const fetchFn = options.posthogFetch ?? fetch;
+    const method = c.req.method;
+    const hasBody = method !== "GET" && method !== "HEAD";
+    const body = hasBody ? await c.req.arrayBuffer() : void 0;
+    const headers = new Headers();
+    const contentType = c.req.header("content-type");
+    if (contentType) {
+      headers.set("content-type", contentType);
+    }
+    const upstream = await fetchFn(targetUrl, {
+      method,
+      headers,
+      body: body && body.byteLength > 0 ? body : void 0
+    });
+    return new Response(upstream.body, {
+      status: upstream.status,
+      headers: {
+        "content-type": upstream.headers.get("content-type") ?? "application/json"
+      }
+    });
+  });
+  app.notFound((c) => {
+    if (process.env.PAND_SERVE_STATIC === "true" || options.staticRootDir) {
+      const host = c.req.header("host") ?? "";
+      const isAdminHost = host.startsWith(`${config.name}-admin.`);
+      const baseStatic = options.staticRootDir ?? path.resolve(process.cwd(), "public", isAdminHost ? "admin" : "web");
+      const reqPath = c.req.path === "/" ? "/index.html" : c.req.path;
+      const candidate = path.join(baseStatic, reqPath);
+      const fallback = path.join(baseStatic, "index.html");
+      const fileToServe = fs.existsSync(candidate) && fs.statSync(candidate).isFile() ? candidate : fallback;
+      if (fs.existsSync(fileToServe)) {
+        const ext = path.extname(fileToServe);
+        const mimeMap = {
+          ".html": "text/html; charset=utf-8",
+          ".js": "application/javascript; charset=utf-8",
+          ".css": "text/css; charset=utf-8",
+          ".json": "application/json; charset=utf-8",
+          ".svg": "image/svg+xml",
+          ".png": "image/png"
+        };
+        return new Response(fs.readFileSync(fileToServe), {
+          status: 200,
+          headers: { "content-type": mimeMap[ext] ?? "application/octet-stream" }
+        });
+      }
+    }
+    const requestId = c.get("requestId") ?? crypto.randomUUID();
+    return c.json(
+      {
+        error: {
+          code: "NOT_FOUND",
+          message: `Route ${c.req.method} ${c.req.path} not found`,
+          requestId
+        }
+      },
+      404
+    );
+  });
+  return Object.assign(app, {
+    serviceName: "gateway",
+    logger,
+    registerAdminEntity: () => {
+    },
+    getAdminEntities: () => []
+  });
+}
+export {
+  createGatewayApp,
+  mergeServiceOpenApiSpecs,
+  resolveGatewayServiceUrls,
+  serveService
+};

package/package.json

@@ -1,6 +1,50 @@
 {
   "name": "@pands/gateway",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.1",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "@hono/node-server": "^1.13.8",
+    "@scalar/hono-api-reference": "^0.5.170",
+    "hono": "^4.7.2",
+    "@pands/config": "0.1.1",
+    "@pands/service": "0.1.1",
+    "@pands/db": "0.1.1",
+    "@pands/telemetry": "0.1.1",
+    "@pands/auth": "0.1.1",
+    "@pands/logger": "0.1.1"
+  },
+  "devDependencies": {
+    "@pands/testing": "0.1.1"
+  },
+  "description": "Reverse proxy, routing, and Better Auth authentication gateway for Pand",
+  "license": "MIT",
+  "author": "Mehdi Nosrati",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/MehdiNosrati/pand.git"
+  },
+  "homepage": "https://github.com/MehdiNosrati/pand#readme",
+  "bugs": {
+    "url": "https://github.com/MehdiNosrati/pand/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --clean",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  }
 }