mptyl/ThothII
1
0
Fork 0
Code Issues 25 Pull Requests Actions Packages Projects Releases 1 Wiki Activity

fix: complete evidence documentation contract

Browse Source
This commit is contained in:
marcopan
2026-08-09 20:47:30 +02:00
parent d77c08884b
commit d7264b843d
3 changed files with 69 additions and 13 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/contracts/workspace-evidence-v3.md
+15 -7
View File
@@ -37,7 +37,9 @@ have no whitespace, control character, backslash, userinfo, query, or fragment.
`authentication: none`; signed mode uses `authentication: signed_urls_file`. Defaults are
`authentication: none`, `connect_timeout_ms: 5000`, `read_timeout_ms: 30000`,
`max_bytes: 10485760`, `max_redirects: 5`, `allow_private_hosts: false`, and
`max_cache_bytes: 67108864`.
`max_cache_bytes: 67108864`. Public HTTP (`authentication: none`) uses the declared query-free
URIs directly and requires no Evidence credential file. Signed HTTP uses the installation file
contract below and preserves a mandatory one-to-one provenance mapping in declared-URI order.
### Example: http
@@ -72,6 +74,8 @@ Defaults are `credentials: ambient`, `trusted_endpoint: false`, `allow_private_e
`allow_insecure_endpoint: false`, `max_bytes: 10485760`, `max_objects: 10000`, `max_pages: 100`,
and `page_size: 1000` (and page size cannot exceed 1000). A custom endpoint requires
`trusted_endpoint: true`; an HTTP endpoint additionally requires `allow_insecure_endpoint: true`.
Endpoint-policy flags cannot be enabled without `endpoint_url`. Ambient S3
(`credentials: ambient`) uses the runtime provider chain and requires no Evidence credential file.
Static mode uses `credentials: static_files`, requires access-key and secret-key files together,
and permits an optional session-token file.
@@ -99,10 +103,14 @@ Safe: `s3://example-evidence/curated/`. Unsafe identities include
`s3://Invalid_Bucket/evidence` and `s3://example-evidence/evidence#section`. S3 userinfo and query
identities are rejected in prose and implementation; no credential-bearing example is published.
## Policy
## Policy and numeric domains
The strict policy defaults to `max_chunk_chars: 4000` and
`retain_published_generations: 3`.
`retain_published_generations: 3`. Filesystem `max_bytes`; HTTP `connect_timeout_ms`,
`read_timeout_ms`, `max_bytes`, and `max_cache_bytes`; S3 `max_bytes`, `max_objects`, `max_pages`,
and `page_size`; and both policy values must be positive safe integers from 1 through
9007199254740991. HTTP `max_redirects` must be a nonnegative safe integer from 0 through
9007199254740991. S3 `page_size` has the stricter maximum of 1000.
## Installation files
@@ -111,12 +119,12 @@ hold file paths, never credential or signed-URL values.
| Mode | Variable | File contract |
| --- | --- | --- |
| Signed HTTP | `THT_WS_<NAMESPACE>_EVIDENCE_SIGNED_URLS_FILE` | Required for `signed_urls_file`; nonempty JSON string array in declared-URI order; query-stripped identities must match `uris`. |
| Static S3 pair | `THT_WS_<NAMESPACE>_EVIDENCE_ACCESS_KEY_FILE` and `THT_WS_<NAMESPACE>_EVIDENCE_SECRET_KEY_FILE` | Required together for `static_files`. |
| Static S3 session | `THT_WS_<NAMESPACE>_EVIDENCE_SESSION_TOKEN_FILE` | Optional, and valid only with the required access/secret pair. |
| Signed HTTP | `THT_WS_<NAMESPACE>_EVIDENCE_SIGNED_URLS_FILE` | Required for `signed_urls_file`; at most 1048576 bytes; nonempty UTF-8 JSON string array in declared-URI order; query-stripped identities must match `uris` one-to-one. |
| Static S3 pair | `THT_WS_<NAMESPACE>_EVIDENCE_ACCESS_KEY_FILE` and `THT_WS_<NAMESPACE>_EVIDENCE_SECRET_KEY_FILE` | Required together for `static_files`; each file is at most 65536 bytes. |
| Static S3 session | `THT_WS_<NAMESPACE>_EVIDENCE_SESSION_TOKEN_FILE` | Optional, valid only with the required access/secret pair, and at most 65536 bytes. |
Every variable is an absolute path to a readable regular file whose resolved target is strictly below one of the roots configured by `THT_WORKSPACE_SECRET_ROOTS`. Scalar S3 files are nonempty
UTF-8 tokens without whitespace. Public docs, exports, and rendered YAML never expose file contents. `changeme`, `replace-me`, `YOUR_SECRET`, `<secret>`, access-key-looking strings, and any
UTF-8 tokens without whitespace or NUL. Public docs, exports, and rendered YAML never expose file contents. `changeme`, `replace-me`, `YOUR_SECRET`, `<secret>`, access-key-looking strings, and any
credential-bearing or query-bearing URI are forbidden as public placeholder values.
## One shared registry repository