Skip to content
Bookmarks Docs

Auth Worker Migration

Auth Worker Migration

Section titled “Auth Worker Migration”

This runbook covers migration from:

  • workers/cosmos/auth

to:

  • workers/bookmarks/auth

with minimal user disruption and a fast rollback path.

Difficulty and timeline

Section titled “Difficulty and timeline”
  • Estimated difficulty: medium-high (7/10)
  • Recommended timeline: 1-2 weeks (fork-and-trim approach)

Scope

Section titled “Scope”

Bookmarks currently depends on auth for:

  • /api/auth/login
  • /api/auth/register
  • /api/auth/password/reset-request
  • /api/auth/password/reset-confirm
  • /api/auth/refresh
  • /api/auth/verify
  • /api/v1/verify (token verification used by Bookmarks API middleware)

Success criteria

Section titled “Success criteria”
  • No increase in login/refresh failure rate after cutover.
  • Session expiry continues to auto-redirect to login in app.
  • Verification and reset emails still deliver and links resolve.
  • Rollback can be completed by binding change only.

Migration strategy

Section titled “Migration strategy”
  1. Clone cosmos-auth-worker to bookmarks-auth-worker.
  2. Clone cosmos-mail-worker to bookmarks-mail-worker.
  3. Keep endpoint contracts identical during first cut.
  4. Use dedicated Bookmarks auth + mail D1/KV/queue resources.
  5. Keep secrets/config parity.
  6. Validate in staging with Bookmarks API bound to new auth worker.
  7. Cut over production by changing only AUTH_SERVICE binding in workers/bookmarks/api.
  8. Monitor, then remove legacy dependency after stabilization.

Phase 1: Create worker

Section titled “Phase 1: Create worker”
  1. Copy workers/cosmos/auth to workers/bookmarks/auth.
  2. Update wrangler.toml names/bindings/database names for Bookmarks.
  3. Keep route paths unchanged.
  4. Keep auth token and verify behavior unchanged.

Phase 1b: Create dedicated mail worker

Section titled “Phase 1b: Create dedicated mail worker”
  1. Copy workers/cosmos/mail to workers/bookmarks/mail.
  2. Update worker/package names to bookmarks-mail-worker.
  3. Provision dedicated Cloudflare resources for Bookmarks mail:
    • KV namespace
    • D1 database
    • queue + DLQ
  4. Replace inherited IDs in wrangler.toml with Bookmarks-specific IDs.
  5. Deploy and validate POST /api/send-email.

Phase 2: Environment parity

Section titled “Phase 2: Environment parity”

Set equivalent vars/secrets in bookmarks-auth-worker:

  • JWT_SECRET
  • ENCRYPTION_KEY
  • APP_URL=https://bookmarksapp.cosmosdigitalservices.com
  • Access verification config (ACCESS_TEAM_DOMAIN, ACCESS_AUD, ACCESS_ISSUER)
  • Turnstile settings, if enabled
  • MAIL_SERVICE binding -> bookmarks-mail-worker

Phase 3: Data + token plan

Section titled “Phase 3: Data + token plan”

Choose one path:

  1. Hard cut (simpler): users re-login once after cutover.
  2. Soft continuity (preferred): preserve token verification compatibility during rollout by keeping token signing/verification compatible until refresh churn completes.

Recommended:

  • Keep JWT verification compatibility at cutover.
  • Accept old refresh tokens for a grace window if feasible.
  • Force rotate tokens after grace window.

Phase 4: Staging validation

Section titled “Phase 4: Staging validation”
  1. Deploy bookmarks-auth-worker to staging.
  2. Deploy bookmarks-mail-worker staging.
  3. Point bookmarks-auth-worker staging MAIL_SERVICE to bookmarks-mail-worker-staging.
  4. Point staging workers/bookmarks/api AUTH_SERVICE to bookmarks-auth-worker.
  5. Run smoke tests:
    • register/login/logout
    • refresh flow
    • password reset request + confirm
    • email verify redirect to /verify-email
    • /v1/me
    • websocket auth to /v1/clubs/:clubId/stream
  6. Confirm app/session behavior:
    • token refresh works
    • expired sessions auto-redirect to login
    • app resume reconnect still works

Phase 5: Production cutover

Section titled “Phase 5: Production cutover”
  1. Deploy bookmarks-auth-worker production.
  2. Deploy bookmarks-mail-worker production.
  3. Ensure bookmarks-auth-worker MAIL_SERVICE binds to bookmarks-mail-worker.
  4. Update workers/bookmarks/api/wrangler.toml:
    • [[services]] binding = "AUTH_SERVICE" -> bookmarks-auth-worker
  5. Deploy bookmarks-api-worker.
  6. Monitor:
    • auth error rate
    • refresh failures
    • password reset failures
    • verification redirect errors

Rollback plan

Section titled “Rollback plan”

If regressions occur:

  1. Re-point workers/bookmarks/api AUTH_SERVICE back to cosmos-auth-worker.
  2. Redeploy bookmarks-api-worker.
  3. Re-run auth smoke tests.

Rollback target time: under 15 minutes (binding + deploy only).

Post-cut cleanup

Section titled “Post-cut cleanup”
  1. Update docs and runbooks to remove cosmos-auth-worker references for Bookmarks flows.
  2. Remove temporary compatibility paths after stabilization window.
  3. Archive migration metrics and incident notes.

Checklist

Section titled “Checklist”
  • bookmarks-auth-worker created from cosmos-auth-worker
  • D1 database created and schema applied
  • bookmarks-mail-worker created from cosmos-mail-worker
  • Mail worker KV/D1/queue resources created
  • Secrets and vars configured
  • Auth MAIL_SERVICE bound to bookmarks-mail-worker and tested
  • Staging binding switched and validated
  • Production binding switched
  • Monitoring clean for 48 hours
  • Legacy dependency references removed