feat: add token update mechanism for new incoming OAuth2 refresh tokens

Author: PromiseFru

docs/rest.md

@@ -100,11 +100,33 @@ Retrieve OAuth2 client metadata for platforms that require dynamic registration
 
 ---
 
+### 6. Publish Content
+
+Submit an encrypted payload for publication to a target platform.
+
+**URL:** `/publications`
+**Method:** `POST`
+
+**Request Body:** `PublishContentRequest`
+
+| Field | Type | Description |
+| :--- | :--- | :--- |
+| address | string | Sender phone number in E.164 format (e.g., `+12025550123`) |
+| text | string | Base64-encoded serialized payload |
+
+**Response Body:** `PublishContentResponse`
+
+| Field | Type | Description |
+| :--- | :--- | :--- |
+| message | string | (Optional) Confirmation message on success |
+| error | string | (Optional) Error description on failure |
+
 ## Error Handling
 
 The API returns standard HTTP status codes:
 
 - `200 OK`: Request successful.
+- `400 Bad Request`: Invalid request parameters or payload.
 - `404 Not Found`: Platform or Key not found.
 - `422 Unprocessable Entity`: Validation error in request parameters.
 - `500 Internal Server Error`: Unexpected server error.

lib_relaysms_payload_specs

@@ -66,3 +66,13 @@ def create(
 def get_by_token_id(token_id: bytes, session: Session) -> Optional[Token]:
     """Fetch a token by its public token_id."""
     return session.query(Token).filter(Token.token_id == token_id).first()
+
+
+def update_token_data(
+    token: Token, new_token_data: dict[str, Any], session: Session
+) -> Token:
+    """Update the token_data of an existing token."""
+    token.token_data = new_token_data
+    session.add(token)
+    session.flush()
+    return token

models/token.py

@@ -7,7 +7,7 @@
 from typing import List
 
 from fastapi import APIRouter, HTTPException, Path, Request
-from fastapi.responses import HTMLResponse
+from fastapi.responses import HTMLResponse, JSONResponse
 
 from db import get_session
 from lib_relaysms_payload_specs.generated import relaysms_spec_payload as rrs
@@ -209,32 +209,34 @@ def create_publications(body: PublishContentRequest) -> PublishContentResponse:
             status_code=400, detail="Invalid base64-encoded text field"
         ) from exc
 
-    try:
-        payload = rrs.V1Payloads.deserialize(payload_raw)
-    except Exception as exc:
-        logger.error("failed to deserialize payload: %s", exc)
-        raise HTTPException(
-            status_code=400, detail="Failed to deserialize payload"
-        ) from exc
-
-    k_id = payload.get_kid()
-    t_id = payload.get_t_id()
-    t_id_bytes = struct.pack("<I", t_id)
-    len_att = payload.get_len_att()
-    sess_id = payload.get_sess_id()
-
-    if sess_id is None:
-        with get_session() as db:
-            publish_content(
-                token_id=t_id_bytes,
-                key_id=k_id,
-                len_att=len_att,
-                content_ciphertext=payload.get_payload(),
-                session=db,
+    payload_type = rrs.v1_get_payload_type(payload_raw)
+
+    match payload_type:
+        case rrs.V1PayloadsTypes.WITHOUT_ATTACHMENT:
+            try:
+                payload = rrs.V1Payloads.deserialize_without_attachment(payload_raw)
+            except Exception as exc:
+                logger.exception("failed to deserialize payload: %s", exc)
+                raise HTTPException(
+                    status_code=400, detail="Failed to deserialize payload"
+                ) from exc
+
+            k_id = payload.get_kid()
+            t_id = payload.get_t_id()
+            t_id_bytes = struct.pack("<I", t_id)
+            len_att = payload.get_len_att()
+
+            with get_session() as db:
+                publish_content(
+                    token_id=t_id_bytes,
+                    key_id=k_id,
+                    len_att=len_att,
+                    content_ciphertext=payload.get_content(),
+                    session=db,
+                )
+        case _:
+            raise ValueError(
+                f"Payload type {payload_type!r} not yet supported. Contact the developers for implementation status."
             )
-    else:
-        raise HTTPException(
-            status_code=501, detail="Multi-segment payloads not yet supported"
-        )
 
     return PublishContentResponse(message="Content published successfully")

rest_services/v1/routes.py

@@ -17,6 +17,7 @@
     delete_by_index as delete_server_key_by_index,
 )
 from models.server_identity_key import mark_key_used as mark_ss_kid_used
