feat: add totp utility routes

Author: subzeroid

README.md

@@ -221,7 +221,7 @@ For typed client generation in C++, C#, F#, D, Erlang, Elixir, Nim, Haskell, Lis
 
 ## Features
 
-1. **Authorization** — login, 2FA, settings management
+1. **Authorization** — login, 2FA, TOTP utilities, settings management
 2. **Account** — account info, profile, profile picture, privacy
 3. **Media** — info, paginated comments, likes, saves, pins, archive, edit, delete
 4. **Direct** — inbox, threads, messages, seen state

aiograpi_rest/main.py

@@ -130,6 +130,8 @@ def _app_version() -> str:
     "patchAuthSettings": "Save auth settings",
     "postAuthTotp": "Enable TOTP two-factor authentication",
     "deleteAuthTotp": "Disable TOTP two-factor authentication",
+    "getAuthTotpCode": "Generate a TOTP code",
+    "getAuthTotpSeed": "Generate a TOTP seed",
     "postAuthChallengeResolve": "Resolve an Instagram login challenge",
     "getAccount": "Get authenticated account info",
     "getAccountArchiveMedia": "List archived account media",

aiograpi_rest/routers/auth.py

@@ -2,7 +2,8 @@
 from typing import Dict, List, Optional, Union
 from unittest.mock import patch
 
-from fastapi import APIRouter, Depends, Form, HTTPException
+from aiograpi import Client
+from fastapi import APIRouter, Depends, Form, HTTPException, Query
 
 from aiograpi_rest.dependencies import ClientStorage, get_clients, get_optional_sessionid, get_sessionid
 
