aliasgate 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (139) hide show
  1. aliasgate-0.1.0/.dockerignore +10 -0
  2. aliasgate-0.1.0/.github/workflows/ci.yml +34 -0
  3. aliasgate-0.1.0/.github/workflows/release.yml +148 -0
  4. aliasgate-0.1.0/.gitignore +23 -0
  5. aliasgate-0.1.0/.python-version +1 -0
  6. aliasgate-0.1.0/AGENTS.md +88 -0
  7. aliasgate-0.1.0/CHANGELOG.md +40 -0
  8. aliasgate-0.1.0/CLAUDE.md +1 -0
  9. aliasgate-0.1.0/CONTRIBUTING.md +52 -0
  10. aliasgate-0.1.0/Dockerfile +68 -0
  11. aliasgate-0.1.0/LICENSE +202 -0
  12. aliasgate-0.1.0/PKG-INFO +151 -0
  13. aliasgate-0.1.0/README.md +118 -0
  14. aliasgate-0.1.0/SECURITY.md +27 -0
  15. aliasgate-0.1.0/docs/architecture.md +445 -0
  16. aliasgate-0.1.0/docs/deployment.md +117 -0
  17. aliasgate-0.1.0/docs/evaluation.md +187 -0
  18. aliasgate-0.1.0/docs/plan/README.md +81 -0
  19. aliasgate-0.1.0/docs/plan/backlog.md +151 -0
  20. aliasgate-0.1.0/docs/plan/slice-01-core-types.md +187 -0
  21. aliasgate-0.1.0/docs/plan/slice-02-rule-detectors.md +178 -0
  22. aliasgate-0.1.0/docs/plan/slice-03-engine.md +180 -0
  23. aliasgate-0.1.0/docs/plan/slice-04-config-and-dictionary.md +249 -0
  24. aliasgate-0.1.0/docs/plan/slice-05-openai-chat-dialect.md +213 -0
  25. aliasgate-0.1.0/docs/plan/slice-06-http-proxy.md +221 -0
  26. aliasgate-0.1.0/docs/plan/slice-07-streaming.md +233 -0
  27. aliasgate-0.1.0/docs/plan/slice-08-anthropic-dialect.md +240 -0
  28. aliasgate-0.1.0/docs/plan/slice-09-ml-detector.md +276 -0
  29. aliasgate-0.1.0/docs/plan/slice-10-audit-policy-metrics.md +241 -0
  30. aliasgate-0.1.0/docs/plan/slice-11-evaluation.md +246 -0
  31. aliasgate-0.1.0/docs/plan/slice-12-cli-docker-release.md +277 -0
  32. aliasgate-0.1.0/docs/state-of-the-art.md +212 -0
  33. aliasgate-0.1.0/docs/threat-model.md +63 -0
  34. aliasgate-0.1.0/docs/usage.md +492 -0
  35. aliasgate-0.1.0/examples/aliasgate.example.yaml +82 -0
  36. aliasgate-0.1.0/examples/anthropic_client.py +59 -0
  37. aliasgate-0.1.0/examples/dictionary.example.yaml +13 -0
  38. aliasgate-0.1.0/examples/docker-compose.yaml +27 -0
  39. aliasgate-0.1.0/examples/openai_client.py +70 -0
  40. aliasgate-0.1.0/pyproject.toml +113 -0
  41. aliasgate-0.1.0/src/aliasgate/__init__.py +5 -0
  42. aliasgate-0.1.0/src/aliasgate/__main__.py +8 -0
  43. aliasgate-0.1.0/src/aliasgate/audit.py +84 -0
  44. aliasgate-0.1.0/src/aliasgate/cli.py +321 -0
  45. aliasgate-0.1.0/src/aliasgate/config.py +367 -0
  46. aliasgate-0.1.0/src/aliasgate/detectors/__init__.py +1 -0
  47. aliasgate-0.1.0/src/aliasgate/detectors/cache.py +57 -0
  48. aliasgate-0.1.0/src/aliasgate/detectors/checksums.py +88 -0
  49. aliasgate-0.1.0/src/aliasgate/detectors/chunking.py +44 -0
  50. aliasgate-0.1.0/src/aliasgate/detectors/dictionary.py +96 -0
  51. aliasgate-0.1.0/src/aliasgate/detectors/gliner.py +195 -0
  52. aliasgate-0.1.0/src/aliasgate/detectors/literal.py +17 -0
  53. aliasgate-0.1.0/src/aliasgate/detectors/rules.py +318 -0
  54. aliasgate-0.1.0/src/aliasgate/dialects/__init__.py +1 -0
  55. aliasgate-0.1.0/src/aliasgate/dialects/anthropic_messages.py +329 -0
  56. aliasgate-0.1.0/src/aliasgate/dialects/base.py +193 -0
  57. aliasgate-0.1.0/src/aliasgate/dialects/openai_chat.py +359 -0
  58. aliasgate-0.1.0/src/aliasgate/dialects/sse.py +108 -0
  59. aliasgate-0.1.0/src/aliasgate/engine.py +237 -0
  60. aliasgate-0.1.0/src/aliasgate/eval/__init__.py +4 -0
  61. aliasgate-0.1.0/src/aliasgate/eval/__main__.py +139 -0
  62. aliasgate-0.1.0/src/aliasgate/eval/corpus.py +105 -0
  63. aliasgate-0.1.0/src/aliasgate/eval/metrics.py +197 -0
  64. aliasgate-0.1.0/src/aliasgate/eval/report.py +103 -0
  65. aliasgate-0.1.0/src/aliasgate/factory.py +67 -0
  66. aliasgate-0.1.0/src/aliasgate/mapping.py +103 -0
  67. aliasgate-0.1.0/src/aliasgate/metrics.py +131 -0
  68. aliasgate-0.1.0/src/aliasgate/placeholders.py +41 -0
  69. aliasgate-0.1.0/src/aliasgate/proxy/__init__.py +1 -0
  70. aliasgate-0.1.0/src/aliasgate/proxy/app.py +602 -0
  71. aliasgate-0.1.0/src/aliasgate/proxy/errors.py +106 -0
  72. aliasgate-0.1.0/src/aliasgate/proxy/headers.py +50 -0
  73. aliasgate-0.1.0/src/aliasgate/py.typed +0 -0
  74. aliasgate-0.1.0/src/aliasgate/resolve.py +32 -0
  75. aliasgate-0.1.0/src/aliasgate/stream.py +50 -0
  76. aliasgate-0.1.0/src/aliasgate/terms.py +18 -0
  77. aliasgate-0.1.0/src/aliasgate/types.py +70 -0
  78. aliasgate-0.1.0/tests/detectors/test_cache.py +211 -0
  79. aliasgate-0.1.0/tests/detectors/test_checksums.py +160 -0
  80. aliasgate-0.1.0/tests/detectors/test_chunking.py +148 -0
  81. aliasgate-0.1.0/tests/detectors/test_dictionary.py +135 -0
  82. aliasgate-0.1.0/tests/detectors/test_gliner.py +453 -0
  83. aliasgate-0.1.0/tests/detectors/test_gliner_real.py +77 -0
  84. aliasgate-0.1.0/tests/detectors/test_literal.py +28 -0
  85. aliasgate-0.1.0/tests/detectors/test_rules.py +449 -0
  86. aliasgate-0.1.0/tests/dialects/fixtures/anthropic/request_all_blocks.json +74 -0
  87. aliasgate-0.1.0/tests/dialects/fixtures/anthropic/response_mixed.json +46 -0
  88. aliasgate-0.1.0/tests/dialects/fixtures/anthropic/stream_text_split.json +49 -0
  89. aliasgate-0.1.0/tests/dialects/fixtures/anthropic/stream_tool_use.json +115 -0
  90. aliasgate-0.1.0/tests/dialects/fixtures/openai_chat/request_all_fields.json +85 -0
  91. aliasgate-0.1.0/tests/dialects/fixtures/openai_chat/request_conversation.json +40 -0
  92. aliasgate-0.1.0/tests/dialects/fixtures/openai_chat/response_two_choices.json +55 -0
  93. aliasgate-0.1.0/tests/dialects/fixtures/openai_chat/stream_content_split.json +88 -0
  94. aliasgate-0.1.0/tests/dialects/fixtures/openai_chat/stream_held_at_finish.json +53 -0
  95. aliasgate-0.1.0/tests/dialects/fixtures/openai_chat/stream_parallel_tools.json +116 -0
  96. aliasgate-0.1.0/tests/dialects/fixtures/openai_chat/stream_tool_call.json +119 -0
  97. aliasgate-0.1.0/tests/dialects/fixtures/openai_chat/stream_two_choices.json +111 -0
  98. aliasgate-0.1.0/tests/dialects/test_anthropic_messages.py +581 -0
  99. aliasgate-0.1.0/tests/dialects/test_anthropic_stream.py +406 -0
  100. aliasgate-0.1.0/tests/dialects/test_base.py +312 -0
  101. aliasgate-0.1.0/tests/dialects/test_openai_chat.py +632 -0
  102. aliasgate-0.1.0/tests/dialects/test_openai_chat_stream.py +313 -0
  103. aliasgate-0.1.0/tests/dialects/test_sse.py +145 -0
  104. aliasgate-0.1.0/tests/eval/__init__.py +1 -0
  105. aliasgate-0.1.0/tests/eval/corpus/synthetic.en.jsonl +500 -0
  106. aliasgate-0.1.0/tests/eval/corpus/synthetic.es.jsonl +500 -0
  107. aliasgate-0.1.0/tests/eval/test_command.py +264 -0
  108. aliasgate-0.1.0/tests/eval/test_corpus.py +277 -0
  109. aliasgate-0.1.0/tests/eval/test_metrics.py +239 -0
  110. aliasgate-0.1.0/tests/eval/test_recall_gate.py +85 -0
  111. aliasgate-0.1.0/tests/fakes.py +43 -0
  112. aliasgate-0.1.0/tests/oracles.py +35 -0
  113. aliasgate-0.1.0/tests/proxy/conftest.py +74 -0
  114. aliasgate-0.1.0/tests/proxy/hygiene.py +51 -0
  115. aliasgate-0.1.0/tests/proxy/payloads.py +37 -0
  116. aliasgate-0.1.0/tests/proxy/test_app.py +539 -0
  117. aliasgate-0.1.0/tests/proxy/test_app_anthropic.py +438 -0
  118. aliasgate-0.1.0/tests/proxy/test_app_stream.py +442 -0
  119. aliasgate-0.1.0/tests/proxy/test_headers.py +87 -0
  120. aliasgate-0.1.0/tests/proxy/test_invariants.py +410 -0
  121. aliasgate-0.1.0/tests/proxy/test_logging_hygiene.py +179 -0
  122. aliasgate-0.1.0/tests/proxy/test_metrics.py +328 -0
  123. aliasgate-0.1.0/tests/proxy/test_upstream_base_path.py +147 -0
  124. aliasgate-0.1.0/tests/test_audit.py +238 -0
  125. aliasgate-0.1.0/tests/test_cli.py +524 -0
  126. aliasgate-0.1.0/tests/test_config.py +709 -0
  127. aliasgate-0.1.0/tests/test_docs.py +170 -0
  128. aliasgate-0.1.0/tests/test_engine.py +391 -0
  129. aliasgate-0.1.0/tests/test_factory.py +291 -0
  130. aliasgate-0.1.0/tests/test_mapping.py +207 -0
  131. aliasgate-0.1.0/tests/test_placeholders.py +210 -0
  132. aliasgate-0.1.0/tests/test_resolve.py +157 -0
  133. aliasgate-0.1.0/tests/test_restore.py +83 -0
  134. aliasgate-0.1.0/tests/test_smoke.py +5 -0
  135. aliasgate-0.1.0/tests/test_stream.py +170 -0
  136. aliasgate-0.1.0/tests/test_terms.py +65 -0
  137. aliasgate-0.1.0/tests/test_types.py +161 -0
  138. aliasgate-0.1.0/tools/generate_corpus.py +615 -0
  139. aliasgate-0.1.0/uv.lock +1763 -0
