Improve auth sandbox and smoke test workflow

Author: Eoic

.env.example

@@ -11,26 +11,44 @@ RATE_LIMIT_AUTH=5
 RATE_LIMIT_GENERAL=100
 RATE_LIMIT_UPLOAD=10
 RATE_LIMIT_BATCH=20
-PUBLIC_BASE_URL=
+
+# Public server URL used in OAuth callbacks and email links.
+# Local desktop testing: http://localhost:8080
+# Mobile/device or real Google testing: use a public HTTPS URL or tunnel.
+PUBLIC_BASE_URL=http://localhost:8080
+
+# Google OAuth web-application credentials.
+# Authorized redirect URI should be:
+#   <PUBLIC_BASE_URL>/v1/auth/oauth/google/callback
 GOOGLE_OAUTH_CLIENT_ID=
 GOOGLE_OAUTH_CLIENT_SECRET=
 OAUTH_STATE_EXPIRE_MINUTES=10
 AUTH_EXCHANGE_CODE_EXPIRE_MINUTES=5
 EMAIL_VERIFICATION_TOKEN_EXPIRE_MINUTES=1440
 PASSWORD_RESET_TOKEN_EXPIRE_MINUTES=60
-EMAIL_DELIVERY_ENABLED=false
-SMTP_HOST=
-SMTP_PORT=587
+
+# Local Mailpit defaults when running the API on the host machine.
+# If the API itself runs in Docker, use SMTP_HOST=mailpit instead.
+EMAIL_DELIVERY_ENABLED=true
+SMTP_HOST=127.0.0.1
+SMTP_PORT=1025
 SMTP_USERNAME=
 SMTP_PASSWORD=
-SMTP_USE_TLS=true
+SMTP_USE_TLS=false
 SMTP_USE_SSL=false
-SMTP_FROM_EMAIL=
+SMTP_FROM_EMAIL=noreply@papyrus.local
 SMTP_FROM_NAME=Papyrus
+
+# Prefer file-based PowerSync keys for local development.
+# Generate them with: ./scripts/generate_dev_powersync_keys.sh
+POWERSYNC_JWT_PRIVATE_KEY_FILE=.local/powersync/private.pem
+POWERSYNC_JWT_PUBLIC_KEY_FILE=.local/powersync/public.pem
+
+# Inline PEM values are still supported if you need them.
 POWERSYNC_JWT_PRIVATE_KEY=
 POWERSYNC_JWT_PUBLIC_KEY=
-POWERSYNC_JWT_KEY_ID=papyrus-powersync-v1
-POWERSYNC_JWT_AUDIENCE=
+POWERSYNC_JWT_KEY_ID=papyrus-powersync-dev
+POWERSYNC_JWT_AUDIENCE=powersync-dev
 POWERSYNC_TOKEN_EXPIRE_MINUTES=5
 POSTGRES_USER=papyrus
 POSTGRES_PASSWORD=papyrus

.gitignore

@@ -30,6 +30,7 @@ env/
 .env
 .env.local
 .env.*.local
+.local/
 
 # IDE
 .idea/

README.md

@@ -13,7 +13,7 @@ uv sync --extra dev
 Run the database:
 
 ```bash
-docker compose up database
+docker compose up -d database mailpit
 ```
 
 Run database migrations:
