locagate 1.0.1

package/README.md

@@ -0,0 +1,81 @@
+# locagate
+
+Tiny, file-configurable local API gateway. YAML config, prefix path routing, optional JWT. One command, zero setup.
+
+```bash
+npx locagate ./config.yaml
+pnpm dlx locagate ./config.yaml
+```
+
+---
+
+## Usage
+
+Create a `locagate.yaml`:
+
+```yaml
+listen: "0.0.0.0:5000"
+jwt:
+  enabled: true
+  secret: "$JWT_SECRET"
+  passthrough: false
+routes:
+  - match: "/v1/core/*"
+    target: "http://localhost:3000"
+  - match: "/*"
+    target: "http://localhost:3003"
+```
+
+Run it:
+
+```bash
+npx locagate ./locagate.yaml
+```
+
+Or install globally:
+
+```bash
+npm install -g locagate
+locagate ./locagate.yaml
+```
+
+## Configuration reference
+
+| Key | Type | Default | Description |
+|-----|------|---------|-------------|
+| `listen` | string | `"0.0.0.0:5000"` | Address + port to bind |
+| `jwt.enabled` | bool | `false` | Enable JWT verification |
+| `jwt.secret` | string | — | HMAC secret (`$VAR` / `${VAR:-default}` expands env vars) |
+| `jwt.passthrough` | bool | `false` | Allow unauthenticated requests through |
+| `jwt.exclude` | string[] | `[]` | Path prefixes that skip JWT |
+| `routes` | array | — | Route table (first match wins) |
+
+**Environment variable expansion** works in `jwt.secret` and route `target` fields.
+
+### Route matching
+
+| Pattern | Matches |
+|---------|---------|
+| `/*` | All paths (catch-all) |
+| `/v1/core/*` | `/v1/core/...` and `/v1/core` |
+| `/health` | Only `/health` |
+
+## How it works
+
+1. Reads your YAML config (first argument, or `./locagate.yaml`)
+2. Expands `$VAR` / `${VAR:-default}` from environment variables
+3. For each incoming request, walks the route table top-to-bottom
+4. First match wins — proxies to `target` via Node's `http.request`
+5. WebSocket upgrade requests (e.g., Next.js HMR) are proxied transparently
+6. JWT verification via HS256, `x-gateway-user` header injected on success
+
+## Files
+
+```
+bin/locagate.js         — CLI entrypoint (what npx runs)
+src/index.ts            — HTTP server, routing, proxying, JWT check
+src/config.ts           — YAML/JSON config loading with $VAR expansion
+src/router.ts           — prefix-based route matching
+src/jwt.ts              — HS256 JWT verification
+locagate.yaml.sample    — annotated example config
+```

package/bin/locagate.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import '../dist/index.js';

package/dist/config.js

@@ -0,0 +1,55 @@
+import { accessSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { load as parseYaml } from 'js-yaml';
+// ponytail: $VAR and ${VAR:-default} expansion; shallow — no recursion
+function expandEnv(value) {
+    return value.replace(/\$([A-Z0-9_]+)|\$\{([A-Z0-9_]+):-([^}]*)\}/g, (_m, simple, braced, defaultVal) => {
+        const name = simple ?? braced;
+        return process.env[name] ?? defaultVal ?? '';
+    });
+}
+function normalizeConfig(raw) {
+    return {
+        listen: raw.listen ?? '0.0.0.0:5000',
+        jwt: {
+            enabled: raw.jwt?.enabled ?? false,
+            secret: raw.jwt?.secret ? expandEnv(raw.jwt.secret) : undefined,
+            passthrough: raw.jwt?.passthrough ?? false,
+            exclude: raw.jwt?.exclude ?? []
+        },
+        routes: (raw.routes ?? []).map((route) => ({
+            match: route.match,
+            target: expandEnv(route.target),
+            jwt: route.jwt
+        }))
+    };
+}
+const CONFIG_FILES = ['locagate.yaml', 'locagate.yml', 'locagate.json'];
+export async function loadConfig(configPath) {
+    const fileName = configPath ?? findConfigFile();
+    const content = await readFile(fileName, 'utf8');
+    const ext = path.extname(fileName).toLowerCase();
+    const parsed = ext === '.json' ? JSON.parse(content) : parseYaml(content);
+    return normalizeConfig(parsed);
+}
+function findConfigFile() {
+    for (const name of CONFIG_FILES) {
+        const p = path.resolve(process.cwd(), name);
+        try {
+            accessSync(p);
+            return p;
+        }
+        catch { /* try next */ }
+    }
+    return path.resolve(process.cwd(), 'locagate.yaml');
+}
+export function resolveConfigPath(input) {
+    if (!input) {
+        return findConfigFile();
+    }
+    if (path.isAbsolute(input)) {
+        return input;
+    }
+    return path.resolve(process.cwd(), input);
+}

