Harden Keryx architecture, runtime, and public repository

.env.example

@@ -1,38 +1,47 @@
 # Keryx AI Gateway — primer konfiguracije.
-# Kopirajte u `.env` i popunite. `.env` je u .gitignore i NE SME se commitovati.
+# Kopirajte u `.env`; fajl je ignorisan i nikada se ne commit-uje.
 
 # --- Server ---
-# Port na kojem Keryx sluša (default: 3000)
 PORT=3000
-# Host za bind (0.0.0.0 unutar kontejnera, 127.0.0.1 lokalno)
 HOST=0.0.0.0
-# Okruzenje: development | production
 NODE_ENV=development
-
-# --- Javni URL ---
-# Bazni URL pod kojim je Keryx dostupan spolja. Koristi se kao `servers.url`
-# u generisanoj OpenAPI šemi koju čita LLM. Bez trailing slash-a.
 PUBLIC_BASE_URL=http://localhost:3000
 
-# --- Bezbednost ---
-# Opcioni bearer token koji klijenti moraju poslati (Authorization: Bearer <token>).
-# Ostavite prazno da iskljucite autentifikaciju (samo za lokalni razvoj!).
+# --- Autentikacija ---
+# Produkcija odbija start ako je token kraći od 32 znaka.
+# Primer generisanja: openssl rand -base64 48
 KERYX_API_TOKEN=
 
-# --- CORS ---
-# Dozvoljeni CORS origini. `*` = svi origini (default).
-# Za produkciju, navedite dozvoljene domene razdvojene zarezom:
-#   KERYX_CORS_ORIGIN=https://example.com,https://app.example.com
-KERYX_CORS_ORIGIN=*
+# --- Browser CORS ---
+# Prazno = browser cross-origin zahtevi nisu dozvoljeni.
+# Više origin-a razdvojite zarezom. Wildcard je dozvoljen samo van produkcije.
+KERYX_CORS_ORIGIN=
+
+# --- MCP Streamable HTTP Origin zaštita ---
+# Prazno = dozvoljen je samo origin izveden iz PUBLIC_BASE_URL.
+# Dodajte druge pouzdane browser origine samo kada su zaista potrebni.
+KERYX_MCP_ALLOWED_ORIGINS=
+
+# --- Reverse proxy i limits ---
+# 0 kada je Keryx direktno izložen; obično 1 iza jednog Caddy/Nginx/Traefik proxy-ja.
+KERYX_TRUST_PROXY=0
+KERYX_RATE_LIMIT_WINDOW_MS=60000
+KERYX_RATE_LIMIT_MAX=100
+KERYX_JSON_LIMIT=1mb
 
 # --- Legacy modul (Siri Shortcuts) ---
-# Koliko dugo (ms) generisana prečica ostaje dostupna za preuzimanje (default: 600000 = 10 min).
 KERYX_SHORTCUT_TTL_MS=600000
-# Maksimalan broj prečica u memoriji. Kada se dostigne, najstarija se briše (default: 1000).
 KERYX_SHORTCUT_STORE_MAX=1000
 
-# --- site_stats alat (opciona integracija sa eksternim sajtom) ---
-# URL endpointa koji vraća statistiku sajta kao JSON (poziva se sa ?format=json).
-# Ako je prazno, alat `site_stats` se NE registruje. Token se ne podešava ovde —
-# alat je "forward" i prosleđuje caller token tom endpointu (scope na izvoru).
+# --- Upstream zaštita ---
+# Najveća veličina JSON odgovora sa SITE_STATS_URL.
+KERYX_UPSTREAM_MAX_BYTES=1000000
+
+# Opciono. U produkciji mora biti HTTPS.
+# Caller bearer se prosleđuje direktno ovom endpointu; redirecti nisu dozvoljeni.
 SITE_STATS_URL=
+
+# --- Docker Compose host bind ---
+# Podrazumevano je 127.0.0.1, što je preporučeno kada ispred stoji reverse proxy.
+# Postavite 0.0.0.0 samo ako svesno želite direktan LAN/WAN pristup portu.
+KERYX_BIND_ADDRESS=127.0.0.1

.github/CODEOWNERS

@@ -0,0 +1,14 @@
+# Default owner
+* @vladimirperovic
+
+# Security-sensitive areas
+/src/core/ @vladimirperovic
+/src/config/ @vladimirperovic
+/src/modules/nextgen/mcp.ts @vladimirperovic
+/src/modules/legacy/ @vladimirperovic
+/.github/workflows/ @vladimirperovic
+/Dockerfile @vladimirperovic
+/docker-compose.yml @vladimirperovic
+/SECURITY.md @vladimirperovic
+/SECURITY_ARCHITECTURE.md @vladimirperovic
+/THREAT_MODEL.md @vladimirperovic

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,60 @@
+name: Bug report
+description: Report a reproducible problem in Keryx
+title: "[Bug]: "
+labels: [bug, triage]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Do not report vulnerabilities here. Follow SECURITY.md for private reporting.
+  - type: input
+    id: version
+    attributes:
+      label: Keryx version or commit
+      placeholder: v0.1.1 or commit SHA
+    validations:
+      required: true
+  - type: dropdown
+    id: deployment
+    attributes:
+      label: Deployment
+      options:
+        - Docker Compose
+        - Docker
+        - Local Node.js
+        - Other
+    validations:
+      required: true
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected behavior
+    validations:
+      required: true
+  - type: textarea
+    id: actual
+    attributes:
+      label: Actual behavior
+    validations:
+      required: true
+  - type: textarea
+    id: reproduce
+    attributes:
+      label: Reproduction steps
+      description: Remove tokens, private URLs, and personal data from logs and examples.
+    validations:
+      required: true
+  - type: textarea
+    id: logs
+    attributes:
+      label: Sanitized logs
+      render: shell
+  - type: checkboxes
+    id: checks
+    attributes:
+      label: Checklist
+      options:
+        - label: I removed secrets and personal data.
+          required: true
+        - label: I searched existing issues.
+          required: true

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,8 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Security vulnerability
+    url: https://github.com/vladimirperovic/keryx/security/policy
+    about: Report vulnerabilities privately; do not open a public issue.
+  - name: Support and usage questions
+    url: https://github.com/vladimirperovic/keryx/discussions
+    about: Ask deployment and integration questions in Discussions when enabled.

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,44 @@
+name: Feature request
+description: Propose a focused improvement or a new gateway tool
+title: "[Feature]: "
+labels: [enhancement, triage]
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem to solve
+      description: Describe the user or operator problem, not only the proposed implementation.
+    validations:
+      required: true
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposed solution
+    validations:
+      required: true
+  - type: dropdown
+    id: area
+    attributes:
+      label: Area
+      options:
+        - MCP
+        - OpenAPI or REST
+        - Siri Shortcuts
+        - Authentication or security
+        - Deployment or Docker
+        - Documentation
+        - Other
+    validations:
+      required: true
+  - type: textarea
+    id: security
+    attributes:
+      label: Security and compatibility considerations
+      description: Mention token scope, upstream access, breaking changes, or new dependencies.
+  - type: checkboxes
+    id: checks
+    attributes:
+      label: Checklist
+      options:
+        - label: I searched existing issues and the roadmap.
+          required: true