@@ -94,6 +95,22 @@ async def auth_relogin(sessionid: str = Depends(get_sessionid),
     return await cl.relogin()
 
 
+@router.get("/totp/seed", response_model=str)
+async def totp_seed(sessionid: str = Depends(get_sessionid),
+                    clients: ClientStorage = Depends(get_clients)) -> str:
+    """Generate TOTP seed
+    """
+    cl = await clients.get(sessionid)
+    return await cl.totp_generate_seed()
+
+
+@router.get("/totp/code", response_model=str)
+async def totp_code(seed: str = Query(...)) -> str:
+    """Generate TOTP code
+    """
+    return Client().totp_generate_code(seed)
+
+
 @router.get("/settings")
 async def settings_get(sessionid: str = Depends(get_sessionid),
                        clients: ClientStorage = Depends(get_clients)) -> Dict:

docs/aiograpi-coverage.md

@@ -9,16 +9,16 @@ the installed `aiograpi.Client` class and the local FastAPI router implementatio
 ## Summary
 
 - Public `aiograpi.Client` methods: **500**
-- Methods reached by REST routes: **269**
-- Methods not exposed as REST routes: **231**
-- Candidate REST backlog: **6**
+- Methods reached by REST routes: **271**
+- Methods not exposed as REST routes: **229**
+- Candidate REST backlog: **4**
 
 ## REST Relevance
 
 | Status | Methods | Meaning |
 |---|---:|---|
-| `exposed` | 269 | Already used by public REST routes. |
-| `candidate` | 6 | Likely useful as a future user-facing REST endpoint. |
+| `exposed` | 271 | Already used by public REST routes. |
+| `candidate` | 4 | Likely useful as a future user-facing REST endpoint. |
 | `duplicate` | 123 | Variant of an already exposed method, such as `_v1`, `_gql`, `_a1`, chunk, or origin helpers. |
 | `internal` | 102 | Low-level auth/request/configuration/signup/challenge helpers that should not be mirrored blindly. |
 
@@ -57,7 +57,7 @@ the installed `aiograpi.Client` class and the local FastAPI router implementatio
 | `signup` | 0 | 0 | 0 | 15 | 15 |
 | `story` | 14 | 0 | 7 | 0 | 21 |
 | `timeline` | 4 | 0 | 0 | 0 | 4 |
-| `totp` | 2 | 2 | 0 | 0 | 4 |
+| `totp` | 4 | 0 | 0 | 0 | 4 |
 | `track` | 5 | 0 | 0 | 0 | 5 |
 | `user` | 46 | 0 | 22 | 6 | 74 |
 | `video` | 5 | 0 | 1 | 4 | 10 |
@@ -69,7 +69,6 @@ the installed `aiograpi.Client` class and the local FastAPI router implementatio
 | `explore` | `report_explore_media` |
 | `fundraiser` | `standalone_fundraiser_info_v1` |
 | `multiple_accounts` | `featured_accounts_v1`, `get_account_family_v1` |
-| `totp` | `totp_generate_code`, `totp_generate_seed` |
 
 ## REST Routes To aiograpi Methods
 
@@ -113,6 +112,8 @@ the installed `aiograpi.Client` class and the local FastAPI router implementatio
 | `PATCH /auth/settings` | `expose`, `set_locale`, `set_proxy`, `set_settings`, `set_timezone_offset` |
 | `DELETE /auth/totp` | `totp_disable` |
 | `POST /auth/totp` | `totp_enable` |
+| `GET /auth/totp/code` | `totp_generate_code` |
+| `GET /auth/totp/seed` | `totp_generate_seed` |
 | `GET /clip/creation/info` | `clip_info_for_creation` |
 | `GET /clip/download` | `clip_download` |
 | `GET /clip/download/by/url` | `clip_download_by_url` |
@@ -731,8 +732,8 @@ the installed `aiograpi.Client` class and the local FastAPI router implementatio
 | `top_search(self, query)` | `public` | - | `internal` | low-level aiograpi helper or unsafe generic surface |
 | `totp_disable(self) -> bool` | `totp` | `DELETE /auth/totp` | `exposed` | used by at least one public REST route |
 | `totp_enable(self, verification_code: str) -> List[str]` | `totp` | `POST /auth/totp` | `exposed` | used by at least one public REST route |
-| `totp_generate_code(seed: str) -> str` | `totp` | - | `candidate` | potential user-facing REST endpoint |
-| `totp_generate_seed(self) -> str` | `totp` | - | `candidate` | potential user-facing REST endpoint |
+| `totp_generate_code(seed: str) -> str` | `totp` | `GET /auth/totp/code` | `exposed` | used by at least one public REST route |
+| `totp_generate_seed(self) -> str` | `totp` | `GET /auth/totp/seed` | `exposed` | used by at least one public REST route |
 | `track_download_by_url(self, url: str, filename: str = '', folder: pathlib._local.Path = '') -> pathlib._local.Path` | `track` | `GET /track/download/by/url` | `exposed` | used by at least one public REST route |
 | `track_info_by_canonical_id(self, music_canonical_id: str) -> aiograpi.types.Track` | `track` | `GET /track` | `exposed` | used by at least one public REST route |
 | `track_info_by_id(self, track_id: str, max_id: str = '') -> Dict` | `track` | `GET /track` | `exposed` | used by at least one public REST route |

docs/api.md

@@ -36,6 +36,10 @@ any of:
 If `POST /auth/login` returns `TwoFactorRequired`, retry the same endpoint with
 the same `username` and `password` plus `verification_code`.
 
+`GET /auth/totp/seed` generates a TOTP seed for the authenticated session.
+`GET /auth/totp/code?seed=...` generates the current six-digit TOTP code from a
+seed without requiring a session.
+
 If it returns `ChallengeRequired`, resolve the Instagram challenge in the
 account/session context first, then retry login or import a known-good saved
 session through `PATCH /auth/settings`.

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "aiograpi-rest"
-version = "5.13.0"
+version = "5.14.0"
 description = "RESTful API service for aiograpi"
 readme = "README.md"
 requires-python = ">=3.13"

tests/test_aiograpi_coverage.py

@@ -167,6 +167,8 @@ def test_aiograpi_coverage_classifies_methods_by_rest_relevance():
     assert classify_method(methods["archive_stories_v1"], covered).status == "duplicate"
     assert classify_method(methods["sticker_tray"], covered).status == "exposed"
     assert classify_method(methods["users_stories_gql"], covered).status == "exposed"
+    assert classify_method(methods["totp_generate_code"], covered).status == "exposed"
+    assert classify_method(methods["totp_generate_seed"], covered).status == "exposed"
     assert classify_method(methods["media_template_v1"], covered).status == "exposed"
     assert classify_method(methods["photo_upload_with_music"], covered).status == "exposed"
     assert classify_method(methods["album_upload_with_music"], covered).status == "exposed"

tests/test_app_system.py

@@ -195,6 +195,7 @@ async def test_openapi_uses_sessionid_authorize_button_for_protected_routes():
     public_paths = {
         "/auth/login",
         "/auth/login/by/sessionid",
+        "/auth/totp/code",
         "/health",
         "/ready",
         "/metrics",
@@ -248,6 +249,8 @@ async def test_openapi_uses_rest_http_methods():
         "/auth/relogin": {"patch"},
         "/auth/settings": {"get", "patch"},
         "/auth/totp": {"delete", "post"},
+        "/auth/totp/code": {"get"},
+        "/auth/totp/seed": {"get"},
         "/build": {"get"},
         "/clip/creation/info": {"get"},
         "/clip/download": {"get"},
@@ -625,6 +628,8 @@ async def test_openapi_uses_human_friendly_operation_summaries():
     assert paths["/auth/login/by/sessionid"]["post"]["summary"] == "Create a session from an existing session ID"
     assert paths["/auth/settings"]["get"]["summary"] == "Get saved auth settings"
     assert paths["/auth/settings"]["patch"]["summary"] == "Save auth settings"
+    assert paths["/auth/totp/code"]["get"]["summary"] == "Generate a TOTP code"
+    assert paths["/auth/totp/seed"]["get"]["summary"] == "Generate a TOTP seed"
     assert paths["/account"]["get"]["summary"] == "Get authenticated account info"
     assert paths["/account"]["patch"]["summary"] == "Update authenticated account profile"
     assert paths["/account/archive/media"]["get"]["summary"] == "List archived account media"

tests/test_auth_routes.py

@@ -39,6 +39,10 @@ async def relogin(self):
         self.calls.append(("relogin",))
         return True
 
+    async def totp_generate_seed(self):
+        self.calls.append(("totp_generate_seed",))
+        return "JBSWY3DPEHPK3PXP"
+
     def get_settings(self):
         return self.settings
 
@@ -305,6 +309,29 @@ async def test_relogin_awaits_aiograpi(fake_storage):
     assert ("relogin",) in fake_storage.created.calls
 
 
+@pytest.mark.asyncio
+async def test_totp_seed_awaits_aiograpi(fake_storage):
+    async with AsyncClient(transport=ASGITransport(app=app), base_url="http://test") as ac:
+        response = await ac.get("/auth/totp/seed", params={"sessionid": "sid"})
+
+    assert response.status_code == 200
+    assert response.json() == "JBSWY3DPEHPK3PXP"
+    assert ("totp_generate_seed",) in fake_storage.created.calls
+
+
+@pytest.mark.asyncio
+async def test_totp_code_generates_six_digit_code(fake_storage):
+    async with AsyncClient(transport=ASGITransport(app=app), base_url="http://test") as ac:
+        response = await ac.get(
+            "/auth/totp/code",
+            params={"seed": "JBSWY3DPEHPK3PXP"},
+        )
+
+    assert response.status_code == 200
+    assert response.json().isdigit()
+    assert len(response.json()) == 6
+
+
 @pytest.mark.asyncio
 async def test_settings_get_returns_client_settings(fake_storage):
     async with AsyncClient(transport=ASGITransport(app=app), base_url="http://test") as ac: