Metadata-Version: 2.4
Name: pregen-registry
Version: 0.3.0
Summary: Reference PRE-GEN registry: ask before you generate, get a signed answer anyone can check.
License-Expression: Apache-2.0
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pregen>=0.12.0
Requires-Dist: fastapi>=0.110
Requires-Dist: uvicorn>=0.29
Requires-Dist: cryptography>=42
Requires-Dist: jsonschema>=4.21
Provides-Extra: test
Requires-Dist: pytest>=8; extra == "test"
Requires-Dist: httpx>=0.27; extra == "test"
Dynamic: license-file

# pregen-registry

The reference PRE-GEN registry. **Ask before you generate; get a signed answer anyone can
check.** It implements `spec/PRE-GEN-CORE.md`, the profile `likeness/1` and these extensions:
`reports`, `provider-keys`, `limits`, `jobs`, `grants`, `licensee`, `observe`, `lookup`, `identity`,
`proof`, `catalog`, `provider-identity` (with `--open-providers`, and always in a sandbox) and, in sandbox
mode, `sandbox`.

It is a registry, not a marketplace: it has no prices, payments or dashboards. Those belong to
each registry's own business.

## Run a sandbox in a minute

```bash
pip install pregen-registry
pregen-registry init --dir ./data --prefix TEST --name "My sandbox" --api http://127.0.0.1:8000 --sandbox
pregen-registry serve --dir ./data
curl -X POST http://127.0.0.1:8000/v2/sandbox/access      # a provider id and token, no account
```

The sandbox holds the standard test subjects `PG-TEST-000001…` to `…000008`. Each one
answers as `spec/extensions/sandbox.md` says.

## Run a real registry

1. **Pick a prefix.** Four letters from `ABCDEFGHJKMNPQRSTVWXYZ`, then apply for it
   (`pregen.org/registries`).
2. **Create the registry:**
   `pregen-registry init --dir ./data --prefix ABCD --name "…" --api https://registry.example --policy https://… --complaints mailto:…`
3. **Give the steward the operator key.** Hand over the key id and public key printed by
   `init`, out of band. Back up `data/operator.key` offline; it is created with mode 600.
4. **Add subjects, grants, providers and end users:**
   - `pregen-registry subject add --name "…" --level verified`
   - `pregen-registry grant add --subject PG-ABCD-… --purposes commercial --days 365 --max-uses 100`
   - `pregen-registry provider add --id frame-ai` — prints the credential once (a registry you created with
     `--open-providers` also answers any provider known by its domain and key, with no credential:
     `spec/extensions/provider-identity.md`; `provider accept --id https://frame.example` once you have vetted one)
   - `pregen-registry connect --provider frame-ai --licensee frame-ai:user-1`
5. **Serve it behind TLS:** `pregen-registry serve --dir ./data --host 0.0.0.0 --port 8000`, or HTTPS directly with
   `--ssl-certfile cert.pem --ssl-keyfile key.pem`.
6. **Anchor public people:** `pregen-registry subject anchor --code PG-ABCD-… --anchor wikidata:Q… --proof-url https://…`
7. **Check yourself:** `pregen-registry check --api https://registry.example [--directory URL]` ends `OK: all checks
   passed` when your document, key set and listing are right.

The whole path, step by step with what each command prints: `docs/registry.md`.

`PREGEN_OPERATOR_KEY_HEX` may hold the operator key instead of the file.

**Rotating the operator key.**
1. `pregen-registry key next --dir ./data` makes the next key and prints it. Give the key id and public key to the
   steward to announce in the directory.
2. Once the directory lists it, run `pregen-registry key rotate --dir ./data` and restart.

The old key stays in `GET /keys` as `retired`, so every answer and proof it signed still verifies. A retired key
never signs again. Move its private key file offline.

## HTTP interface

| Method and path | What |
|---|---|
| `GET /.well-known/pregen-registry.json` | who this registry is |
| `GET /keys` | its signed operator key set: every key it ever signed with, current and retired |
| `POST /v2/requests` | ask → `{"answer": <signed pg.answer.v1>}` |
| `POST /v2/reports` | report → `{"ack": <signed pg.report_ack.v1>}` |
| `POST /v2/keys`, `GET /v2/keys/{provider_id}` | provider keysets (a provider known by its domain publishes them in its party document instead) |
| `GET /v2/grants/{id}` | a signed grant (credential, or `PG-Access`) |
| `GET /v2/codes/{code}` | public lookup |
| `POST /v2/sandbox/access` | sandbox credentials (sandbox mode only) |
| `POST /v2/sandbox/party` | a provider's party document by post (sandbox mode only) |

## Limits of this version

- **One process, SQLite, one write lock.** Correct and simple; move to Postgres with per-row
  locks when throughput matters.
- **Managed subject keys are stored in the database.** Encrypt them, or use a KMS, before
  holding real people.
- **Provider key recovery** (a keyset co-signed by the registry) is not implemented yet.
- **`bind`** (a person connecting licences to an app) is specified (`spec/extensions/bind.md`), not implemented.
- **Party documents** are fetched after a one-shot address check; a resolver that pins the checked address closes
  the rebinding gap before holding real people. The registrable-domain rule (Public Suffix List) is not enforced.

## Tests

```bash
pip install -e ".[test]" && pytest
```

The tests cover:
- every rule of the core and of the extensions above;
- twenty concurrent jobs racing for a grant's last use;
- the byte vectors in `spec/test-vectors/messages.json`.
