Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 5 additions & 3 deletions .github/workflows/release.yml
Original file line number Diff line number Diff line change
Expand Up @@ -87,9 +87,11 @@ jobs:
# CRITICAL blocks the release; HIGH is visible in the scan output but the
# Debian base image rotates packages too often to gate on it.
#
# The ignore file is passed explicitly: its YAML form (which supports an
# expiry date, so an exception cannot rot) is not auto-detected.
ignorefile: .trivyignore.yaml
# trivy-action's input is `trivyignores` (plural, comma-separated), not the
# CLI's `--ignorefile`; passing the wrong name is only a warning, so the scan
# silently ran without the exceptions. The YAML form is not auto-detected, so
# it has to be named explicitly.
trivyignores: .trivyignore.yaml
severity: CRITICAL
exit-code: "1"
ignore-unfixed: true
Expand Down
10 changes: 10 additions & 0 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -158,6 +158,16 @@ a smoke check. Never claim a fix without running both.
version — Central is immutable. After a `-P release` build the jar in `target/` is the
plain library, so rebuild before running the smoke suite.
- CI pins `ubuntu-26.04` (latest LTS) instead of `ubuntu-latest`; bump it deliberately.
- **The Dockerfile fetches Maven itself, not through `./mvnw`.** The wrapper shells out to
curl/unzip, which `eclipse-temurin` does not fully ship; inside the image it downloaded a
file that failed its own SHA-256 check and broke every container build. The build stage
installs those tools and verifies the pin from
`.mvn/wrapper/maven-wrapper.properties` explicitly. Do not "simplify" it back to `./mvnw`
without building the image.
- **`.trivyignore.yaml` must be passed to Trivy explicitly.** The YAML form (the one that
supports `expired_at`) is not auto-detected; the release workflow sets `ignorefile`. Every
entry carries a `statement` and a deadline, so an accepted CVE fails the gate again on
that date instead of living forever.
- **Every action is pinned to a commit SHA**, with the tag in a trailing comment
(`actions/checkout@3d3c42e5... # v7.0.1`). A mutable tag can be repointed at any commit,
which is exactly the supply-chain hole this closes. Bump by merging the Dependabot
Expand Down
1 change: 1 addition & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,7 @@ verbatim as the body of the matching GitHub release.

| Version | Date | Notes |
|---|---|---|
| v0.2.2 | 2026-11-17 | [changelog/v0.2.2.md](changelog/v0.2.2.md) |
| v0.2.1 | 2026-11-17 | [changelog/v0.2.1.md](changelog/v0.2.1.md) |
| v0.2.0 | 2026-11-17 | [changelog/v0.2.0.md](changelog/v0.2.0.md) |
| v0.1.0 | 2026-11-17 | [changelog/v0.1.0.md](changelog/v0.1.0.md) |
Expand Down
1 change: 1 addition & 0 deletions SECURITY.md
Original file line number Diff line number Diff line change
Expand Up @@ -36,6 +36,7 @@ Every pull request runs:
| Static analysis for Java | CodeQL |
| Secrets and misconfiguration in the tree | Trivy |
| Repointed action tags (every `uses:` is pinned to a commit SHA) | Dependabot + review |
| Accepted CVEs (`.trivyignore.yaml`, each with a statement and an expiry date) | release gate + review |
| Admin auth brute force (10 failures / 5 min per address) | built-in limiter |
| Unit, integration and end-to-end tests | Maven + the smoke suite |

Expand Down
111 changes: 111 additions & 0 deletions changelog/v0.2.2.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,111 @@
# v0.2.2

Supersedes `v0.2.0` and `v0.2.1`, neither of which completed: both pushed a container image
and then stopped at the vulnerability scan, so no GitHub release or notes were published
for either tag.

`v0.2.1` fixed the vulnerabilities; it failed because the workflow passed the Trivy ignore
file under the wrong input name (`ignorefile` instead of `trivyignores`), which the action
only warns about, so the scan ran without the exceptions and failed on the two accepted
CVEs.

Adds the dependency updates that scan demanded, and the workflow input that makes them
take effect. Everything else since the `v0.1.0` tag: the gateway gains a second routing strategy, guardrails,
an end-user billing axis, a semantic cache, Azure OpenAI and a Helm chart — plus the
fixes from a twelve-point security and billing audit.

## Added

### Routing and model selection

- **Adaptive routing.** A route can declare `strategy`: `priority` (the default, unchanged),
`fastest` (ordered by an exponentially weighted latency) or `cheapest-viable` (cheapest
route under a `latency_slo_ms`, the rest demoted to fallback). Route views expose
`ewma_latency_ms` and `ewma_error_rate` so the decision is auditable, and `provider.order`
still overrides any strategy.
- **Operator-defined aliases.** `GET/POST /admin/aliases` stores an ordered chain
(`prod-chat` → `claude-sonnet-4.5`, then `gpt-4o`). Chains are validated at write time —
an unknown model, a self-reference or more than ten hops is a 400, so a broken alias
cannot become a 500 on a customer request. The four computed aliases (`cheap`, `fast`,
`long-context`, `vision`) are unchanged.

### Billing and limits

