Move the AuthProvider contract into @wasp.sh/auth-contract and collapse verification into authenticate()

[FranjoMindek]

Description

Stack: PR 4 of the auth provider series, on top of #4716. First of four PRs that turn the provider seam into the real adapter architecture: npm-installable auth adapters, a provider-first spec, and capability-gated codegen. Designed by a multi-agent panel (4 independent designs, judged, synthesized, adversarially verified); every decision below survived a verifier trying to refute it.

This PR makes the provider contract something a third-party npm package can implement, and finalizes the interface before any adapter package exists:

• @wasp.sh/auth-contract, a new lib in waspc/data/Generator/libs/auth-contract/. It rides the existing WaspLib machinery: packed as an npm tarball shipped with the CLI, copied into .wasp/out/libs/, installed into every generated app via file: deps of the SDK and server. npm hoists it into the app's node_modules, so generated code, hand-written adapters, and adapter packages all resolve the same copy. (The plan doc proposed @wasp.sh/lib-auth; rejected — argon2 native deps and a react peer have no place in a pure contract.)
• verifyRequest/verifyCredential collapse into authenticate(request: Request) — a standard web Request. Clerk's and Better Auth's SDKs consume one natively, which deletes the per-adapter toWebRequest shims; Wasp builds it in exactly one place for HTTP, and synthesizes one carrying only the Authorization header for websockets. The contract documents that adapters must authenticate from headers alone (a verifier caught that typing the parameter as Express's request would be a lie on the websocket path).
• VerifiedSession gains an optional claims payload — provider-verified profile data (email, name). Both verification passes flagged its absence as the one blocker: without claims, JIT provisioning can never populate a user entity with required columns, and the first request from a new subject is a permanent 401. Claims are recorded as AuthIdentity.providerData at provisioning; the next PRs feed them to userSignupFields.
• The contract also ships the (not-yet-consumed) factory shapes for adapter packages: WaspServerRuntime (with dbProvider — Better Auth's prisma adapter needs the dialect), ServerAdapter (one factory returns provider + route handler, so both share one configured instance), and the client-adapter types.

Example adapters are updated to the collapsed method; both now return claims.

One npm behavior worth knowing (cost a debugging session): with an existing node_modules and a committed lock, npm install trusts the lock's stale manifest snapshot for the .wasp/out/sdk/wasp path and silently skips a newly added file: dep. ./run bust-libs-cache is the repo's own cure; the committed example locks are regenerated here.

Type of change

• 🔧 Just code/docs improvement
• 🐞 Bug fix
• 🚀 New/improved feature
• 💥 Breaking change

Checklist

• I tested my change in a Wasp app to verify that it works as intended.

  Runtime-verified at the top of the stack: the wasp-auth example (signup 200, login → sessionId, /auth/me 200, wrong password 401, logout kills the session) and the better-auth example (claims recorded as providerData) both run the collapsed authenticate() path live. All 932 e2e tests green at this commit.

• 🧪 Tests and apps:

  • I added unit tests for my change.

    The contract package is types plus one predicate; the e2e goldens verify the generated re-export and dependency wiring verbatim, and tsc --noEmit runs in the package build.

  • (if you fixed a bug) I added a regression test for the bug I fixed.

  • (if you added/updated a feature) I added/updated e2e tests in examples/kitchen-sink/e2e-tests.

  • (if you added/updated a feature) I updated the starter templates in waspc/data/Cli/templates, as needed.

  • (if you added/updated a feature) I updated the example apps in examples/, as needed.

    • (if you updated examples/tutorials) I updated the tutorial in the docs (and vice versa).

• 📜 Documentation:

  • (if you added/updated a feature) I added/updated the documentation in web/docs/.

    Still experimental and unreleased; holding docs until the API stops moving, like the rest of the stack.

• 🆕 Changelog: (if change is more than just code/docs improvement)

  • I updated waspc/ChangeLog.md with a user-friendly description of the change.
  • (if you did a breaking change) I added a step to the current migration guide in web/docs/migration-guides/.
  • I bumped the version in waspc/waspc.cabal to reflect the changes I introduced.

  Holding changelog/version with the rest of the experimental stack.

[cloudflare-workers-and-pages]

Deploying wasp-docs-on-main with    Cloudflare Pages

Latest commit:	26128ca
Status:	✅  Deploy successful!
Preview URL:	https://35a0308d.wasp-docs-on-main.pages.dev
Branch Preview URL:	https://franjo-auth-contract-package.wasp-docs-on-main.pages.dev

View logs

[pkg-pr-new]

Open in StackBlitz

@wasp.sh/spec

npx https://pkg.pr.new/wasp-lang/wasp/@wasp.sh/spec@4718

@wasp.sh/wasp-cli

npx https://pkg.pr.new/wasp-lang/wasp/@wasp.sh/wasp-cli@4718

@wasp.sh/wasp-cli-darwin-arm64-unknown

npx https://pkg.pr.new/wasp-lang/wasp/@wasp.sh/wasp-cli-darwin-arm64-unknown@4718

@wasp.sh/wasp-cli-darwin-x64-unknown

npx https://pkg.pr.new/wasp-lang/wasp/@wasp.sh/wasp-cli-darwin-x64-unknown@4718

@wasp.sh/wasp-cli-linux-arm64-glibc

npx https://pkg.pr.new/wasp-lang/wasp/@wasp.sh/wasp-cli-linux-arm64-glibc@4718

@wasp.sh/wasp-cli-linux-x64-glibc

npx https://pkg.pr.new/wasp-lang/wasp/@wasp.sh/wasp-cli-linux-x64-glibc@4718

@wasp.sh/wasp-cli-linux-x64-musl

npx https://pkg.pr.new/wasp-lang/wasp/@wasp.sh/wasp-cli-linux-x64-musl@4718

commit: 26128ca

[FranjoMindek]

Superseded by the restacked series (stack of #4724–#4730). The @wasp.sh/auth-contract package is now where the contract is born (#4725); the adapter-package surface (ServerAdapterFactory, setupFn) lands together with its consumers in #4729.