punt-observe 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.
- punt_observe-0.1.0/LICENSE +21 -0
- punt_observe-0.1.0/PKG-INFO +122 -0
- punt_observe-0.1.0/README.md +108 -0
- punt_observe-0.1.0/pyproject.toml +69 -0
- punt_observe-0.1.0/pyproject.toml.orig +45 -0
- punt_observe-0.1.0/src/punt_observe/__init__.py +6 -0
- punt_observe-0.1.0/src/punt_observe/_private_fs.py +156 -0
- punt_observe-0.1.0/src/punt_observe/logging/__init__.py +15 -0
- punt_observe-0.1.0/src/punt_observe/logging/append_log.py +358 -0
- punt_observe-0.1.0/src/punt_observe/logging/authority_mask.py +278 -0
- punt_observe-0.1.0/src/punt_observe/logging/config.py +100 -0
- punt_observe-0.1.0/src/punt_observe/logging/formatter.py +62 -0
- punt_observe-0.1.0/src/punt_observe/logging/handler.py +70 -0
- punt_observe-0.1.0/src/punt_observe/logging/log_form.py +45 -0
- punt_observe-0.1.0/src/punt_observe/logging/redactor.py +299 -0
- punt_observe-0.1.0/src/punt_observe/logging/sanitize.py +18 -0
- punt_observe-0.1.0/src/punt_observe/py.typed +0 -0
- punt_observe-0.1.0/src/punt_observe/telemetry/__init__.py +35 -0
- punt_observe-0.1.0/src/punt_observe/telemetry/_diagnostics.py +31 -0
- punt_observe-0.1.0/src/punt_observe/telemetry/_exit.py +95 -0
- punt_observe-0.1.0/src/punt_observe/telemetry/_fork.py +47 -0
- punt_observe-0.1.0/src/punt_observe/telemetry/_hash_provenance.py +3 -0
- punt_observe-0.1.0/src/punt_observe/telemetry/_pruning.py +39 -0
- punt_observe-0.1.0/src/punt_observe/telemetry/api.py +258 -0
- punt_observe-0.1.0/src/punt_observe/telemetry/config.py +52 -0
- punt_observe-0.1.0/src/punt_observe/telemetry/otlp.py +87 -0
- punt_observe-0.1.0/src/punt_observe/telemetry/providers.py +238 -0
- punt_observe-0.1.0/src/punt_observe/telemetry/salt.py +95 -0
- punt_observe-0.1.0/src/punt_observe/telemetry/schema.py +221 -0
- punt_observe-0.1.0/src/punt_observe/telemetry/sqlite_exporter.py +266 -0
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Punt Labs
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1,122 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: punt-observe
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Private diagnostics and privacy-safe telemetry for Punt Labs
|
|
5
|
+
Author: Punt Labs
|
|
6
|
+
License-Expression: MIT
|
|
7
|
+
License-File: LICENSE
|
|
8
|
+
Requires-Dist: opentelemetry-api>=1.39,<2
|
|
9
|
+
Requires-Dist: opentelemetry-sdk>=1.39,<2
|
|
10
|
+
Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.39,<2 ; extra == 'otlp'
|
|
11
|
+
Requires-Python: >=3.13
|
|
12
|
+
Provides-Extra: otlp
|
|
13
|
+
Description-Content-Type: text/markdown
|
|
14
|
+
|
|
15
|
+
# punt-observe
|
|
16
|
+
|
|
17
|
+
Shared private diagnostics and privacy-safe local telemetry for Punt Labs Python tools.
|
|
18
|
+
Python 3.13+, Linux and macOS. Licensed under MIT.
|
|
19
|
+
|
|
20
|
+
## Install
|
|
21
|
+
|
|
22
|
+
```sh
|
|
23
|
+
uv add punt-observe
|
|
24
|
+
# Optional network exporter:
|
|
25
|
+
uv add 'punt-observe[otlp]'
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
## Diagnostics
|
|
29
|
+
|
|
30
|
+
Each CLI, MCP, hook, daemon and detached worker configures its own role. Libraries
|
|
31
|
+
only create module loggers. No output is written to stdout.
|
|
32
|
+
|
|
33
|
+
```python
|
|
34
|
+
import logging
|
|
35
|
+
from punt_observe.logging import configure_logging
|
|
36
|
+
|
|
37
|
+
configure_logging("my-tool", "cli")
|
|
38
|
+
logger = logging.getLogger(__name__)
|
|
39
|
+
logger.info("Completed operation: items=%d", 3)
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
Files live at `~/.punt-labs/my-tool/logs/my-tool.log`, UTF-8, INFO by default,
|
|
43
|
+
5 MiB plus five backups. Directories are 0700; files and backups are 0600.
|
|
44
|
+
Rotation is safe across cooperating processes using a stable flock lock.
|
|
45
|
+
Setup permission failures raise `LoggingSetupError`; append failures are best-effort.
|
|
46
|
+
Final formatted records are redacted, control-escaped and bounded to 64 KiB including
|
|
47
|
+
their newline. Redaction is defense in depth: **never log content or secrets**.
|
|
48
|
+
|
|
49
|
+
## Telemetry
|
|
50
|
+
|
|
51
|
+
Declare schemas once; instrument through the facade, never an exporter.
|
|
52
|
+
|
|
53
|
+
```python
|
|
54
|
+
from punt_observe.telemetry import (
|
|
55
|
+
EnumAttr,
|
|
56
|
+
HashAttr,
|
|
57
|
+
SignalSchema,
|
|
58
|
+
TelemetryConfig,
|
|
59
|
+
open_telemetry,
|
|
60
|
+
)
|
|
61
|
+
|
|
62
|
+
schemas = [
|
|
63
|
+
SignalSchema(
|
|
64
|
+
"my-tool.cli.run",
|
|
65
|
+
1,
|
|
66
|
+
"span",
|
|
67
|
+
{
|
|
68
|
+
"outcome": EnumAttr(("ok", "error")),
|
|
69
|
+
"item": HashAttr(),
|
|
70
|
+
},
|
|
71
|
+
)
|
|
72
|
+
]
|
|
73
|
+
telemetry = open_telemetry("my-tool", schemas, TelemetryConfig())
|
|
74
|
+
with telemetry.span("my-tool.cli.run", 1, item=telemetry.hash_id("local-id")):
|
|
75
|
+
pass # Perform the operation. Exceptions propagate without recording text.
|
|
76
|
+
telemetry.shutdown(timeout_s=2)
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
Use `event(name, version, **attrs)`, `count(name, version, n=1, **attrs)` or
|
|
80
|
+
`record(name, version, value, **attrs)` with matching event/counter/histogram schemas.
|
|
81
|
+
Attribute types: closed EnumAttr, BoolAttr, IntAttr, DurationAttr (ms), CountAttr,
|
|
82
|
+
SizeAttr (By), LengthAttr and HashAttr. Unknown attributes/versions, wrong types,
|
|
83
|
+
free text and arbitrary strings posing as hashes are dropped before OTel.
|
|
84
|
+
Only explicit schema-derived lengths and salted hashes may derive from content.
|
|
85
|
+
|
|
86
|
+
Local SQLite capture defaults on at `~/.punt-labs/my-tool/telemetry.db`, separate
|
|
87
|
+
from diagnostics. Store and SQLite sidecars are private, retained 90 days by
|
|
88
|
+
default (configurable 1–3650); startup and hourly export-triggered pruning reclaim
|
|
89
|
+
space incrementally. Per-install salt is `~/.punt-labs/telemetry.salt` (0600).
|
|
90
|
+
|
|
91
|
+
**Any off switch wins:** `PUNT_TELEMETRY=off`, `MY_TOOL_TELEMETRY=off`, or
|
|
92
|
+
`TelemetryConfig(enabled=False)`. Also accepts 0/false/no, case-insensitively.
|
|
93
|
+
Disabled telemetry creates no store, salt, provider or worker.
|
|
94
|
+
|
|
95
|
+
Network export requires `TelemetryConfig(exporter="otlp", otlp_consent=True,
|
|
96
|
+
otlp_endpoint="https://collector.example")`. Environment variables
|
|
97
|
+
`PUNT_TELEMETRY_EXPORTER` and `PUNT_TELEMETRY_OTLP_ENDPOINT` may select the
|
|
98
|
+
exporter/endpoint but **cannot grant consent**. Missing optional OTLP dependency
|
|
99
|
+
falls back to SQLite. Instrumentation stays identical.
|
|
100
|
+
|
|
101
|
+
Providers are private, never process-global. Pending span export is bounded at
|
|
102
|
+
2048; saturation drops records, not tool results. Shutdown bounds waiting; a
|
|
103
|
+
misbehaving exporter may finish on a daemon thread after the deadline.
|
|
104
|
+
`shutdown(timeout_s=2)` force-flushes pending metrics, spans and events without
|
|
105
|
+
waiting for their periodic export interval. As a fallback, normal Python exit
|
|
106
|
+
(including `sys.exit` or an uncaught `KeyboardInterrupt`) flushes pending live
|
|
107
|
+
providers through one atexit registry, with a **two-second total** wait across
|
|
108
|
+
all instances. Explicitly shut-down instances and forked children that have not
|
|
109
|
+
emitted do no exit work. Explicit shutdown remains the preferred lifecycle.
|
|
110
|
+
|
|
111
|
+
**The library never installs signal handlers.** A SIGTERM with its default
|
|
112
|
+
disposition skips atexit, as do SIGKILL and `os._exit`. Daemons must convert
|
|
113
|
+
SIGTERM into normal Python unwinding (for example, raise `SystemExit`), or call
|
|
114
|
+
`shutdown` before terminating. A server that restores and re-raises default
|
|
115
|
+
SIGTERM before an outer telemetry context unwinds still skips that context and
|
|
116
|
+
atexit; move explicit shutdown into its graceful lifecycle instead.
|
|
117
|
+
|
|
118
|
+
## Development
|
|
119
|
+
|
|
120
|
+
`uv sync --frozen`; `make check`; `make build`. CI checks Linux and macOS.
|
|
121
|
+
`make help` lists targets. The original append protocol is from punt-labs/vox;
|
|
122
|
+
redaction and URL grammar are from punt-labs/quarry (MIT, Punt Labs).
|
|
@@ -0,0 +1,108 @@
|
|
|
1
|
+
# punt-observe
|
|
2
|
+
|
|
3
|
+
Shared private diagnostics and privacy-safe local telemetry for Punt Labs Python tools.
|
|
4
|
+
Python 3.13+, Linux and macOS. Licensed under MIT.
|
|
5
|
+
|
|
6
|
+
## Install
|
|
7
|
+
|
|
8
|
+
```sh
|
|
9
|
+
uv add punt-observe
|
|
10
|
+
# Optional network exporter:
|
|
11
|
+
uv add 'punt-observe[otlp]'
|
|
12
|
+
```
|
|
13
|
+
|
|
14
|
+
## Diagnostics
|
|
15
|
+
|
|
16
|
+
Each CLI, MCP, hook, daemon and detached worker configures its own role. Libraries
|
|
17
|
+
only create module loggers. No output is written to stdout.
|
|
18
|
+
|
|
19
|
+
```python
|
|
20
|
+
import logging
|
|
21
|
+
from punt_observe.logging import configure_logging
|
|
22
|
+
|
|
23
|
+
configure_logging("my-tool", "cli")
|
|
24
|
+
logger = logging.getLogger(__name__)
|
|
25
|
+
logger.info("Completed operation: items=%d", 3)
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
Files live at `~/.punt-labs/my-tool/logs/my-tool.log`, UTF-8, INFO by default,
|
|
29
|
+
5 MiB plus five backups. Directories are 0700; files and backups are 0600.
|
|
30
|
+
Rotation is safe across cooperating processes using a stable flock lock.
|
|
31
|
+
Setup permission failures raise `LoggingSetupError`; append failures are best-effort.
|
|
32
|
+
Final formatted records are redacted, control-escaped and bounded to 64 KiB including
|
|
33
|
+
their newline. Redaction is defense in depth: **never log content or secrets**.
|
|
34
|
+
|
|
35
|
+
## Telemetry
|
|
36
|
+
|
|
37
|
+
Declare schemas once; instrument through the facade, never an exporter.
|
|
38
|
+
|
|
39
|
+
```python
|
|
40
|
+
from punt_observe.telemetry import (
|
|
41
|
+
EnumAttr,
|
|
42
|
+
HashAttr,
|
|
43
|
+
SignalSchema,
|
|
44
|
+
TelemetryConfig,
|
|
45
|
+
open_telemetry,
|
|
46
|
+
)
|
|
47
|
+
|
|
48
|
+
schemas = [
|
|
49
|
+
SignalSchema(
|
|
50
|
+
"my-tool.cli.run",
|
|
51
|
+
1,
|
|
52
|
+
"span",
|
|
53
|
+
{
|
|
54
|
+
"outcome": EnumAttr(("ok", "error")),
|
|
55
|
+
"item": HashAttr(),
|
|
56
|
+
},
|
|
57
|
+
)
|
|
58
|
+
]
|
|
59
|
+
telemetry = open_telemetry("my-tool", schemas, TelemetryConfig())
|
|
60
|
+
with telemetry.span("my-tool.cli.run", 1, item=telemetry.hash_id("local-id")):
|
|
61
|
+
pass # Perform the operation. Exceptions propagate without recording text.
|
|
62
|
+
telemetry.shutdown(timeout_s=2)
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
Use `event(name, version, **attrs)`, `count(name, version, n=1, **attrs)` or
|
|
66
|
+
`record(name, version, value, **attrs)` with matching event/counter/histogram schemas.
|
|
67
|
+
Attribute types: closed EnumAttr, BoolAttr, IntAttr, DurationAttr (ms), CountAttr,
|
|
68
|
+
SizeAttr (By), LengthAttr and HashAttr. Unknown attributes/versions, wrong types,
|
|
69
|
+
free text and arbitrary strings posing as hashes are dropped before OTel.
|
|
70
|
+
Only explicit schema-derived lengths and salted hashes may derive from content.
|
|
71
|
+
|
|
72
|
+
Local SQLite capture defaults on at `~/.punt-labs/my-tool/telemetry.db`, separate
|
|
73
|
+
from diagnostics. Store and SQLite sidecars are private, retained 90 days by
|
|
74
|
+
default (configurable 1–3650); startup and hourly export-triggered pruning reclaim
|
|
75
|
+
space incrementally. Per-install salt is `~/.punt-labs/telemetry.salt` (0600).
|
|
76
|
+
|
|
77
|
+
**Any off switch wins:** `PUNT_TELEMETRY=off`, `MY_TOOL_TELEMETRY=off`, or
|
|
78
|
+
`TelemetryConfig(enabled=False)`. Also accepts 0/false/no, case-insensitively.
|
|
79
|
+
Disabled telemetry creates no store, salt, provider or worker.
|
|
80
|
+
|
|
81
|
+
Network export requires `TelemetryConfig(exporter="otlp", otlp_consent=True,
|
|
82
|
+
otlp_endpoint="https://collector.example")`. Environment variables
|
|
83
|
+
`PUNT_TELEMETRY_EXPORTER` and `PUNT_TELEMETRY_OTLP_ENDPOINT` may select the
|
|
84
|
+
exporter/endpoint but **cannot grant consent**. Missing optional OTLP dependency
|
|
85
|
+
falls back to SQLite. Instrumentation stays identical.
|
|
86
|
+
|
|
87
|
+
Providers are private, never process-global. Pending span export is bounded at
|
|
88
|
+
2048; saturation drops records, not tool results. Shutdown bounds waiting; a
|
|
89
|
+
misbehaving exporter may finish on a daemon thread after the deadline.
|
|
90
|
+
`shutdown(timeout_s=2)` force-flushes pending metrics, spans and events without
|
|
91
|
+
waiting for their periodic export interval. As a fallback, normal Python exit
|
|
92
|
+
(including `sys.exit` or an uncaught `KeyboardInterrupt`) flushes pending live
|
|
93
|
+
providers through one atexit registry, with a **two-second total** wait across
|
|
94
|
+
all instances. Explicitly shut-down instances and forked children that have not
|
|
95
|
+
emitted do no exit work. Explicit shutdown remains the preferred lifecycle.
|
|
96
|
+
|
|
97
|
+
**The library never installs signal handlers.** A SIGTERM with its default
|
|
98
|
+
disposition skips atexit, as do SIGKILL and `os._exit`. Daemons must convert
|
|
99
|
+
SIGTERM into normal Python unwinding (for example, raise `SystemExit`), or call
|
|
100
|
+
`shutdown` before terminating. A server that restores and re-raises default
|
|
101
|
+
SIGTERM before an outer telemetry context unwinds still skips that context and
|
|
102
|
+
atexit; move explicit shutdown into its graceful lifecycle instead.
|
|
103
|
+
|
|
104
|
+
## Development
|
|
105
|
+
|
|
106
|
+
`uv sync --frozen`; `make check`; `make build`. CI checks Linux and macOS.
|
|
107
|
+
`make help` lists targets. The original append protocol is from punt-labs/vox;
|
|
108
|
+
redaction and URL grammar are from punt-labs/quarry (MIT, Punt Labs).
|
|
@@ -0,0 +1,69 @@
|
|
|
1
|
+
[project]
|
|
2
|
+
name = "punt-observe"
|
|
3
|
+
version = "0.1.0"
|
|
4
|
+
description = "Private diagnostics and privacy-safe telemetry for Punt Labs"
|
|
5
|
+
requires-python = ">=3.13"
|
|
6
|
+
license = "MIT"
|
|
7
|
+
license-files = ["LICENSE"]
|
|
8
|
+
readme = "README.md"
|
|
9
|
+
dependencies = [
|
|
10
|
+
"opentelemetry-api>=1.39,<2",
|
|
11
|
+
"opentelemetry-sdk>=1.39,<2",
|
|
12
|
+
]
|
|
13
|
+
|
|
14
|
+
[[project.authors]]
|
|
15
|
+
name = "Punt Labs"
|
|
16
|
+
|
|
17
|
+
[project.optional-dependencies]
|
|
18
|
+
otlp = ["opentelemetry-exporter-otlp-proto-http>=1.39,<2"]
|
|
19
|
+
|
|
20
|
+
[dependency-groups]
|
|
21
|
+
dev = [
|
|
22
|
+
"pytest>=8,<10",
|
|
23
|
+
"hypothesis>=6,<7",
|
|
24
|
+
"ruff>=0.11",
|
|
25
|
+
"mypy>=1.15",
|
|
26
|
+
"pyright>=1.1",
|
|
27
|
+
]
|
|
28
|
+
|
|
29
|
+
[build-system]
|
|
30
|
+
requires = ["uv_build>=0.9.14,<0.14"]
|
|
31
|
+
build-backend = "uv_build"
|
|
32
|
+
|
|
33
|
+
[tool.uv.build-backend]
|
|
34
|
+
module-name = "punt_observe"
|
|
35
|
+
|
|
36
|
+
[tool.ruff]
|
|
37
|
+
line-length = 88
|
|
38
|
+
target-version = "py313"
|
|
39
|
+
|
|
40
|
+
[tool.ruff.lint]
|
|
41
|
+
select = [
|
|
42
|
+
"E",
|
|
43
|
+
"F",
|
|
44
|
+
"I",
|
|
45
|
+
"UP",
|
|
46
|
+
"B",
|
|
47
|
+
"SIM",
|
|
48
|
+
"LOG",
|
|
49
|
+
"G",
|
|
50
|
+
"T20",
|
|
51
|
+
]
|
|
52
|
+
|
|
53
|
+
[tool.ruff.lint.pydocstyle]
|
|
54
|
+
convention = "google"
|
|
55
|
+
|
|
56
|
+
[tool.mypy]
|
|
57
|
+
python_version = "3.13"
|
|
58
|
+
strict = true
|
|
59
|
+
|
|
60
|
+
[tool.pyright]
|
|
61
|
+
pythonVersion = "3.13"
|
|
62
|
+
typeCheckingMode = "strict"
|
|
63
|
+
include = [
|
|
64
|
+
"src",
|
|
65
|
+
"tests",
|
|
66
|
+
]
|
|
67
|
+
|
|
68
|
+
[tool.pytest.ini_options]
|
|
69
|
+
testpaths = ["tests"]
|
|
@@ -0,0 +1,45 @@
|
|
|
1
|
+
[project]
|
|
2
|
+
name = "punt-observe"
|
|
3
|
+
version = "0.1.0"
|
|
4
|
+
description = "Private diagnostics and privacy-safe telemetry for Punt Labs"
|
|
5
|
+
requires-python = ">=3.13"
|
|
6
|
+
license = "MIT"
|
|
7
|
+
license-files = ["LICENSE"]
|
|
8
|
+
authors = [{name = "Punt Labs"}]
|
|
9
|
+
readme = "README.md"
|
|
10
|
+
dependencies = ["opentelemetry-api>=1.39,<2", "opentelemetry-sdk>=1.39,<2"]
|
|
11
|
+
|
|
12
|
+
[project.optional-dependencies]
|
|
13
|
+
otlp = ["opentelemetry-exporter-otlp-proto-http>=1.39,<2"]
|
|
14
|
+
|
|
15
|
+
[dependency-groups]
|
|
16
|
+
dev = ["pytest>=8,<10", "hypothesis>=6,<7", "ruff>=0.11", "mypy>=1.15", "pyright>=1.1"]
|
|
17
|
+
|
|
18
|
+
[build-system]
|
|
19
|
+
requires = ["uv_build>=0.9.14,<0.14"]
|
|
20
|
+
build-backend = "uv_build"
|
|
21
|
+
|
|
22
|
+
[tool.uv.build-backend]
|
|
23
|
+
module-name = "punt_observe"
|
|
24
|
+
|
|
25
|
+
[tool.ruff]
|
|
26
|
+
line-length = 88
|
|
27
|
+
target-version = "py313"
|
|
28
|
+
|
|
29
|
+
[tool.ruff.lint]
|
|
30
|
+
select = ["E", "F", "I", "UP", "B", "SIM", "LOG", "G", "T20"]
|
|
31
|
+
|
|
32
|
+
[tool.ruff.lint.pydocstyle]
|
|
33
|
+
convention = "google"
|
|
34
|
+
|
|
35
|
+
[tool.mypy]
|
|
36
|
+
python_version = "3.13"
|
|
37
|
+
strict = true
|
|
38
|
+
|
|
39
|
+
[tool.pyright]
|
|
40
|
+
pythonVersion = "3.13"
|
|
41
|
+
typeCheckingMode = "strict"
|
|
42
|
+
include = ["src", "tests"]
|
|
43
|
+
|
|
44
|
+
[tool.pytest.ini_options]
|
|
45
|
+
testpaths = ["tests"]
|
|
@@ -0,0 +1,156 @@
|
|
|
1
|
+
"""Secure owner-only regular files before opening diagnostic or telemetry sinks."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
import os
|
|
6
|
+
import re
|
|
7
|
+
import stat
|
|
8
|
+
import tempfile
|
|
9
|
+
from pathlib import Path
|
|
10
|
+
from typing import Self
|
|
11
|
+
|
|
12
|
+
|
|
13
|
+
class PrivatePaths:
|
|
14
|
+
"""Prepare private directories and files, refusing symlink leaves."""
|
|
15
|
+
|
|
16
|
+
_path: Path
|
|
17
|
+
|
|
18
|
+
def __new__(cls, path: Path) -> Self:
|
|
19
|
+
self = super().__new__(cls)
|
|
20
|
+
self._path = path
|
|
21
|
+
return self
|
|
22
|
+
|
|
23
|
+
@staticmethod
|
|
24
|
+
def root(tool: str | None = None) -> Path:
|
|
25
|
+
"""Resolve the home namespace, rejecting unsafe tool names.
|
|
26
|
+
|
|
27
|
+
Raises:
|
|
28
|
+
ValueError: The tool name is not a bounded lowercase slug.
|
|
29
|
+
"""
|
|
30
|
+
root = Path.home() / ".punt-labs"
|
|
31
|
+
if tool is None:
|
|
32
|
+
return root
|
|
33
|
+
if re.fullmatch(r"[a-z][a-z0-9-]{0,63}", tool) is None:
|
|
34
|
+
raise ValueError("invalid tool name")
|
|
35
|
+
return root / tool
|
|
36
|
+
|
|
37
|
+
@classmethod
|
|
38
|
+
def for_append_sink(cls, path: Path) -> PrivatePaths:
|
|
39
|
+
"""Bind the private path used by vox's append protocol."""
|
|
40
|
+
return cls(path)
|
|
41
|
+
|
|
42
|
+
@staticmethod
|
|
43
|
+
def ensure_directory(path: Path) -> None:
|
|
44
|
+
"""Create and tighten private directories without following symlink ancestors.
|
|
45
|
+
|
|
46
|
+
Raises:
|
|
47
|
+
OSError: The directory cannot be secured.
|
|
48
|
+
"""
|
|
49
|
+
fd = PrivatePaths._directory_fd(path, create=True)
|
|
50
|
+
os.close(fd)
|
|
51
|
+
|
|
52
|
+
@classmethod
|
|
53
|
+
def _directory_fd(cls, path: Path, *, create: bool) -> int:
|
|
54
|
+
path = path.absolute()
|
|
55
|
+
if ".." in path.parts:
|
|
56
|
+
raise OSError("parent traversal is not allowed")
|
|
57
|
+
anchors = (
|
|
58
|
+
Path.home(),
|
|
59
|
+
Path(tempfile.gettempdir()),
|
|
60
|
+
Path("/tmp"),
|
|
61
|
+
Path("/var/tmp"),
|
|
62
|
+
)
|
|
63
|
+
anchor = max(
|
|
64
|
+
(
|
|
65
|
+
p.absolute()
|
|
66
|
+
for p in anchors
|
|
67
|
+
if path.is_relative_to(p.absolute()) and p.is_dir()
|
|
68
|
+
),
|
|
69
|
+
key=lambda p: len(p.parts),
|
|
70
|
+
default=Path("/"),
|
|
71
|
+
)
|
|
72
|
+
flags = os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW
|
|
73
|
+
fd = os.open(anchor.resolve(strict=True), flags)
|
|
74
|
+
current = anchor
|
|
75
|
+
root = cls.root().absolute()
|
|
76
|
+
try:
|
|
77
|
+
for part in path.relative_to(anchor).parts:
|
|
78
|
+
current /= part
|
|
79
|
+
created = False
|
|
80
|
+
if create:
|
|
81
|
+
try:
|
|
82
|
+
os.mkdir(part, mode=0o700, dir_fd=fd)
|
|
83
|
+
created = True
|
|
84
|
+
except FileExistsError:
|
|
85
|
+
pass
|
|
86
|
+
child = os.open(part, flags, dir_fd=fd)
|
|
87
|
+
os.close(fd)
|
|
88
|
+
fd = child
|
|
89
|
+
if created or current in (path, root) or root in current.parents:
|
|
90
|
+
info = os.fstat(fd)
|
|
91
|
+
if info.st_uid != os.getuid():
|
|
92
|
+
raise PermissionError(
|
|
93
|
+
"directory is not owned by the current user"
|
|
94
|
+
)
|
|
95
|
+
if stat.S_IMODE(info.st_mode) != 0o700:
|
|
96
|
+
os.fchmod(fd, 0o700)
|
|
97
|
+
return fd
|
|
98
|
+
except BaseException:
|
|
99
|
+
os.close(fd)
|
|
100
|
+
raise
|
|
101
|
+
|
|
102
|
+
def ensure_private_tree(self) -> None:
|
|
103
|
+
"""Secure every owned namespace level through the immediate parent.
|
|
104
|
+
|
|
105
|
+
Raises:
|
|
106
|
+
OSError: The directory cannot be secured.
|
|
107
|
+
"""
|
|
108
|
+
self.ensure_directory(self._path.parent)
|
|
109
|
+
|
|
110
|
+
def open_private(self, flags: int) -> int:
|
|
111
|
+
"""Open a regular file privately and tighten the returned descriptor.
|
|
112
|
+
|
|
113
|
+
Raises:
|
|
114
|
+
OSError: Opening or tightening the file failed.
|
|
115
|
+
"""
|
|
116
|
+
parent = self._directory_fd(self._path.parent, create=False)
|
|
117
|
+
open_flags = flags | os.O_NOFOLLOW | os.O_NONBLOCK
|
|
118
|
+
try:
|
|
119
|
+
try:
|
|
120
|
+
fd = os.open(self._path.name, open_flags, 0o600, dir_fd=parent)
|
|
121
|
+
except FileNotFoundError:
|
|
122
|
+
if not flags & os.O_CREAT or flags & os.O_EXCL:
|
|
123
|
+
raise
|
|
124
|
+
fd = os.open(self._path.name, open_flags, 0o600, dir_fd=parent)
|
|
125
|
+
finally:
|
|
126
|
+
os.close(parent)
|
|
127
|
+
try:
|
|
128
|
+
info = os.fstat(fd)
|
|
129
|
+
if not stat.S_ISREG(info.st_mode):
|
|
130
|
+
raise OSError("not a regular file")
|
|
131
|
+
if info.st_uid != os.getuid():
|
|
132
|
+
raise PermissionError("file is not owned by the current user")
|
|
133
|
+
if not flags & os.O_NONBLOCK:
|
|
134
|
+
os.set_blocking(fd, True)
|
|
135
|
+
if stat.S_IMODE(info.st_mode) != 0o600:
|
|
136
|
+
os.fchmod(fd, 0o600)
|
|
137
|
+
except BaseException:
|
|
138
|
+
os.close(fd)
|
|
139
|
+
raise
|
|
140
|
+
return fd
|
|
141
|
+
|
|
142
|
+
def secure(self) -> None:
|
|
143
|
+
"""Precreate a private leaf or tighten the existing regular file.
|
|
144
|
+
|
|
145
|
+
Raises:
|
|
146
|
+
OSError: The directory or file cannot be secured.
|
|
147
|
+
"""
|
|
148
|
+
self.ensure_private_tree()
|
|
149
|
+
try:
|
|
150
|
+
fd = self.open_private(os.O_WRONLY | os.O_CREAT | os.O_EXCL)
|
|
151
|
+
except FileExistsError:
|
|
152
|
+
try:
|
|
153
|
+
fd = self.open_private(os.O_WRONLY)
|
|
154
|
+
except FileNotFoundError:
|
|
155
|
+
return
|
|
156
|
+
os.close(fd)
|
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
"""Expose shared private logging configuration and redaction primitives."""
|
|
2
|
+
|
|
3
|
+
from punt_observe.logging.append_log import AtomicAppendLog
|
|
4
|
+
from punt_observe.logging.config import LoggingSetupError, Role, configure_logging
|
|
5
|
+
from punt_observe.logging.redactor import LogRedactor
|
|
6
|
+
from punt_observe.logging.sanitize import escape
|
|
7
|
+
|
|
8
|
+
__all__ = [
|
|
9
|
+
"AtomicAppendLog",
|
|
10
|
+
"LoggingSetupError",
|
|
11
|
+
"Role",
|
|
12
|
+
"configure_logging",
|
|
13
|
+
"LogRedactor",
|
|
14
|
+
"escape",
|
|
15
|
+
]
|