storefront-auth — Implementation Plan

storefront-auth — Implementation Plan

Alias: sa — invoke as /pipeline sa <section> or /discovery sa <section>. Section IDs in YAML + commits still use the canonical slug storefront-auth.

Context

/products is the monetization layer of fabled10x.com and the only place on the site that requires authentication. Everything else — /episodes, /cases, /tools, /about — stays open. This job is #3 in docs/future-jobs.md and Phase 2 of docs/fabled10x-website-implementation-plan.md under "Products — Storefront".

The scope is the complete /products route tree plus every piece of infrastructure it needs to exist: a Product MDX content type and loader (same pattern as Episode/Case), a Postgres persistence layer for users and purchases, Auth.js v5 wired to Resend magic-link email, Stripe Checkout integration, post-purchase delivery via a gated download route, and a customer account page. The doc frames auth as the defining constraint — auth lives here and only here, so every public route on the site must continue to render without a session cookie after this job ships.

This job depends entirely on website-foundation (alias wf) having shipped: brand design tokens, <Container>, <Header> + NAV_ITEMS, site shell, <EmailCapture> (used as a shape reference for the sign-in form), the MDX pipeline, the content loader pattern, Zod validators, the dynamic sitemap, and the resend + zod dependencies all come from that job.

Out of scope (explicit non-goals, per docs/future-jobs.md): subscription/recurring billing, course/cohort enrollment (separate cohort-enrollment job), affiliate program, refund automation, search over products, social login (magic-link only for v1), and real production product content (seed data is two placeholder MDX files with stub copy).

The four strategic decisions flagged as jobbuild-time choices have been resolved with the user:

1. Auth provider: Auth.js v5 with Resend magic-link.
2. Payment flow: Stripe Checkout (redirect).
3. Delivery mechanism: Gated download page + receipt email.
4. Persistence: Postgres + Drizzle ORM (local dev via docker-compose.yml).

What Already Exists

Already in the repo today (2026-04-11)

• Next.js 16.2.3 App Router scaffold — React 19.2.4, Tailwind 4, strict TS, @/ → src/. (package.json, tsconfig.json, next.config.ts)
• Content schemas — src/content/schemas/{content-tier,content-pillar,episode,source-material,index}.ts
• Test infra — Vitest 2.1.8 + jsdom, @testing-library/jest-dom/vitest loaded via src/__tests__/setup.ts, MSW 2.7 installed, coverage thresholds 70/80/80/80 (vitest.config.ts)
• Source docs — docs/fabled10x-website-implementation-plan.md, docs/future-jobs.md, docs/fabled10x-brand-identity.md

Delivered by website-foundation (prerequisite — NOT YET SHIPPED when this plan is written)

This job reuses these wf outputs and cannot start until they exist.

