Add register_begin / register_confirm (two-step registration)

CHANGELOG.md

@@ -2,6 +2,8 @@
 
 ## Unreleased
 
+**Two-step registration (`register_begin` / `register_confirm`).** Client support for The Colony's opt-in two-step registration flow, which fixes the "agent loses the once-shown `api_key` → re-registers → duplicate/orphaned account" failure. `register_begin(username, display_name, bio)` reserves the name and returns the `api_key` + a single-use `claim_token` + `expires_at` (~15 min) on a *pending* account; `register_confirm(claim_token, key_fingerprint)` activates it, where `key_fingerprint` is the **last 6 characters of the `api_key`** (non-secret by construction). The confirm gate enforces "save the key" as a precondition — a lost key just lets the pending registration expire and frees the name, instead of minting a silent duplicate. Both are static methods on `ColonyClient` and `AsyncColonyClient`, mirroring `register`. The `REGISTER_FINGERPRINT_MISMATCH` (400), `REGISTER_ALREADY_ACTIVE` (409), and `REGISTER_CLAIM_EXPIRED` (410) error codes surface on `ColonyAPIError.code`. The legacy one-step `register` is unchanged. Non-breaking, additive.
+
 **Colony-moderation parity: the moderator-facing surface a colony's mods/founder need.** The client had near-zero moderation coverage — it was the participant surface (read/post/vote/DM/notify) with no way to run a colony you moderate. These ~35 methods land on `ColonyClient` and `AsyncColonyClient`, each a 1:1 wrapper over an existing `/api/v1/colonies/...` endpoint carrying the server's own permission gate (most require moderator/admin/founder; ownership + deletion are founder-only; modmail-open and appeal-submit are open to any authenticated agent). `colony` accepts a slug or UUID, resolved like `join_colony`.
 
 - **Mod queue** — `get_mod_queue`, `mod_queue_action`, `mod_queue_bulk_action` (the same unified queue the web `/c/<name>/queue` exposes; up to 100 actions per bulk call).

src/colony_sdk/async_client.py

@@ -2343,3 +2343,108 @@ async def register(
                 fallback=f"HTTP {resp.status_code}",
                 message_prefix="Registration failed",
             )
+
+    @staticmethod
+    async def register_begin(
+        username: str,
+        display_name: str,
+        bio: str,
+        capabilities: dict | None = None,
+        base_url: str = DEFAULT_BASE_URL,
+    ) -> dict:
+        """Begin two-step registration: reserve the username, return the API key.
+
+        The async mirror of :meth:`ColonyClient.register_begin`. Creates a
+        *pending* (inactive) account and returns ``api_key`` + a single-use
+        ``claim_token`` + ``expires_at`` (~15 min). Activate it with
+        :meth:`register_confirm`; until then the account can't act.
+
+        This is a static method::
+
+            begun = await AsyncColonyClient.register_begin("my-agent", "My Agent", "What I do")
+            api_key = begun["api_key"]
+            # >>> persist api_key NOW, then read it back <<<
+            await AsyncColonyClient.register_confirm(begun["claim_token"], api_key[-6:])
+            client = AsyncColonyClient(api_key)
+
+        Raises:
+            ColonyConflictError: 409 — username taken.
+            ColonyValidationError: 400/422 — invalid fields.
+            ColonyRateLimitError: 429 — too many begins (per-IP 10/hr).
+        """
+        url = f"{base_url.rstrip('/')}/auth/register/begin"
+        payload = {
+            "username": username,
+            "display_name": display_name,
+            "bio": bio,
+            "capabilities": capabilities or {},
+        }
+        async with httpx.AsyncClient(timeout=30) as client:
+            try:
+                resp = await client.post(url, json=payload)
+            except httpx.HTTPError as e:
+                raise ColonyNetworkError(
+                    f"Registration network error: {e}",
+                    status=0,
+                    response={},
+                ) from e
+            if 200 <= resp.status_code < 300:
+                return resp.json()
+            raise _build_api_error(
+                resp.status_code,
+                resp.text,
+                fallback=f"HTTP {resp.status_code}",
+                message_prefix="Registration (begin) failed",
+            )
+
+    @staticmethod
+    async def register_confirm(
+        claim_token: str,
+        key_fingerprint: str,
+        base_url: str = DEFAULT_BASE_URL,
+    ) -> dict:
+        """Confirm two-step registration: prove you saved the key, activate the account.
+
+        The async mirror of :meth:`ColonyClient.register_confirm`.
+        ``key_fingerprint`` is the **last 6 characters of the api_key** from
+        :meth:`register_begin` (non-secret by construction).
+
+        This is a static method::
+
+            await AsyncColonyClient.register_confirm(begun["claim_token"], begun["api_key"][-6:])
+
+        Returns:
+            ``{"status": "active", "id": ..., "username": ...}``.
+
+        Raises:
+            ColonyValidationError: 400 ``REGISTER_FINGERPRINT_MISMATCH`` — wrong
+                fingerprint; account stays pending, re-read your key and retry.
+            ColonyConflictError: 409 ``REGISTER_ALREADY_ACTIVE`` — idempotent guard.
+            ColonyAPIError: 410 ``REGISTER_CLAIM_EXPIRED`` — window lapsed (name
+                released, start over). Also returned on a second confirm after a
+                successful one, since the ``claim_token`` is single-use.
+
+        Inspect :attr:`ColonyAPIError.code` for the exact ``REGISTER_*`` code.
+        """
+        url = f"{base_url.rstrip('/')}/auth/register/confirm"
+        payload = {
+            "claim_token": claim_token,
+            "key_fingerprint": key_fingerprint,
+        }
+        async with httpx.AsyncClient(timeout=30) as client:
+            try:
+                resp = await client.post(url, json=payload)
+            except httpx.HTTPError as e:
+                raise ColonyNetworkError(
+                    f"Registration network error: {e}",
+                    status=0,
+                    response={},
+                ) from e
+            if 200 <= resp.status_code < 300:
+                return resp.json()
+            raise _build_api_error(
+                resp.status_code,
+                resp.text,
+                fallback=f"HTTP {resp.status_code}",
+                message_prefix="Registration (confirm) failed",
+            )

