feat: remove v2 compatibility paths

[olliethedev]

Summary

• make top-level StackProvider router, API, and auth configuration the only framework wiring path
• remove legacy plugin override fields, page-render guard callbacks, boolean-return hook shims, and manual comments identity props
• update tests, codegen templates, docs, agent guidance, and rebuilt shadcn registry artifacts

Validation

• pnpm build
• pnpm typecheck
• pnpm lint
• pnpm test (594 tests)
• pnpm --filter @btst/stack run knip --reporter github-actions
• COREPACK_ENABLE_AUTO_PIN=0 pnpm --dir docs build
• pnpm --filter @btst/stack test-registry
• scoped rg sweeps and git diff --check

Closes #151

---

Note

Medium Risk
This is a breaking consumer-facing API change around provider wiring, comments identity, and hook denial semantics. Risk is mainly migration/auth gating, not new security primitives.

Overview
v3 now has a single wiring path: router, api, and auth live on StackProvider. Plugin overrides keep only plugin-specific values (uploads, slots, localization). Per-plugin Link/Image/navigate/refresh/apiBaseURL/apiBasePath are gone from override types.

Auth and hooks: onBefore*PageRendered callbacks are removed; client gating uses auth.can on ComposedRoute permissions. Lifecycle hooks deny by throwing, not return false. Comments (CommentThread, counts, my-comments) read API/identity/login from the provider instead of manual props.

Docs, agent skills, CLI templates, and comments e2e tests are updated to this contract (including dropping currentUserId query spoofing in list tests). SSR plugin factories still take apiBaseURL/apiBasePath because loaders run outside React context.

^{Reviewed by Cursor Bugbot for commit 981f2a5. Bugbot is set up for automated code reviews on this repo. Configure here.}

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
better-stack-docs	Ready	Preview	Aug 20, 2026 11:44pm
better-stack-playground	Ready	Preview	Aug 20, 2026 11:44pm

[cursor]

Security Review — feat: remove v2 compatibility paths

Overall this is a clean major-version break. No injection, SSRF, XSS, or supply-chain risks were found. Two findings are worth addressing before merge, one at medium and one at low-medium severity.

---

[MEDIUM] Silent authorization bypass — onBeforeSubmission returns false

form-builder/api/plugin.ts calls onBeforeSubmission directly (not via runHook) and previously had an explicit compat guard:

// Removed in this PR:
if (hookResult === false) {
    originalError = new Error("Submission rejected");
}

After this PR, if a consumer's onBeforeSubmission hook returns false to block a submission, originalError remains undefined, the submission proceeds normally, and onSubmissionError is never called. Only throwing works as a denial now. Unlike the runHookWithShim → runHook rename (which is consistently applied and documented), this specific guard is removed without a mention in breaking-changes.mdx.

Concrete risk: A consumer with:

onBeforeSubmission: async (formId, data, ctx) => {
  if (!ctx.headers.get('x-user-id')) return false; // ← now silently allows
}

will have their denial bypassed after upgrading to v3.

Recommendation: Add a note to the "Backend hooks deny by throwing" section in breaking-changes.mdx that explicitly calls out onBeforeSubmission, or reintroduce a guard at the call site that throws (or warns) when hookResult === false.

---

[LOW-MEDIUM] Client-side page guards removed — no auth.can replacement shown in routes

Three client-side render guards were removed from the Comments plugin (onBeforeModerationPageRendered, onBeforeResourceCommentsRendered, onBeforeUserCommentsPageRendered). The breaking-changes doc says to replace them with auth.can on StackProvider, but the moderation and user-comments route definitions in commentsClientPlugin do not add a ComposedRoute permission gate. SSR loader hooks remain and protect server-side prefetching, but there is no client-side navigation guard equivalent.

Concrete risk: A consumer relying on onBeforeModerationPageRendered to gate the admin dashboard loses that protection silently after upgrading unless they also wire auth.can.

Recommendation: Add a before/after migration example in breaking-changes.mdx showing the auth.can replacement, and/or add a ComposedRoute auth gate to the moderation and user-comments route definitions.

---

Informational — return false in all other onBefore* backend hooks

The runHookWithShim → runHook rename removes the boolean-return compat shim from all remaining backend hooks. This is documented in breaking-changes.mdx under "Backend hooks deny by throwing". The dev-mode console.warn that previously surfaced un-migrated hooks is also removed, so consumers get no runtime signal if they missed updating a hook. Acceptable for a major-version break, but worth emphasizing in the release notes (e.g., grep for return false in onBefore* hooks before upgrading).

---

Not flagged

• headers prop removal from CommentThread: causes server-side auth errors rather than bypasses; acceptable breaking change.
• apiBaseURL/apiBasePath fallback to undefined: causes obvious runtime fetch errors, not silent bypasses.
• No new injection, SSRF, XSS, deserialization, or supply-chain risks introduced.

  

_{Sent by Cursor Automation: Find vulnerabilities}

[cursor]

[MEDIUM] Silent allow when onBeforeSubmission returns false

The hookResult === false → originalError guard was removed here. A consumer's hook that returns false to reject a submission will now silently allow it — only throwing works after this change. Unlike every other onBefore* backend hook, this call site is not wrapped in runHook, so the change is not covered by the documented "Backend hooks deny by throwing" migration. Either add an explicit guard here or add a call-out for onBeforeSubmission in breaking-changes.mdx.

[cursor]

[LOW-MEDIUM] Client-side render guard removed; auth.can replacement not wired

onBeforeModerationPageRendered guarded client-side rendering. It is removed here without an auth.can gate in the route definition. The SSR loader hook still protects server-side prefetching, but a consumer who upgrades without also configuring auth.can will expose this page to unauthenticated client-side navigation. Please add a migration example in breaking-changes.mdx and consider adding a ComposedRoute permission gate to the route definition.

[github-actions]

✅ Shadcn registry updated — registry JSON files were rebuilt and committed to this branch.