feat: integrate @zitadel/tanstack-auth (#2)

* feat: initial example-tanstack-start-auth app with @zitadel/tanstack-start-auth

* fix: align scaffold files for byte-level parity with other example repos

- Add missing .editorconfig
- Update devbox.lock to Node.js 22.22.0 (matches other repos)
- Fix .gitignore: remove .astro/.svelte-kit/dist artifacts, add .vinxi for Vinxi build
- Fix .prettierignore: remove .astro (not used by TanStack Start)
- Fix .env.example: correct framework name in comment
- Fix playwright.config.ts: align ZITADEL_CALLBACK_URL to match other repos
- Fix README.md: comprehensive documentation matching pattern of other examples
- Fix knip.config.js: add TanStack Start-specific entry points

* fix: add tailwind CSS entry file and align scaffold files with parity standards

* fix: route devcontainer commands through devbox to use project-local npm cache

* fix: update import to renamed @zitadel/tanstack-auth package

* fix: add depcheck script

* chore: bump prettier-plugin-tailwindcss to 0.6.14

* chore: add trailing newline to .nvmrc

* chore: add .devbox/ to .gitignore

* chore: switch to file: reference to generate package-lock.json

* feat: integrate @zitadel/tanstack-auth and refactor auth routes

* fix: migrate to @tanstack/react-start v1.168 vite-based API

The installed @tanstack/react-start v1.168 no longer exports
'@tanstack/react-start/config' or '@tanstack/react-start/api', and
Meta/Scripts/StartClient are gone. This commit aligns the example with
the new vite-plugin-based API the SDK playground uses:

- Replace vinxi + app.config.ts with vite.config.ts using
  tanstackStart({srcDirectory:'app'}) and @vitejs/plugin-react.
- Rewrite app/server.tsx to use createStartHandler + createServerEntry
  and inline the /api/auth/* and /api/userinfo handlers (replacing the
  removed createAPIFileRoute pattern).
- Rewrite app/client.tsx to hydrateStart() and app/router.tsx to use
  createRouter with routeTree.gen.
- Add app/session.ts with a createServerFn-based fetchSession helper.
- Switch /profile to a loader-based pattern using fetchSession.
- Drop validateSearch from /auth/login to avoid the search-param
  redirect loop (matches SDK playground).
- Move Session/JWT augmentation into app/types/auth.d.ts and add
  tsconfig paths to dedup @auth/core.
- Turn off plain no-unused-vars in eslint config (it false-positives
  on TS function-type parameter names).
- Clean up knip.config (drop stale entries, ignore routeTree.gen.ts).

* fix: ignore generated routeTree.gen.ts in prettier; gitignore dist

- Add app/routeTree.gen.ts to .prettierignore so format:check no
  longer fails on the auto-generated route tree.
- Add dist/ to .gitignore and remove the previously-committed build
  output. The build is reproducible from source.

* chore: align with @zitadel/tanstack-auth directory rename

The sibling SDK directory was renamed from tanstack-start-auth to
tanstack-auth; this commit updates the example's package metadata to
match:

- package.json — name now matches the SDK family
- @zitadel/tanstack-auth file: link points at ../tanstack-auth (was
  ../tanstack-start-auth)
- regenerated package-lock.json

* fix: redirect /api/auth/logout/callback to /logout/success and clear logout_state cookie

The handler in app/server.tsx was redirecting to /, but the test in
test/app.spec.ts expects /logout/success — which is the actual page
the user should land on after RP-initiated logout completes. It also
wasn't clearing the logout_state cookie. logout_state is set with
Path=/api/auth/logout/callback when the logout flow starts, so the
clearing Set-Cookie needs the same Path attribute or the browser
will retain the cookie.

* fix: mount React via hydrateRoot in client entry

The previous client.tsx only called hydrateStart() from
@tanstack/react-start/client, which initialises the TanStack router
but does not mount React. As a result, no useEffect ran and no event
handlers attached — every page was static HTML pretending to be a
React app. SSR worked and every test that only clicked plain anchors
continued to pass, hiding the bug.

Switches client.tsx to the canonical TanStack Start template:
hydrateRoot(document, <StrictMode><StartClient /></StrictMode>) inside
a startTransition. StartClient internally calls hydrateStart, so this
is a strict superset of the previous behaviour.

* fix(auth/login): submit POST form with CSRF token

The previous anchor pointed at GET /api/auth/signin/zitadel which
Auth.js rejects (the per-provider endpoint requires a POST with a
CSRF token); the user landed on /auth/error?error=Configuration on
click. Matches the pattern used by example-sveltekit-auth and
example-solidstart-auth: fetch /api/auth/csrf in useEffect, populate
a hidden input, submit a POST form to /api/auth/signin/zitadel.

* refactor(profile): redirect unauth users via SDK signInUrl

Replaces the hardcoded throw redirect({ to: '/auth/login' }) with
throw redirect({ href: signInUrl({ redirectTo: '/profile' }) }).
signInUrl is the canonical way to encapsulate the sign-in URL
across the SDK family.

* fix(logout/callback): validate state before clearing cookies

The previous handler cleared authjs.* cookies and the logout_state
cookie unconditionally on any GET /api/auth/logout/callback. The
other seven example apps validate the `state` query parameter
against the `logout_state` cookie before clearing — preventing an
attacker from triggering an unwanted logout via a crafted link.

Brings tanstack into parity with the other seven by:
1. Reading `state` from the URL and `logout_state` from the cookie jar
2. Only clearing cookies when both are present and match
3. Otherwise redirecting to /logout/error?reason=Invalid+or+missing+state+parameter.
4. Adding Clear-Site-Data: "cookies" + HttpOnly; SameSite=Lax on the
   logout_state expiry header to match the other seven verbatim

The existing app.spec.ts already exercises the success path
(provides state + matching cookie) and continues to pass.

* fix(server): implement POST /api/auth/logout properly

Previously stubbed with 405 ("back-channel logout not implemented"),
so clicking SignOutButton hit a dead endpoint and the user never
left the app. Replaces the stub with the same handler the other
seven examples use: load session, generate state, set
Path-scoped logout_state cookie, redirect to Zitadel's
end_session_endpoint. The /api/auth/logout/callback handler then
validates state on return (already in place from the prior commit).

Verified in-browser via the Sign out button: now redirects through
Zitadel and lands on /logout/success with cookies cleared.

* fix(logout): add conditional Secure flag to logout_state cookie

The logout_state cookie was being set without the Secure flag in any
environment. In production (HTTPS) the CSRF cookie should always be
Secure; in dev (HTTP) it must be unset so the browser doesn't drop
the cookie and silently break the state round-trip.

Apply the same conditional pattern used by example-remix-auth.

* chore(env): add AUTH_URL to .env.example

Documents the @auth/core v5 base URL env var. Aligns with the other
example apps so users get a consistent .env across all 8.

* feat(auth/login): render provider name dynamically from /api/auth/providers

Match the dynamic-provider pattern used by the other examples: fetch
/api/auth/providers + /api/auth/csrf in parallel, render the form
with provider.signinUrl and "Sign in with {provider.name}" instead
of hardcoded values.

* chore(playwright): add AUTH_URL to test env

Aligns with the other 7 examples; .env.example already had it.

* chore(deps): switch @zitadel/tanstack-auth@^1.0.0 from file: to published version

Switch package.json from file:../tanstack-auth to ^1.0.0 (now
published on npm). Also drop the signInUrl import from
~/auth.server in profile.tsx — tanstack-start's import-protection
plugin rejects `**/*.server.*` imports from route files (since
routes run in both environments), and signInUrl was only used to
build a static redirect URL. Use a route-relative redirect instead.

* chore: trigger CI

* fix(deps): regenerate lockfile with linux-x64 optional binaries

Adds cross-platform install entries for native deps (@rollup,
@oxc-resolver, @oxc-parser) so 'npm ci' on Linux runners finds the
linux-x64-gnu binaries. The previous lockfile was generated on
darwin-arm64 only, omitting the Linux entries; CI hit npm/cli#4828
and refused to install them.

Regenerated via:
  npm install --include=optional --os=linux --cpu=x64 --package-lock-only
  npm install --include=optional

* chore(devcontainer): decouple from devbox

devbox is a local-only nix-based package manager; coupling it to the
devcontainer image (which already provides Node via the base image)
creates an unnecessary dependency for contributors using the
devcontainer. Remove the devbox feature and use plain npm ci /
playwright install instead.

* chore(knip): drop stale unresolved:off rule + SDK ignore

The unresolved:off rule was added for an earlier tanstack-router issue that is no longer reproducible. The SDK ignore was always wrong since the SDK is imported by app code.

* chore: bump tailwind to ^4.3 + prettier plugin to ^0.8 + README v22

* chore: add X-Content-Type-Options + tsconfig moduleResolution PascalCase

* feat(api): add /api/userinfo handler in server.tsx

Adds a /api/userinfo GET handler to the server entry's path-match
chain. Mirrors the other 7 examples; sits next to the existing
/api/auth/* and /api/(un)?protected blocks. TanStack Start doesn't
have a file-based API route convention so this lives inline.

* docs: add JSDoc on auth helpers + callbacks (parity with astro/nuxt/sveltekit/qwik)

* chore: default callbackUrl to /profile + drop unused demo routes + bump typescript-eslint to ^8.60

* fix(deps): pin @auth/core to ^0.40.0 to match SDK (dedupe single copy)

* fix: use client signIn helper on home and bump @zitadel/tanstack-auth to 1.1.2

The home Login button hardcoded a GET to /api/auth/signin/zitadel, which
Auth.js v5 rejects with a Configuration error. Use the SDK client signIn
helper (CSRF+POST) and bump the SDK to the version that ships the fix.

Author: mridang

.devcontainer/devcontainer.json

@@ -0,0 +1,22 @@
+{
+  "name": "Zitadel Example TanStack Start Auth",
+  "image": "mcr.microsoft.com/devcontainers/javascript-node:22-bookworm",
+  "forwardPorts": [3000],
+  "portsAttributes": {
+    "3000": {
+      "label": "Application",
+      "onAutoForward": "notify"
+    }
+  },
+  "otherPortsAttributes": {
+    "onAutoForward": "silent"
+  },
+  "onCreateCommand": "cp -n .env.example .env",
+  "updateContentCommand": "npm ci",
+  "postCreateCommand": "npx playwright install --with-deps chromium",
+  "customizations": {
+    "vscode": {
+      "extensions": ["dbaeumer.vscode-eslint", "esbenp.prettier-vscode"]
+    }
+  }
+}

.editorconfig

@@ -0,0 +1,10 @@
+root = true
+
+[*]
+charset = utf-8
+indent_style = space
+indent_size = 2
+end_of_line = lf
+trim_trailing_whitespace = true
+insert_final_newline = true
+max_line_length = 120

.env.example

@@ -0,0 +1,65 @@
+# -----------------------------------------------------------------------------
+# App Configuration
+# -----------------------------------------------------------------------------
+# The environment in which the application is running. This should be set to
+# 'production' on your live server to enable security features like secure
+# cookies. For local development, 'development' is appropriate.
+NODE_ENV=development
+
+# The network port on which the TanStack Start dev server will listen for incoming
+# connections. Change this if port 3000 is already in use on your system.
+PORT=3000
+
+# -----------------------------------------------------------------------------
+# Session Configuration
+# -----------------------------------------------------------------------------
+# A long, random, and secret string used to sign the session cookie. This
+# prevents the cookie from being tampered with. It must be kept private.
+# Generate a secure key using:
+# node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
+SESSION_SECRET="your-very-secret-and-strong-session-key"
+
+# The total duration of the session in seconds. After this period of
+# inactivity, the user will be effectively logged out.
+# Default is 3600, which is 1 hour (60 * 60).
+SESSION_DURATION=3600
+
+# -----------------------------------------------------------------------------
+# ZITADEL OpenID Connect (OIDC) Configuration
+# -----------------------------------------------------------------------------
+# The full domain URL of your ZITADEL instance. You can find this in your
+# ZITADEL organization's settings.
+# Example: https://my-org-a1b2c3.zitadel.cloud
+ZITADEL_DOMAIN="https://your-zitadel-domain"
+
+# The unique Client ID for your application, obtained from the ZITADEL Console.
+# This identifier tells ZITADEL which application is making the request.
+ZITADEL_CLIENT_ID="your-zitadel-application-client-id"
+
+# While the Authorization Code Flow with PKCE for public clients
+# does not strictly require a client secret for OIDC specification compliance,
+# Auth.js will still require a value for its internal configuration.
+# Therefore, please provide a randomly generated string here.
+# You can generate a secure key using:
+# node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
+ZITADEL_CLIENT_SECRET="your-randomly-generated-client-secret"
+
+# The full URL where ZITADEL redirects the user after they have authenticated.
+# This MUST exactly match one of the "Redirect URIs" you have configured in
+# your ZITADEL application settings.
+ZITADEL_CALLBACK_URL="http://localhost:3000/api/auth/callback/zitadel"
+
+# The internal URL within your application where users are sent after a
+# successful login is processed at the callback URL.
+# Defaults to "/profile" if not specified.
+ZITADEL_POST_LOGIN_URL="/profile"
+
+# The full URL where ZITADEL redirects the user after they have logged out.
+# This MUST exactly match one of the "Post Logout Redirect URIs" configured
+# in your ZITADEL application settings.
+ZITADEL_POST_LOGOUT_URL="http://localhost:3000/api/auth/logout/callback"
+
+# The full public URL of your application.
+# Auth.js requires this to create secure callback and redirect links.
+# This is optional for local development but REQUIRED for production.
+AUTH_URL="http://localhost:3000"

.gitattributes

@@ -0,0 +1 @@
+* text=auto eol=lf

.github/dependabot.yml

@@ -0,0 +1,52 @@
+version: 2
+updates:
+  - package-ecosystem: 'npm'
+    directory: '/'
+    schedule:
+      interval: 'weekly'
+    commit-message:
+      prefix: 'chore(deps):'
+    open-pull-requests-limit: 10
+    groups:
+      npm-version-updates:
+        patterns:
+          - '*'
+        applies-to: 'version-updates'
+      npm-security-updates:
+        patterns:
+          - '*'
+        applies-to: 'security-updates'
+
+  - package-ecosystem: 'github-actions'
+    directory: '/'
+    schedule:
+      interval: 'weekly'
+    commit-message:
+      prefix: 'chore(deps):'
+    open-pull-requests-limit: 10
+    groups:
+      actions-version-updates:
+        patterns:
+          - '*'
+        applies-to: 'version-updates'
+      actions-security-updates:
+        patterns:
+          - '*'
+        applies-to: 'security-updates'
+
+  - package-ecosystem: 'docker'
+    directory: '/'
+    schedule:
+      interval: 'weekly'
+    commit-message:
+      prefix: 'chore(deps):'
+    open-pull-requests-limit: 10
+    groups:
+      docker-version-updates:
+        patterns:
+          - '*'
+        applies-to: 'version-updates'
+      docker-security-updates:
+        patterns:
+          - '*'
+        applies-to: 'security-updates'

.github/pull_request_template.md

@@ -0,0 +1,36 @@
+<!--- Provide a general summary of your changes in the Title above -->
+
+## Description
+
+<!--- Describe your changes -->
+
+## Related Issue
+
+<!--- This project only accepts pull requests related to open issues -->
+<!--- If suggesting a new feature or change, please discuss it in an issue first -->
+<!--- If fixing a bug, there should be an issue describing it with steps to reproduce -->
+<!--- Please link to the issue here: -->
+
+## Motivation and Context
+
+<!--- Why is this change required? What problem does it solve? -->
+
+## How Has This Been Tested?
+
+<!--- Please describe in detail how you tested your changes. -->
+<!--- Include details of your testing environment, and the tests you ran to -->
+<!--- see how your change affects other areas of the code, etc. -->
+
+## Documentation:
+
+<!--- Upon PR's approval, link the wiki page for your corresponding changes here. -->
+
+## Checklist:
+
+- [ ] I have updated the documentation accordingly.
+- [ ] I have assigned the correct milestone or created one if non-existent.
+- [ ] I have correctly labeled this pull request.
+- [ ] I have linked the corresponding issue in this description.
+- [ ] I have requested a review from at least 2 reviewers
+- [ ] I have checked the base branch of this pull request
+- [ ] I have checked my code for any possible security vulnerabilities

.github/workflows/commitlint.yml

@@ -0,0 +1,36 @@
+name: Commits
+
+on:
+  workflow_call:
+    inputs:
+      ref:
+        required: true
+        type: string
+
+permissions:
+  contents: read
+
+jobs:
+  lint-commits:
+    permissions:
+      contents: read
+      pull-requests: read
+    runs-on: ubuntu-latest
+    name: Validate Commits
+
+    steps:
+      - name: Harden runner
+        uses: step-security/harden-runner@0634a2670c59f64b4a01f0f96f84700a4088b9f0 # v2.12.0
+        with:
+          egress-policy: audit
+
+      - name: Checkout code
+        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+        with:
+          ref: ${{ inputs.ref }}
+          fetch-depth: 0
+
+      - name: Inspect Commits
+        uses: mridang/action-commit-lint@v1
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/depcheck.yml

@@ -0,0 +1,22 @@
+name: Dependency Review
+
+on:
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  dependency-review:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Harden Runner
+        uses: step-security/harden-runner@0634a2670c59f64b4a01f0f96f84700a4088b9f0 # v2.12.0
+        with:
+          egress-policy: audit
+
+      - name: Checkout code
+        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+
+      - name: Review Dependencies
+        uses: actions/dependency-review-action@da24556b548a50705dd671f47852072ea4c105d9 # v4.7.1

.github/workflows/linting.yml

@@ -0,0 +1,60 @@
+name: Linting
+
+on:
+  workflow_call:
+    inputs:
+      ref:
+        required: true
+        type: string
+      commit_changes:
+        required: false
+        type: boolean
+        default: false
+
+defaults:
+  run:
+    working-directory: ./
+
+permissions:
+  contents: read
+
+jobs:
+  lint-format:
+    permissions:
+      contents: write
+    runs-on: ubuntu-latest
+    name: Reformat Code
+
+    steps:
+      - name: Harden runner
+        uses: step-security/harden-runner@0634a2670c59f64b4a01f0f96f84700a4088b9f0 # v2.12.0
+        with:
+          egress-policy: audit
+
+      - name: Checkout code
+        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+        with:
+          ref: ${{ inputs.ref }}
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          cache: 'npm'
+          node-version-file: '.nvmrc'
+
+      - name: Install Dependencies
+        run: npm ci --no-progress
+
+      - name: Run Formatter
+        run: npm run format
+
+      - name: Commit Changes
+        if: ${{ inputs.commit_changes == true }}
+        uses: stefanzweifel/git-auto-commit-action@b863ae1933cb653a53c021fe36dbb774e1fb9403 # v5.2.0
+        with:
+          commit_message: 'style: Apply automated code formatting [skip ci]'
+          commit_options: '--no-verify'
+          repository: .
+          commit_user_name: github-actions[bot]
+          commit_user_email: github-actions[bot]@users.noreply.github.com
+          commit_author: github-actions[bot] <github-actions[bot]@users.noreply.github.com>

.github/workflows/pipeline.yml

@@ -0,0 +1,84 @@
+name: Pipeline
+
+on:
+  push:
+    branches:
+      - main
+      - master
+      - next
+      - next-major
+      - beta
+      - alpha
+      - '[0-9]*.x'
+      - develop
+      - 'release/**'
+      - 'hotfix/**'
+      - 'support/**'
+  pull_request:
+
+permissions:
+  contents: write
+  actions: read
+  checks: write
+  pull-requests: write
+
+jobs:
+  lint-commits:
+    name: Run Commitlint Checks
+    if: github.event_name == 'pull_request'
+    uses: ./.github/workflows/commitlint.yml
+    with:
+      ref: ${{ github.event.pull_request.head.sha }}
+    secrets: inherit
+
+  code-style:
+    name: Run Linter Formatter
+    uses: ./.github/workflows/linting.yml
+    with:
+      ref: ${{ github.event_name == 'pull_request' && github.event.pull_request.head.sha || github.ref }}
+      commit_changes: ${{ github.event_name == 'push' && github.ref == 'refs/heads/main' }}
+    secrets: inherit
+
+  type-check:
+    name: Run Type Checks
+    uses: ./.github/workflows/typecheck.yml
+    with:
+      ref: ${{ github.event_name == 'pull_request' && github.event.pull_request.head.sha || github.ref }}
+    secrets: inherit
+
+  run-tests:
+    name: Run Test Suite
+    uses: ./.github/workflows/test.yml
+    with:
+      ref: ${{ github.event_name == 'pull_request' && github.event.pull_request.head.sha || github.ref }}
+    secrets: inherit
+
+  check-deps:
+    name: Run Dependency Checks
+    uses: ./.github/workflows/unused.yml
+    with:
+      ref: ${{ github.event_name == 'pull_request' && github.event.pull_request.head.sha || github.ref }}
+    secrets: inherit
+
+  all-passed:
+    name: Check Build Status
+    runs-on: ubuntu-latest
+    if: always()
+    needs:
+      - lint-commits
+      - code-style
+      - type-check
+      - run-tests
+      - check-deps
+    steps:
+      - name: Harden runner
+        uses: step-security/harden-runner@0634a2670c59f64b4a01f0f96f84700a4088b9f0 # v2.12.0
+        with:
+          egress-policy: audit
+
+      - name: Verify all jobs passed
+        run: |
+          if [[ "${{ contains(needs.*.result, 'failure') || contains(needs.*.result, 'cancelled') }}" == "true" ]]; then
+            echo "One or more jobs failed or were cancelled."
+            exit 1
+          fi