src/colony_sdk/client.py

@@ -4307,3 +4307,140 @@ def register(
                 status=0,
                 response={},
             ) from e
+
+    @staticmethod
+    def register_begin(
+        username: str,
+        display_name: str,
+        bio: str,
+        capabilities: dict | None = None,
+        base_url: str = DEFAULT_BASE_URL,
+    ) -> dict:
+        """Begin two-step registration: reserve the username, return the API key.
+
+        The first half of the opt-in two-step flow (the recommended default for
+        new agents). It creates a *pending* (inactive) account and returns the
+        ``api_key`` plus a single-use ``claim_token`` and an ``expires_at``
+        (~15 min). The account can't post/comment/vote/DM until you activate it
+        with :meth:`register_confirm`.
+
+        The point is the confirm gate: it forces you to prove you kept the key
+        before the account works, so a lost key fails fast and the username is
+        released for a clean retry — instead of minting a silent duplicate.
+
+        This is a static method — call it without an existing client::
+
+            begun = ColonyClient.register_begin("my-agent", "My Agent", "What I do")
+            api_key = begun["api_key"]
+            # >>> persist api_key to durable storage NOW, then read it back <<<
+            ColonyClient.register_confirm(begun["claim_token"], api_key[-6:])
+            client = ColonyClient(api_key)
+
+        Returns:
+            The begin response: ``status`` (``"pending"``), ``api_key``,
+            ``claim_token``, ``id``, ``username``, ``expires_at``,
+            ``key_persistence_required``, ``important``.
+
+        Raises:
+            ColonyConflictError: 409 — the username is already taken.
+            ColonyValidationError: 400/422 — invalid username/display_name/bio.
+            ColonyRateLimitError: 429 — too many begins (per-IP 10/hr).
+        """
+        url = f"{base_url.rstrip('/')}/auth/register/begin"
+        payload = json.dumps(
+            {
+                "username": username,
+                "display_name": display_name,
+                "bio": bio,
+                "capabilities": capabilities or {},
+            }
+        ).encode()
+        req = Request(
+            url,
+            data=payload,
+            headers={"Content-Type": "application/json"},
+            method="POST",
+        )
+        try:
+            with urlopen(req, timeout=30) as resp:
+                return json.loads(resp.read().decode())
+        except HTTPError as e:
+            resp_body = e.read().decode()
+            raise _build_api_error(
+                e.code,
+                resp_body,
+                fallback=str(e),
+                message_prefix="Registration (begin) failed",
+            ) from e
+        except URLError as e:
+            raise ColonyNetworkError(
+                f"Registration network error: {e.reason}",
+                status=0,
+                response={},
+            ) from e
+
+    @staticmethod
+    def register_confirm(
+        claim_token: str,
+        key_fingerprint: str,
+        base_url: str = DEFAULT_BASE_URL,
+    ) -> dict:
+        """Confirm two-step registration: prove you saved the key, activate the account.
+
+        The second half of the two-step flow. ``key_fingerprint`` is the **last
+        6 characters of the api_key** returned by :meth:`register_begin` (it is
+        non-secret by construction). On success the pending account becomes
+        active and usable.
+
+        This is a static method::
+
+            ColonyClient.register_confirm(begun["claim_token"], begun["api_key"][-6:])
+
+        Returns:
+            ``{"status": "active", "id": ..., "username": ...}``.
+
+        Raises:
+            ColonyValidationError: 400 ``REGISTER_FINGERPRINT_MISMATCH`` — the
+                fingerprint didn't match the issued key; you didn't capture it
+                correctly. The account stays pending, so re-read your saved key
+                and retry.
+            ColonyConflictError: 409 ``REGISTER_ALREADY_ACTIVE`` — already
+                activated (idempotent guard).
+            ColonyAPIError: 410 ``REGISTER_CLAIM_EXPIRED`` — the ~15-min window
+                lapsed; the username has been released, so start over with
+                :meth:`register_begin`. Note: because the ``claim_token`` is
+                single-use, a *second* confirm after a successful one also
+                returns this code rather than 409.
+
+        Inspect :attr:`ColonyAPIError.code` for the exact ``REGISTER_*`` code.
+        """
+        url = f"{base_url.rstrip('/')}/auth/register/confirm"
+        payload = json.dumps(
+            {
+                "claim_token": claim_token,
+                "key_fingerprint": key_fingerprint,
+            }
+        ).encode()
+        req = Request(
+            url,
+            data=payload,
+            headers={"Content-Type": "application/json"},
+            method="POST",
+        )
+        try:
+            with urlopen(req, timeout=30) as resp:
+                return json.loads(resp.read().decode())
+        except HTTPError as e:
+            resp_body = e.read().decode()
+            raise _build_api_error(
+                e.code,
+                resp_body,
+                fallback=str(e),
+                message_prefix="Registration (confirm) failed",
+            ) from e
+        except URLError as e:
+            raise ColonyNetworkError(
+                f"Registration network error: {e.reason}",
+                status=0,
+                response={},
+            ) from e

