portunus

README

PORTUNUS

Named after Portunus, the Roman god of keys, doors, and harbors — the guardian of gateways.

Point your base_url at PORTUNUS. Compliance is on.

"Compliance is on" means the controls are active — like "TLS is on." It does not mean your organization is compliant; see Compliance posture for the boundary.

PORTUNUS is an open-source, compliance-first AI gateway in Go — a single binary that sits between your applications and LLM providers and enforces reversible PII tokenization, security guards, and hash-linked, signed, offline-verifiable, framework-mapped audit logging on every call.

Demo: swap your base_url, send a prompt containing an email, and watch the upstream receive only <PII_EMAIL_1> while your client gets the real value back — then portunus audit tail shows the hash-linked, signed, framework-mapped evidence. (Animated terminal cast lands with the launch.)

Quickstart

No provider key required — the bundled stub upstream lets you watch the whole pipeline end-to-end on localhost:

git clone https://github.com/Spaceflow-Technologies-INC/portunus
cd portunus
./examples/quickstart/run.sh

That script tokenizes a PII-bearing request, detokenizes the response inside your boundary, and prints the audit evidence — verified offline with portunus audit verify.

To put PORTUNUS in front of a real provider, point your SDK at the gateway — the only change is the base_url:

from openai import OpenAI

client = OpenAI(base_url="http://localhost:8080/v1", api_key="prtns_…")  # your PORTUNUS client key
client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "email me at ann@example.com"}],
)
# The upstream provider sees <PII_EMAIL_1>, never ann@example.com.
# Your application gets the real value back, restored inside your boundary.

curl http://localhost:8080/v1/chat/completions \
  -H "Authorization: Bearer $PORTUNUS_API_KEY" \
  -d '{"model":"gpt-4o","messages":[{"role":"user","content":"email me at ann@example.com"}]}'

Then watch your audit trail — that's the point:

portunus audit tail      # recent events: metadata only, with the framework citations
portunus audit verify    # replay the hash chain + checkpoints offline; tamper-evident

v0.1 ships as a single binary and the CLI above; there is no web UI yet (the localhost console arrives with v0.2, per ADR-0003). A published container image is on the roadmap.

Why PORTUNUS

• Your provider should never see raw PII. Most teams send prompts straight to a third-party model. PORTUNUS tokenizes the PII it can structurally detect (IDs, IBANs, cards, emails, IPs, Bitcoin addresses) before dispatch and restores it after the response — the provider only ever handles neutral markers. (Free-text names and addresses need the NER engine on the roadmap; Features has the exact scope.)
• "We have logs" is not audit evidence. PORTUNUS records a hash-linked, signed, externally-anchorable event chain you can verify offline — metadata only, never prompt content or matched values.
• Compliance bolted on after the fact leaks. PORTUNUS starts from the compliance model: one policy engine, inspect-before-transform, fail-closed on the request path.
• One binary, your infrastructure. Go, no telemetry, no phone-home; the token vault and audit chain never leave your boundary.

Features

• Reversible PII tokenization — detects structurally-verifiable PII (Turkish TCKN/VKN, IBAN, credit cards, emails, IP addresses, Bitcoin addresses) — a precision, not recall, guarantee; free-text names and addresses (and GDPR Art. 9 / KVKK Art. 6 special-category data) need the NER engine on the roadmap. Detected values are conversation-scoped and tokenized; the provider sees <PII_TYPE_N> markers, responses are detokenized inside your boundary, and a marker-safe holdback detokenizer gives true pass-through streaming.
• Tamper-evident audit logging — hash-linked events with signed, externally-anchorable checkpoints; portunus audit verify proves integrity offline. Events carry metadata only.
• Toggleable compliance packs — GDPR and KVKK today (data-only YAML, each rule citing its framework references); more via community PRs.
• Prompt-injection guard — RE2/structural signals over Unicode-normalized input; monitor (flag) or enforce (block) mode.
• Provider adapters — OpenAI-compatible and native Anthropic; adapters are pure translation, with store:false forced upstream by default.
• Client authentication — bearer API keys (portunus auth keygen), peppered HMAC at rest.

How it differs

PORTUNUS is the compliance-first AI gateway: others bolt guardrails onto a routing/load-balancing product; PORTUNUS starts from the compliance model. A factual comparison (no benchmark claims):

	PORTUNUS	Typical AI gateway