- **End-user attribution.** `end_user` (or OpenAI's `user`) is stored on every usage row
and indexed, `/v1/usage` returns a per-end-user breakdown, `/admin/usage` and the CSV
export filter by it, and a key can cap each customer with `end_user_daily_limit_usd` —
reserved with an atomic conditional update, so concurrency cannot overshoot.
- **Project rate limits.** Projects carry `rpm_limit` and `max_concurrent_requests`,
enforced in addition to each key's caps, and shared across replicas through the Valkey
limiter.
- **Project budget alerts.** `project.budget_low` and `project.budget_exhausted` fire once
per project, window and period.
- **`POST /v1/tokens/count`.** Free but authenticated: reports prompt tokens and whether the
prompt fits, counting tool definitions, which is where estimates are usually wrong.
- **Idempotent embeddings.** `/v1/embeddings` honours `Idempotency-Key`; a retried batch is
no longer billed twice.

### Safety and privacy

- **Guardrails.** PII redaction for prompt logs (on by default) and optionally before send,
plus opt-in moderation passthrough that refuses a flagged prompt with 400
`content_flagged`. `GET /admin/settings` reports what is active.
- **Semantic cache tier.** With `semantic_cache_enabled` on a route and
`GATEWAY_SEMANTIC_MODEL` set, a near-duplicate prompt can reuse a stored completion,
under the same `temperature: 0`, tool-free, per-key rules as the exact cache.

### Providers and deployment

- **Azure OpenAI.** Setting `api_version` on a provider puts the deployment in the path, the
version in `?api-version` and the credential in the `api-key` header, for chat,
embeddings, moderation and the probe.
- **Helm chart** in `deploy/helm/path`: drain-aware grace period enforced at render time,
HPA with a custom-metric hook, PDB, optional Postgres and Valkey, ServiceMonitor.
- **Per-provider health** at `/actuator/health/providers`; overall health only reports
OUT_OF_SERVICE when every enabled provider is circuit-open.

## Fixed

The post-0.1.0 audit found twelve issues; all are fixed:

- `models/sync` imported unpriced routes enabled, serving inference for free.
- 500 responses returned internal exception messages; they now return a reference id and
log the detail server-side.
- Chunked request bodies bypassed the size limit; reading is now counted and 413s.
- The demo API key was created by default, including in the `prod` profile.
- A large `max_tokens` could reserve credit the call would never use.
- Reservation now uses the expected cost while still refusing when it does not fit.
- `/v3/api-docs` was served in production; off in the `prod` profile.
- The in-memory rate-limit windows were never evicted.
- Release tags were not verified to be on `main`.
- `UpstreamClient` allocated an `ObjectMapper` per error.
- Project filters were missing from `/admin/usage`, `/admin/stats` and the CSV export.
- Admin auth had no lockout; ten failures in five minutes now return 429.

Also fixed: the end-user cap was skipped for keys without a credit limit, and `api_version`
was ignored on provider `PATCH`.

## Security

- **Tomcat 10.1.55 → 10.1.62** and **Netty 4.1.135 → 4.1.141**, both of which Spring Boot
3.5.16 still pins and both of which carry CRITICAL advisories. Overridden in the pom
rather than by moving the framework version; drop the overrides when Boot manages them.
- **Two Spring Framework CVEs are accepted, with a deadline.** `CVE-2026-47884` (RCE via
`XsltView` path limitation) and `CVE-2026-47890` (SSE corruption during view rendering)
are fixed only in Spring Framework 7.0.9, which means Spring Boot 4. Path registers no
view resolver and renders nothing through a `View`, so neither path is reachable. They
are listed in `.trivyignore.yaml` with a `statement` and an `expired_at` of 2027-02-01,
after which the release gate fails again until they are revisited.

- Every GitHub Action is pinned to a commit SHA; a mutable tag can be repointed at any
commit and would run with this repository's token.
- Master key rotation (`POST /admin/rotate-master-key`) re-encrypts stored credentials
before switching the active key.

## Notes

- Maven Central publishing is configured (`-P release`, `io.github.an1ndra:path`) and
verified locally against a throwaway key; the upload itself is pending a namespace and a
Portal token. See `docs/PUBLISHING.md`.
- Five stories remain open: Spring AI module, Vertex/Gemini native, Valkey-shared breaker,
usage partitioning, and the Central publication.
4 changes: 2 additions & 2 deletions deploy/helm/path/Chart.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -2,8 +2,8 @@ apiVersion: v2
name: path
description: Path — a provider-agnostic LLM gateway with routing, fallback, credits and cache-aware token metering
type: application
version: 0.2.1
appVersion: "0.2.1"
version: 0.2.2
appVersion: "0.2.2"
kubeVersion: ">=1.27.0-0"
home: https://github.com/an1ndra/path
sources:
Expand Down
2 changes: 1 addition & 1 deletion pom.xml
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@

<groupId>io.github.an1ndra</groupId>
<artifactId>path</artifactId>
<version>0.2.1</version>
<version>0.2.2</version>
<name>path</name>
<description>Provider-agnostic LLM gateway: routing, fallback, credits and cache-aware token metering for OpenAI, Anthropic and any OpenAI-compatible API</description>
<url>https://github.com/an1ndra/path</url>
Expand Down
Loading