pregen-registry 0.2.0__tar.gz

pregen_registry-0.2.0/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

pregen_registry-0.2.0/PKG-INFO

@@ -0,0 +1,102 @@
+Metadata-Version: 2.4
+Name: pregen-registry
+Version: 0.2.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.11.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` 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
+   - `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 |
+| `GET /v2/grants/{id}` | a signed grant |
+| `GET /v2/codes/{code}` | public lookup |
+| `POST /v2/sandbox/access` | sandbox credentials (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.
+
+## 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`.

pregen_registry-0.2.0/README.md

@@ -0,0 +1,84 @@
+# 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` 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
+   - `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 |
+| `GET /v2/grants/{id}` | a signed grant |
+| `GET /v2/codes/{code}` | public lookup |
+| `POST /v2/sandbox/access` | sandbox credentials (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.
+
+## 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`.

pregen_registry-0.2.0/pregen_registry/__init__.py

@@ -0,0 +1,2 @@
+"""pregen-registry: the reference PRE-GEN registry (spec/PRE-GEN-CORE.md)."""
+__version__ = "0.1.0"

pregen_registry-0.2.0/pregen_registry/app.py

@@ -0,0 +1,97 @@
+"""HTTP interface (PRE-GEN-CORE.md and extensions/*.md)."""
+from __future__ import annotations
+
+import time
+
+from fastapi import Body, FastAPI, Header, Request
+from fastapi.responses import JSONResponse, PlainTextResponse
+
+from . import __version__
+from .protocol import ProtocolError
+from .registry import Registry
+
+SANDBOX_ACCESS_PER_HOUR = 10
+
+
+def create_app(registry: Registry, policy_file=None) -> FastAPI:
+    """`policy_file`: a published policy page, served at GET /policy (text/markdown) when it exists."""
+    app = FastAPI(title=f"PRE-GEN registry — {registry.config.name}", version=__version__,
+                  docs_url="/docs", redoc_url=None)
+    issued: dict[str, list[float]] = {}            # sandbox credentials per client address, last hour
+
+    @app.exception_handler(ProtocolError)
+    def protocol_error(_: Request, e: ProtocolError):
+        return JSONResponse({"error": e.code, "error_description": e.detail, **e.extra}, status_code=e.status)
+
+    @app.get("/.well-known/pregen-registry.json")
+    def document():
+        return registry.document()
+
+    @app.get("/keys")
+    def keys():
+        return registry.key_set()
+
+    @app.get("/policy")
+    def policy():
+        if not (policy_file and policy_file.exists()):
+            raise ProtocolError("PG_NOT_FOUND", "no policy.md in this registry's data folder", status=404)
+        return PlainTextResponse(policy_file.read_text(encoding="utf-8"), media_type="text/markdown; charset=utf-8")
+
+    @app.post("/v2/requests")
+    def requests(env=Body(...), x_provider_id: str = Header(""), authorization: str | None = Header(None)):
+        return registry.request(x_provider_id, authorization, env)
+
+    @app.post("/v2/reports")
+    def reports(env=Body(...), x_provider_id: str = Header(""), authorization: str | None = Header(None)):
+        return registry.report(x_provider_id, authorization, env)
+
+    @app.post("/v2/keys")
+    def post_keys(env=Body(...), x_provider_id: str = Header(""), authorization: str | None = Header(None)):
+        return registry.post_keyset(x_provider_id, authorization, env)
+
+    @app.get("/v2/keys/{provider_id}")
+    def get_keys(provider_id: str):
+        return registry.get_keysets(provider_id)
+
+    @app.get("/v2/grants/{grant_id}")
+    def grant(grant_id: str, x_provider_id: str = Header(""), authorization: str | None = Header(None)):
+        if not registry.config.sandbox:
+            registry.authenticate(x_provider_id, authorization)
+        return registry.grant(grant_id)
+
+    @app.get("/v2/codes/{code}")
+    def lookup(code: str):
+        return registry.lookup(code)
+
+    @app.get("/v2/anchors")
+    def anchors():
+        return registry.anchors()
+
+    @app.get("/v2/catalog")
+    def catalog():
+        return registry.catalog()
+
+    @app.get("/v2/statement")
+    def statement(x_provider_id: str = Header(""), authorization: str | None = Header(None)):
+        return registry.statement(x_provider_id, authorization)
+
+    @app.get("/v2/proofs/{short_id}")
+    def proof(short_id: str):
+        return registry.proof(short_id)
+
+    @app.post("/v2/sandbox/access")
+    def sandbox_access(request: Request):
+        """extensions/sandbox.md: credentials without an account — only in a sandbox, which holds no real people."""
+        if not registry.config.sandbox:
+            raise ProtocolError("PG_NOT_FOUND", "this registry is not a sandbox", status=404)
+        who, now = request.client.host if request.client else "?", time.time()
+        recent = [t for t in issued.get(who, []) if now - t < 3600]
+        if len(recent) >= SANDBOX_ACCESS_PER_HOUR:
+            raise ProtocolError("PG_RATE_LIMITED", "too many sandbox credentials from this address; try later",
+                                status=429)
+        issued[who] = [*recent, now]
+        provider_id, token = registry.add_provider()
+        return {"provider_id": provider_id, "token": token, "registry": registry.document()["api"],
+                "note": "Sandbox only: test subjects, no real people. Keep the token secret; it is shown once."}
+
+    return app

pregen_registry-0.2.0/pregen_registry/check.py

@@ -0,0 +1,129 @@
+"""pregen-registry check: a registry's live self-test, from the outside, as a provider and a verifier see it.
+
+It checks the registry document, the signed key set, the error shape of an unauthenticated request and, given the
+directory and its steward key, that the steward lists this registry with its current key. With a provider credential
+and a subject code, it also asks and checks the answer as a provider must (core rule 5). It changes nothing.
+"""
+from __future__ import annotations
+
+import json
+import secrets
+import time
+import urllib.error
+import urllib.request
+from email.utils import parsedate_to_datetime
+
+import pregen
+
+EXTENSIONS_NEEDED = ("reports", "provider-keys")
+
+
+def _get(url, headers=None):
+    with urllib.request.urlopen(urllib.request.Request(url, headers={"Accept": "application/json"}), timeout=10) as r:
+        if headers is not None:
+            headers["Date"] = r.headers.get("Date")                  # HTTPMessage looks names up in any case
+        return json.loads(r.read())
+
+
+def _post(url, env, headers):
+    req = urllib.request.Request(url, data=json.dumps(env).encode(), method="POST",
+                                 headers={"Content-Type": "application/json", **headers})
+    try:
+        with urllib.request.urlopen(req, timeout=10) as r:
+            return r.status, json.loads(r.read())
+    except urllib.error.HTTPError as e:
+        return e.code, json.loads(e.read() or b"{}")
+
+
+def check(api: str, directory_url: str | None = None, steward: str | None = None, provider_id: str | None = None,
+          token: str | None = None, subject: str | None = None, purpose: str = "commercial", licensee: str = ""):
+    """Yields (ok, what) lines."""
+    api = api.rstrip("/")
+    served = {}
+    try:
+        doc = _get(api + "/.well-known/pregen-registry.json", served)
+    except Exception as e:  # noqa: BLE001 — any failure to reach it is the finding
+        yield False, f"GET {api}/.well-known/pregen-registry.json: {e}"
+        return
+    if served.get("Date"):                                # answers and give-back windows are timed by its clock
+        skew = round(parsedate_to_datetime(served["Date"]).timestamp() - time.time())
+        yield abs(skew) <= 60, f"the registry's clock is {abs(skew)} s {'ahead of' if skew > 0 else 'behind'} this one"
+    missing = [k for k in ("prefix", "name", "api", "keys", "profiles", "extensions", "policy", "complaints", "sandbox")
+               if k not in doc]
+    yield not missing, "registry document" + (f": missing {missing}" if missing else
+                                              f": prefix {doc['prefix']}, profiles {doc['profiles']}")
+    yield doc.get("api", "").rstrip("/") == api, f"document api is {doc.get('api')!r}"
+    yield "likeness/1" in doc.get("profiles", []), "answers under likeness/1"
+    yield all(x in doc.get("extensions", []) for x in EXTENSIONS_NEEDED), f"declares {', '.join(EXTENSIONS_NEEDED)}"
+    try:
+        with urllib.request.urlopen(doc.get("policy", ""), timeout=10) as r:
+            yield r.status == 200, f"the policy page answers: {doc.get('policy')}"
+    except Exception as e:  # noqa: BLE001
+        yield False, f"the policy page does not answer: {doc.get('policy')!r} ({e})"
+    try:
+        ks = _get(doc["keys"])
+    except Exception as e:  # noqa: BLE001
+        yield False, f"GET {doc.get('keys')}: {e}"
+        return
+    keys = ks.get("keys") or []
+    current = next((k for k in keys if k.get("key_id") == ks.get("current_key_id")), None)
+    yield current is not None, f"key set: current key {ks.get('current_key_id')}, {len(keys)} key(s) in its history"
+    if current is None:
+        return
+    good = True
+    for k in keys:
+        try:
+            pregen.check_public_key(k["public_key_hex"])
+            good &= pregen.fingerprint(k["public_key_hex"]) == k["key_id"]
+        except (pregen.PregenError, KeyError):
+            good = False
+    yield good, "every key id is its key's fingerprint, and no key is small-order"
+    yield pregen.verify_signed(ks, current["public_key_hex"], "signature"), "key set signed by its current key"
+    from .registry import mint_code
+    probe = {"subject_ref": mint_code(doc.get("prefix", "TEST"), 1), "provider_id": "pregen-check-nobody",
+             "profile": "likeness/1", "use": {"purpose": "commercial"}, "job_id": "pregen-check", "job_hash": "0" * 64}
+    status, err = _post(api + "/v2/requests", pregen.sign_envelope("pg.request.v1", probe),
+                        {"X-Provider-ID": "pregen-check-nobody", "Authorization": "Bearer " + secrets.token_hex(8)})
+    yield status == 401 and err.get("error") == "PG_NOT_AUTHENTICATED", \
+        f"a request with an unknown credential is refused: HTTP {status} {err.get('error')}"
+    if "identity" in doc.get("extensions", []):           # a hidden list would hide an opt-out from every provider
+        try:
+            env = _get(api + "/v2/anchors")
+            b = env.get("body") or {}
+            signed = env.get("type") == "pg.anchors.v1" and b.get("registry") == doc.get("prefix") and \
+                [s.get("key_id") for s in b.get("signers", [])] == [current["key_id"]] and \
+                pregen.verify_bytes(current["public_key_hex"], (env.get("signatures") or [""])[0],
+                                    pregen.signing_input(env["type"], b))
+            yield signed, f"anchors list signed by the current key: {len(b.get('anchors') or [])} public person(s)"
+        except Exception as e:  # noqa: BLE001
+            yield False, f"GET {api}/v2/anchors: {e}"
+    directory = None
+    if directory_url:
+        try:
+            directory = pregen.load_directory(directory_url, **({"steward_public_key_hex": steward} if steward else {}))
+        except Exception as e:  # noqa: BLE001
+            yield False, f"directory {directory_url}: {e}"
+            return
+        entry = next((r for r in directory.registries if r["prefix"] == doc.get("prefix")), None)
+        yield entry is not None, f"the directory (sequence {directory.sequence}) lists prefix {doc.get('prefix')}" + (
+            f" with keys {', '.join(entry['key_fingerprints'])}" if entry else "")
+        if entry:
+            yield entry["api"].rstrip("/") == api and entry["keys"] == doc["keys"], "listed with this api and keys URL"
+            yield current["key_id"] in entry["key_fingerprints"], "listed with the current key"
+    if provider_id and token and subject:
+        body = {"subject_ref": subject, "provider_id": provider_id, "profile": "likeness/1",
+                "use": {"purpose": purpose}, "job_id": "pregen-check-" + secrets.token_hex(4), "job_hash": "0" * 64,
+                **({"licensee_id": licensee} if licensee else {})}
+        request = pregen.sign_envelope("pg.request.v1", body)
+        status, res = _post(api + "/v2/requests", request, {"X-Provider-ID": provider_id,
+                                                           "Authorization": "Bearer " + token})
+        answer = res.get("answer")
+        yield status == 200 and answer is not None, f"POST /v2/requests for {subject}, purpose {purpose}" + (
+            f", licensee {licensee}" if licensee else "") + f": HTTP {status}" + (
+            f", {answer['body']['status']} {answer['body'].get('reason') or ''}".rstrip() if answer else f" {res}")
+        if answer and directory:
+            try:
+                pregen.verify_answer(answer, request, directory, testing=bool(doc.get("sandbox")))
+                yield True, "the answer verifies through the directory (core rule 5)"
+            except pregen.PregenError as e:
+                yield False, f"the answer does not verify: {e}"