Merge pull request 'docs: this describes the prod deployment now, not beta' (#11) from fix/docs-prod-forge-bases into main

Docs-only. NOTE: merged WITHOUT a completed granthi-review. The gate's webhook rejection was fixed today (item 52eea395), but reviews still fail open — diff fetch timeout, and shre-router returning prose instead of JSON (item 6d4e8819). Merged on explicit human approval, not on a green check.

README.md

@@ -1,8 +1,10 @@
 # granthi-sync v1.2
 
 The signup → download → link-folders → cloud product spine for the Granthi
-forge, tested against the BETA forge (granthi-beta.shre.ai). Python 3 stdlib +
-git CLI only — same portability heritage as the estate's `gitea_sync.py` mesh.
+forge. Developed and live-E2E-tested against the BETA forge
+(granthi-beta.shre.ai); **the deployed service now runs against the PRODUCTION
+forge** — see "Where this actually runs" below. Python 3 stdlib + git CLI only
+— same portability heritage as the estate's `gitea_sync.py` mesh.
 
 ```
    ┌──────────────┐   device flow    ┌─────────────────┐
@@ -13,7 +15,8 @@ git CLI only — same portability heritage as the estate's `gitea_sync.py` mesh.
    │              │  POST /v1/link {zitadel_access_token, device_name}
    │              │ ───────────────▶ ┌───────────────────────────────┐
    │              │ ◀─────────────── │ granthi-link  :3042           │
-   │              │  {login, token}  │ (granthi VPS, tailnet-only)   │
+   │              │  {login, token}  │ (granthi VPS; public via      │
+   │              │                  │  https://granthi-link.shre.ai)│
    │              │                  │  · userinfo validation        │
    │              │  POST /v1/repos  │  · ensure Gitea user (admin)  │
    │              │ ───────────────▶ │  · mint scoped user token     │
@@ -21,11 +24,28 @@ git CLI only — same portability heritage as the estate's `gitea_sync.py` mesh.
    │              │   git push/fetch (user token    │ admin API
    │              │   via credential helper)        ▼
    │              │ ───────────────▶ ┌───────────────────────────────┐
-   └──────────────┘                  │ BETA forge  :3041             │
-                                     │ granthi-beta.shre.ai          │
+   └──────────────┘                  │ PROD forge  :3040             │
+                                     │ granthi.shre.ai               │
                                      └───────────────────────────────┘
 ```
 
+## Where this actually runs
+
+Verified on the granthi VPS (`[email protected]`) on 2026-08-30, because
+this file previously described the beta tier long after the deployment moved:
+
+| | value |
+|---|---|
+| service | `/opt/granthi-link/`, `granthi-link.service`, `systemctl is-active` → `active` |
+| public entry | `https://granthi-link.shre.ai` — `/health` → 200. `/` → 404 is **no root route**, not an outage |
+| `gitea_base` | `http://127.0.0.1:3040` (container `gitea-central-gitea-1`) |
+| `public_gitea_base` | `https://granthi.shre.ai` |
+| rate limiting | `trust_forwarded_for: true`, `trusted_proxies: ["100.107.37.98/32"]`, no `rules` key → falls back to `DEFAULT_RATE_RULES` |
+| deployed version | `/health` reports **1.1.0** while this repo is **v1.2** — the running service lags `main` |
+
+So a new computer that follows Quickstart lands on the **production** forge.
+Beta remains where changes are proven before they reach it.
+
 ## Quickstart (invited user)
 
 You need a shre-id account — an operator creates it; there is no open signup
@@ -194,13 +214,16 @@ So:
   **64 KB** (413 beyond; missing `Content-Length` → 411, invalid → 400).
 * `POST /v1/repos {token, name, private}` → creates the user repo with the
   USER token; clone/html URLs are rebased onto `public_gitea_base` because the
-  container `ROOT_URL` (https://granthi-beta.shre.ai) does not resolve for
-  tailnet-only clients.
+  container `ROOT_URL` does not necessarily resolve for the client that asked
+  (it was a tailnet-only address on beta; on prod the rebase keeps clone URLs
+  on `https://granthi.shre.ai` rather than the container's own view).
 
 Deployment: `/opt/granthi-link/{granthi_link.py,config.json,state.json}` +
 systemd unit `granthi-link.service`; binds `127.0.0.1:3042` **and**
-`100.111.127.127:3042` (tailnet). **Not publicly exposed** — see promotion
-window. The service **refuses to start** (exit 2) unless `config.json` is
+`100.111.127.127:3042` (tailnet), and is **publicly reachable** at
+`https://granthi-link.shre.ai` through the `pulse-granthi-edge` cloudflared
+tunnel (done 2026-08-23; re-verified 2026-08-30). The service **refuses to
+start** (exit 2) unless `config.json` is
 mode 0600/0400 and owned by the user it runs as — the config carries the
 forge admin password, so permissive perms fail closed, not open.
 
@@ -620,10 +643,12 @@ Shape this should take, so the next session does not re-litigate it:
    `https://granthi-link.shre.ai` (second-level, see above), origin stays
    tailnet-only, `trust_forwarded_for` on with the tunnel as the only
    trusted proxy.
-2. **Swap forge base URLs** in `/opt/granthi-link/config.json`:
-   `gitea_base` → prod forge, `public_gitea_base` →
-   `https://granthi.shre.ai`; the client default server URL moves to the
-   public endpoint.
+2. ~~**Swap forge base URLs** in `/opt/granthi-link/config.json`~~
+   **DONE — verified live 2026-08-30**: the deployed config reads
+   `gitea_base: http://127.0.0.1:3040` and
+   `public_gitea_base: https://granthi.shre.ai`, and the client default
+   server is already the public endpoint. Linking a new device therefore
+   creates the account on **prod**.
 3. The `granthi-web` OIDC app already lists the prod callback; the device
    app is host-independent. Rotate the beta admin token/password out of the
    config when pointing at prod (prod forge is READ-ONLY to this estate —

server/config.example.json

@@ -1,15 +1,17 @@
 {
-  "gitea_base": "http://127.0.0.1:3041",
-  "public_gitea_base": "http://100.111.127.127:3041",
+  "_comment_forge": "Values below mirror the LIVE prod deployment (verified 2026-08-30). For the beta tier use gitea_base http://127.0.0.1:3041, public_gitea_base https://granthi-beta.shre.ai, container gitea-beta-gitea-1, creds /opt/gitea-beta/.admin-creds.",
+  "gitea_base": "http://127.0.0.1:3040",
+  "public_gitea_base": "https://granthi.shre.ai",
   "zitadel_userinfo": "https://id.shre.ai/oidc/v1/userinfo",
-  "admin_token": "MINT-VIA: docker exec -u git gitea-beta-gitea-1 gitea admin user generate-access-token --username nirpa --scopes write:admin,write:user,write:repository --raw",
+  "admin_token": "MINT-VIA: docker exec -u git gitea-central-gitea-1 gitea admin user generate-access-token --username nirpa --scopes write:admin,write:user,write:repository --raw",
   "admin_login": "nirpa",
-  "admin_password": "FROM /opt/gitea-beta/.admin-creds (required: Gitea 1.27 token minting only works via basic auth + Sudo header)",
+  "admin_password": "FROM shre-cred: superadmin/granthi-link/granthi-prod-forge-admin (required: Gitea 1.27 token minting only works via basic auth + Sudo header). NEVER paste this into chat or a shell history.",
   "binds": [["127.0.0.1", 3042], ["100.111.127.127", 3042]],
   "test_mode": false,
   "rate_limit": {
     "enabled": true,
-    "trust_forwarded_for": false,
+    "trust_forwarded_for": true,
+    "trusted_proxies": ["100.107.37.98/32"],
     "rules": {"/v1/link": [5, 3600], "/v1/repos": [60, 3600]}
   }
 }

server/granthi_link.py

@@ -80,6 +80,9 @@ TEST_MODE_ENV = "GRANTHI_LINK_ALLOW_TEST_MODE"
 
 # Sentinel: create_user hit a 409 (someone else created the login first).
 USER_CREATE_CONFLICT = object()
+# Sentinel: the address already belongs to another forge account, which is a
+# 409 the caller can act on -- not a 502 that reads like the service is down.
+EMAIL_IN_USE = object()
 
 LOGIN_SAFE = re.compile(r"[^a-zA-Z0-9._-]+")
 
@@ -292,6 +295,14 @@ def check_config_perms(path, euid=None):
 # Identity map: zitadel sub -> gitea login (JSON, 0600, atomic writes)
 # --------------------------------------------------------------------------
 
+def _email_in_use_message(login, userinfo):
+    email = userinfo.get("email") or "your address"
+    return (f"cannot create the account '{login}': {email} already belongs to "
+            f"a different account on this forge. If that other account is "
+            f"yours, an operator must bind your identity to it; if it is not, "
+            f"use a different address.")
+
+
 class IdentityStore:
     """Persistent map of Zitadel `sub` -> Gitea login binding records.
 
@@ -677,6 +688,14 @@ class LinkService:
             headers=self._admin_hdr(), body=body)
         if status == 409:
             return USER_CREATE_CONFLICT
+        if status == 422 and "e-mail already in use" in str(resp).lower():
+            # The address belongs to a DIFFERENT forge account. Reported as its
+            # own case because the generic path turns it into a bare 502, and
+            # "502" sends the person looking for an outage when the real answer
+            # is "that address is already somebody's account here". Hit live on
+            # 2026-08-23: an operator moved an email onto another account and
+            # the next sign-in failed with nothing but the number.
+            return EMAIL_IN_USE
         if status != 201:
             return f"gitea admin user create failed (HTTP {status}): {resp}"
         return None
@@ -733,6 +752,8 @@ class LinkService:
                                  "was not created by this service; refusing "
                                  "to re-create"}, None
                 err = self.create_user(login, userinfo)
+                if err is EMAIL_IN_USE:
+                    return 409, {"error": _email_in_use_message(login, userinfo)}, None
                 if err and err is not USER_CREATE_CONFLICT:
                     return 502, {"error": err}, None
                 LOG.info("re-created service-managed gitea user %s", login)
@@ -758,6 +779,8 @@ class LinkService:
                     return 409, {"error": "login exists and is not linked "
                                           "to this identity"}, None
                 LOG.info("user %s created concurrently; continuing", login)
+            elif err is EMAIL_IN_USE:
+                return 409, {"error": _email_in_use_message(login, userinfo)}, None
             elif err:
                 return 502, {"error": err}, None
             else:

tests/test_server.py

@@ -77,6 +77,10 @@ class StubUpstream(BaseHTTPRequestHandler):
         if self.path == "/api/v1/admin/users":
             if body["username"] in st["users"]:
                 return self._json(409, {"message": "user already exists"})
+            if body.get("email") in st["users"].values():
+                # real Gitea: emails are unique across accounts
+                return self._json(422, {"message":
+                    f"e-mail already in use [email: {body['email']}]"})
             st["users"][body["username"]] = body["email"]
             st["created"].append(body)
             return self._json(201, {"login": body["username"]})
@@ -1001,6 +1005,34 @@ class TestInviteSurvivesAFailedGrant(ServiceTestBase):
         self.assertEqual([g["repo"] for g in self.svc.state.peek_invites("[email protected]")],
                          ["alice/reports"])
 
+
+class TestDuplicateEmailIsExplained(ServiceTestBase):
+    """A 502 sends someone looking for an outage. The real answer is that the
+    address already belongs to another account here -- say so. (Hit live on
+    2026-08-23 when an operator moved an email onto a different account.)"""
+
+    def setUp(self):
+        super().setUp()
+        self.enable_test_mode()
+        # an existing account already holds the address
+        StubUpstream.state["users"]["existing"] = "[email protected]"
+
+    def test_it_is_a_409_that_names_the_problem(self):
+        status, resp = self.stub_link("s-new", "brandnew", email="[email protected]",
+                                      verified=True, device_id="dev-x")
+        self.assertEqual(status, 409, resp)
+        msg = resp["error"]
+        self.assertIn("[email protected]", msg)
+        self.assertIn("already belongs to a different account", msg)
+        self.assertIn("brandnew", msg)          # names the login it tried
+        self.assertNotIn("502", msg)
+
+    def test_a_normal_create_is_unaffected(self):
+        status, resp = self.stub_link("s-ok", "fresh", email="[email protected]",
+                                      verified=True, device_id="dev-y")
+        self.assertEqual(status, 200, resp)
+        self.assertIn("token", resp)
+
 if __name__ == "__main__":
     unittest.main()