package/dist/index.js

@@ -0,0 +1,182 @@
+import 'dotenv/config';
+import http from 'node:http';
+import { loadConfig, resolveConfigPath } from './config.js';
+import { verifyJwt } from './jwt.js';
+import { matchRoute } from './router.js';
+function parseListenAddress(value) {
+    const trimmed = value.trim();
+    if (!trimmed) {
+        return { host: '127.0.0.1', port: 5000 };
+    }
+    if (/^:\d+$/.test(trimmed)) {
+        return { host: '127.0.0.1', port: Number(trimmed.slice(1)) };
+    }
+    const lastColon = trimmed.lastIndexOf(':');
+    if (lastColon === -1) {
+        return { host: '127.0.0.1', port: Number(trimmed) };
+    }
+    // ponytail: keep 0.0.0.0 as-is — needed for Docker port forwarding
+    const host = trimmed.slice(0, lastColon) || '127.0.0.1';
+    const port = Number(trimmed.slice(lastColon + 1));
+    return { host, port };
+}
+function getAuthHeader(req) {
+    const header = req.headers.authorization;
+    if (!header)
+        return undefined;
+    return Array.isArray(header) ? header[0] : header;
+}
+function shouldBypassJwt(pathname, jwtConfig, routeJwtOverride) {
+    if (!jwtConfig?.enabled)
+        return true;
+    if (routeJwtOverride === false)
+        return true;
+    if (routeJwtOverride === true)
+        return false;
+    if (jwtConfig.exclude?.some((entry) => entry === pathname || pathname.startsWith(entry.replace(/\*$/, '')))) {
+        return true;
+    }
+    return false;
+}
+async function proxyRequest(req, res, target) {
+    const headers = {};
+    for (const [key, value] of Object.entries(req.headers)) {
+        if (value === undefined)
+            continue;
+        const resolvedValue = Array.isArray(value) ? value.join(',') : value ?? '';
+        headers[key] = resolvedValue;
+    }
+    headers.host = target.host;
+    headers['x-forwarded-host'] = req.headers.host ?? 'localhost';
+    headers['x-forwarded-proto'] = 'http';
+    headers['x-forwarded-for'] = req.socket.remoteAddress ?? '127.0.0.1';
+    const incomingUrl = new URL(req.url ?? '/', 'http://localhost');
+    const targetPathname = `${target.pathname === '/' ? '' : target.pathname}${incomingUrl.pathname}`;
+    const targetPath = `${targetPathname === '' ? '/' : targetPathname}${incomingUrl.search}`;
+    const targetReq = http.request({
+        protocol: target.protocol,
+        hostname: target.hostname,
+        port: target.port,
+        path: targetPath,
+        method: req.method,
+        headers
+    }, (targetRes) => {
+        res.writeHead(targetRes.statusCode ?? 502, targetRes.headers);
+        targetRes.pipe(res);
+    });
+    targetReq.on('error', (error) => {
+        if (!res.headersSent) {
+            res.writeHead(502, { 'content-type': 'application/json' });
+        }
+        res.end(JSON.stringify({ error: 'Upstream connection failed', details: error.message }));
+    });
+    req.pipe(targetReq);
+}
+// ponytail: WebSocket upgrade proxy — no JWT check (HMR / dev connections are unauthenticated).
+//             Add JWT if production WebSockets need it.
+function proxyUpgrade(req, socket, head, routes) {
+    const url = new URL(req.url ?? '/', 'http://localhost');
+    const route = matchRoute(url.pathname, routes);
+    if (!route) {
+        socket.destroy();
+        return;
+    }
+    const targetUrl = new URL(route.target);
+    const incomingUrl = new URL(req.url ?? '/', 'http://localhost');
+    const targetPathname = `${targetUrl.pathname === '/' ? '' : targetUrl.pathname}${incomingUrl.pathname}`;
+    const targetPath = `${targetPathname === '' ? '/' : targetPathname}${incomingUrl.search}`;
+    const headers = {};
+    for (const [key, value] of Object.entries(req.headers)) {
+        if (value === undefined)
+            continue;
+        headers[key] = Array.isArray(value) ? value.join(',') : value;
+    }
+    headers.host = targetUrl.host;
+    const proxyReq = http.request({
+        hostname: targetUrl.hostname,
+        port: targetUrl.port,
+        path: targetPath,
+        method: req.method ?? 'GET',
+        headers,
+    });
+    proxyReq.on('upgrade', (proxyRes, proxySocket) => {
+        // Forward 101 response headers back to the client
+        const rawHeaders = Object.entries(proxyRes.headers)
+            .map(([k, v]) => `${k}: ${Array.isArray(v) ? v.join(', ') : v}`)
+            .join('\r\n');
+        socket.write('HTTP/1.1 101 Switching Protocols\r\n' + rawHeaders + '\r\n\r\n');
+        // Forward the initial head chunk (if any), then pipe bidirectionally
+        if (head?.length)
+            proxySocket.write(head);
+        proxySocket.pipe(socket);
+        socket.pipe(proxySocket);
+    });
+    // ponytail: if target responds without upgrading (non-101), close the socket
+    proxyReq.on('response', () => socket.destroy());
+    proxyReq.on('error', () => socket.destroy());
+    proxyReq.end();
+}
+async function main() {
+    const configPath = process.argv[2];
+    const resolvedPath = resolveConfigPath(configPath);
+    console.error('config:', resolvedPath);
+    const gatewayConfig = await loadConfig(resolvedPath);
+    console.error('routes:', JSON.stringify(gatewayConfig.routes.map(r => ({ match: r.match, target: r.target }))));
+    const { host, port } = parseListenAddress(gatewayConfig.listen);
+    console.error('listen:', host, port);
+    const server = http.createServer(async (req, res) => {
+        const url = new URL(req.url ?? '/', 'http://localhost');
+        const route = matchRoute(url.pathname, gatewayConfig.routes);
+        if (!route) {
+            res.writeHead(404, { 'content-type': 'application/json' });
+            res.end(JSON.stringify({ error: 'No matching route' }));
+            return;
+        }
+        const authHeader = getAuthHeader(req);
+        const jwtConfig = gatewayConfig.jwt;
+        const routeJwtOverride = route.jwt;
+        const shouldCheckJwt = !shouldBypassJwt(url.pathname, jwtConfig, routeJwtOverride);
+        if (jwtConfig?.enabled && shouldCheckJwt) {
+            if (!authHeader) {
+                if (jwtConfig.passthrough) {
+                    // allow unauthenticated request when passthrough is enabled
+                }
+                else {
+                    res.writeHead(401, { 'content-type': 'application/json' });
+                    res.end(JSON.stringify({ error: 'Missing bearer token' }));
+                    return;
+                }
+            }
+            else {
+                const [scheme, token] = authHeader.split(' ');
+                if (scheme?.toLowerCase() !== 'bearer' || !token) {
+                    res.writeHead(401, { 'content-type': 'application/json' });
+                    res.end(JSON.stringify({ error: 'Invalid authorization header' }));
+                    return;
+                }
+                const verification = verifyJwt(token, jwtConfig);
+                if (!verification.ok) {
+                    res.writeHead(401, { 'content-type': 'application/json' });
+                    res.end(JSON.stringify({ error: verification.reason ?? 'Invalid JWT' }));
+                    return;
+                }
+                const payload = verification.payload;
+                res.setHeader('x-gateway-user', payload?.sub ?? 'unknown');
+            }
+        }
+        const targetUrl = new URL(route.target);
+        await proxyRequest(req, res, targetUrl);
+    });
+    // ponytail: upgrade handler for Next.js HMR WebSocket — no JWT validation
+    server.on('upgrade', (req, socket, head) => {
+        // @ts-ignore
+        proxyUpgrade(req, socket, head, gatewayConfig.routes);
+    });
+    server.listen(port, host, () => {
+        console.log(`locagate listening on http://${host}:${port}`);
+    });
+}
+main().catch((error) => {
+    console.error(error);
+    process.exit(1);
+});

