Metadata-Version: 2.4
Name: somanyfacts
Version: 0.2.1
Summary: Layered factbases for organizations, accessed by agents
License-Expression: AGPL-3.0-only
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: psycopg[binary]>=3.2
Requires-Dist: PyYAML>=6
Requires-Dist: cryptography>=42
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: pytest-cov>=5; extra == "dev"
Requires-Dist: ruff<0.17,>=0.16; extra == "dev"
Dynamic: license-file

# SoManyFacts as a library

The `0.2.x` series of `somanyfacts` is installed by another product as one dependency:
`pip install "somanyfacts>=0.2,<0.3"`. This page names the five modules and the names in them that the series
keeps. A test in the repository, `tests/test_library_surface.py`, imports each name below and fails if one is
removed or renamed.

## Compatibility

In `0.2.x` the names below are only added to, never removed, renamed or given a different meaning: a new name or
a new optional argument may appear, an existing one does not change. `0.3` may rename or remove any name, change
what a function returns, or change the database layout. A product that pins `>=0.2,<0.3` is not affected by `0.3`
until it moves the pin.

## Modules and names

### `somanyfacts.canonical`

Canonical JSON bytes and hashes, the same on every machine.

- `canonical_bytes`: a value as sorted-key, compact, UTF-8 JSON bytes, after `normalize`.
- `canonical_hash`: the SHA-256 of `canonical_bytes`, as 64 lowercase hex characters.
- `sha256_hex`: the SHA-256 of bytes, as hex.
- `normalize`: a deep copy with every text in Unicode NFC form; refuses values that would serialise ambiguously.
- `nfc`: one text in NFC form.
- `parse_ts`, `format_ts`: an RFC 3339 timestamp to a UTC datetime and back (`YYYY-MM-DDTHH:MM:SSZ`); naive times are refused.
- `ValidationError`: raised for refused values; its `code` says why.

### `somanyfacts.sealing`

Encrypted storage of sealed facts and their data keys.

- `KeyStore`: the key store in a PostgreSQL database. Methods the product may use: `KeyStore.get`, `KeyStore.destroy` (erases a key, and with it the fact), `KeyStore.wrap_all`, `KeyStore.close`.
- `words`: the search words of a text (lowercase, two characters or more, a trailing plural "s" dropped).
- `SEALED_LABELS`: the labels whose facts are sealed, `("confidential", "restricted")`.

### `somanyfacts.keywrap`

Wrapping of data keys, so a copy of the key store alone opens nothing.

- `LocalWrapper`: wraps under a 32-byte master key.
- `TransitWrapper`: wraps through an OpenBao or Vault transit engine.
- `Wrapper`: the type of either wrapper; both have `wrap(key_id, key)` and `unwrap(key_id, wrapped)`.
- `from_env`: picks a wrapper from `SF_TRANSIT_ADDR` and `SF_TRANSIT_TOKEN`, or from `SF_MASTER_KEY`, or returns `None`.

### `somanyfacts.anchors`

Signed audit anchors. It signs and verifies Ed25519 anchors and nothing else. It does not talk to Rekor, and no Rekor
client is part of `0.2.x`.

- `AnchorSigner`: holds an Ed25519 private key. Methods: `AnchorSigner.generate`, `AnchorSigner.from_file`, `AnchorSigner.from_env`, `AnchorSigner.sign`, `AnchorSigner.public_pem`, `AnchorSigner.verify`.
- `verify`: checks a signature against a public key, an audit position and a head; returns `True` or `False`.

### `somanyfacts.db`

- `TempCluster`: a private PostgreSQL cluster in a temp directory, on a Unix socket, for tests. Needs PostgreSQL server binaries (set `SF_PG_BIN` if they are not found). Methods: `TempCluster.start`, `TempCluster.dsn`, `TempCluster.create_database`, `TempCluster.dump`, `TempCluster.restore`, `TempCluster.stop`.

## What the product must not import or expect

- Any other module of `somanyfacts` (the gateway, the HTTP API, the importer, the organization tools and so on) is not part of the surface and may change in any release.
- Names starting with an underscore, and SQL held in module constants, are private.
- No Rekor client, no transparency-log upload and no other anchor signature type than Ed25519 exist in `0.2.x`.
- The database layout is not a contract; reach it through the names above.
