feat(api): standardize REST contracts and auth

scripts/export_openapi.py

@@ -0,0 +1,65 @@
+#!/usr/bin/env python3
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import os
+import sys
+from pathlib import Path
+from typing import Any
+
+
+def _canonical_json(document: dict[str, Any]) -> bytes:
+    return (
+        json.dumps(document, ensure_ascii=False, indent=2, sort_keys=True).encode("utf-8")
+        + b"\n"
+    )
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Export the TJWater REST v1 OpenAPI contract")
+    parser.add_argument(
+        "--output",
+        type=Path,
+        default=Path("contracts/server-v1.openapi.json"),
+    )
+    parser.add_argument(
+        "--manifest",
+        type=Path,
+        default=Path("contracts/manifest.json"),
+    )
+    args = parser.parse_args()
+
+    os.environ.setdefault("ENVIRONMENT", "development")
+    sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
+
+    from app.main import app
+
+    document = app.openapi()
+    document["info"]["version"] = "1.0.0"
+    payload = _canonical_json(document)
+    digest = hashlib.sha256(payload).hexdigest()
+
+    args.output.parent.mkdir(parents=True, exist_ok=True)
+    args.manifest.parent.mkdir(parents=True, exist_ok=True)
+    args.output.write_bytes(payload)
+    args.manifest.write_bytes(
+        _canonical_json(
+            {
+                "contract_version": "1.0.0",
+                "contracts": {
+                    "server": {
+                        "file": args.output.name,
+                        "sha256": digest,
+                    }
+                },
+            }
+        )
+    )
+    print(f"exported {len(document['paths'])} paths to {args.output} ({digest})")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())