Skip to content

Implement the starter roadmap - #13

Open
solev wants to merge 10 commits into
mainfrom
feat/roadmap-implementation
Open

solev wants to merge 10 commits into
mainfrom
feat/roadmap-implementation

Conversation

@solev

@solev solev commented Aug 17, 2026 •

Copy link
Copy Markdown
Owner

Implements docs/roadmap.md end to end. Closes #12.

Rocket had no tests, no lint gate, and no CI, so every claim about it was
unverified. This branch builds that floor first, then uses it to fix Core
correctness, give capabilities a contract, and take the Better Auth upgrade
that had been waiting on a safety net.

1. Quality foundation

Biome, a three-project Vitest harness (59 unit + 27 integration tests), a
Playwright smoke journey, migration drift detection, .env.example drift
detection, CI, and Dependabot. bun run check is the single gate; CI runs the
same command, so local and CI cannot disagree.

Zod-validated env replaces scattered process.env reads. emptyStringAsUndefined
is what kills the GOOGLE_CLIENT_ID || "" class of bug: a blank var is now
absent, not a silent empty credential.

2. Core correctness

The tests immediately found real defects, each now locked by a regression test:

  • Logout did not log you out. auth.api.signOut deleted the session row but
    its cookie-clearing headers were never forwarded, so the browser kept the
    cookie. With the session cookie cache this left a five-minute window where a
    signed-out user was still authenticated.
  • Password reset was unreachable (Password reset is unreachable without an email transport #12) — no routes existed. Better Auth's
    own response body differs for known vs unknown addresses, leaking account
    existence, so /forgot-password discards the upstream result and always
    returns the same acknowledgement.
  • Google sign-in rendered when unconfigured, sending users to a broken
    consent screen.
  • /avatars/shadcn.jpg did not exist, so every dashboard render raised a
    routing error.

3. Capability contract

A capability is either fully configured or absent; there is no half-configured
state. Billing and AI chat are retrofitted onto the pattern — a pure config.ts
with no env access plus a thin .server.ts binding — each with four-state tests
and a guide in docs/capabilities/.

4. Better Auth 1.3.7 → 1.6.29

Deliberately done last, because the upgrade needed the safety net from section 1
to be verifiable rather than hopeful. It forced @polar-sh/better-auth 1.1.0 →
1.8.4, and auth.api.forgetPassword became requestPasswordReset. Migration
0004 adds the indexes 1.6 generates by default and backfills the verification
timestamps before making them NOT NULL.

5. Five defects found by running against the production build

Pointing the smoke journey at the built artifact instead of the dev server —
the thing that actually gets deployed, and the only one where rate limiting is
on — turned up five more. None were visible in a screenshot.

  • Auth rate limits put every user in one bucket. Better Auth only takes the
    client IP from a single header you name, because behind an appending proxy the
    first entry of a forwarded chain is client-controlled. With none named it
    cannot tell callers apart, and /sign-in/email allows three attempts per ten
    seconds — so three failed sign-ins from anyone locked out everybody.
    AUTH_IP_ADDRESS_HEADER must be set when deploying; see the README.
  • The eleventh user sharing a display name could not sign up. Organization
    slugs counted upwards with a hard cap of ten, and exhausting it threw.
  • Anything typed before hydration was silently discarded. The auth forms
    were controlled by React state, so the first state update replaced what the
    user typed and submitted a blank form. Both are uncontrolled now and read
    FormData.
  • Vercel Web Analytics broke hydration everywhere except Vercel. Its script
    404s off-platform and hydration failed with React error #418, leaving pages
    that looked correct but had dead event handlers.
  • A cold bun run dev reloaded the page mid-hydration, wiping half-filled
    forms.

Review notes

  • No table is dropped. An earlier revision of this branch dropped the unused
    Better Auth two_factor table; that was reverted. A starter's migrations run
    against every clone's database, and a clone that mounted the twoFactor
    plugin would hold real TOTP secrets, so the table is declared in schema.ts
    and left in place instead. The plugin stays unmounted.

  • Polar webhook routing is unverified. Proving it needs a live Polar
    account, which the test contract forbids. Tracked in the roadmap.

  • The organization plugin is deliberately not mounted — Define the organizations and admin capability #9 was closed
    unresolved, so mounting it would expose undecided endpoints. A test asserts
    /api/auth/organization/create returns 404.

  • Signup is now atomic. Better Auth commits the user row before the
    user.create.after hook runs and does not roll it back when that hook throws.
    Organization provisioning happens in that hook, so any failure there stranded a
    user with no account row — reserving the address so the person could neither
    sign in nor sign up again. Found while diagnosing a local registration failure
    against an unmigrated database. The hook now removes the row it cannot complete
    and rethrows the original cause. The session hook stays strict: a session with
    no organization has no ownership boundary.

  • First-run setup friction, found by hitting it. TEST_DATABASE_URL was
    commented out in .env.example, so it was absent from every copied .env and the
    first bun run check stopped on a missing variable. The gate's own command comment
    also listed every step except test:integration, so that stop read like a broken
    test rather than an unset variable. The key now ships uncommented with the value
    db:up already creates, and the comment names the step. env:check strips comment
    markers, so drift detection is unaffected either way.

Verification

bun run check exits 0 (format, lint, typecheck, env drift, 59 unit tests, 30
integration tests, migration drift, build). All 7 Playwright tests pass with no
retries. CI is green across all four jobs, and the database migrates from zero.

solev and others added 3 commits August 17, 2026 12:06
…ty contract

Implements docs/roadmap.md sections 1-3.

Quality foundation
- Centralize environment validation in app/lib/env with @t3-oss/env-core and
  Zod. Empty strings become absent, so silent `|| ""` fallbacks cannot return.
  Capability variables validate as all-or-nothing groups; BETTER_AUTH_SECRET
  and BETTER_AUTH_URL are required in production.
- Guard the test database: refuse to run when TEST_DATABASE_URL is absent,
  equals DATABASE_URL, or names a database without "test" in it.
- Add Biome, Vitest (unit / dom / integration projects) and a Playwright smoke
  journey. `bun run check` is the single gate, locally and in CI.
- Add schema-drift and .env.example checks, and GitHub Actions in four
  parallel jobs plus grouped Dependabot updates.

Core correctness
- Make password reset reachable (#12): add /forgot-password and
  /reset-password/:token, link them from the login form, and route delivery
  through a Core email seam that logs in development and refuses in
  production. The forgot-password action answers identically for known and
  unknown addresses; Better Auth's own endpoint leaks account existence.
- Gate Google sign-in honestly: absent credentials mean the provider is never
  registered and its button never renders; partial credentials fail startup.
- Drop the dead two_factor table, whose plugin was never mounted.
- Add organization-aware ownership: organization and member tables,
  session.activeOrganizationId, and provisioning via Better Auth database
  hooks. The organization plugin stays unmounted, since management was
  dropped in #9 and mounting it would expose undecided endpoints.

Capability retrofit
- Localize Polar billing and Azure AI Chat under app/capabilities/, each split
  into a pure config.ts and a server binding, with a non-throwing availability
  check, CapabilityUnavailableError on unavailable invocation, four-state
  tests, and a guide covering manual removal.

Bugs found and fixed while testing
- Logout deleted the server session but never forwarded Better Auth's
  cookie-clearing headers. With the new session cookie cache, a signed-out
  visitor stayed authenticated until the cache expired.
- The sidebar fell back to /avatars/shadcn.jpg, which does not exist, so every
  dashboard render raised a routing error. Missing avatars now show initials.
- Slugs turned apostrophes into separators, producing
  "ada-lovelace-s-organization".
- Reset links were relative, and so unusable in a message.

Also rewrites the README for what Rocket now is, adds capability guides, and
stops tracking .openlogs/.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
The pin was the last open item in docs/roadmap.md section 2. It was deferred
until the test suite existed to catch a regression; with 57 unit and 26
integration tests plus the smoke journey in place, the upgrade is verifiable.

- better-auth 1.3.7 -> 1.6.29
- @polar-sh/better-auth 1.1.0 -> 1.8.4 and @polar-sh/sdk -> 0.47.0. The old
  plugin does not satisfy the new BetterAuthPlugin type; its peer range
  requires better-auth ^1.4.12, so both had to move together.
- auth.api.forgetPassword is now auth.api.requestPasswordReset. The reset
  callback path is unchanged, so /reset-password/:token still matches.
- Set BETTER_AUTH_URL in the integration harness. 1.6 warns that it otherwise
  derives the origin per request, which would make reset links depend on
  whichever request built them.

Schema alignment (migration 0004, non-destructive):
- index session.user_id, account.user_id, and verification.identifier, which
  1.6 now generates by default
- verification.created_at and updated_at become NOT NULL, backfilled first so
  the migration also applies to a database that predates the guarantee

Verified: bun run check passes, the database migrates from zero, and the
Playwright smoke journey passes.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
- roadmap: move the 1.3.7 pin out of "Still open" into a done section, and
  note that bun run check omits the smoke journey by design
- dependabot: also ignore better-auth minors, not just majors. The 1.3 -> 1.6
  upgrade renamed an api method and changed the generated schema, so its
  minors are breaking in practice. Pin the Polar plugin alongside it, since it
  peers on a narrow better-auth range and can only move in the same pass.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@vercel

vercel Bot commented Aug 17, 2026 •

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated (UTC)
rocket Ready Ready Preview Aug 22, 2026 12:38pm

@github-advanced-security

Copy link
Copy Markdown

You are seeing this message because GitHub Code Scanning has recently been set up for this repository, or this pull request contains the workflow file for the Code Scanning tool.

What Enabling Code Scanning Means:

  • The 'Security' tab will display more code scanning analysis results (e.g., for the default branch).
  • Depending on your configuration and choice of analysis tool, future pull requests will be annotated with code scanning analysis results.
  • You will be able to see the analysis results for the pull request's branch on this overview once the scans have completed and the checks have passed.

For more information about GitHub Code Scanning, check out the documentation.

The journey ran against the dev server, which hid real problems and invented
fake ones: it was flaky in CI, and the flake turned out to be the app, not the
test. Pointing it at the production build — the artifact that actually gets
deployed, and the only one where rate limiting is on — surfaced the rest.

Auth rate limits put every user in one bucket. Better Auth only takes the
client IP from a single header you name, because behind an appending proxy the
first entry of a forwarded chain is client-controlled. With no header named it
cannot tell callers apart, and since /sign-in/email allows three attempts per
ten seconds, three failed sign-ins from anyone locked out everybody.
AUTH_IP_ADDRESS_HEADER now names it, and each smoke test presents its own
address so the suite exercises per-caller bucketing rather than working around
it.

The eleventh user sharing a display name could not sign up. Organization slugs
were disambiguated by counting upwards with a hard cap of ten; exhausting it
threw and failed the signup. Allocation now tries a few readable candidates and
then switches to a random token, so a common name cannot deny anyone an
account.

Anything typed before hydration was silently discarded. The login and signup
forms were controlled by React state, so the first state update replaced what
the user had typed with the empty initial state and submitted a blank form.
Both forms are uncontrolled now and read FormData on submit. The regression
test throttles the CPU to make hydration reliably slow enough to type ahead of.

Vercel Web Analytics broke hydration everywhere except Vercel. Its script 404s
off-platform, React Router logged an unmatched route on every page load, and
hydration failed with React error #418 — leaving pages that looked correct but
had dead event handlers. It is gated on the platform providing it, and the
journey now asserts the public pages hydrate without browser errors, since a
screenshot cannot tell the difference.

A cold `bun run dev` reloaded the page mid-hydration. Vite's first crawl only
sees the root route, so the first navigation discovered a second batch of
dependencies and force-reloaded, which is what wiped half-filled forms.
optimizeDeps.include names them so it pre-bundles in one pass.

Each fix has a test that fails without it. bun run check passes and all 7
Playwright tests pass.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Throttling the CPU 20x reproduced the bug locally but timed out on CI's slower
shared runners, so the test passed only on retry — a flaky test that reports the
app is fine when it never actually finished.

Hold the scripts back instead. A slow connection reproduces the same condition
as a slow machine, but on a schedule the test controls: type into the
server-rendered HTML, release hydration, then submit. It fails against the old
controlled forms and passes against the fix, in five seconds rather than thirty.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
two_factor is Better Auth's, created by its twoFactor plugin. An earlier commit
dropped it as dead weight, on the grounds that the plugin was never mounted --
user.twoFactorEnabled was never added either, so two-factor auth has never
actually worked in this repo.

That reasoning was about tidiness and it loses to a data-safety one. Rocket is a
starter: its migration history runs against every clone's database, and a clone
that diverged and mounted the plugin would hold real TOTP secrets and backup
codes. DROP TABLE ... CASCADE in shared migration history destroys those with no
way back, which is a poor trade for removing an empty table that costs nothing
to keep. It also cuts against the upstreaming workflow, where clones are
expected to diverge and feed work back.

- drop the two statements from migration 0003, which has not merged to main, so
  no drop-then-recreate churn is needed
- declare the table in schema.ts so drizzle stops proposing the drop on every
  generate, with a comment on why it is unmounted
- restore two_factor in the 0003 and 0004 metadata snapshots to match

The plugin stays unmounted; mounting it is a product decision and would need
twoFactorEnabled on user. Verified with drizzle-kit check, a migration from
zero, and bun run check.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
solev and others added 2 commits August 22, 2026 15:21
Found while diagnosing a local registration failure: the dev database was
missing the organization and member tables, so signup returned
FAILED_TO_CREATE_USER — and left a user row behind.

Better Auth commits the user before user.create.after runs and does not
roll it back when the hook throws. Organization provisioning happens in
that hook, so any failure there stranded a user with no account row. The
practical harm is worse than the error itself: the address is reserved,
so the person can neither sign in (no credentials exist) nor sign up
again. The test reproduces exactly that, failing with "User already
exists. Use another email."

The hook now removes the row it cannot complete and rethrows the original
cause, so a failed attempt leaves no trace and retrying works once the
underlying problem is fixed. Cleanup failure is swallowed deliberately —
the original error is the one worth surfacing.

The session hook is deliberately left strict. It provisions lazily for
users who predate organization ownership, but a session with no
organization has no ownership boundary, so failing there is correct.

Verified: the three new tests fail without the fix, bun run check exits 0,
30 integration tests pass.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
An unmigrated database does not fail at startup; it fails when the missing
table is first queried, which reads as an unrelated runtime error. That
cost real debugging time when a missing organization table surfaced only
as a failed signup.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
The command comment listed every step except `test:integration`, so a
`check` run that stopped on a missing `TEST_DATABASE_URL` looked like a
broken test rather than an unset variable. Name the step and point at the
section that explains the variable.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Commented out, the key was absent from every copied .env, so the first
`bun run check` stopped on a missing variable. The value it needs is the
database `db:up` already creates, so hand it over rather than making each
clone rediscover it. `env:check` strips comment markers, so uncommenting
does not affect drift detection.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

This branch was successfully deployed

1 active deployment
Preview — 5b4b36aa Deployed Aug 22, 2026 by vercel[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Password reset is unreachable without an email transport

2 participants