@@ -28,10 +28,22 @@ Run the server:
 uv run uvicorn papyrus.main:app --reload
 ```
 
+Generate local PowerSync keys for auth testing:
+
+```bash
+./scripts/generate_dev_powersync_keys.sh
+```
+
 ## Development
 
 Run tests:
 
 ```bash
 uv run pytest --cov --cov-report html
 ```
+
+## Auth Testing
+
+Local auth testing supports Mailpit for SMTP capture, a dev auth sandbox at `/__dev/auth-sandbox`, and opt-in provider smoke tests.
+
+See [`docs/auth-testing.md`](docs/auth-testing.md) for the exact `.env` values, Google OAuth setup, and end-to-end test workflow.

docker-compose.yml

@@ -16,6 +16,13 @@ services:
       timeout: 5s
       retries: 5
 
+  mailpit:
+    image: axllent/mailpit:v1.26
+    restart: unless-stopped
+    ports:
+      - "1025:1025"
+      - "8025:8025"
+
   server:
     build: .
     restart: unless-stopped
@@ -25,6 +32,8 @@ services:
     depends_on:
       database:
         condition: service_healthy
+      mailpit:
+        condition: service_started
     command: >
       sh -c "alembic upgrade head && papyrus-server"
 

docs/auth-testing.md

@@ -0,0 +1,170 @@
+# Authentication Testing Setup
+
+This repo can now support a full local auth test loop:
+
+- email/password login
+- refresh and logout flows
+- verification and password-reset emails
+- PowerSync token minting
+- Google OAuth browser flow after you add Google credentials
+
+## Local Setup
+
+1. Start local dependencies:
+
+```bash
+docker compose up -d database mailpit
+```
+
+1. Generate local PowerSync signing keys:
+
+```bash
+./scripts/generate_dev_powersync_keys.sh
+```
+
+1. Make sure `.env` contains the auth values shown in `.env.example`.
+
+Recommended local values when the API runs on the host with `uvicorn`:
+
+```dotenv
+PUBLIC_BASE_URL=http://localhost:8080
+EMAIL_DELIVERY_ENABLED=true
+SMTP_HOST=127.0.0.1
+SMTP_PORT=1025
+SMTP_USE_TLS=false
+SMTP_USE_SSL=false
+SMTP_FROM_EMAIL=noreply@papyrus.local
+SMTP_FROM_NAME=Papyrus
+POWERSYNC_JWT_PRIVATE_KEY_FILE=.local/powersync/private.pem
+POWERSYNC_JWT_PUBLIC_KEY_FILE=.local/powersync/public.pem
+POWERSYNC_JWT_KEY_ID=papyrus-powersync-dev
+POWERSYNC_JWT_AUDIENCE=powersync-dev
+```
+
+If the API runs inside Docker instead of on the host, set `SMTP_HOST=mailpit` and `POSTGRES_HOST=database`.
+
+1. Apply migrations and run the API:
+
+```bash
+uv run alembic upgrade head
+uv run uvicorn papyrus.main:app --reload
+```
+
+## Useful Local Pages
+
+- API index: `http://localhost:8080/`
+- Swagger UI: `http://localhost:8080/docs`
+- ReDoc: `http://localhost:8080/redoc`
+- Dev auth sandbox: `http://localhost:8080/__dev/auth-sandbox`
+- Mailpit inbox UI: `http://localhost:8025`
+
+## SMTP End-to-End Testing
+
+Mailpit is a local SMTP sink. No real mailbox is needed.
+
+- Trigger `forgot password` or `resend verification` from the sandbox or API.
+- Open `http://localhost:8025` to inspect the delivered messages.
+- For the opt-in smoke test, use any recipient address:
+
+```bash
+RUN_SMTP_SMOKE_TEST=true \
+AUTH_SMOKE_EMAIL_RECIPIENT=smoke@papyrus.local \
+uv run pytest tests/integration/test_auth_smoke.py -m auth_smoke -q
+```
+
+## Google OAuth Setup
+
+Papyrus uses a server-owned browser OAuth flow. The Flutter app opens:
+
+- `GET /v1/auth/oauth/google/start`
+
+Google redirects back to the server callback:
+
+- `GET /v1/auth/oauth/google/callback`
+
+The server then redirects to your app callback URI with a one-time Papyrus exchange code.
+
+### What To Create In Google Cloud
+
+Create an OAuth client with:
+
+- Client type: `Web application`
+- Redirect URI:
+  - local desktop testing: `http://localhost:8080/v1/auth/oauth/google/callback`
+  - public tunnel/device testing: `https://<your-public-host>/v1/auth/oauth/google/callback`
+
+Authorized JavaScript origins are not required for this backend-owned redirect flow. If the Google UI requires one for localhost testing, use:
+
+- `http://localhost:8080`
+
+Set the resulting values in `.env`:
+
+```dotenv
+GOOGLE_OAUTH_CLIENT_ID=...
+GOOGLE_OAUTH_CLIENT_SECRET=...
+PUBLIC_BASE_URL=http://localhost:8080
+```
+
+For mobile-device testing or any device where the browser cannot reach your workstation as `localhost`, use a public HTTPS base URL and set `PUBLIC_BASE_URL` to that exact value.
+
+### Localhost vs Public Testing
+
+- Desktop same-machine testing:
+  - `PUBLIC_BASE_URL=http://localhost:8080`
+  - Google redirect URI: `http://localhost:8080/v1/auth/oauth/google/callback`
+- Mobile emulator, physical phone, or shared test device:
+  - expose the backend through a public HTTPS URL
+  - set `PUBLIC_BASE_URL=https://<your-public-host>`
+  - Google redirect URI: `https://<your-public-host>/v1/auth/oauth/google/callback`
+
+The callback URI must match Google exactly, including scheme, host, port, path, and trailing slash behavior.
+
+### OAuth Consent Screen Notes
+
+For development:
+
+- keep the app in testing mode
+- add your Google account under test users if Google requires it
+
+Papyrus only requests basic identity scopes:
+
+- `openid`
+- `email`
+- `profile`
+
+## Google Smoke Test
+
+The Google smoke test now validates a live Papyrus session produced by a successful Google browser login.
+
+Recommended workflow:
+
+1. Complete a real Google login in the auth sandbox.
+2. Copy the access token or refresh token from the sandbox.
+3. Run the smoke test against the running server.
+
+Access-token-only mode:
+
+```bash
+RUN_GOOGLE_SMOKE_TEST=true \
+AUTH_SMOKE_SERVER_BASE_URL=http://localhost:8080 \
+AUTH_SMOKE_GOOGLE_ACCESS_TOKEN=<access-token-from-sandbox> \
+uv run pytest tests/integration/test_auth_smoke.py -m auth_smoke -q
+```
+
+Refresh-token mode is more durable and also validates token rotation:
+
+```bash
+RUN_GOOGLE_SMOKE_TEST=true \
+AUTH_SMOKE_SERVER_BASE_URL=http://localhost:8080 \
+AUTH_SMOKE_GOOGLE_REFRESH_TOKEN=<refresh-token-from-sandbox> \
+uv run pytest tests/integration/test_auth_smoke.py -m auth_smoke -q
+```
+
+If both are provided, the test tries the access token first and falls back to refresh if the access token is expired.
+
+Notes:
+
+- refresh-token mode rotates the provided refresh token, so the old token will stop working after the test
+- on success, the test prints `AUTH_SMOKE_ROTATED_REFRESH_TOKEN=...`; use that value for the next manual run
+- if you only provide an access token, the test is non-destructive but depends on that token still being unexpired
+- `AUTH_SMOKE_SERVER_BASE_URL` defaults to `PUBLIC_BASE_URL` if omitted

