chore(changelog): update changelog for v0.5.0

- Change the default `LT_SERVER_PORT` from 8010 to 8081 in usage examples
- Reflect the updated port in the environment variables table

.gitea/workflows/build-nightly.yml

@@ -43,7 +43,7 @@ jobs:
           CREATED=$(date -u +%Y-%m-%dT%H:%M:%SZ)
           VERSION_TAG=nightly-$(date +%Y%m%d)
           docker buildx build \
-            --tag git.0xmax42.io/simdev/lt-auth-proxy:nightly \
+            --tag git.0xmax42.io/maxp/lt-auth-proxy:nightly \
             --platform linux/amd64,linux/arm64 \
             --label org.opencontainers.image.description="Lightweight LanguageTool Auth Proxy" \
             --label org.opencontainers.image.documentation="https://git.0xmax42.io/maxp/lt-auth-proxy" \

.gitea/workflows/build-release.yml

@@ -63,8 +63,8 @@ jobs:
       - name: Build Docker Image
         run: |
           docker buildx build \
-            --tag git.0xmax42.io/simdev/lt-auth-proxy:${{ steps.version.outputs.VERSION_STRIPPED }} \
-            --tag git.0xmax42.io/simdev/lt-auth-proxy:latest \
+            --tag git.0xmax42.io/maxp/lt-auth-proxy:${{ steps.version.outputs.VERSION_STRIPPED }} \
+            --tag git.0xmax42.io/maxp/lt-auth-proxy:latest \
             --label org.opencontainers.image.description="Lightweight LanguageTool Auth Proxy" \
             --label org.opencontainers.image.documentation="https://git.0xmax42.io/maxp/lt-auth-proxy" \
             --label org.opencontainers.image.authors="0xMax42 <mail@0xmax42.io>" \

CHANGELOG.md

@@ -2,6 +2,63 @@
 
 All notable changes to this project will be documented in this file.
 
