# Real Production Onboarding

> **SUPERSEDED (2026-08-19):** This PayPal/license-key design is historical only. Current production architecture is Connect/social auth + Stripe checkout + encrypted backend-issued per-site API credentials, using the Cloudflare Worker `/api/*` contract. Do not implement this document.


Audience: AI coding agents first.

- Status: ACTIVE
- Task IDs: B1–B5 (backend), P1–P7 (plugin) — defined in [design spec](../specs/2026-08-13-real-onboarding-design.md)
- Source request: owner mission 2026-08-13 — replace the abandoned mock-checkout demo concept with REAL production onboarding: real registration via existing backend onboarding routes, REAL checkout via PayPal (sole payment processor; Morning/Green Invoice invoices only), license activation, managed credential provisioning. Keep the one-click UX shape of the preserved snapshot spec; discard everything mock/dev-only. PayPal SANDBOX validation only; no live keys; no production smoke transactions; no deploy.

## Outcome

WP admin enters email+password, clicks `Register & Start Translating` once, approves the PayPal sandbox subscription, and lands on `#/translations` with an active license and a managed API credential stored encrypted server-side. Browser never sees license key, API credential, or account token. All money/auth mutations idempotent; webhook processing replay-safe.

## Acceptance criteria

1. Real registration via backend `/v1/auth/register` through existing plugin route; JWT server-side only.
2. Real checkout via backend PayPal subscription checkout (`/v1/subscriptions/checkout` resolvable — B1) with `Idempotency-Key` (B3); duplicate click/retry NEVER creates a second PayPal subscription.
3. Session retrieval mints license AND managed API credential in one transaction (B2); plugin persists both encrypted atomically before reporting active (P1/P2); no secret in any browser-visible response (P3).
4. Mock-checkout plugin proxies removed; UJ-010 updated to the real path (P4).
5. `/onboarding/status` reports `{needs_onboarding, needs_credential_repair, license_status}`; repair path re-provisions credential idempotently (P5/B5).
6. Webhook handler failure no longer swallows redelivery (B4).
7. Gates green: plugin factory-gate (php-syntax, phpunit+standalone, phpcs, phpstan, admin lint/build), backend Jest + tsc + Prisma migration, commit gate; every signal resolved.
8. Independent adversarial security review of auth+payment diff (IDOR, credential leakage, idempotency, webhook replay) — findings fixed.
9. End-to-end verified against PayPal sandbox + local Podman WordPress only.
10. Landed on origin/master (fetch/rebase, non-force push). NOT deployed.

## Constraints / preserved WIP

- Coordinate with in-flight licensing-hardening lane (`wt/licensing-hardening`, ActivationManager AES-256-GCM key handling): fetch/rebase before touching `includes/Licensing/`; build on it if landed, otherwise port the key handling (master's copy was clobbered by the `2d7b31a1e` rebase; gate test `LicenseStorageKeyStandaloneTest` red on master).
- Working branch: `wt/real-onboarding` in `.worktrees/real-onboarding` (from origin/master `826ba2bf8`).
- NEVER touch abandoned Translate/Multilingual plugin trees.
- PayPal sandbox credentials present in `press-zone-backend/api/.env` (shared checkout; `PAYPAL_MODE=sandbox`, plan IDs configured).

## Execution steps

1. Phase 1 (this commit): design spec + this plan + INDEX entry; land docs commit separately.
2. Backend B1–B5 with Jest coverage (checkout idempotency, session retrieval mint, webhook replay).
3. Plugin P1–P7 with unit/standalone coverage; admin SPA rebuild.
4. Gates + adversarial security review; fix findings.
5. Sandbox E2E: local backend stack (podman-compose, sandbox env) + local Podman WordPress; full one-click journey incl. PayPal sandbox approval.
6. Fetch/rebase, push HEAD:master non-force. Report SHAs + sandbox evidence.

## Receipt

- 2026-08-13: surveys complete (plugin + backend maps), design spec authored, plan registered. Next executable action: land docs commit, then backend B1–B5.