papyrus/api/routes/dev_auth_sandbox.py

@@ -349,12 +349,16 @@ def _sandbox_html(request: Request) -> str:
       }};
 
       document.getElementById("google-login").onclick = async () => {{
+        state.pendingOauthMode = "login";
+        saveState();
         const url = new URL(config.googleStartUrl, window.location.origin);
         url.searchParams.set("redirect_uri", config.redirectUri);
         window.location.assign(url.toString());
       }};
 
       document.getElementById("google-link").onclick = async () => {{
+        state.pendingOauthMode = "link";
+        saveState();
         const {{ body }} = await callApi(config.googleLinkStartUrl, {{
           method: "POST",
           body: JSON.stringify({{ redirect_uri: config.redirectUri }}),
@@ -437,19 +441,52 @@ def _sandbox_html(request: Request) -> str:
         saveState();
       }});
 
-      const params = new URLSearchParams(window.location.search);
-      const code = params.get("code");
-      const error = params.get("error");
-      if (code) {{
-        refs.exchangeCode.value = code;
-        renderLastResponse({{ status: 302, body: {{ code }} }});
-        history.replaceState(null, "", config.redirectUri);
-      }} else if (error) {{
-        renderLastResponse({{ status: 302, body: {{ error }} }});
-        history.replaceState(null, "", config.redirectUri);
+      async function handleOAuthReturn() {{
+        const params = new URLSearchParams(window.location.search);
+        const code = params.get("code");
+        const error = params.get("error");
+
+        if (code) {{
+          refs.exchangeCode.value = code;
+          history.replaceState(null, "", config.redirectUri);
+
+          if (state.pendingOauthMode === "login") {{
+            const {{ response, body }} = await callApi(config.exchangeUrl, {{
+              method: "POST",
+              body: JSON.stringify({{
+                code,
+                client_type: refs.clientType.value || "web",
+                device_label: refs.deviceLabel.value || null,
+              }}),
+            }});
+
+            if (response.ok && body) {{
+              setTokens(body);
+            }}
+          }} else if (state.pendingOauthMode === "link" && state.accessToken) {{
+            await callApi(config.googleLinkCompleteUrl, {{
+              method: "POST",
+              body: JSON.stringify({{ code }}),
+            }}, true);
+          }} else {{
+            renderLastResponse({{ status: 302, body: {{ code }} }});
+          }}
+
+          delete state.pendingOauthMode;
+          saveState();
+          return;
+        }}
+
+        if (error) {{
+          renderLastResponse({{ status: 302, body: {{ error }} }});
+          history.replaceState(null, "", config.redirectUri);
+          delete state.pendingOauthMode;
+          saveState();
+        }}
       }}
 
       setTokens(state);
+      handleOAuthReturn();
     </script>
   </body>
 </html>"""