.github/PULL_REQUEST_TEMPLATE.md

@@ -1,22 +1,33 @@
-## What & why
+## Summary
 
-Briefly describe the change and the motivation.
+Describe the change and the problem it solves.
 
 ## Type of change
 
 - [ ] Bug fix
-- [ ] New feature / tool
-- [ ] Docs
-- [ ] Refactor / chore
+- [ ] New feature or tool
+- [ ] Security hardening
+- [ ] Documentation
+- [ ] Refactor or maintenance
+
+## Security impact
+
+- [ ] No authentication, authorization, token-forwarding, network, or secret-handling changes
+- [ ] Security-sensitive behavior changed and is explained below
+
+## Validation
+
+- [ ] `npm run check`
+- [ ] Docker image builds
+- [ ] Tests cover new or changed behavior
+- [ ] `README.md` and `.env.example` are updated when configuration changed
 
 ## Checklist
 
-- [ ] `npm run typecheck` passes
-- [ ] `npm run build` passes
-- [ ] `npm test` passes
-- [ ] Updated `README.md` / `.env.example` if behaviour or config changed
-- [ ] No secrets committed
+- [ ] The diff is focused and compatibility implications are documented
+- [ ] No secrets, private endpoints, personal data, or production tokens are included
+- [ ] New tools validate all input and use the correct auth model
 
 ## Notes for reviewers
 
-Anything specific you'd like feedback on.
+Call out the highest-risk part of the change and any follow-up work.

.github/dependabot.yml

@@ -0,0 +1,36 @@
+version: 2
+
+updates:
+  - package-ecosystem: npm
+    directory: /
+    schedule:
+      interval: weekly
+      day: monday
+      time: "08:00"
+      timezone: Europe/Belgrade
+    open-pull-requests-limit: 5
+    groups:
+      production-dependencies:
+        dependency-type: production
+      development-dependencies:
+        dependency-type: development
+
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly
+      day: monday
+      time: "08:15"
+      timezone: Europe/Belgrade
+    groups:
+      github-actions:
+        patterns:
+          - "*"
+
+  - package-ecosystem: docker
+    directory: /
+    schedule:
+      interval: weekly
+      day: monday
+      time: "08:30"
+      timezone: Europe/Belgrade

.github/workflows/ci.yml

@@ -5,19 +5,51 @@ on:
     branches: [main]
   pull_request:
 
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
 jobs:
   build:
+    # Keep the historical check names required by the existing main-branch rule,
+    # while mapping them to maintained Node.js runtimes.
+    name: build (${{ matrix.required_context }})
     runs-on: ubuntu-latest
+    timeout-minutes: 10
     strategy:
+      fail-fast: false
       matrix:
-        node: [20, 22]
+        include:
+          - required_context: 20
+            node: 22
+          - required_context: 22
+            node: 24
     steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
+      - name: Checkout
+        uses: actions/checkout@v6
+      - name: Setup Node ${{ matrix.node }}
+        uses: actions/setup-node@v5
         with:
           node-version: ${{ matrix.node }}
           cache: npm
-      - run: npm ci
-      - run: npm run typecheck
-      - run: npm run build
-      - run: npm test
+      - name: Install
+        run: npm ci
+      - name: Typecheck, build and test
+        run: npm run check
+      - name: Audit production dependencies
+        run: npm audit --omit=dev --audit-level=high
+
+  docker:
+    name: Docker and Compose
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+      - name: Validate Compose configuration
+        run: docker compose config
+      - name: Build image
+        run: docker build --tag keryx:ci .

.github/workflows/codeql.yml

@@ -0,0 +1,31 @@
+name: CodeQL
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  schedule:
+    - cron: "17 4 * * 1"
+
+permissions:
+  contents: read
+  security-events: write
+
+jobs:
+  analyze:
+    name: Analyze JavaScript and TypeScript
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+      - name: Initialize CodeQL
+        uses: github/codeql-action/init@v4
+        with:
+          languages: javascript-typescript
+          queries: security-extended
+      - name: Autobuild
+        uses: github/codeql-action/autobuild@v4
+      - name: Analyze
+        uses: github/codeql-action/analyze@v4