@@ -0,0 +1,10 @@
1
+ # Only what the image build needs. Everything else stays out, in particular local
2
+ # configurations and dictionaries, which may name real customers.
3
+ *
4
+ !pyproject.toml
5
+ !uv.lock
6
+ !README.md
7
+ !LICENSE
8
+ !src/
9
+ **/__pycache__
10
+ **/*.py[cod]
@@ -0,0 +1,34 @@
1
+ name: CI
2
+
3
+ on:
4
+ push:
5
+ branches: [main]
6
+ pull_request:
7
+ # The release workflow runs these checks before it publishes anything.
8
+ workflow_call:
9
+
10
+ permissions:
11
+ contents: read
12
+
13
+ concurrency:
14
+ group: ci-${{ github.ref }}
15
+ cancel-in-progress: true
16
+
17
+ jobs:
18
+ check:
19
+ runs-on: ubuntu-latest
20
+ strategy:
21
+ fail-fast: false
22
+ matrix:
23
+ python-version: ["3.12", "3.13"]
24
+ steps:
25
+ - uses: actions/checkout@v4
26
+ - uses: astral-sh/setup-uv@v6
27
+ with:
28
+ python-version: ${{ matrix.python-version }}
29
+ enable-cache: true
30
+ - run: uv sync --locked
31
+ - run: uv run ruff format --check .
32
+ - run: uv run ruff check .
33
+ - run: uv run mypy
34
+ - run: uv run pytest --cov -m "not ml"
@@ -0,0 +1,148 @@
1
+ # Release: pushing a tag vX.Y.Z runs the CI checks, pushes the images
2
+ # ghcr.io/<owner>/aliasgate:X.Y.Z and :X.Y.Z-ml, publishes the package to PyPI with trusted
3
+ # publishing (OIDC, no stored token), and creates a GitHub release with the changelog section of
4
+ # X.Y.Z. PyPI comes after the images because a PyPI version can never be uploaded again: if an
5
+ # image fails, delete the tag, fix, and push the tag again; nothing irreversible has happened.
6
+ #
7
+ # Before the first tag, the maintainer configures by hand:
8
+ # 1. On PyPI, a (pending) trusted publisher for project "aliasgate": this repository, workflow
9
+ # "release.yml", environment "pypi".
10
+ # 2. In the repository settings, an environment named "pypi" (optionally with required
11
+ # reviewers and a rule that only v* tags may deploy to it).
12
+ # To release: set the version in pyproject.toml and src/aliasgate/__init__.py, move the
13
+ # changelog's Unreleased entries under the new version, merge, then push the tag vX.Y.Z from main.
14
+ #
15
+ # Third-party actions are pinned by commit; the comment names the release.
16
+
17
+ name: Release
18
+
19
+ on:
20
+ push:
21
+ tags: ["v*"]
22
+
23
+ permissions: {}
24
+
25
+ concurrency:
26
+ group: release-${{ github.ref }}
27
+ cancel-in-progress: false
28
+
29
+ jobs:
30
+ ci:
31
+ uses: ./.github/workflows/ci.yml
32
+ permissions:
33
+ contents: read
34
+
35
+ build:
36
+ needs: ci
37
+ runs-on: ubuntu-latest
38
+ permissions:
39
+ contents: read
40
+ outputs:
41
+ version: ${{ steps.version.outputs.version }}
42
+ steps:
43
+ - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
44
+ with:
45
+ persist-credentials: false
46
+ - uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2 # v10.3.3
47
+ with:
48
+ version: "0.11.26"
49
+ - name: Check that the tag names the package version
50
+ id: version
51
+ run: |
52
+ version="$(uv version --short)"
53
+ if [ "v${version}" != "${GITHUB_REF_NAME}" ]; then
54
+ echo "::error::tag ${GITHUB_REF_NAME} does not match the package version ${version}"
55
+ exit 1
56
+ fi
57
+ echo "version=${version}" >> "${GITHUB_OUTPUT}"
58
+ - run: uv build
59
+ - uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
60
+ with:
61
+ name: dist
62
+ path: dist/
63
+ if-no-files-found: error
64
+
65
+ pypi:
66
+ needs: [build, images]
67
+ runs-on: ubuntu-latest
68
+ environment:
69
+ name: pypi
70
+ url: https://pypi.org/project/aliasgate/${{ needs.build.outputs.version }}/
71
+ permissions:
72
+ id-token: write # trusted publishing: PyPI exchanges this OIDC token; nothing is stored
73
+ steps:
74
+ - uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
75
+ with:
76
+ name: dist
77
+ path: dist/
78
+ - uses: pypa/gh-action-pypi-publish@7245906fb61fa33a13554f9d5fb856fe61758086 # v1.14.3
79
+
80
+ images:
81
+ needs: build
82
+ runs-on: ubuntu-latest
83
+ permissions:
84
+ contents: read
85
+ packages: write
86
+ strategy:
87
+ fail-fast: false
88
+ matrix:
89
+ include:
90
+ - extras: ""
91
+ suffix: ""
92
+ - extras: ml
93
+ suffix: "-ml"
94
+ steps:
95
+ - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
96
+ with:
97
+ persist-credentials: false
98
+ - uses: docker/setup-qemu-action@99012661954931238ded8c8b007157a8430204e1 # v4.4.0
99
+ - uses: docker/setup-buildx-action@f87e5991a6d7451dcb8d9637bfbc97413f497069 # v4.4.1
100
+ - uses: docker/login-action@8aa5831fb8d48d8f76594c7ddde61ae58019f550 # v4.8.0
101
+ with:
102
+ registry: ghcr.io
103
+ username: ${{ github.actor }}
104
+ password: ${{ github.token }} # the job's own short-lived token
105
+ - name: Image name
106
+ id: image
107
+ run: echo "name=ghcr.io/${GITHUB_REPOSITORY,,}" >> "${GITHUB_OUTPUT}"
108
+ - uses: docker/build-push-action@c3c9e263c25d99ce0380d002d59b67737d91b0dc # v7.4.0
109
+ with:
110
+ context: .
111
+ platforms: linux/amd64,linux/arm64
112
+ build-args: EXTRAS=${{ matrix.extras }}
113
+ tags: ${{ steps.image.outputs.name }}:${{ needs.build.outputs.version }}${{ matrix.suffix }}
114
+ push: true
115
+
116
+ release:
117
+ needs: [build, images, pypi]
118
+ runs-on: ubuntu-latest
119
+ permissions:
120
+ contents: write
121
+ steps:
122
+ - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
123
+ with:
124
+ persist-credentials: false
125
+ - uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
126
+ with:
127
+ name: dist
128
+ path: dist/
129
+ - name: Changelog section
130
+ env:
131
+ VERSION: ${{ needs.build.outputs.version }}
132
+ run: |
133
+ awk -v heading="## [${VERSION}]" '
134
+ index($0, "## [") == 1 { if (found) exit; found = index($0, heading) == 1; next }
135
+ /^\[[^]]*\]: / { exit } # the link definitions at the end of the file
136
+ found { print }
137
+ ' CHANGELOG.md > notes.md
138
+ if ! grep -q '[^[:space:]]' notes.md; then
139
+ echo "::error::CHANGELOG.md has no section for ${VERSION}"
140
+ exit 1
141
+ fi
142
+ - name: GitHub release
143
+ env:
144
+ GH_TOKEN: ${{ github.token }}
145
+ VERSION: ${{ needs.build.outputs.version }}
146
+ run: >-
147
+ gh release create "${GITHUB_REF_NAME}" dist/*
148
+ --verify-tag --title "aliasgate ${VERSION}" --notes-file notes.md
@@ -0,0 +1,23 @@
1
+ __pycache__/
2
+ *.py[cod]
3
+ .venv/
4
+ dist/
5
+ build/
6
+ *.egg-info/
7
+ .pytest_cache/
8
+ .mypy_cache/
9
+ .ruff_cache/
10
+ .hypothesis/
11
+ .coverage
12
+ coverage.xml
13
+ htmlcov/
14
+ .env
15
+ .env.*
16
+ !.env.example
17
+ # Local configuration and dictionaries may contain real customer names. Never commit them.
18
+ aliasgate.yaml
19
+ dictionary*.yaml
20
+ !examples/**
21
+ .DS_Store
22
+ .idea/
23
+ .vscode/
@@ -0,0 +1 @@
1
+ 3.13
@@ -0,0 +1,88 @@
1
+ # Working rules for coding agents and contributors
2
+
3
+ Read this file completely before changing anything. It applies to humans too.
4
+
5
+ ## What this project is
6
+
7
+ A security product. Its job is to stop customer data from reaching an LLM provider. A bug here is
8
+ not a wrong pixel; it is a data leak. Prefer the boring, obviously correct solution every time.
9
+
10
+ ## Before you write code
11
+
12
+ 1. Read [docs/architecture.md](docs/architecture.md) and [docs/threat-model.md](docs/threat-model.md).
13
+ 2. Read [docs/plan/README.md](docs/plan/README.md), then the file of the slice you were asked to
14
+ implement. Implement **one slice per pull request**, nothing more.
15
+ 3. Check that every slice listed under "Depends on" is merged. If not, stop and say so.
16
+
17
+ ## How to work on a slice
18
+
19
+ 1. Create a branch `slice-NN-short-name` from `main`.
20
+ 2. Write the tests listed in the slice file first. Run them and watch them fail.
21
+ 3. Implement until they pass. Add tests for any behaviour you add that the slice file does not
22
+ list.
23
+ 4. Run the full check (below). All four commands must pass.
24
+ 5. Tick the slice's acceptance checklist in the pull request description, set the slice status
25
+ to `done` in `docs/plan/README.md` and in the roadmap table in `README.md`.
26
+ 6. Commit with [Conventional Commits](https://www.conventionalcommits.org/) (`feat:`, `fix:`,
27
+ `test:`, `docs:`, `chore:`, `refactor:`). Open a pull request. Do not push to `main`.
28
+
29
+ ```bash
30
+ uv run ruff format .
31
+ uv run ruff check .
32
+ uv run mypy
33
+ uv run pytest --cov -m "not ml"
34
+ ```
35
+
36
+ ## Hard rules
37
+
38
+ These are not style preferences. A change that breaks one is rejected.
39
+
40
+ 1. **Never use real personal data.** Tests, fixtures, examples and documentation use synthetic
41
+ values only. Use the test vectors given in the slice files, `example.com` / `example.org`
42
+ domains, and obviously fictional names.
43
+ 2. **Never log text.** No request text, response text, detected value, or mapping in any log
44
+ line, exception message, metric label or trace attribute. Log counts, types, durations, ids.
45
+ When you raise an exception about a value, describe its position and type, not its content.
46
+ 3. **Fail closed.** If something goes wrong before forwarding, reject the request. Never add a
47
+ code path that forwards a request whose pseudonymisation did not complete.
48
+ 4. **Nothing reversible on disk.** Do not persist mappings, caches containing text, or request
49
+ bodies. In-memory only.
50
+ 5. **Respect the layers.** Core modules do not import from `dialects` or `proxy`. Dialects do not
51
+ import from `proxy` and do not perform I/O. See the table in architecture §1.
52
+ 6. **Do not change public interfaces defined in the architecture or in a merged slice** without
53
+ updating the architecture document in the same pull request and explaining why.
54
+ 7. **Do not add a dependency that the slice file does not list.** If you believe one is needed,
55
+ stop and ask.
56
+ 8. **No network in tests.** Upstream providers are mocked (`respx`). Tests marked `ml` are the
57
+ only ones allowed to download a model and they do not run in default CI.
58
+ 9. **Do not weaken a test to make it pass.** If a specified test seems wrong, stop and report
59
+ the contradiction instead of editing the expectation.
60
+
61
+ ## Code style
62
+
63
+ - Python 3.12+, fully typed, `mypy --strict` clean. No `Any` in core modules; `Any` is
64
+ acceptable for JSON payloads in dialects.
65
+ - `from __future__ import annotations` is not needed on 3.12; do not add it.
66
+ - Dataclasses are `frozen=True, slots=True` unless mutation is the point.
67
+ - Pure functions in the core. No global mutable state. No singletons.
68
+ - Compile regular expressions once at module level.
69
+ - Public functions and classes have a one-line docstring saying what they guarantee. Do not
70
+ write comments that restate the code.
71
+ - Test names describe behaviour: `test_iban_with_wrong_checksum_is_not_detected`.
72
+ - Property tests (Hypothesis) are required wherever the slice file says "property".
73
+
74
+ ## When you are unsure
75
+
76
+ If the slice file is ambiguous or contradicts the architecture, do not guess. Write down the
77
+ question, the options you see and your recommendation, and stop. A wrong guess in this codebase
78
+ can leak data.
79
+
80
+ ## External facts to verify, not assume
81
+
82
+ Library APIs and model identifiers change. Before using any of the following, check the current
83
+ documentation and record the version you verified in the pull request description:
84
+
85
+ - provider request and response shapes (OpenAI Chat Completions, Anthropic Messages), including
86
+ streaming event formats;
87
+ - the `gliner` package API and the chosen model's identifier and licence;
88
+ - `phonenumbers`, `httpx`, `starlette` and `respx` APIs.
@@ -0,0 +1,40 @@
1
+ # Changelog
2
+
3
+ All notable changes to this project are documented in this file. The format is based on
4
+ [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the project follows
5
+ [Semantic Versioning](https://semver.org/spec/v2.0.0.html). Before 1.0.0, a minor version may
6
+ change the configuration or the command line.
7
+
8
+ ## [Unreleased]
9
+
10
+ ## [0.1.0] - 2026-11-20
11
+
12
+ First release. Alpha: the gateway works end to end and its safety properties are tested, but
13
+ it has not run in production yet. Read the threat model before relying on it.
14
+
15
+ ### Added
16
+
17
+ - Gateway for OpenAI Chat Completions (`POST /v1/chat/completions`) and Anthropic Messages
18
+ (`POST /v1/messages`, `POST /v1/messages/count_tokens`), whole and streamed, with tool calls.
19
+ Upstreams may have a base path, for Azure OpenAI and Claude in Microsoft Foundry.
20
+ - Detection in layers: placeholder literals already in the text, company dictionaries, rules
21
+ with checksum validation (email, phone, IBAN, card, Spanish DNI/NIE and US SSN, Spanish CIF,
22
+ IP address, secrets, optional URL), an optional local GLiNER model (`ml` extra), an allow
23
+ list, and propagation of detected values to their other occurrences.
24
+ - Typed, numbered placeholders (`[TYPE_N]`), deterministic per request and stable when a
25
+ conversation grows; restoration that tolerates common model alterations, including
26
+ placeholders split across streamed chunks.
27
+ - Fail-closed policy: unknown endpoints and uninspectable content (images, audio, files) are
28
+ rejected by default, end-user identifiers are removed, and a leak audit rejects any request
29
+ whose outbound body still holds a detected value.
30
+ - Prometheus metrics, JSON logs without text, and the `x-aliasgate-request-id` and
31
+ `x-aliasgate-entities` response headers.
32
+ - `aliasgate` command: `serve`, `check`, `demo` and `version`.
33
+ - Evaluation harness, `python -m aliasgate.eval`, with synthetic English and Spanish corpora
34
+ and a recall gate in CI.
35
+ - Docker images `ghcr.io/jcjmenez/aliasgate:0.1.0` and `:0.1.0-ml` (model baked in, runs
36
+ offline), non-root, with no configuration inside.
37
+ - Documentation: usage, deployment, architecture, threat model, evaluation.
38
+
39
+ [Unreleased]: https://github.com/jcjmenez/aliasgate/compare/v0.1.0...HEAD
40
+ [0.1.0]: https://github.com/jcjmenez/aliasgate/releases/tag/v0.1.0
@@ -0,0 +1 @@
1
+ @AGENTS.md
@@ -0,0 +1,52 @@
1
+ # Contributing
2
+
3
+ Thank you for helping. This is a security-sensitive project, so the process is strict on a few
4
+ points and relaxed on the rest.
5
+
6
+ ## Setup
7
+
8
+ Install [uv](https://docs.astral.sh/uv/), then:
9
+
10
+ ```bash
11
+ uv sync
12
+ ```
13
+
14
+ ## Checks
15
+
16
+ All of these run in CI and must pass:
17
+
18
+ ```bash
19
+ uv run ruff format --check .
20
+ uv run ruff check .
21
+ uv run mypy
22
+ uv run pytest --cov -m "not ml"
23
+ ```
24
+
25
+ ## Rules
26
+
27
+ The working rules in [AGENTS.md](AGENTS.md) apply to every contribution, whoever or whatever
28
+ writes it. The most important ones:
29
+
30
+ - synthetic data only, in tests, examples and issues;
31
+ - no request or response text in logs;
32
+ - fail closed;
33
+ - one slice or one focused change per pull request, with tests.
34
+
35
+ ## Pull requests
36
+
37
+ - Branch from `main`, use [Conventional Commits](https://www.conventionalcommits.org/).
38
+ - Describe what changed, why, and how you tested it.
39
+ - If the change touches detection, include before and after numbers from the
40
+ [evaluation harness](docs/evaluation.md) (`uv run python -m aliasgate.eval
41
+ tests/eval/corpus/*.jsonl`).
42
+ - If the change touches a security invariant listed in
43
+ [docs/threat-model.md](docs/threat-model.md), say so explicitly.
44
+
45
+ ## Reporting a detection miss
46
+
47
+ A value that should have been pseudonymised and was not is a bug. Open an issue with a
48
+ **synthetic** example that reproduces it. Never paste real data into an issue.
49
+
50
+ ## Security vulnerabilities
51
+
52
+ Do not open a public issue. See [SECURITY.md](SECURITY.md).
@@ -0,0 +1,68 @@
1
+ # syntax=docker/dockerfile:1
2
+ #
3
+ # aliasgate gateway image.
4
+ #
5
+ # docker build -t aliasgate . # rules and dictionary
6
+ # docker build -t aliasgate:ml --build-arg EXTRAS=ml . # plus the GLiNER model, baked in
7
+ #
8
+ # No configuration or dictionary is baked in: mount them at /etc/aliasgate. Base images are
9
+ # pinned by digest; update the tag and the digest together.
10
+
11
+ FROM ghcr.io/astral-sh/uv:0.11.26@sha256:3d868e555f8f1dbc324afa005066cd11e1053fc4743b9808ca8025283e65efa5 AS uv
12
+
13
+ FROM python:3.13-slim@sha256:e48f59cdba69a3cbd9ed2cf0f348d90d45a8d350d98134cf1070bc106ee9ed90 AS build
14
+ COPY --from=uv /uv /usr/local/bin/uv
15
+ ENV UV_COMPILE_BYTECODE=1 \
16
+ UV_LINK_MODE=copy \
17
+ UV_PYTHON=/usr/local/bin/python3 \
18
+ UV_PYTHON_DOWNLOADS=never \
19
+ UV_PROJECT_ENVIRONMENT=/opt/aliasgate
20
+ # Empty for the core image; "ml" adds the ML extra.
21
+ ARG EXTRAS=""
22
+ WORKDIR /src
23
+ # Dependencies first, from the lock file only, so that a source change does not reinstall them.
24
+ COPY pyproject.toml uv.lock ./
25
+ RUN --mount=type=cache,target=/root/.cache/uv \
26
+ uv sync --locked --no-dev --no-install-project ${EXTRAS:+--extra "$EXTRAS"}
27
+ COPY README.md LICENSE ./
28
+ COPY src ./src
29
+ RUN --mount=type=cache,target=/root/.cache/uv \
30
+ uv sync --locked --no-dev --no-editable ${EXTRAS:+--extra "$EXTRAS"}
31
+
32
+ # The ML image downloads the pinned model at build time, together with the tokenizer of its
33
+ # base encoder (microsoft/mdeberta-v3-base, fetched at its default branch), then proves that
34
+ # the detector builds from the cache alone, as the container will at start-up.
35
+ ENV HF_HOME=/opt/huggingface HF_HUB_DISABLE_TELEMETRY=1
36
+ RUN mkdir -p "$HF_HOME" && if [ "$EXTRAS" = "ml" ]; then \
37
+ /opt/aliasgate/bin/python -c 'from aliasgate.config import MLSettings; \
38
+ from aliasgate.detectors.gliner import load_gliner; \
39
+ ml = MLSettings(); load_gliner(ml.model, ml.revision)' \
40
+ && HF_HUB_OFFLINE=1 /opt/aliasgate/bin/python -c 'from aliasgate.config import Settings; \
41
+ from aliasgate.factory import build_pseudonymizer; \
42
+ build_pseudonymizer(Settings.model_validate({"detection": {"ml": {"enabled": True}}}))'; \
43
+ fi \
44
+ # huggingface_hub writes some cache files as 0600; the gateway's user must read them all.
45
+ && chmod -R a+rX "$HF_HOME"
46
+
47
+ FROM python:3.13-slim@sha256:e48f59cdba69a3cbd9ed2cf0f348d90d45a8d350d98134cf1070bc106ee9ed90
48
+ LABEL org.opencontainers.image.title="aliasgate" \
49
+ org.opencontainers.image.description="Reversible pseudonymisation gateway for LLM APIs" \
50
+ org.opencontainers.image.source="https://github.com/jcjmenez/aliasgate" \
51
+ org.opencontainers.image.licenses="Apache-2.0"
52
+ RUN useradd --system --uid 10001 --user-group --no-create-home --home-dir /nonexistent \
53
+ --shell /usr/sbin/nologin aliasgate
54
+ # Owned by root and read-only for the gateway's user.
55
+ COPY --from=build /opt/aliasgate /opt/aliasgate
56
+ COPY --from=build /opt/huggingface /opt/huggingface
57
+ ENV PATH=/opt/aliasgate/bin:$PATH \
58
+ PYTHONDONTWRITEBYTECODE=1 \
59
+ PYTHONUNBUFFERED=1 \
60
+ HF_HOME=/opt/huggingface \
61
+ HF_HUB_OFFLINE=1 \
62
+ HF_HUB_DISABLE_TELEMETRY=1
63
+ USER 10001:10001
64
+ EXPOSE 8080
65
+ # http.client ignores proxy variables, so the probe always reaches the gateway itself.
66
+ HEALTHCHECK --interval=30s --timeout=5s --start-period=60s --retries=3 CMD ["python", "-c", "import http.client, sys; c = http.client.HTTPConnection('127.0.0.1', 8080, timeout=4); c.request('GET', '/healthz'); sys.exit(c.getresponse().status != 200)"]
67
+ ENTRYPOINT ["aliasgate"]
68
+ CMD ["serve", "--config", "/etc/aliasgate/aliasgate.yaml", "--host", "0.0.0.0"]