aliasgate 0.1.0__py3-none-any.whl

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.
aliasgate/__init__.py ADDED
@@ -0,0 +1,5 @@
1
+ """aliasgate: reversible pseudonymization gateway for LLM APIs."""
2
+
3
+ __version__ = "0.1.0"
4
+
5
+ __all__ = ["__version__"]
aliasgate/__main__.py ADDED
@@ -0,0 +1,8 @@
1
+ """`python -m aliasgate` runs the `aliasgate` command (see `aliasgate.cli`)."""
2
+
3
+ import sys
4
+
5
+ from aliasgate.cli import main
6
+
7
+ if __name__ == "__main__":
8
+ sys.exit(main())
aliasgate/audit.py ADDED
@@ -0,0 +1,84 @@
1
+ """Outbound leak audit (architecture §8): the gateway checks its own work before forwarding."""
2
+
3
+ import re
4
+ import unicodedata
5
+ from collections.abc import Iterable, Iterator
6
+ from dataclasses import dataclass
7
+
8
+ from aliasgate.mapping import Mapping
9
+ from aliasgate.terms import build_term_pattern, term_body
10
+ from aliasgate.types import LITERAL
11
+
12
+
13
+ @dataclass(frozen=True, slots=True)
14
+ class AuditResult:
15
+ """How many entities of the mapping were found in the outbound body, and their types.
16
+
17
+ Never which ones: it holds no surface.
18
+ """
19
+
20
+ leaked_entities: int
21
+ leaked_types: tuple[str, ...]
22
+
23
+
24
+ def audit_outbound(payload: object, mapping: Mapping, *, min_length: int) -> AuditResult:
25
+ """Search every string value of the outbound JSON payload for the entities of the mapping.
26
+
27
+ Every string value is searched, wherever it is, so a field no dialect processes is caught
28
+ too; keys are not. `LITERAL` entities and entities whose key is shorter than `min_length`
29
+ are skipped. An entity is found when its whole-term pattern matches (case-insensitive,
30
+ flexible whitespace, as propagation searches), or when its key matches the string after
31
+ NFKC normalisation and case folding, which also catches variants with the same key that
32
+ the pattern misses, such as "STRASSE" for "Straße".
33
+ """
34
+ entities = [
35
+ entity
36
+ for entity in mapping.entities()
37
+ if entity.entity_type != LITERAL and len(entity.key) >= min_length
38
+ ]
39
+ if not entities:
40
+ return AuditResult(0, ())
41
+ strings = list(_string_values(payload))
42
+ folded = [_fold(text) for text in strings]
43
+ # One alternation per side finds whether any entity occurs, in one pass per string. Only
44
+ # when one does is each entity searched on its own, to count them.
45
+ longest_first = sorted(entities, key=lambda entity: -len(entity.surface))
46
+ any_term = _whole_terms((term_body(entity.surface) for entity in longest_first), re.IGNORECASE)
47
+ any_key = _whole_terms(term_body(entity.key) for entity in longest_first)
48
+ if not _search(any_term, strings) and not _search(any_key, folded):
49
+ return AuditResult(0, ())
50
+ leaked = [
51
+ entity
52
+ for entity in entities
53
+ if _search(build_term_pattern(entity.surface), strings)
54
+ or _search(_whole_terms([term_body(entity.key)]), folded)
55
+ ]
56
+ return AuditResult(len(leaked), tuple(sorted({entity.entity_type for entity in leaked})))
57
+
58
+
59
+ def _whole_terms(bodies: Iterable[str], flags: int = 0) -> re.Pattern[str]:
60
+ """Any of the bodies as a whole term. Folded text is matched by folded keys, without
61
+ IGNORECASE."""
62
+ return re.compile(rf"(?<!\w)(?:{'|'.join(bodies)})(?!\w)", flags)
63
+
64
+
65
+ def _search(pattern: re.Pattern[str], strings: list[str]) -> bool:
66
+ return any(pattern.search(text) for text in strings)
67
+
68
+
69
+ def _fold(text: str) -> str:
70
+ """The text as keys are made (architecture §4.2), without collapsing whitespace."""
71
+ return unicodedata.normalize("NFKC", text).casefold()
72
+
73
+
74
+ def _string_values(payload: object) -> Iterator[str]:
75
+ """Every string value of a JSON value, iteratively, so that nesting depth is no limit."""
76
+ stack = [payload]
77
+ while stack:
78
+ value = stack.pop()
79
+ if isinstance(value, str):
80
+ yield value
81
+ elif isinstance(value, dict):
82
+ stack.extend(value.values())
83
+ elif isinstance(value, list):
84
+ stack.extend(value)
aliasgate/cli.py ADDED
@@ -0,0 +1,321 @@
1
+ """The `aliasgate` command: `serve`, `check`, `demo` and `version`.
2
+
3
+ Exit codes: 0 success, 2 configuration error (or invalid arguments), 1 anything else. Errors
4
+ name files, fields and entry positions, never configuration or dictionary values. `demo` is the
5
+ only code path that prints detected values, and only with `--show-mapping`.
6
+ """
7
+
8
+ import argparse
9
+ import ipaddress
10
+ import json
11
+ import sys
12
+ from collections import Counter
13
+ from collections.abc import Callable, Sequence
14
+ from pathlib import Path
15
+ from typing import Final
16
+
17
+ import uvicorn
18
+ import yaml
19
+ from pydantic import ValidationError
20
+
21
+ from aliasgate import __version__
22
+ from aliasgate.config import ListenSettings, Settings, load_settings, load_terms
23
+ from aliasgate.detectors.dictionary import Term
24
+ from aliasgate.engine import DetectionError, Pseudonymizer
25
+ from aliasgate.factory import build_pseudonymizer
26
+ from aliasgate.proxy.app import configure_logging, create_app
27
+
28
+ EXIT_OK: Final = 0
29
+ EXIT_FAILURE: Final = 1
30
+ EXIT_CONFIGURATION: Final = 2
31
+
32
+ _NOT_LOOPBACK: Final = (
33
+ "warning: listening on {host}, which is not a loopback address. The gateway has no client"
34
+ " authentication and must sit behind a trusted network boundary (docs/deployment.md)."
35
+ )
36
+
37
+
38
+ class _ConfigurationError(Exception):
39
+ """Invalid configuration or dictionaries; each problem names a field, file or position."""
40
+
41
+ def __init__(self, problems: Sequence[str]) -> None:
42
+ super().__init__(f"{len(problems)} configuration problem(s)")
43
+ self.problems = tuple(problems)
44
+
45
+
46
+ def main(argv: Sequence[str] | None = None) -> int:
47
+ """Run one command and return its exit code: 0 success, 2 configuration error, 1 otherwise."""
48
+ try:
49
+ args = _parser().parse_args(argv)
50
+ except SystemExit as exc: # --help (0) or invalid arguments (2); argparse printed why
51
+ return exc.code if isinstance(exc.code, int) else EXIT_CONFIGURATION
52
+ command: Callable[[argparse.Namespace], int] = args.run
53
+ try:
54
+ return command(args)
55
+ except _ConfigurationError as exc:
56
+ for problem in exc.problems:
57
+ _error(problem)
58
+ return EXIT_CONFIGURATION
59
+ except DetectionError as exc: # names the detector, never text
60
+ _error(str(exc))
61
+ return EXIT_FAILURE
62
+ except Exception as exc: # any other message may hold text
63
+ _error(f"unexpected failure ({type(exc).__name__})")
64
+ return EXIT_FAILURE
65
+
66
+
67
+ def _parser() -> argparse.ArgumentParser:
68
+ parser = argparse.ArgumentParser(
69
+ prog="aliasgate", description="Reversible pseudonymisation gateway for LLM APIs."
70
+ )
71
+ commands = parser.add_subparsers(title="commands", metavar="COMMAND", required=True)
72
+
73
+ serve = commands.add_parser(
74
+ "serve", help="serve the gateway", description="Serve the gateway until interrupted."
75
+ )
76
+ _config_argument(serve)
77
+ serve.add_argument("--host", help="address to listen on; overrides listen.host")
78
+ serve.add_argument("--port", type=int, help="port to listen on; overrides listen.port")
79
+ serve.set_defaults(run=_serve)
80
+
81
+ check = commands.add_parser(
82
+ "check",
83
+ help="validate the configuration and dictionaries",
84
+ description="Validate the configuration and dictionaries, build the detectors (loading "
85
+ "the model if enabled) and print a summary.",
86
+ )
87
+ _config_argument(check)
88
+ check.set_defaults(run=_check)
89
+
90
+ demo = commands.add_parser(
91
+ "demo",
92
+ help="pseudonymise standard input, for tuning dictionaries",
93
+ description="Pseudonymise standard input and print the result. Entity counts go to "
94
+ "standard error. A local debugging aid: never run it on shared terminals or in CI logs "
95
+ "with --show-mapping.",
96
+ )
97
+ _config_argument(demo)
98
+ demo.add_argument(
99
+ "--show-mapping",
100
+ action="store_true",
101
+ help="also print each placeholder and the value it replaced to standard error",
102
+ )
103
+ demo.set_defaults(run=_demo)
104
+
105
+ version = commands.add_parser("version", help="print the version")
106
+ version.set_defaults(run=_version)
107
+ return parser
108
+
109
+
110
+ def _config_argument(parser: argparse.ArgumentParser) -> None:
111
+ parser.add_argument(
112
+ "--config",
113
+ type=Path,
114
+ required=True,
115
+ metavar="PATH",
116
+ help="YAML configuration file; ALIASGATE_* environment variables override it",
117
+ )
118
+
119
+
120
+ def _serve(args: argparse.Namespace) -> int:
121
+ settings = _with_listen(_load_settings(args.config), args.host, args.port)
122
+ _load_dictionaries(settings)
123
+ configure_logging(settings.logging.level)
124
+ if not _is_loopback(settings.listen.host):
125
+ print(_NOT_LOOPBACK.format(host=settings.listen.host), file=sys.stderr)
126
+ app = create_app(settings, pseudonymizer=_build(settings))
127
+ # The gateway logs one line per request itself; uvicorn's access log would add the path
128
+ # and query string of every request.
129
+ uvicorn.run(
130
+ app,
131
+ host=settings.listen.host,
132
+ port=settings.listen.port,
133
+ log_config=None,
134
+ access_log=False,
135
+ )
136
+ return EXIT_OK
137
+
138
+
139
+ def _check(args: argparse.Namespace) -> int:
140
+ settings = _load_settings(args.config)
141
+ dictionaries = _load_dictionaries(settings)
142
+ pseudonymizer = _build(settings)
143
+ print(_summary(args.config, settings, dictionaries, pseudonymizer))
144
+ return EXIT_OK
145
+
146
+
147
+ def _demo(args: argparse.Namespace) -> int:
148
+ settings = _load_settings(args.config)
149
+ _load_dictionaries(settings)
150
+ pseudonymizer = _build(settings)
151
+ batch = pseudonymizer.pseudonymize([sys.stdin.read()])
152
+ sys.stdout.write(batch.texts[0])
153
+ sys.stdout.flush()
154
+ entities = batch.mapping.entities()
155
+ if not entities:
156
+ print("no entities detected", file=sys.stderr)
157
+ return EXIT_OK
158
+ found = Counter(entity.entity_type for entity in entities)
159
+ replaced: Counter[str] = Counter()
160
+ for (entity_type, _source), count in batch.stats.entities_by_type_and_source.items():
161
+ replaced[entity_type] += count
162
+ width = max(len("entity type"), *(len(entity_type) for entity_type in found))
163
+ print(f"{'entity type':<{width}} entities occurrences", file=sys.stderr)
164
+ for entity_type in sorted(found):
165
+ print(
166
+ f"{entity_type:<{width}} {found[entity_type]:>8} {replaced[entity_type]:>11}",
167
+ file=sys.stderr,
168
+ )
169
+ if args.show_mapping:
170
+ print("\nplaceholder value", file=sys.stderr)
171
+ for entity in entities:
172
+ surface = json.dumps(entity.surface, ensure_ascii=False)
173
+ print(f"{entity.placeholder} {surface}", file=sys.stderr)
174
+ return EXIT_OK
175
+
176
+
177
+ def _version(args: argparse.Namespace) -> int:
178
+ print(f"aliasgate {__version__}")
179
+ return EXIT_OK
180
+
181
+
182
+ def _load_settings(path: Path) -> Settings:
183
+ try:
184
+ return load_settings(path)
185
+ except yaml.YAMLError as exc:
186
+ # The parser's message quotes the offending line.
187
+ raise _ConfigurationError(
188
+ [f"the configuration file {path} is not valid YAML{_yaml_position(exc)}"]
189
+ ) from None
190
+ except ValidationError as exc:
191
+ raise _ConfigurationError(_field_problems(exc)) from None
192
+ except OSError as exc:
193
+ raise _ConfigurationError([_unreadable(path, exc)]) from None
194
+ except ValueError as exc: # an ALIASGATE_* variable that does not parse; names the field
195
+ raise _ConfigurationError([str(exc)]) from None
196
+
197
+
198
+ def _with_listen(settings: Settings, host: str | None, port: int | None) -> Settings:
199
+ if host is None and port is None:
200
+ return settings
201
+ listen = settings.listen.model_dump()
202
+ if host is not None:
203
+ listen["host"] = host
204
+ if port is not None:
205
+ listen["port"] = port
206
+ try:
207
+ validated = ListenSettings.model_validate(listen)
208
+ except ValidationError as exc:
209
+ raise _ConfigurationError(_field_problems(exc, prefix=("listen",))) from None
210
+ return settings.model_copy(update={"listen": validated})
211
+
212
+
213
+ def _load_dictionaries(settings: Settings) -> list[list[Term]]:
214
+ """Every dictionary file, parsed; the problems of all files are reported together."""
215
+ loaded: list[list[Term]] = []
216
+ problems: list[str] = []
217
+ for path in settings.detection.dictionary.files:
218
+ try:
219
+ loaded.append(load_terms(path))
220
+ except OSError as exc:
221
+ problems.append(_unreadable(path, exc))
222
+ except ValueError as exc: # names the file and the entry, never a term
223
+ problems.append(str(exc))
224
+ if problems:
225
+ raise _ConfigurationError(problems)
226
+ return loaded
227
+
228
+
229
+ def _build(settings: Settings) -> Pseudonymizer:
230
+ try:
231
+ return build_pseudonymizer(settings)
232
+ except (ValueError, RuntimeError) as exc:
233
+ # Conflicting dictionary terms (named by position), a missing ML extra or a window the
234
+ # model cannot take. No request text exists yet, and terms are never in these messages.
235
+ raise _ConfigurationError([str(exc)]) from None
236
+
237
+
238
+ def _summary(
239
+ path: Path,
240
+ settings: Settings,
241
+ dictionaries: Sequence[Sequence[Term]],
242
+ pseudonymizer: Pseudonymizer,
243
+ ) -> str:
244
+ detection = settings.detection
245
+ ml = detection.ml
246
+ terms = [term for terms in dictionaries for term in terms]
247
+ types = {*detection.rules.enabled_types, *(term.entity_type for term in terms)}
248
+ if ml.enabled:
249
+ types.update(ml.labels.values())
250
+ revision = "a local directory" if ml.revision is None else f"revision {ml.revision}"
251
+ ml_line = f"ml: {ml.model} at {revision}, threshold {ml.threshold}"
252
+ else:
253
+ ml_line = "ml: off"
254
+ dictionary = (
255
+ f"{_plural(len(terms), 'term')} in {_plural(len(dictionaries), 'file')}"
256
+ if dictionaries
257
+ else "no terms"
258
+ )
259
+ upstreams = settings.upstreams
260
+ policy = settings.policy
261
+ return "\n".join(
262
+ [
263
+ f"configuration: {path} is valid",
264
+ "detectors: " + ", ".join(detector.name for detector in pseudonymizer.detectors),
265
+ f"dictionary: {dictionary}",
266
+ "entity types: " + (", ".join(sorted(types)) or "none"),
267
+ ml_line,
268
+ "upstreams:",
269
+ f" openai: {upstreams.openai.base_url}",
270
+ f" anthropic: {upstreams.anthropic.base_url}",
271
+ "passthrough: " + (", ".join(upstreams.passthrough_paths) or "none"),
272
+ f"listen: {settings.listen.host} port {settings.listen.port}",
273
+ "policy: "
274
+ f"unsupported_content={policy.unsupported_content}, "
275
+ f"strip_user_identifiers={_on(policy.strip_user_identifiers)}, "
276
+ f"tool_definitions={_on(policy.tool_definitions)}, "
277
+ f"leak_audit={_on(policy.leak_audit)}",
278
+ f"propagation: {_on(detection.propagate)}",
279
+ f"metrics: {_on(settings.metrics.enabled)}",
280
+ ]
281
+ )
282
+
283
+
284
+ def _field_problems(exc: ValidationError, prefix: tuple[str, ...] = ()) -> list[str]:
285
+ """One line per error: the field path and pydantic's reason, which never holds the input
286
+ (every settings model sets `hide_input_in_errors`)."""
287
+ problems = []
288
+ for error in exc.errors(include_url=False, include_input=False, include_context=False):
289
+ location = ".".join(str(part) for part in (*prefix, *error["loc"])) or "(top level)"
290
+ problems.append(f"{location}: {error['msg']}")
291
+ return problems
292
+
293
+
294
+ def _yaml_position(exc: yaml.YAMLError) -> str:
295
+ mark = getattr(exc, "problem_mark", None)
296
+ return f" at line {mark.line + 1}, column {mark.column + 1}" if mark is not None else ""
297
+
298
+
299
+ def _unreadable(path: Path, exc: OSError) -> str:
300
+ return f"cannot read {path}: {exc.strerror or type(exc).__name__}"
301
+
302
+
303
+ def _is_loopback(host: str) -> bool:
304
+ if host.lower() == "localhost":
305
+ return True
306
+ try:
307
+ return ipaddress.ip_address(host).is_loopback
308
+ except ValueError:
309
+ return False
310
+
311
+
312
+ def _plural(count: int, word: str) -> str:
313
+ return f"{count} {word}" if count == 1 else f"{count} {word}s"
314
+
315
+
316
+ def _on(flag: bool) -> str:
317
+ return "on" if flag else "off"
318
+
319
+
320
+ def _error(message: str) -> None:
321
+ print(f"error: {message}", file=sys.stderr)