Auth Adoption Plan

Purpose

This document turns the high-level auth roadmap into a concrete host-app rollout plan for:

• zip.wtf
• lobpress
• cloudflare-unified-inbox
• desbio
• dbscript

It is intentionally opinionated about sequencing, boundaries, and what "done" looks like at each stage.

Non-goals

• Not a central jampress-owned user database by default.
• Not mandatory cross-site SSO.
• Not a forced provider choice for every host app.

Each host app keeps its own user store and auth tables in its own D1 or MySQL database. jampress provides the contracts, storage adapters, provider adapters, and transport adapters.

Target Shape

The long-term target is:

1. auth-core defines the stable auth domain model
2. storage adapters persist identities, sessions, challenges, revocations, and host mappings
3. provider adapters handle proof of identity
4. transport adapters deliver runtime-specific auth behavior
5. host apps map the resolved auth identity into their own user/account/role model

In practical terms:

• Web browser: cookie session + CSRF + redirect helpers
• Native app: bearer/access token + refresh token + app callback/exchange flow
• WordPress hybrid: WP login/logout bridged into the same session model

Foundational Decisions

1. Per-app ownership stays the default

Each host app owns:

• its own auth tables
• its own user/account records
• its own permissions and business roles
• its own provider migration timing

jampress owns:

• auth contracts
• package implementations
• schema patterns
• migrations
• shared transport/provider/storage logic

2. Auth is modeled as identity -> proof -> session -> authorization

Do not let cookies, magic links, Firebase objects, or Better Auth session types become the core model. Those belong at the edge.

3. auth-astro-workers is a transport adapter, not the architecture center

The Astro/Workers package should remain the browser delivery adapter. It should not be the place where the long-term session model gets defined.

Required Platform Work

These are the next platform changes needed before broad adoption.

A. Harden auth-core

Add or formalize:

• AuthSession
• VerificationChallenge
• PresentedCredential
• AuthenticatedActor or equivalent runtime-neutral principal
• explicit host identity mapping types

The current Viewer contract remains important for host apps, but it should sit above a more general session/actor model.

B. Persist host mappings for real

The D1 schema already includes:

• host_user_id
• host_account_id

in auth_identities, but current storage code does not yet persist those values as part of the live auth flow. That needs to become a real capability before provider migration and multi-host adoption are considered reliable.

C. Expand storage beyond basic web sessions

Storage adapters should be able to persist:

• auth identities
• verification challenges
• browser sessions
• native/device sessions
• refresh token families
• revocation state
• audit events

D. Introduce transport-specific adapters

Add a clearer split between:

• auth-transport-web
• auth-transport-native or equivalent
• auth-astro-workers
• wp-plugin-auth-bridge

Web remains cookie-based. Native should not be forced to imitate cookie + CSRF browser semantics.

E. Stabilize migration and observability hooks

Add shared support for:

• dual-session migration windows
• revoke-one / revoke-all session operations
• session inspection by host app
• provider usage reporting
• basic auth event auditing

Rollout Order

Adopt in this order:

1. zip.wtf
2. lobpress
3. cloudflare-unified-inbox
4. desbio
5. dbscript

This order matters. It proves the core on the easiest Astro/Cloudflare hosts first, then on the richer authorization model, then on the WordPress hybrid sites.

Phase 1: Core Hardening + zip.wtf

Goal

Prove that jampress can replace inline auth in a real Astro/Cloudflare app without leaking provider or storage details into product code.

Deliverables

• auth-core upgraded with explicit session/challenge concepts
• D1 storage updated to persist host mappings
• web adapter remains cookie + CSRF but no longer defines the whole auth model
• migration notes for moving an existing app onto jampress
• zip.wtf migrated to the SDK

Done means

• zip.wtf pages and API routes depend on viewer and host hooks, not provider code
• existing auth routes are removed or reduced to thin wrappers
• current user/account behavior remains unchanged for end users
• session revocation and logout are verified

Phase 2: lobpress

Goal

Prove the pattern is reusable on a second Astro/Cloudflare app with minimal host-specific auth code.

Deliverables

• lobpress bootstraps auth through a host-level createAuth() module
• shared docs updated from lessons learned in zip.wtf
• any package seams that were too zip-specific are corrected

Done means

• lobpress adopts the same auth packages without forking core behavior
• host-specific logic lives only in viewer/account resolution and permissions
• the migration path is documented enough to repeat

Phase 3: cloudflare-unified-inbox

Goal

Embed jampress into a richer app that already has multi-user roles, mailbox access, and conversation-level permissions.

Integration model

cloudflare-unified-inbox should embed jampress as an in-process auth SDK, not call out to a central jampress auth service.

Deliverables

• replace inbox-local auth orchestration with a host bootstrap module
• map jampress identities/sessions onto inbox users
• keep mailbox and conversation authorization inside the inbox app
• standardize web auth routes on shared transport code
• document what a future native client would use instead of browser cookies

Done means

• auth proof/session logic comes from jampress
• inbox-specific authorization remains local to inbox code
• browser login/logout/me/OAuth routes are thin wrappers over the SDK
• the app is no longer structurally blocked on future iOS/native auth work

Phase 4: WordPress Bridge for desbio

Goal

Support Astro-served authenticated or role-sensitive pages while WordPress remains the main system of record for users and login.

Deliverables

• auth-storage-mysql is production-usable
• wp-plugin-auth-bridge can create/revoke SDK sessions on WP login/logout
• WordPress roles or user metadata can map into the host app's Viewer
• Astro routes can serve role-sensitive content using the bridged session

Done means

• a WP-authenticated user can hit protected Astro routes without a second login
• role-sensitive Astro content is available without duplicating auth logic
• no central user migration is required

Phase 5: WordPress Bridge for dbscript

Goal

Reuse the DesBio bridge pattern on a second WordPress hybrid app and harden the approach for repeatable agency use.

Deliverables

• dbscript-specific host mapping rules documented
• any DesBio assumptions removed from bridge/package code
• guidance for protected Astro routes in hybrid WP deployments

Done means

• the WP bridge is clearly reusable across multiple hybrid sites
• role-aware Astro content is not a one-off implementation

Native Readiness Track

This track should begin once Phases 1-3 are stable. It does not need to block the first zip.wtf and lobpress migrations, but it should be designed in parallel so we do not overfit to browser-only auth.

Required capabilities

• session exchange flow after magic link or OAuth
• bearer/access token support
• refresh-token support
• device/client session metadata
• native logout and revoke-device semantics
• documented iOS callback/deep-link flow

Success condition

A future iOS app can authenticate against the same auth core and the same host app user model without pretending to be a browser.

Optional Future: Federation

Cross-site identity federation remains optional and should only be revisited after:

• at least two non-trivial host apps are stable on the auth substrate
• the WordPress bridge is working in production
• the native-ready session model is clear

Federation should remain opt-in and additive. It is not required for the host app adoption plan above.

Immediate Next Milestones

1. Update auth-core and storage contracts so host mappings and richer session concepts are real, not just documented.
2. Migrate zip.wtf.
3. Migrate lobpress.
4. Replace inbox-local auth orchestration with jampress-owned auth plumbing.
5. Finish the WordPress bridge for desbio.
6. Reuse the bridge pattern for dbscript.
7. Add the native transport track once the web core is stable.