+## [0.5.0](https://git.0xmax42.io/maxp/lt-auth-proxy/compare/v0.4.0..v0.5.0) - 2025-05-11
+
+### 🚀 Features
+
+- *(env)* Update default LanguageTool server port to 8081 - ([f15cfec](https://git.0xmax42.io/maxp/lt-auth-proxy/commit/f15cfec74f9fb8325e90c7acc40ff7a166b9f9df))
+
+### 📚 Documentation
+
+- Update LanguageTool backend port in README - ([9d902dc](https://git.0xmax42.io/maxp/lt-auth-proxy/commit/9d902dce55f12d274d3b9bd75cc3d3b0f75384c6))
+- *(readme)* Update service configuration and license link - ([427cee1](https://git.0xmax42.io/maxp/lt-auth-proxy/commit/427cee188404b00ec30c8f52f4a66c4609511a8f))
+- *(readme)* Update service configuration and license link - ([92b075d](https://git.0xmax42.io/maxp/lt-auth-proxy/commit/92b075df558d2d52da9496f74f84c149d3b18df5))
+- *(readme)* Add project time badge - ([5597c2a](https://git.0xmax42.io/maxp/lt-auth-proxy/commit/5597c2ae3fa3920340499e0b5924b75352591729))
+
+## [0.4.0](https://git.0xmax42.io/maxp/lt-auth-proxy/compare/v0.3.0..v0.4.0) - 2025-05-11
+
+### 🚀 Features
+
+- *(server)* Add graceful shutdown handling - ([d57cc27](https://git.0xmax42.io/maxp/lt-auth-proxy/commit/d57cc27e19e68c13ac08af223c3721a9c45fafd1))
+
+## [0.3.0](https://git.0xmax42.io/maxp/lt-auth-proxy/compare/v0.2.1..v0.3.0) - 2025-05-11
+
+### 🚀 Features
+
+- *(logging)* Add debug logs for key validation and request handling - ([3299419](https://git.0xmax42.io/maxp/lt-auth-proxy/commit/32994197261e9ab5a46df5f90f2faed89cd68558))
+- *(utils)* Add utility to mask API keys - ([79dfbcf](https://git.0xmax42.io/maxp/lt-auth-proxy/commit/79dfbcf053d613fe3fff63bfd24537a1665c9389))
+
+## [0.2.1](https://git.0xmax42.io/maxp/lt-auth-proxy/compare/v0.1.1..v0.2.1) - 2025-05-11
+
+### 🚀 Features
+
+- *(handler)* Sanitize sensitive fields in form data - ([b6763f7](https://git.0xmax42.io/maxp/lt-auth-proxy/commit/b6763f748325bf9c4129c5230c5e8101f93a2388))
+
+### 🐛 Bug Fixes
+
+- *(auth)* Validate API key from POST body and handle content type - ([4326a2d](https://git.0xmax42.io/maxp/lt-auth-proxy/commit/4326a2d92cb789b8bbed95d9e72b5cbadbafd93a))
+
+### 🚜 Refactor
+
+- *(dockerfile)* Update runtime base image to alpine:latest - ([ec18f7b](https://git.0xmax42.io/maxp/lt-auth-proxy/commit/ec18f7b4e39bbfa88ba23ef3fdf825917ac5303b))
+
+### 📚 Documentation
+
+- *(readme)* Update Docker image size information - ([828494c](https://git.0xmax42.io/maxp/lt-auth-proxy/commit/828494c92a3d517a35f2feece48af5cd6116f1d4))
+- *(readme)* Enhance documentation with usage and features - ([573fcf0](https://git.0xmax42.io/maxp/lt-auth-proxy/commit/573fcf0e65b3446b7efdce6b1695722c9d757410))
+
+### ⚙️ Miscellaneous Tasks
+
+- *(dockerfile)* Switch base image to debian and update curl setup - ([60dcc30](https://git.0xmax42.io/maxp/lt-auth-proxy/commit/60dcc30c0d9bad5dc9c0b1e4f79a4cb53330a965))
+- *(readme)* Update image repository URL - ([7ea8e26](https://git.0xmax42.io/maxp/lt-auth-proxy/commit/7ea8e26660b9c29ead8f5597647a96c27cc9dcb5))
+- *(workflows)* Rename build-docker.yml to build-nightly.yml - ([787bcdc](https://git.0xmax42.io/maxp/lt-auth-proxy/commit/787bcdc1a20e85699b810082895d2a461216c9cf))
+
+## [0.1.1](https://git.0xmax42.io/maxp/lt-auth-proxy/compare/v0.1.0..v0.1.1) - 2025-05-10
+
+### ⚙️ Miscellaneous Tasks
+
+- *(workflows)* Update Docker image repository path - ([f931e87](https://git.0xmax42.io/maxp/lt-auth-proxy/commit/f931e876f9d99c40a29f9aca8626af22b9f0772e))
+
 ## [0.1.0] - 2025-05-10
 
 ### 🚀 Features

Dockerfile

@@ -14,10 +14,12 @@ COPY import_map.json ./import_map.json
 RUN deno task compile
 
 # -------- Stage 2: Minimal runtime environment --------
-FROM denoland/deno:alpine
+FROM debian:bookworm-slim
 
-# Optional: Install curl for container-level health checks (not needed for production-only binaries)
-RUN apk add --no-cache curl
+# Optional: Install curl for container-level health checks
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends curl \
+    && rm -rf /var/lib/apt/lists/*
 
 # Copy only the compiled application binary from the builder stage
 COPY --from=builder /app/app /app/app

README.md

@@ -1,3 +1,91 @@
 # lt-auth-proxy
 
-Language Tool authentication proxy
+![Project Time](https://waka.0xmax42.io/api/badge/0XMax42/interval:today/project:lt-auth-proxy?label=Project%20Time)
+
+A lightweight, production-ready reverse proxy for [LanguageTool](https://languagetool.org) with API key authentication.
+
+This service acts as a transparent gateway that verifies an `apiKey` before forwarding requests to a running LanguageTool server instance. It is fully self-contained, built in Deno, and distributed as a minimal multi-architecture Docker image.
+
+---
+
+## ✨ Features
+
+* 🔐 **API key authentication** via query or form body
+* 📡 **Transparent proxying** to any LanguageTool backend
+* 🐳 **Minimal Docker image (\~166 MB)**
+* 🧱 **Statically compiled** Deno binary
+* 🧪 **Unit tested** middleware and proxy logic
+* 🛠️ Compatible with regular LT clients
+
+---
+
+## 🚀 Usage
+
+You can run the proxy via Docker:
+
+```bash
+docker run -p 8011:8011 \
+  -e API_KEYS="demo-key,another-key" \
+  -e LT_SERVER_HOST=lt-server \
+  -e LT_SERVER_PORT=8081 \
+  git.0xmax42.io/simdev/lt-auth-proxy:latest
+```
+
+---
+
+## 🧪 Supported Environment Variables
+
+| Variable         | Required | Default     | Description                              |
+| ---------------- | -------- | ----------- | ---------------------------------------- |
+| `API_KEYS`       | ✅ yes    | –           | Comma-separated list of valid API tokens |
+| `PROXY_HOST`     | ❌ no     | `0.0.0.0`   | Host/IP address to bind the proxy to     |
+| `PROXY_PORT`     | ❌ no     | `8011`      | Port the proxy listens on                |
+| `LT_SERVER_HOST` | ❌ no     | `localhost` | Hostname of the LanguageTool backend     |
+| `LT_SERVER_PORT` | ❌ no     | `8081`      | Port of the LanguageTool backend         |
+
+---
+
+## 📁 File Structure
+
+```
+src/
+├── main.ts          # Entry point, sets up the HTTP kernel
+├── env.ts           # Lazy-loaded environment access
+├── ltProxyAuth.ts   # Middleware to check the apiKey
+├── ltProxyHandler.ts# Handler to forward the request to LT
+```
+
+---
+
+## 🐳 Docker Compose Example
+
+```yaml
+services:
+  lt-server:
+    image: meyay/languagetool:latest
+    restart: unless-stopped
+    user: "783:783"
+    networks:
+      - default
+
+  proxy:
+    image: git.0xmax42.io/maxp/lt-auth-proxy:latest
+    ports:
+      - "8011:8011"
+    environment:
+      - API_KEYS=demo-key,another-key
+      - LT_SERVER_HOST=lt-server
+      - LT_SERVER_PORT=8081
+```
+
+Please note that this setup does not include SSL encryption. A reverse proxy such as Traefik should be used for this.
+
+---
+
+## 📖 License
+
+[MIT © 0xMax42](./LICENSE)
+
+---
+
+[https://git.0xmax42.io/maxp/lt-auth-proxy](https://git.0xmax42.io/maxp/lt-auth-proxy)

VERSION

@@ -1 +1 @@
-0.1.0
+0.5.0

src/__tests__/ltProxyAuth.test.ts

@@ -6,11 +6,19 @@ import { ltProxyAuth } from '../ltProxyAuth.ts';
 Deno.test('ltProxyAuth: accepts valid API key', async () => {
     Deno.env.set('API_KEYS', 'valid123');
 
-    const req = new Request('http://localhost/?apiKey=valid123');
+    const body = new URLSearchParams({ apiKey: 'valid123' });
+    const req = new Request('http://localhost/', {
+        method: 'POST',
+        headers: {
+            'content-type': 'application/x-www-form-urlencoded',
+        },
+        body,
+    });
+
     const ctx: IContext = {
         req,
         params: {},
-        query: { apiKey: 'valid123' },
+        query: {},
         state: {},
     };
 
@@ -26,11 +34,19 @@ Deno.test('ltProxyAuth: accepts valid API key', async () => {
 Deno.test('ltProxyAuth: rejects invalid API key', async () => {
     Deno.env.set('API_KEYS', 'valid123');
 
-    const req = new Request('http://localhost/?apiKey=invalid456');
+    const body = new URLSearchParams({ apiKey: 'invalid456' });
+    const req = new Request('http://localhost/', {
+        method: 'POST',
+        headers: {
+            'content-type': 'application/x-www-form-urlencoded',
+        },
+        body,
+    });
+
     const ctx: IContext = {
         req,
         params: {},
-        query: { apiKey: 'invalid456' },
+        query: {},
         state: {},
     };
 
@@ -46,7 +62,15 @@ Deno.test('ltProxyAuth: rejects invalid API key', async () => {
 Deno.test('ltProxyAuth: rejects missing API key', async () => {
     Deno.env.set('API_KEYS', 'valid123');
 
-    const req = new Request('http://localhost/');
+    const body = new URLSearchParams({ text: 'nur text ohne apiKey' });
+    const req = new Request('http://localhost/', {
+        method: 'POST',
+        headers: {
+            'content-type': 'application/x-www-form-urlencoded',
+        },
+        body,
+    });
+
     const ctx: IContext = {
         req,
         params: {},
@@ -60,4 +84,5 @@ Deno.test('ltProxyAuth: rejects missing API key', async () => {
     );
 
     assertEquals(response.status, 403);
+    assertEquals(await response.text(), 'Forbidden – Invalid API key');
 });

src/__tests__/ltProxyHandler.test.ts

@@ -16,12 +16,16 @@ Deno.test('ltProxyHandler: proxies request and returns response', async () => {
     const originalFetch = globalThis.fetch;
     globalThis.fetch = async () => expectedResponse;
 
+    // Form body wie bei echtem Request
+    const formData = new URLSearchParams({ text: 'Hallo Welt' });
+    const bodyBytes = new TextEncoder().encode(formData.toString());
+
     const req = new Request('http://localhost/v2/check?language=de-DE', {
         method: 'POST',
-        body: new TextEncoder().encode('text=Hallo+Welt'),
         headers: {
             'content-type': 'application/x-www-form-urlencoded',
         },
+        body: bodyBytes,
     });
 
     const ctx: IContext = {
@@ -30,7 +34,9 @@ Deno.test('ltProxyHandler: proxies request and returns response', async () => {
         query: {
             language: 'de-DE',
         },
-        state: {},
+        state: {
+            body: bodyBytes,
+        },
     };
 
     const response = await ltProxyHandler(ctx);

src/env.ts

@@ -53,10 +53,10 @@ export class Env {
         return this._ltServerHost;
     }
 
-    /** Port of the LanguageTool backend (default: 8010) */
+    /** Port of the LanguageTool backend (default: 8081) */
     static get ltServerPort(): number {
         if (this._ltServerPort === undefined) {
-            this._ltServerPort = Number(this.getEnv('LT_SERVER_PORT') || 8010);
+            this._ltServerPort = Number(this.getEnv('LT_SERVER_PORT') || 8081);
         }
         return this._ltServerPort;
     }

src/ltProxyAuth.ts

@@ -1,20 +1,32 @@
 import { Middleware } from 'http-kernel/Types/mod.ts';
 import { Env } from './env.ts';
+import { maskApiKey } from './utils.ts';
 
 /**
- * Middleware that checks for a valid API key via ?apiKey=... query/form param.
- * Rejects request with 403 if the key is missing or invalid.
+ * Middleware that checks for a valid API key via form param.
+ * Also stores the body in ctx.state.body for later use.
  */
 export const authMiddleware: Middleware = async (ctx, next) => {
-    const key = ctx.query.apiKey;
+    const contentType = ctx.req.headers.get('content-type') || '';
 
-    // Support both ?apiKey=... and form body with apiKey=...
-    const extractedKey = Array.isArray(key) ? key[0] : key;
+    if (contentType.includes('application/x-www-form-urlencoded')) {
+        const bodyBuffer = await ctx.req.arrayBuffer();
+        ctx.state.body = new Uint8Array(bodyBuffer);
 
-    if (!extractedKey || !Env.apiKeys.includes(extractedKey)) {
-        return new Response('Forbidden – Invalid API key', { status: 403 });
+        const text = new TextDecoder().decode(ctx.state.body as Uint8Array);
+        const params = new URLSearchParams(text);
+        const key = params.get('apiKey');
+
+        if (!key || !Env.apiKeys.includes(key)) {
+            console.debug('Invalid API key:', maskApiKey(key));
+            return new Response('Forbidden – Invalid API key', { status: 403 });
+        }
+    } else {
+        console.debug('Unsupported content type:', contentType);
+        return new Response('Unsupported content type', { status: 415 });
     }
 
+    console.debug('Valid API key:', maskApiKey(ctx.req.headers.get('apiKey')));
     return await next();
 };
 

src/ltProxyHandler.ts

@@ -4,6 +4,7 @@ import { Env } from './env.ts';
 /**
  * Forwards the incoming request to the actual LanguageTool server.
  * Dynamically passes through path and query string.
+ * Removes `username` and `apiKey` from the FormData body if present.
  */
 export const handler: Handler = async (ctx) => {
     const originalUrl = new URL(ctx.req.url);
@@ -12,16 +13,44 @@ export const handler: Handler = async (ctx) => {
         `http://${Env.ltServerHost}:${Env.ltServerPort}`,
     );
 
+    const contentType = ctx.req.headers.get('content-type') ?? '';
+    let body: BodyInit | null = null;
+
+    if (
+        contentType.includes('application/x-www-form-urlencoded') &&
+        ctx.state.body
+    ) {
+        const text = new TextDecoder().decode(ctx.state.body as Uint8Array);
+        const params = new URLSearchParams(text);
+
+        // Remove `apiKey` and `username` from the params
+        // LanguageTool will react with a error if they are present
+        params.delete('apiKey');
+        params.delete('username');
+
+        body = params.toString();
+    } else {
+        console.debug('Unsupported content type:', contentType);
+        body = ctx.state.body as BodyInit | null;
+    }
+
+    const headers = new Headers(ctx.req.headers);
+    headers.delete('content-length');
+
+    console.debug('Forwarding request to:', proxyUrl.toString());
+
     const forwarded = await fetch(proxyUrl.toString(), {
         method: ctx.req.method,
-        headers: ctx.req.headers,
-        body: ctx.req.body,
+        headers,
+        body,
     });
 
-    const headers = new Headers(forwarded.headers);
+    console.debug('Received response from LT server:', forwarded.status);
+
+    const respHeaders = new Headers(forwarded.headers);
     return new Response(forwarded.body, {
         status: forwarded.status,
-        headers,
+        headers: respHeaders,
     });
 };
 

src/main.ts

@@ -3,6 +3,7 @@ import { Env } from './env.ts';
 import { ltProxyAuth } from './ltProxyAuth.ts';
 import { ltProxyHandler } from './ltProxyHandler.ts';
 
+const ac = new AbortController();
 const httpKernel = new HttpKernel();
 
 httpKernel.route({
@@ -11,9 +12,19 @@ httpKernel.route({
 }).middleware(ltProxyAuth).handle(ltProxyHandler);
 
 Deno.serve({
+    signal: ac.signal,
     port: Env.proxyPort,
     hostname: Env.proxyHost,
     onListen: ({ hostname, port }) => {
         console.info(`lt-auth-proxy listening on ${hostname}:${port}`);
     },
 }, async (req) => await httpKernel.handle(req));
+
+const shutdown = () => {
+    console.info('Shutting down the server...');
+    ac.abort();
+    console.info('Server shut down successfully.');
+};
+
+Deno.addSignalListener('SIGINT', shutdown);
+Deno.addSignalListener('SIGTERM', shutdown);

src/utils.ts

@@ -0,0 +1,6 @@
+export const maskApiKey = (key: string | null): string => {
+    if (!key) return '*****';
+    return key.length <= 5
+        ? '*'.repeat(key.length)
+        : key.slice(0, 5) + '*'.repeat(key.length - 5);
+};