Primary design goal	Compliance & auditability	Routing / cost / throughput
License	Apache 2.0	Mixed (some source-available)
Footprint	Single Go binary, self-hosted	Varies; often hosted/SaaS
PII handling	Reversible tokenization (checksum-validated)	One-way masking or none
Audit	Hash-linked, signed, framework-mapped, offline-verifiable	Basic request logs
Guardrails	Native policy engine	Delegated / bolt-on
Telemetry	None	Varies

Compliance posture

PORTUNUS provides technical controls and evidence mapped to named framework requirements. The compliance packs cite the specific articles each control supports — for example, the PII tokenization decision records:

• GDPR — Art. 5(1)(c) data minimisation · Art. 25(1) data protection by design · Art. 32(1)(a) pseudonymisation
• KVKK — Md. 4 genel ilkeler (data minimisation & proportionality) · Md. 12 veri güvenliği (data security measures)

These controls apply to the structurally-verifiable PII the detector recognizes (see Features); coverage of free-text PII — names, addresses, special-category data — arrives with the NER engine on the roadmap. The detector offers a precision, not recall, guarantee.

The framework citations shown are illustrative, pending independent legal review (the compliance map is versioned …-illustrative; see ADR-0018). Treat them as a starting point for your own assessment, not as authoritative legal mappings.

Disclaimer. PORTUNUS provides technical controls and evidence. It is not legal advice and does not by itself make your organization compliant.

Architecture

flowchart TB
    app(["Your app"])
    llm(["LLM provider"])

    subgraph boundary["Your boundary · one binary · vault & audit chain never leave"]
        direction TB
        auth["Client auth"] --> engine["Policy engine<br/>inspect → transform"]
        engine --> tok["PII tokenize<br/>vault, in-boundary"]
        tok --> adapter["Provider adapter<br/>store:false forced"]
        engine -.->|"every exchange,<br/>metadata only"| audit[("Audit chain<br/>signed · hash-linked")]
    end

    app -->|"base_url → PORTUNUS<br/>(OpenAI-compatible / Anthropic)"| auth
    adapter -->|"sees only &lt;PII_TYPE_N&gt; markers"| llm
    llm -.->|"response → detokenized in-boundary"| app

Everything runs inside your boundary; the token vault and audit chain never leave it. See docs/PLAN.md for the full design.

Documentation

Everything about this project is written down:

• docs/PLAN.md — the master decision map and build order.
• docs/adr/ — Architecture Decision Records: every significant decision, one file each.
• docs/research/ — the market/technical research behind the decisions (findings, never decisions).
• docs/specs/ — versioned byte-level format specs (auditor-facing).
• AGENTS.md — orientation for AI coding agents (and impatient humans).

Roadmap

⚠️ Pre-v1, under active development. Formats and APIs may change before v0.1 is tagged. Not yet recommended for production.

Working today: portunus serve proxies /v1/chat/completions (streaming and non-streaming) with reversible PII tokenization, the GDPR and KVKK packs, the prompt-injection guard, client authentication, OpenAI-compatible and native Anthropic adapters, and offline-verifiable audit logging. All foundational decisions are recorded as ADRs (docs/adr/).

Before v0.1: launch quickstart + demo, an independent external security/crypto review of the audit/vault/auth core, and the optional ONNX prompt-injection classifier (a build-tagged layer pending a dependency review).

Beyond v0.1: published container image, more compliance packs, data-residency routing, and the v0.2 localhost console. See docs/vision/roadmap.md.

Contributing

Contributions are welcome — data-only pack/preset PRs especially. By contributing you agree to the Developer Certificate of Origin (git commit -s). Start with AGENTS.md and docs/PLAN.md.

License

Apache 2.0 — see ADR-0002 for the reasoning.

Documentation

Overview

Package portunus is the exported root of the PORTUNUS module.

PORTUNUS is an open-source, compliance-first AI gateway. All implementation lives under internal/ (ADR-0009); this package deliberately exposes only build/version identity and, in the future, the Go embedding entry point. It must never grow business logic.

Index

• func Version() string
• func VersionString() string

Functions

func Version

func Version() string

Version reports the version string set at build time, or "dev" for non-release builds.

func VersionString

func VersionString() string

VersionString returns the full human-readable build identity, suitable for `portunus version` output and the audit log's gateway.version field (ADR-0007 envelope).