package/dist/jwt.js

@@ -0,0 +1,55 @@
+import { createHmac, timingSafeEqual } from 'node:crypto';
+function base64UrlDecode(value) {
+    const normalized = value.replace(/-/g, '+').replace(/_/g, '/');
+    const pad = normalized.length % 4;
+    const padded = pad ? normalized + '='.repeat(4 - pad) : normalized;
+    return Buffer.from(padded, 'base64');
+}
+function parseJwt(token) {
+    const parts = token.split('.');
+    if (parts.length !== 3)
+        return null;
+    try {
+        const header = JSON.parse(base64UrlDecode(parts[0]).toString('utf8'));
+        const payload = JSON.parse(base64UrlDecode(parts[1]).toString('utf8'));
+        return { header, payload };
+    }
+    catch {
+        return null;
+    }
+}
+function verifySignature(token, secret, algorithm) {
+    const [headerB64, payloadB64, signatureB64] = token.split('.');
+    if (!headerB64 || !payloadB64 || !signatureB64)
+        return false;
+    const signingInput = `${headerB64}.${payloadB64}`;
+    const expected = createHmac('sha256', secret).update(signingInput).digest();
+    const actual = Buffer.from(signatureB64.replace(/-/g, '+').replace(/_/g, '/'), 'base64');
+    if (actual.length !== expected.length)
+        return false;
+    return timingSafeEqual(expected, actual);
+}
+export function verifyJwt(token, jwtConfig) {
+    if (!jwtConfig.enabled || !jwtConfig.secret) {
+        return { ok: false, reason: 'jwt-disabled' };
+    }
+    const parsed = parseJwt(token);
+    if (!parsed) {
+        return { ok: false, reason: 'invalid-token' };
+    }
+    const { header, payload } = parsed;
+    if (!header || !payload) {
+        return { ok: false, reason: 'invalid-token' };
+    }
+    if (header.alg !== 'HS256') {
+        return { ok: false, reason: 'unsupported-algorithm' };
+    }
+    if (!verifySignature(token, jwtConfig.secret, header.alg)) {
+        return { ok: false, reason: 'signature-mismatch' };
+    }
+    const now = Math.floor(Date.now() / 1000);
+    if (payload.exp && payload.exp < now) {
+        return { ok: false, reason: 'token-expired' };
+    }
+    return { ok: true, payload };
+}

