Roadmap

See docs/AUTH_ADOPTION_PLAN.md for the host-by-host adoption sequence across zip.wtf, lobpress, cloudflare-unified-inbox, desbio, and dbscript.

v1 — DIY magic-link auth for Astro/Cloudflare

Goal: Extract, improve, and generalize the auth pattern from zip.wtf into a reusable SDK. Ship it back into zip.wtf and lobpress.com as validation.

Packages built

• packages/auth-core — contracts, types, interfaces
• packages/auth-provider-magic-link — DIY email-link flow with security hardening
• packages/auth-storage-d1 — D1 schema, migrations, queries implementing StorageAdapter
• packages/auth-astro-workers — Astro middleware, route handlers, cookie management
• packages/auth-widget-subscribe — dual-purpose subscribe/auth form component
• apps/playground-astro — dogfood demo app
• apps/site — minimal jampress.pw landing page

Key improvements over zip.wtf's current auth

• Tokens hashed at rest (SHA-256)
• D1 as source of truth for tokens/sessions (not KV — no eventual-consistency gaps)
• Rate limiting on request and verify endpoints
• Configurable cookie name, sender domain, email copy, route paths
• auth_identities table from day one (enables future provider migration)
• CSRF protection via origin checking
• Audit logging without token leakage
• Test coverage for auth flows

Deliverables

• All v1 packages implemented and tested
• playground-astro running on Cloudflare Pages
• jampress.pw deployed with docs
• Zeptomail configured on jampress.pw domain for prototype sending
• zip.wtf migrated from inline auth to SDK import

v1.5 — WordPress auth bridge + MySQL storage

Goal: Enable auth continuity for sites running WordPress alongside Astro (DesBio/DBScript decoupling use case).

Packages built

• packages/wp-shared — Shared PHP utilities + Plugin Update Checker wrapper for auto-updates from GitHub
• packages/auth-storage-mysql — MySQL storage adapter implementing the same StorageAdapter contract
• packages/wp-plugin-auth-bridge — WordPress plugin bridging WP auth events into SDK sessions

Plugin distribution pipeline

• GitHub Actions workflow per WP plugin: detect changes → Turborepo build → zip plugin directory (with wp-shared bundled) → create GitHub release → attach zip as release asset
• Tag convention: wp-{plugin-slug}-v{version} (e.g., wp-auth-bridge-v1.0.0)
• Each plugin includes Plugin Update Checker (via wp-shared wrapper) so WordPress sites see updates in wp-admin
• Private repo access via JAMPRESS_GITHUB_TOKEN constant in wp-config.php
• Future: 10up's WordPress Plugin Deploy GitHub Action for wordpress.org SVN publishing

What this unlocks

• A practitioner logs into DesBio's WordPress admin → their session is also valid on Astro-served routes
• Gradual page-by-page decoupling without auth fragmentation
• WordPress user table stays the source of truth; SDK sessions are derived
• One-click plugin updates on all managed WordPress sites via wp-admin

Deliverables

• wp-shared package with Plugin Update Checker wrapper
• GitHub Actions release workflow for WP plugins
• auth-storage-mysql passing same test suite as auth-storage-d1
• wp-plugin-auth-bridge installed on a test WordPress site
• Session bridging validated: WP login → Astro route authenticated
• Documentation for WordPress host app integration

v2 — Provider adapters (BetterAuth + Firebase)

Goal: Enable auth scaling without host app changes.

Packages built

• packages/auth-provider-betterauth — Better Auth adapter (recommended for Cloudflare-native projects)
• packages/auth-provider-firebase — Firebase Auth adapter (recommended for WordPress/hybrid projects)

Migration tooling

• Dual-session window: old provider sessions validate until natural expiry, new logins go through new provider
• CLI or Worker route to initiate/monitor migration
• Identity mapping table (auth_identities) bridges old and new provider user IDs
• Post-migration report: "X% of sessions on new provider, safe to disable old"

Auth evolution recommendations (documented)

