docs/EMBEDDING.md · Oversight

126 lines · markdown

# Embedding the Oversight Verification Core
 
This document is the integration contract for downstream projects that want
to embed the Oversight Rust verification core. The first known consumer is
the [`oversight-mobile`](https://github.com/oversight-protocol/oversight-mobile)
Flutter + Rust verifier app, which embeds these crates via
`flutter_rust_bridge` so the desktop CLI and the mobile app share one
verification implementation. The same contract applies to any future
embedder (Electron, browser-wasm, server-side verifier, third-party tooling).
 
The goal is to give downstream consumers a stable, reproducible way to depend
on the verifier without forking the protocol or pinning to `main`.
 
## Verifier-safe crates
 
These seven crates are designed to be embedded and have no I/O or
sender-only surface. A consumer that wants to verify Oversight artifacts
should depend on these and only these.
 
| Crate | What it does |
|---|---|
| `oversight-crypto` | X25519, Ed25519, ChaCha20-Poly1305, HKDF-SHA256 primitives. Pure RustCrypto; no platform-specific code. |
| `oversight-manifest` | Manifest data structures, signature verification, canonicalization. |
| `oversight-container` | `.sealed` container parsing and authenticated decryption. |
| `oversight-tlog` | Transparency-log data structures and inclusion-proof verification. |
| `oversight-rekor` | Sigstore Rekor v2 client for fetching tree heads and inclusion proofs. |
| `oversight-watermark` | L1 zero-width and L2 whitespace watermark detection (read-only). |
| `oversight-policy` | Policy evaluation for unseal-time decisions (`allow`, `deny`, `warn`). |
 
These crates compile cleanly for desktop, iOS (`aarch64`), and Android
(`aarch64`, `armv7`, `x86_64`, `i686`). The 32-bit Android targets require
oversight v0.4.8 or later because of the `MAX_CIPHERTEXT_BYTES` portability
fix landed in that release.
 
## Crates not for embedding
 
These crates exist in the workspace but are not part of the embedding
contract. Depending on them from a downstream consumer will work today but
will couple the consumer to surface that is intentionally out of scope for a
verifier and that may change without an embedding-API minor bump.
 
| Crate | Why it is not for downstream embedding |
|---|---|
| `oversight-cli` | Desktop CLI binary. Pulls in TTY, file-tree, and Rich-formatted output. Not a library. |
| `oversight-registry` | Axum + SQLx registry server. Sender-side and operator-side; verifiers do not run a registry. |
| `oversight-formats` | PDF, DOCX, image DCT/LSB watermark application. Sender-only; pulls in heavy format dependencies that are wrong for a verifier binary's size budget. |
| `oversight-semantic` | L3 semantic synonym rotation. Sender-only; the verifier path uses `oversight-watermark` for L1/L2 detection only. |
 
A verifier-only embedder that finds it needs something from these crates is
probably reaching for the wrong API; open an issue describing the use case
before depending on them.
 
## Pin pattern
 
Embedders pin to a tagged release, never to `main` and never via a path
dependency. Path dependencies break reproducibility (the build is sensitive
to whatever sits next to the consumer's checkout) and break clone-and-build
for new contributors. Git plus tag is the supported pin.
 
```toml
[dependencies]
oversight-crypto    = { git = "https://github.com/oversight-protocol/oversight.git", tag = "v0.4.11" }
oversight-manifest  = { git = "https://github.com/oversight-protocol/oversight.git", tag = "v0.4.11" }
oversight-container = { git = "https://github.com/oversight-protocol/oversight.git", tag = "v0.4.11" }
oversight-tlog      = { git = "https://github.com/oversight-protocol/oversight.git", tag = "v0.4.11" }
oversight-rekor     = { git = "https://github.com/oversight-protocol/oversight.git", tag = "v0.4.11" }
oversight-watermark = { git = "https://github.com/oversight-protocol/oversight.git", tag = "v0.4.11" }
oversight-policy    = { git = "https://github.com/oversight-protocol/oversight.git", tag = "v0.4.11" }
```
 
Cargo resolves all seven entries against the same git checkout, so the
fetch happens once and every crate is byte-identical to what the desktop
CLI shipped against. `Cargo.lock` records the resolved commit
(`14547d9` for `v0.4.11`); a downstream consumer who commits their lock file
will get reproducible resolution across machines.
 
For a consumer that prefers a commit-sha pin over a tag pin, the same
pattern works with `rev` instead of `tag`. Tag is the recommended default
because tags are how the protocol announces release boundaries.
 
## Minimum versions
 
| Embedder target | Minimum oversight tag | Reason |
|---|---|---|
| Desktop / 64-bit only | `v0.4.5` | First release with hardened parser strictness. |
| Mobile with 64-bit Android only | `v0.4.5` | Same. |
| Mobile with 32-bit Android (`armv7`, `i686`) | `v0.4.8` | `MAX_CIPHERTEXT_BYTES` 4 GiB literal gated to 64-bit; falls back to `usize::MAX` on 32-bit. |
| Anyone needing the GHSA-82j2-j2ch-gfr8 CRL fix | `v0.4.8` | `rustls-webpki` lifted to 0.103.13. |
 
Older releases will continue to compile, but the project does not
backport security or portability fixes to anything below the current
stable line.
 
## Build profile expectations
 
The workspace's `[profile.release]` defaults are tuned for the desktop CLI:
unwinding panics, default codegen-units, debuginfo on. Embedders are free
to override the profile in their own `Cargo.toml`. The mobile companion's
release profile, for example, sets `lto = true`, `codegen-units = 1`,
`strip = true`, and `opt-level = "z"` for binary-size reasons. None of
those choices change the verifier's behavior; they are downstream concerns.
 
## Versioning expectations
 
The Rust workspace version is independent of the Python `oversight-protocol`
package version. The workspace tracks its own `[workspace.package].version`
in `oversight-rust/Cargo.toml`. Embedders that want a stable lib-API
contract should pin against the git tag of the desktop release, not the
workspace version. The git tag is the canonical Oversight release; the
workspace version is an implementation detail of the Rust members.
 
## Reporting integration issues
 
Open an issue at
[oversight-protocol/oversight](https://github.com/oversight-protocol/oversight/issues)
with the embedder name, the desktop tag the build pinned against, and the
target triple. The mobile companion is the worked example for what a
clean embedding looks like, including its CI configuration for cross-compile
to four Android ABIs and one iOS ABI.
 
## Referenced from
 
- [`oversight-protocol/oversight-mobile`](https://github.com/oversight-protocol/oversight-mobile)
  - Flutter + Rust verifier; embeds the seven verifier-safe crates via
  `flutter_rust_bridge`. Mobile `v0.1.13` tagged the `v0.4.9` pin; current
  mobile `main` pins the same seven crates to oversight `v0.4.11`.

1	# Embedding the Oversight Verification Core
2
3	This document is the integration contract for downstream projects that want
4	to embed the Oversight Rust verification core. The first known consumer is
5	the [`oversight-mobile`](https://github.com/oversight-protocol/oversight-mobile)
6	Flutter + Rust verifier app, which embeds these crates via
7	`flutter_rust_bridge` so the desktop CLI and the mobile app share one
8	verification implementation. The same contract applies to any future
9	embedder (Electron, browser-wasm, server-side verifier, third-party tooling).
10
11	The goal is to give downstream consumers a stable, reproducible way to depend
12	on the verifier without forking the protocol or pinning to `main`.
13
14	## Verifier-safe crates
15
16	These seven crates are designed to be embedded and have no I/O or
17	sender-only surface. A consumer that wants to verify Oversight artifacts
18	should depend on these and only these.
19
20	\| Crate \| What it does \|
21	\|---\|---\|
22	\| `oversight-crypto` \| X25519, Ed25519, ChaCha20-Poly1305, HKDF-SHA256 primitives. Pure RustCrypto; no platform-specific code. \|
23	\| `oversight-manifest` \| Manifest data structures, signature verification, canonicalization. \|
24	\| `oversight-container` \| `.sealed` container parsing and authenticated decryption. \|
25	\| `oversight-tlog` \| Transparency-log data structures and inclusion-proof verification. \|
26	\| `oversight-rekor` \| Sigstore Rekor v2 client for fetching tree heads and inclusion proofs. \|
27	\| `oversight-watermark` \| L1 zero-width and L2 whitespace watermark detection (read-only). \|
28	\| `oversight-policy` \| Policy evaluation for unseal-time decisions (`allow`, `deny`, `warn`). \|
29
30	These crates compile cleanly for desktop, iOS (`aarch64`), and Android
31	(`aarch64`, `armv7`, `x86_64`, `i686`). The 32-bit Android targets require
32	oversight v0.4.8 or later because of the `MAX_CIPHERTEXT_BYTES` portability
33	fix landed in that release.
34
35	## Crates not for embedding
36
37	These crates exist in the workspace but are not part of the embedding
38	contract. Depending on them from a downstream consumer will work today but
39	will couple the consumer to surface that is intentionally out of scope for a
40	verifier and that may change without an embedding-API minor bump.
41
42	\| Crate \| Why it is not for downstream embedding \|
43	\|---\|---\|
44	\| `oversight-cli` \| Desktop CLI binary. Pulls in TTY, file-tree, and Rich-formatted output. Not a library. \|
45	\| `oversight-registry` \| Axum + SQLx registry server. Sender-side and operator-side; verifiers do not run a registry. \|
46	\| `oversight-formats` \| PDF, DOCX, image DCT/LSB watermark application. Sender-only; pulls in heavy format dependencies that are wrong for a verifier binary's size budget. \|
47	\| `oversight-semantic` \| L3 semantic synonym rotation. Sender-only; the verifier path uses `oversight-watermark` for L1/L2 detection only. \|
48
49	A verifier-only embedder that finds it needs something from these crates is
50	probably reaching for the wrong API; open an issue describing the use case
51	before depending on them.
52
53	## Pin pattern
54
55	Embedders pin to a tagged release, never to `main` and never via a path
56	dependency. Path dependencies break reproducibility (the build is sensitive
57	to whatever sits next to the consumer's checkout) and break clone-and-build
58	for new contributors. Git plus tag is the supported pin.
59
60	```toml
61	[dependencies]
62	oversight-crypto = { git = "https://github.com/oversight-protocol/oversight.git", tag = "v0.4.11" }
63	oversight-manifest = { git = "https://github.com/oversight-protocol/oversight.git", tag = "v0.4.11" }
64	oversight-container = { git = "https://github.com/oversight-protocol/oversight.git", tag = "v0.4.11" }
65	oversight-tlog = { git = "https://github.com/oversight-protocol/oversight.git", tag = "v0.4.11" }
66	oversight-rekor = { git = "https://github.com/oversight-protocol/oversight.git", tag = "v0.4.11" }
67	oversight-watermark = { git = "https://github.com/oversight-protocol/oversight.git", tag = "v0.4.11" }
68	oversight-policy = { git = "https://github.com/oversight-protocol/oversight.git", tag = "v0.4.11" }
69	```
70
71	Cargo resolves all seven entries against the same git checkout, so the
72	fetch happens once and every crate is byte-identical to what the desktop
73	CLI shipped against. `Cargo.lock` records the resolved commit
74	(`14547d9` for `v0.4.11`); a downstream consumer who commits their lock file
75	will get reproducible resolution across machines.
76
77	For a consumer that prefers a commit-sha pin over a tag pin, the same
78	pattern works with `rev` instead of `tag`. Tag is the recommended default
79	because tags are how the protocol announces release boundaries.
80
81	## Minimum versions
82
83	\| Embedder target \| Minimum oversight tag \| Reason \|
84	\|---\|---\|---\|
85	\| Desktop / 64-bit only \| `v0.4.5` \| First release with hardened parser strictness. \|
86	\| Mobile with 64-bit Android only \| `v0.4.5` \| Same. \|
87	\| Mobile with 32-bit Android (`armv7`, `i686`) \| `v0.4.8` \| `MAX_CIPHERTEXT_BYTES` 4 GiB literal gated to 64-bit; falls back to `usize::MAX` on 32-bit. \|
88	\| Anyone needing the GHSA-82j2-j2ch-gfr8 CRL fix \| `v0.4.8` \| `rustls-webpki` lifted to 0.103.13. \|
89
90	Older releases will continue to compile, but the project does not
91	backport security or portability fixes to anything below the current
92	stable line.
93
94	## Build profile expectations
95
96	The workspace's `[profile.release]` defaults are tuned for the desktop CLI:
97	unwinding panics, default codegen-units, debuginfo on. Embedders are free
98	to override the profile in their own `Cargo.toml`. The mobile companion's
99	release profile, for example, sets `lto = true`, `codegen-units = 1`,
100	`strip = true`, and `opt-level = "z"` for binary-size reasons. None of
101	those choices change the verifier's behavior; they are downstream concerns.
102
103	## Versioning expectations
104
105	The Rust workspace version is independent of the Python `oversight-protocol`
106	package version. The workspace tracks its own `[workspace.package].version`
107	in `oversight-rust/Cargo.toml`. Embedders that want a stable lib-API
108	contract should pin against the git tag of the desktop release, not the
109	workspace version. The git tag is the canonical Oversight release; the
110	workspace version is an implementation detail of the Rust members.
111
112	## Reporting integration issues
113
114	Open an issue at
115	[oversight-protocol/oversight](https://github.com/oversight-protocol/oversight/issues)
116	with the embedder name, the desktop tag the build pinned against, and the
117	target triple. The mobile companion is the worked example for what a
118	clean embedding looks like, including its CI configuration for cross-compile
119	to four Android ABIs and one iOS ABI.
120
121	## Referenced from
122
123	- [`oversight-protocol/oversight-mobile`](https://github.com/oversight-protocol/oversight-mobile)
124	- Flutter + Rust verifier; embeds the seven verifier-safe crates via
125	`flutter_rust_bridge`. Mobile `v0.1.13` tagged the `v0.4.9` pin; current
126	mobile `main` pins the same seven crates to oversight `v0.4.11`.