package/dist/router.js

@@ -0,0 +1,23 @@
+function normalizePattern(pattern) {
+    if (pattern === '*')
+        return '*';
+    if (pattern.endsWith('/*'))
+        return pattern.slice(0, -2);
+    return pattern;
+}
+export function matchRoute(pathname, routes) {
+    for (const route of routes) {
+        const match = route.match;
+        if (match === '*')
+            return route;
+        if (match.endsWith('/*')) {
+            const prefix = normalizePattern(match);
+            if (pathname === prefix || pathname.startsWith(prefix + '/'))
+                return route;
+            continue;
+        }
+        if (match.startsWith('/') && match === pathname)
+            return route;
+    }
+    return routes.find((route) => route.match === '/') || undefined;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/locagate.yaml.sample

@@ -0,0 +1,28 @@
+# locagate configuration — YAML
+# Point to this file with `node src/index.ts /path/to/locagate.yaml`
+# or place it in the working directory as locagate.yaml / locagate.yml.
+
+listen: "0.0.0.0:5000"
+
+# Optional JWT authentication
+jwt:
+  enabled: true
+  secret: "$JWT_SECRET"       # $VAR references are expanded from the environment
+  passthrough: false          # true = allow unauthenticated requests through
+  exclude:
+    - /health
+    - /
+    - /v1/identity/login
+    - /v1/identity/register
+
+# Route table — first match wins
+# TARGET_HOST defaults to localhost; set to another host to route elsewhere
+routes:
+  - match: "/v1/core/*"
+    target: "http://${TARGET_HOST:-localhost}:3000"
+  - match: "/v1/identity/*"
+    target: "http://${TARGET_HOST:-localhost}:3001"
+  - match: "/v1/notification/*"
+    target: "http://${TARGET_HOST:-localhost}:3002"
+  - match: "/*"
+    target: "http://${TARGET_HOST:-localhost}:3003"

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "locagate",
+  "version": "1.0.1",
+  "type": "module",
+  "description": "Tiny, file-configurable local API gateway — YAML config, prefix routing, optional JWT. Run with one command.",
+  "bin": {
+    "locagate": "./bin/locagate.js"
+  },
+  "scripts": {
+    "dev": "tsx src/index.ts",
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "files": [
+    "bin/",
+    "dist/",
+    "locagate.yaml.sample"
+  ],
+  "devDependencies": {
+    "@types/js-yaml": "^4.0.9",
+    "@types/node": "^22.10.1",
+    "tsx": "^4.23.0",
+    "typescript": "^6.0.3"
+  },
+  "dependencies": {
+    "dotenv": "^17.4.2",
+    "js-yaml": "^4.1.0"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  }
+}