+from models.token import update_token_data
 from platforms.adapter_ipc_handler import AdapterIPCHandler
 
 logger = get_logger(__name__)
@@ -83,7 +84,7 @@ def publish_content(
             received_payload=content_ciphertext,
         )
     except Exception as exc:
-        logger.error("decryption failed for key_id=%d: %s", key_id, exc)
+        logger.exception("decryption failed for key_id=%d: %s", key_id, exc)
         raise ValueError("failed to decrypt content") from exc
 
     _consume_used_keys(
@@ -93,13 +94,13 @@ def publish_content(
     try:
         cat_id = rrs.v1_content_category_from_u8(token.cat_id)
     except Exception as exc:
-        logger.error("unknown cat_id=%r on token: %s", token.cat_id, exc)
+        logger.exception("unknown cat_id=%r on token: %s", token.cat_id, exc)
         raise
 
     try:
         content = rrs.V1ContentsContainer.deserialize(content_bytes, cat_id, len_att)
     except Exception as exc:
-        logger.error("content deserialization failed: %s", exc)
+        logger.exception("content deserialization failed: %s", exc)
         raise ValueError("failed to deserialize content") from exc
 
     if token.protocol == "oauth2":
@@ -135,3 +136,17 @@ def publish_content(
     if pipe.get("error"):
         logger.error("failed to publish content: %s", pipe["error"])
         raise ValueError("failed to publish content")
+
+    result = pipe.get("result", {})
+
+    if token.protocol == "oauth2":
+        refreshed_token = result.get("refreshed_token") or {}
+        new_refresh_token = refreshed_token.get("refresh_token")
+        old_refresh_token = token.token_data["token"].get("refresh_token")
+        if new_refresh_token and new_refresh_token != old_refresh_token:
+            update_token_data(
+                token, {**token.token_data, "token": refreshed_token}, session
+            )
+            logger.info(
+                "Successfully refreshed OAuth2 token for platform %r", token.platform
+            )

rest_services/v1/services.py

@@ -61,7 +61,7 @@ python -m tests.client sync-keys
 > [!NOTE]
 > If multiple tokens are stored, you will be prompted interactively to select one
 > or you can specify the token using the `--token` argument.
-
+>
 ### 4. Revoke OAuth2 Token
 
 Revokes a stored OAuth2 token.
@@ -73,7 +73,7 @@ python -m tests.client revoke-oauth2-token
 > [!NOTE]
 > If multiple tokens are stored, you will be prompted interactively to select one
 > or you can specify the token using the `--token` argument.
-
+>
 ### 5. Get PNBA Code
 
 Requests a passcode/OTP for Phone Number-Based Authentication (PNBA).
@@ -90,6 +90,12 @@ Exchanges the PNBA OTP code for a token, decrypts it, and stores the session dat
 python -m tests.client exchange-pnba-code --platform telegram --phone-number +123456789 --code <OTP_CODE>
 ```
 
+If the account has two-step verification enabled, re-run with `--password`:
+
+```sh
+python -m tests.client exchange-pnba-code --platform telegram --phone-number +123456789 --code <OTP_CODE> --password <PASSWORD>
+```
+
 ### 7. Revoke PNBA Token
 
 Revokes a stored PNBA token.
@@ -101,3 +107,29 @@ python -m tests.client revoke-pnba-token
 > [!NOTE]
 > If multiple tokens are stored, you will be prompted interactively to select one
 > or you can specify the token using the `--token` argument.
+
+### 8. Send
+
+Encrypts a message and publishes it to a platform via the REST `POST /v1/publications` endpoint. Constructs and serializes a `V1Payloads` payload, encrypts the content, and POSTs it with the sender's phone number as the `address`.
+
+```sh
+python -m tests.client send --platform gmail --address +237123456789 --to friend@example.com --subject "Hello" --body "Test message"
+```
+
+```sh
+python -m tests.client send --platform telegram --address +237123456789 --to +237123456789 --body "Hi there"
+```
+
+**Arguments:**
+
+| Argument | Required | Description |
+| :--- | :--- | :--- |
+| `--address` | Yes | Sender's phone number in E.164 format (e.g. `+237123456789`) |
+| `--body` | Yes | Message body |
+| `--to` | No | Recipient address (email or phone number). Required for email/messaging platforms. |
+| `--subject` | No | Message subject. Email platforms only. |
+| `--token` | No | Raw token (base64) to use. Omit for interactive prompt. |
+| `--dry-run` | No | Print the request body instead of sending it. |
+
+> [!NOTE]
+> Each send consumes one ephemeral keypair. The used keypair is removed from local state after a successful publish. Run `sync-keys` to replenish the pool when it runs low.

tests/README.md

@@ -737,10 +737,11 @@ def cmd_send(args: argparse.Namespace) -> bool:
         return False
 
     logger.info(
-        "platform=%s | shortcode=%s | cat_id=%s",
+        "platform=%s | shortcode=%s | cat_id=%s | key_id=%d",
         platform_info["name"],
         platform_info["shortcode"],
         platform_info["cat_id"],
+        kid_index,
     )
 
     try:
@@ -753,7 +754,7 @@ def cmd_send(args: argparse.Namespace) -> bool:
             attachment=None,
         ).serialize()
     except Exception as e:
-        logger.error("V1ContentsContainer.serialize failed: %s", e)
+        logger.exception("V1ContentsContainer.serialize failed: %s", e)
         return False
 
     try:
@@ -765,7 +766,7 @@ def cmd_send(args: argparse.Namespace) -> bool:
             plaintext=content_bytes,
         )
     except Exception as e:
-        logger.error("v1_platform_publisher_encrypt failed: %s", e)
+        logger.exception("v1_platform_publisher_encrypt failed: %s", e)
         return False
 
     token_id_bytes = b64d(token_data["token_id"])
@@ -778,13 +779,13 @@ def cmd_send(args: argparse.Namespace) -> bool:
             len_att=0,
             t_id=t_id_int,
             sess_id=None,
-        ).serialize()
+        ).serialize_without_attachment()
     except Exception as e:
-        logger.error("V1Payloads.serialize failed: %s", e)
+        logger.exception("V1Payloads.serialize_without_attachment failed: %s", e)
         return False
 
     url = f"{args.rest_api}/v1/publications"
-    body = {"address": args.address, "text": b64(payload_bytes)}
+    body = {"address": args.address, "text": b64(payload_bytes, urlsafe=False)}
 
     if args.dry_run:
         print("--- dry run: would POST to", url)

tests/client.py

@@ -48,8 +48,12 @@ def db_set(key: str, value) -> None:
 # ---------------------------------------------------------------------------
 
 
-def b64(data: bytes, *, truncate: int = 0) -> str:
-    encoded = base64.urlsafe_b64encode(data).decode()
+def b64(data: bytes, *, urlsafe: bool = True, truncate: int = 0) -> str:
+    encoded = (
+        base64.urlsafe_b64encode(data).decode()
+        if urlsafe
+        else base64.b64encode(data).decode()
+    )
     return encoded[:truncate] + "..." if truncate else encoded