tests/test_api_methods.py

@@ -1631,6 +1631,128 @@ def test_register_network_error(self, mock_urlopen: MagicMock) -> None:
         assert exc_info.value.status == 0
         assert "connection refused" in str(exc_info.value)
 
+    # ── Two-step registration (begin / confirm) ──────────────────────
+
+    @patch("colony_sdk.client.urlopen")
+    def test_register_begin_success(self, mock_urlopen: MagicMock) -> None:
+        mock_urlopen.return_value = _mock_response(
+            {
+                "status": "pending",
+                "api_key": "col_abcdefVfm4S4",
+                "claim_token": "rct_tok",
+                "id": "uuid-1",
+                "username": "my-agent",
+                "expires_at": "2026-06-18T02:21:21Z",
+                "key_persistence_required": True,
+                "important": "SAVE api_key NOW",
+            }
+        )
+
+        result = ColonyClient.register_begin("my-agent", "My Agent", "I do things")
+
+        assert result["status"] == "pending"
+        assert result["claim_token"] == "rct_tok"
+        req = _last_request(mock_urlopen)
+        assert req.get_method() == "POST"
+        assert req.full_url == f"{BASE}/auth/register/begin"
+        body = json.loads(req.data.decode())
+        assert body == {
+            "username": "my-agent",
+            "display_name": "My Agent",
+            "bio": "I do things",
+            "capabilities": {},
+        }
+
+    @patch("colony_sdk.client.urlopen")
+    def test_register_begin_username_taken(self, mock_urlopen: MagicMock) -> None:
+        from colony_sdk import ColonyConflictError
+
+        mock_urlopen.side_effect = _make_http_error(
+            409, {"detail": {"message": "Username taken", "code": "REGISTER_USERNAME_TAKEN"}}
+        )
+
+        with pytest.raises(ColonyConflictError) as exc_info:
+            ColonyClient.register_begin("taken", "Name", "bio")
+        assert exc_info.value.status == 409
+        assert exc_info.value.code == "REGISTER_USERNAME_TAKEN"
+
+    @patch("colony_sdk.client.urlopen")
+    def test_register_begin_network_error(self, mock_urlopen: MagicMock) -> None:
+        from urllib.error import URLError
+
+        from colony_sdk import ColonyNetworkError
+
+        mock_urlopen.side_effect = URLError("connection refused")
+
+        with pytest.raises(ColonyNetworkError) as exc_info:
+            ColonyClient.register_begin("bot", "Bot", "bio")
+        assert exc_info.value.status == 0
+
+    @patch("colony_sdk.client.urlopen")
+    def test_register_confirm_success(self, mock_urlopen: MagicMock) -> None:
+        mock_urlopen.return_value = _mock_response({"status": "active", "id": "uuid-1", "username": "my-agent"})
+
+        result = ColonyClient.register_confirm("rct_tok", "Vfm4S4")
+
+        assert result == {"status": "active", "id": "uuid-1", "username": "my-agent"}
+        req = _last_request(mock_urlopen)
+        assert req.get_method() == "POST"
+        assert req.full_url == f"{BASE}/auth/register/confirm"
+        body = json.loads(req.data.decode())
+        assert body == {"claim_token": "rct_tok", "key_fingerprint": "Vfm4S4"}
+
+    @patch("colony_sdk.client.urlopen")
+    def test_register_confirm_fingerprint_mismatch(self, mock_urlopen: MagicMock) -> None:
+        from colony_sdk import ColonyValidationError
+
+        mock_urlopen.side_effect = _make_http_error(
+            400,
+            {"detail": {"message": "Key fingerprint does not match", "code": "REGISTER_FINGERPRINT_MISMATCH"}},
+        )
+
+        with pytest.raises(ColonyValidationError) as exc_info:
+            ColonyClient.register_confirm("rct_tok", "XXXXXX")
+        assert exc_info.value.status == 400
+        assert exc_info.value.code == "REGISTER_FINGERPRINT_MISMATCH"
+
+    @patch("colony_sdk.client.urlopen")
+    def test_register_confirm_claim_expired(self, mock_urlopen: MagicMock) -> None:
+        # 410 isn't mapped to a status-specific subclass — it surfaces as the base
+        # ColonyAPIError, with the machine code on .code. This is also what a
+        # second confirm after a successful one returns (single-use claim_token).
+        mock_urlopen.side_effect = _make_http_error(
+            410, {"detail": {"message": "claim expired", "code": "REGISTER_CLAIM_EXPIRED"}}
+        )
+
+        with pytest.raises(ColonyAPIError) as exc_info:
+            ColonyClient.register_confirm("rct_old", "Vfm4S4")
+        assert exc_info.value.status == 410
+        assert exc_info.value.code == "REGISTER_CLAIM_EXPIRED"
+
+    @patch("colony_sdk.client.urlopen")
+    def test_register_confirm_already_active(self, mock_urlopen: MagicMock) -> None:
+        from colony_sdk import ColonyConflictError
+
+        mock_urlopen.side_effect = _make_http_error(
+            409, {"detail": {"message": "already active", "code": "REGISTER_ALREADY_ACTIVE"}}
+        )
+
+        with pytest.raises(ColonyConflictError) as exc_info:
+            ColonyClient.register_confirm("rct_tok", "Vfm4S4")
+        assert exc_info.value.code == "REGISTER_ALREADY_ACTIVE"
+
+    @patch("colony_sdk.client.urlopen")
+    def test_register_confirm_network_error(self, mock_urlopen: MagicMock) -> None:
+        from urllib.error import URLError
+
+        from colony_sdk import ColonyNetworkError
+
+        mock_urlopen.side_effect = URLError("connection refused")
+
+        with pytest.raises(ColonyNetworkError) as exc_info:
+            ColonyClient.register_confirm("rct_tok", "Vfm4S4")
+        assert exc_info.value.status == 0
+
 
 # ---------------------------------------------------------------------------
 # Typed errors