Runbook: Email Pull OAuth App Swap

This runbook covers the transition of the Email Pull feature from the legacy gog-cli OAuth app to the CASA-verified Ordermatic OAuth app.

Overview

The gog-cli OAuth app was used during initial development and Phase 1. As we move to Phase 1.5, we must swap to the official Ordermatic app which has undergone CASA (Cloud App Security Assessment) verification.

Critical Note: Refresh tokens are bound to the OAuth app that issued them. Swapping the client_id and client_secret will invalidate all existing customer connections. Customers MUST reconnect their mailboxes to resume polling.

Phase 1: Pre-Swap Notification (Window: T-48h)

1. Identify Affected Customers: Query the database for all active email pull connections:

   SELECT DISTINCT clerk_organization_id, email_address, provider
   FROM email_pull_connections
   WHERE status = 'active';

2. Send Notification: Email affected customers/admins notifying them of the scheduled maintenance window.
   • Subject: [Action Required] Reconnect your Email Ingestion mailbox
   • Content: We are upgrading our security infrastructure. Your email connection will be paused on [Date/Time]. You will need to click “Reconnect” in the Settings -> Email Connections menu to resume order ingestion.

Phase 2: Swap Window

1. Update Secrets in Infisical: Update the following secrets in the webapp and temporal-worker environments (Staging and Production):

   • GOOGLE_OAUTH_CLIENT_ID
   • GOOGLE_OAUTH_CLIENT_SECRET
   • MICROSOFT_OAUTH_CLIENT_ID
   • MICROSOFT_OAUTH_CLIENT_SECRET

   These should now point to the Ordermatic CASA-verified app credentials.

2. Verify Secret Deployment: Trigger a deployment or restart of the webapp and temporal-worker to ensure they pick up the new secrets.

Phase 3: Post-Swap Verification

1. Monitor Failures: Monitor the email_pull.poll.failure counter in Grafana/Betterstack.

   • Expected Behavior: A spike in auth_revoked or invalid_grant errors for all existing connections.
   • Recovery: Errors should decrease as customers reconnect.

2. Support Reconnection: Customers will see a “Disconnected” or “Error” status in the UI. They should click the “Reconnect” button (implemented in ENG-504) to initiate a new OAuth flow with the Ordermatic app.

3. Validate New Connections: Ensure new connections are successfully issuing tokens from the new app.

   SELECT id, email_address, status, last_error, updated_at
   FROM email_pull_connections
   ORDER BY updated_at DESC LIMIT 10;

Rollback Plan

If critical issues occur (e.g., the new app is not accepting tokens):

1. Revert the Infisical secrets to the gog-cli credentials.
2. Notify customers that the upgrade has been postponed and they should reconnect if they already did.