v3+ — Future

Cross-site identity federation (packages/auth-federation)

• Central identity registry Worker with its own D1
• Opt-in SSO for related sites (e.g., DesBio + DBScript practitioner accounts)
• Each project still owns its own user record
• Registry stores email ↔ project mappings only
• Dedicated WP plugin or module for WordPress sites participating in federation
• Not default behavior — explicit opt-in per project

WordPress SSG export (packages/wp-plugin-ssg)

• Pull content from WordPress REST API or WPGraphQL
• Output Astro-compatible content collections or static pages
• Handle authenticated vs. public content based on auth-core
• Incremental builds: only re-export changed content

Gravity Forms bridge (packages/wp-plugin-gravity-bridge)

• Expose Gravity Forms submissions via REST API for Jamstack consumption
• Optional auth context for form submissions in headless setups
• Webhook forwarding to Cloudflare Workers for processing

Headless WooCommerce (packages/wp-plugin-woo-headless)

• Cart, checkout, account flows via API
• Depends on wp-plugin-auth-bridge for session continuity
• Product data access for Astro rendering
• Practitioner commission system support (DBScript use case)

Auth monitoring dashboard

• Route injectable into host apps or standalone on jampress.pw
• Session count trends, magic link send rates, failed verification attempts
• Provider usage breakdown per project
• Threshold alerts suggesting when to consider a managed provider

Additional widget variants

• auth-widget-modal — popup login modal
• auth-widget-inline — inline login form for gated content sections

Astro site-fleet blueprints

The first bounded slice is packages/fleet-schema: a versioned, data-only fleet.yaml contract with strict YAML parsing, JSON Schema validation, deterministic normalization, and a fictional three-site fixture. It supports independent collection/site D1 and R2 topology declarations without resolving Cloudflare resources or changing runtime auth.

The blueprint slices now include packages/blueprint-cli, strict versioned release/lock schemas, generated-versus-extension ownership, bounded site parameters, clean tagged releases, and offline temporary-consumer smoke tests. The provisional astro-static@0.1.0 fixture remains immutable historical evidence; 0.1.2 is the first clean release and 0.2.0 is the first multi-site parameterized release. Collection-shared D1 remains runtime-blocked until auth gains a realm/site-scoped contract.

The lock is collection-aware: one root record can map several site IDs to non-overlapping app targets, deduplicate a shared release, and represent staged per-site version upgrades. Sable and the local farm collection now provide separate three-site adoption proofs. 0.3.0 adds exact downstream verification and bundles the private verifier as a checksummed release tarball; it does not add Studio, provisioning, deployment, or a general upgrade engine. See docs/SITE_BLUEPRINTS.md.

astro-static@0.1.2 is the first clean release generated from a tagged main source commit using the guarded blueprint:release command. Its artifact lands in a separate review commit and records the source tag and commit; the existing dirty astro-static@0.1.0 fixture remains immutable historical evidence. The 0.1.1 source tag was reserved but produced no release after acceptance caught an ownership error. The next bounded work after the 0.3.0 verifier release is a deliberate downstream update workflow and the first reviewed visual/content migration into an app's extension-owned paths.

Studio/content contract slice

packages/content-contracts and packages/studio-core now provide the first host-neutral editorial seam. Records and immutable revision contracts carry collection/site scope, and every mutation carries a caller-retained replay key and optimistic version where a head already exists. Atomic replay, history, and concurrency still require a conforming repository. The role policy allows editors to draft while owners and operators control publish, rollback, and archive.

Future runtime work requires a concrete consumer and separate review: atomic storage and conformance, provider-neutral media publication contracts, and a host-authenticated HTTP adapter. Private source files and website assets must remain in separate physical buckets, with explicit authorized publication copy. No local unpublished storage proposal is a dependency of this slice. Shared-D1 deployment remains blocked until authentication and membership queries carry the same realm/site scope. Package 0.1.0 metadata is not a release receipt; immutable Studio export and downstream adoption remain future work.