• Brand design tokens (src/app/globals.css from wf 1.3) — --color-{ink,parchment,ember,steel,mist,signal} + semantic aliases --color-{background,foreground,muted,accent,link}. Tailwind surface: bg-accent, text-muted, border-mist, text-link, bg-parchment, font-display.
• <Container> layout primitive (src/components/site/Container.tsx from wf 1.4) — mx-auto w-full max-w-5xl px-6 md:px-10, accepts className + as prop (div/section/main/article).
• <Header> + NAV_ITEMS (src/components/site/Header.tsx from wf 1.4) — this job modifies NAV_ITEMS to add /products alongside /episodes, /cases, /about.
• <Footer> (src/components/site/Footer.tsx from wf 1.4) — reused unchanged.
• <EmailCapture source="..." /> (src/components/capture/EmailCapture.tsx from wf 4.1) — not rendered inside /products (no capture funnels from the storefront) but its useActionState + server action shape is the template for <SignInForm>.
• Content loader pattern (src/lib/content/loader.ts, src/lib/content/episodes.ts, src/lib/content/cases.ts from wf 2.2) — mirrored as src/lib/content/products.ts with getAllProducts() / getProductBySlug().
• MDX pipeline (next.config.ts wrapped with createMDX(), mdx-components.tsx at project root, wf 2.1) — reused unchanged; product MDX files slot in at src/content/products/*.mdx.
• Zod validators (src/content/schemas/validators.ts from wf 1.2) — CaseSchema is the template for ProductSchema.
• Case schema shape (src/content/schemas/case.ts from wf 1.1) — reference for the Product interface structure and the as const tuple + z.enum(TUPLE) pattern.
• generateStaticParams + dynamicParams = false (wf 3.3 for /episodes/[slug], wf 3.5 for /cases/[slug]) — same pattern for /products/[slug].
• JSON-LD via dangerouslySetInnerHTML (wf 4.3) — same pattern for Product + Offer structured data on product detail pages.
• Dynamic sitemap (src/app/sitemap.ts from wf 4.4) — MODIFY to append /products + per-product URLs. Gated routes (/products/account/*, /products/downloads/*, /login*) NEVER appear in the sitemap.
• metadataBase (src/app/layout.tsx from wf 1.3) — reused for OpenGraph URLs.
• resend dependency (installed by wf 4.1) — reused for Auth.js magic-link + purchase confirmation emails.
• zod dependency (installed by wf 1.2) — reused throughout.

Gaps (must build fresh — wf provides zero coverage)

• Auth layer (identity, session management, sign-in flow)
• Route protection middleware
• A persistence layer of any kind
• Stripe integration (checkout, webhook, fulfillment)
• Download delivery
• Customer account UI

Feature Overview (10 Features, 4 Phases)

Size guide: S = few hours, single file. M = half day, 2-3 files. L = full day, 4+ files. XL = multi-day, new content type + loader + UI.

Total rough job size: XL — the biggest job in the fabled10x backlog by feature count and by the breadth of new infrastructure (DB + auth + payments

• fulfillment, all net-new).

Dependency Graph

Phase 1: Catalog (public)
│
│   1.1 → 1.2                    ← strictly sequential
│
v
Phase 2: Auth + Persistence
│
│   2.1 → 2.2 → 2.3              ← strictly sequential
│
v
Phase 3: Payments + Fulfillment
│
│   3.1 ─┬─→ 3.2 → 3.3
│        └─→ 3.3                 ← 3.2 + 3.3 both depend on 3.1 (shared client)
│
v
Phase 4: Account + SEO polish
│
    4.1, 4.2                     ← parallel after Phase 3 ships

Hard dependencies:

• 1.1 → 1.2 — both catalog routes call getAllProducts() / getProductBySlug(); the validator gates the loader at content boundary.
• Phase 1 → Phase 2 — Phase 2 doesn't read the product catalog, but the plan ships sequentially so the public catalog is shippable on its own if auth/payments slip.
• 2.1 → 2.2 — Auth.js adapter consumes Drizzle schema (users, sessions, verificationTokens tables).
• 2.2 → 2.3 — middleware reads the Auth.js session cookie set by sign-in; <SignInForm> calls Auth.js's signIn('resend', ...) server action.
• Phase 2 → Phase 3 — every payment feature depends on a logged-in user (Stripe customer linked to users.id) and on purchases table existing.
• 3.1 → 3.2, 3.3 — webhook + download handler both consume the Stripe client and the live BuyButton from 3.1.
• 3.2 → 3.3 — download handler reads purchases rows that the webhook wrote.
• Phase 3 → Phase 4 — account pages read purchases rows the webhook creates.
• 4.2 can run in parallel with 4.1 after Phase 3 ships — different surfaces (account UI vs cross-cutting SEO/error polish).

New Content Types Required

The Product schema lives at src/content/schemas/product.ts and is re-exported from src/content/schemas/index.ts alongside Episode, Case, SourceMaterial. Product content files live at src/content/products/*.mdx following the same export const meta = {...} + MDX body convention established by wf 2.3 for episodes and cases.

New DB Tables (Drizzle schemas, Postgres dialect)

Indexes: purchases(user_id) for account-page list queries, purchases(stripe_session_id) (implicit via UNIQUE) for webhook idempotency checks. No email password column — Auth.js v5 magic-link never touches passwords.

Critical Files Reference

New files

Content schema + catalog (Phase 1)

Public catalog routes (Phase 1)

Persistence + auth (Phase 2)

Payments + fulfillment (Phase 3)

Customer account (Phase 4)

SEO + global (Phases 1 & 4)

Reference-only files (read, don't modify)

• src/content/schemas/case.ts — shape to mirror for Product
• src/content/schemas/validators.ts — CaseSchema is the template for ProductSchema
• src/lib/content/loader.ts — core loadContent<T>() helper called by the product loader
• src/lib/content/episodes.ts + src/lib/content/cases.ts — loader API to mirror in products.ts
• src/app/episodes/[slug]/page.tsx + src/app/cases/[slug]/page.tsx — detail page pattern (async, params: Promise<{ slug: string }>, generateStaticParams, dynamicParams = false, JSON-LD inline)
• src/components/capture/EmailCapture.tsx — useActionState + server action shape for <SignInForm>
• src/app/sitemap.ts (before modification) — existing dynamic sitemap pattern
• node_modules/next/dist/docs/01-app/02-guides/authentication.md — Next.js 16 guidance on middleware, cookies, sessions
• node_modules/next/dist/docs/01-app/03-api-reference/04-functions/cookies.md — async cookies() API
• node_modules/next/dist/docs/01-app/03-api-reference/03-file-conventions/route.md — Route Handler signatures
• node_modules/next/dist/docs/01-app/02-guides/upgrading/version-16.md — params: Promise<...> breaking change

Verification Plan

Phase Documentation

• Phase 1: Catalog — Product schema, validator, loader, /products index, /products/[slug] detail
• Phase 2: Auth + Persistence — Postgres+Drizzle, Auth.js v5, middleware, login pages
• Phase 3: Payments + Fulfillment — Stripe client, checkout session, webhook, download handler, confirmation email
• Phase 4: Account + SEO — account pages, sign-out, SEO/JSON-LD/sitemap/nav/robots, polish

Dependencies to Add

Installed at the start of each phase that needs them:

• Phase 2.1: postgres, drizzle-orm, drizzle-kit (devDep)
• Phase 2.2: next-auth@5, @auth/drizzle-adapter
• Phase 3.1: stripe

Already installed by wf and reused: zod, resend, @testing-library/*, vitest, Tailwind, React 19.

Environment Variables

Required before the matching phase can be verified end-to-end. All are server-only (no NEXT_PUBLIC_ prefix) except the Stripe publishable key.

Open Items (Resolve During Implementation)

• Product seed copy — 1.1 ships two stub MDX files with placeholder title / summary / price. Real product content is a separate concern and not part of this job.
• Stripe product/price provisioning — user must create Stripe Product + Price objects in the Stripe dashboard and map the resulting price_xxx IDs to product slugs via the stripePriceId field in each MDX meta export. Phase 3.1's resolveStripePriceId() helper reads from the loaded Product record.
• Production DB hosting — docker-compose.yml covers local dev. Production hosting decision (same VPS via docker/systemd vs managed Postgres via Neon/Supabase/Render) is deferred; the app only needs DATABASE_URL. Document the decision in docs/deployment-notes.md (new, as a follow-up) before the first deploy.
• License-model scaling — PRODUCT_LICENSE_TYPES tuple ships with 'single-user' | 'team' | 'agency' to leave room for future expansion, but only 'single-user' appears in seed data and is handled by the checkout flow. Team/agency pricing + seat management is a future job.
• Asset hosting migration — Phase 3.3 streams files from private/products/ on the VPS filesystem. Migrating to S3-compatible object storage with signed URLs is a future polish.

Section IDs for TDD Workflow

Each feature maps to one section ID used by /discovery, /red, /green, /refactor. Section IDs use the canonical slug storefront-auth, not the alias sa.

These IDs are consumed by pipeline/active/session.yaml and used as directory names under pipeline/active/.