@zitadel/cli 0.2.0 → 0.4.0

package/dist/skills/zitadel-sdk-tanstack-start/SKILL.md

@@ -0,0 +1,150 @@
+---
+name: zitadel-sdk-tanstack-start
+description: >-
+  Integrate Zitadel authentication into an existing or custom TanStack Start app
+  with @zitadel/sdk-tanstack-start. Use when the user wants login, logout,
+  session handling, or protected routes in a TanStack Start (React) app and is
+  wiring the SDK by hand rather than letting the CLI scaffold a fresh project —
+  registering the request middleware in `src/start.ts`, guarding a route with a
+  server function, or rendering the `ZitadelLogin` / `ZitadelSession` widgets.
+---
+
+# @zitadel/sdk-tanstack-start
+
+TanStack Start request middleware and helpers that add Zitadel (Nextgen) auth to
+a TanStack Start app. The middleware proxies auth traffic same-origin under
+`/__nextgen`, verifies the session JWT via JWKS on the server, places the result
+on the request context as `nextgenAuth`, and redirects unauthenticated requests
+on protected routes. Unlike the other meta-framework SDKs it also ships the
+widgets (a `/react` entry), so no other Zitadel package is needed.
+
+## When to use
+
+The `zitadel` CLI (`zitadel setup --framework tanstack-start`) scaffolds
+`src/start.ts`, login/register/profile routes, and `.env.local` into a fresh or
+detected TanStack Start project — prefer it for greenfield work. Reach for
+**this skill** when you are adding auth to an **existing or custom** TanStack
+Start app by hand, or adjusting a scaffolded wiring.
+
+## Install
+
+```bash
+pnpm add @zitadel/sdk-tanstack-start@latest
+```
+
+Peer deps: `@tanstack/react-start >=1.168.10`, `react >=18`, `react-dom >=18`.
+
+## Integrate
+
+**1. Request middleware.** Register it in `src/start.ts`, the file TanStack Start
+auto-loads, via `requestMiddleware`. Having this file turns off the automatic
+CSRF protection for server functions, so list `createCsrfMiddleware` before auth:
+
+```ts
+import { createCsrfMiddleware, createMiddleware, createStart } from '@tanstack/react-start';
+import { createNextgenRequestMiddleware } from '@zitadel/sdk-tanstack-start/server';
+
+const csrfMiddleware = createCsrfMiddleware({
+  filter: (ctx) => ctx.handlerType === 'serverFn',
+});
+
+const authMiddleware = createMiddleware({ type: 'request' }).server(
+  createNextgenRequestMiddleware({
+    url: process.env.ZITADEL_URL,
+    projectSecret: process.env.ZITADEL_PROJECT_SECRET,
+    protectedRoutes: ['/admin', '/dashboard*'], // trailing * matches sub-paths
+    loginPath: '/login',
+  }),
+);
+
+export const startInstance = createStart(() => ({
+  requestMiddleware: [csrfMiddleware, authMiddleware],
+}));
+```
+
+Sessions count only in the app's own project: `projectId`, else
+`ZITADEL_PROJECT_ID`, else `VITE_ZITADEL_PROJECT_ID`. With none set, nobody is
+signed in.
+
+The same proxy/verify/protect decision is exported as the framework-agnostic
+`handleNextgenRequest(request, options)` for a custom server entry.
+
+**2. Read auth and guard routes through a server function.** Server functions
+receive the middleware's context; a route's `beforeLoad` does not, and on
+client-side navigation it runs in the browser. Call a server function from
+`beforeLoad`:
+
+```ts
+import { createServerFn } from '@tanstack/react-start';
+import { createFileRoute, redirect } from '@tanstack/react-router';
+import { getAuth } from '@zitadel/sdk-tanstack-start/server';
+
+// A server function's return value is serialised to the browser, so return
+// only client-safe fields: `getAuth` also carries the raw session token.
+const fetchAuth = createServerFn().handler(({ context }) => {
+  const auth = getAuth(context);
+  return auth.isAuthenticated
+    ? { isAuthenticated: true as const, userId: auth.session.userId }
+    : { isAuthenticated: false as const };
+});
+
+export const Route = createFileRoute('/admin')({
+  beforeLoad: async () => {
+    const auth = await fetchAuth();
+    if (!auth.isAuthenticated) throw redirect({ to: '/login' });
+    return { userId: auth.userId };
+  },
+});
+```
+
+**3. Render the widgets** from the `/react` entry, with `configureZitadel` from
+`/client`:
+
+```tsx
+import { ZitadelLogin } from '@zitadel/sdk-tanstack-start/react';
+import { configureZitadel } from '@zitadel/sdk-tanstack-start/client';
+
+const project = configureZitadel({
+  projectId: import.meta.env.VITE_ZITADEL_PROJECT_ID,
+  proxyPath: '/__nextgen',
+});
+
+export function LoginPage() {
+  return <ZitadelLogin project={project} purpose="login" postSignInUrl="/admin" />;
+}
+```
+
+`<ZitadelSession project={project} postSignOutUrl="/login" />` renders the
+signed-in card with sign-out, and `<ZitadelLogout>` a sign-out control on its own.
+
+## Widget props and events
+
+This SDK is not server-only: its `/react` entry wraps the widgets from `@zitadel/sdk-react`, so no other package is needed. Read the `@zitadel/sdk-react` skill for the widget props and events.
+
+## Read these, don't guess
+
+The package README at `node_modules/@zitadel/sdk-tanstack-start/README.md` and
+the bundled `.d.ts` types (`dist/server.d.ts`, `dist/client.d.ts`,
+`dist/react.d.ts`) are authoritative and versioned with the installed package —
+read them before wiring anything, and let them override anything remembered.
+This skill teaches the pattern, not a full catalog of options, widget props, or
+the shared JWT-verification pipeline (that lives in `@zitadel/sdk-core`). Check
+exact option names, props, and defaults against the installed version rather
+than assuming.
+
+## Gotchas
+
+- **Import widgets from `/react`, not `/client`.** `/client` only configures the
+  SDK and exports no components.
+- **The widgets render nothing on the server and during hydration.** They mount
+  right after, with every prop in place; do not expect them in the SSR markup.
+- **Keep `createCsrfMiddleware` ahead of auth.** `src/start.ts` opts the app out
+  of TanStack Start's automatic CSRF protection.
+- **`beforeLoad` has no `nextgenAuth`.** Read it with `getAuth(context)` inside a
+  server function, not from the route context.
+- **Never return `getAuth(context)` itself from a server function.** Its session
+  carries the raw token, and a server function's result reaches browser scripts.
+  Return only `userId` and other client-safe fields.
+- **`protectedRoutes` only guards full document requests.** Client-side `<Link>`
+  navigation needs the `beforeLoad` server-function guard; without it only the
+  `ZitadelSession` card sends a signed-out visitor away.

package/dist/skills/zitadel-sdk-vue/SKILL.md

@@ -0,0 +1,147 @@
+---
+name: zitadel-sdk-vue
+description: >-
+  Integrate Zitadel authentication into a Vue 3 single-page app with
+  @zitadel/sdk-vue. Use when the user wants to add Zitadel login, logout, or a
+  signed-in session card to an existing or custom Vue/Vite SPA — wiring the
+  configureZitadel handle, the ZitadelLogin / ZitadelLogout / ZitadelSession
+  components, the same-origin backend proxy, and post-sign-in / post-sign-out
+  redirects.
+---
+
+# @zitadel/sdk-vue
+
+`@zitadel/sdk-vue` provides Vue 3 components wrapping the Zitadel auth UI web
+components (`ZitadelLogin`, `ZitadelLogout`, `ZitadelSession`) for client-side
+SPAs (Vite, etc.). You configure one project handle with `configureZitadel(...)`
+and hand it to the components; they talk to the backend over a same-origin
+proxy path.
+
+## When to use
+
+Reach for this skill when integrating Zitadel into an **existing or custom** Vue
+app, where you are adding the components by hand.
+
+For a **fresh** scaffold, prefer the CLI instead — it wires the proxy, env, and
+components for you:
+
+```sh
+npx @zitadel/cli@latest setup --framework vue --non-interactive --json
+```
+
+Use this skill when `setup` is not appropriate (an app with its own structure,
+a partial integration, or customizing what the CLI produced).
+
+## Install
+
+```sh
+npm install @zitadel/sdk-vue@latest
+```
+
+Peer dependencies: `vue >=3.2`. Requires TypeScript ≥ 5.0 (the published types use `export type *`).
+
+## Integrate
+
+Configure once with `configureZitadel(...)`, then pass the returned handle as
+`:project` to each component. The components register the underlying web
+components on import — no Vue plugin or `app.use(...)` is needed.
+
+```vue
+<script setup lang="ts">
+import { ZitadelLogin, configureZitadel } from '@zitadel/sdk-vue';
+
+const project = configureZitadel({
+  projectId: import.meta.env.VITE_ZITADEL_PROJECT_ID,
+  proxyPath: '/__nextgen',
+});
+</script>
+
+<template>
+  <ZitadelLogin :project="project" purpose="login" postSignInUrl="/" />
+</template>
+```
+
+Logout and the signed-in session card take the same `:project` handle:
+
+```vue
+<ZitadelLogout :project="project" postSignOutUrl="/login" />
+<ZitadelSession :project="project" />
+```
+
+- `purpose` on `ZitadelLogin` is `"login"` by default (also accepts the other
+  flow purposes, e.g. registration).
+- `postSignInUrl` / `postSignOutUrl` are where the browser lands after the flow.
+- The widgets call `${proxyPath}/…` **same-origin** (default `/__nextgen`), so
+  your host must proxy that path to the Zitadel backend. For local development
+  you can instead point `proxyPath` straight at the backend cross-origin, e.g.
+  `proxyPath: 'http://localhost:8080'` (the `zitadel start` local runtime port).
+
+## Widget props and events
+
+`ZitadelLogin`, `ZitadelLogout` and `ZitadelSession` take the props below, spelled the same in every SPA SDK. An unset prop keeps the widget's own default.
+
+| Prop | Type | Default | Widgets | Description |
+| --- | --- | --- | --- | --- |
+| `project` | `ZitadelProject` | unset | Login, Logout, Session | The handle from `configureZitadel(...)`. Wins over `projectId` and `proxyPath`. |
+| `projectId` | `string` | unset | Login, Logout, Session | Project id, read when no `project` handle is passed. |
+| `proxyPath` | `string` | `"/__nextgen"` | Login, Logout, Session | Same-origin path the widget calls. |
+| `purpose` | `CreateFlowBodyPurpose` | `"login"` | Login | Flow purpose. |
+| `flowName` | `string` | unset | Login | Runs the flow definition with this `name`; unset runs the project's default flow for the purpose. |
+| `postSignInUrl` | `string` | unset | Login | Where to navigate after a completed sign-in. When the page's `next` query parameter names a path on the same origin, as the server SDKs' middleware sets it for a signed-out visit to a protected route, the widget returns there instead. |
+| `forcePostSignInUrl` | `boolean` | `false` | Login | Navigates to `postSignInUrl` even when the page's `next` query parameter names a path, for a page that uses `next` for something of its own. |
+| `postSignOutUrl` | `string` | unset | Logout, Session | Where to navigate after sign-out. |
+| `resumeFlowId` | `string` or `null` | unset | Login | An existing flow's id to resume instead of starting a new flow; unset, `null` or `""` falls back to the `flow` query parameter, and an id that no longer resolves starts a new flow. |
+| `variant` | `"widget"` or `"page"` | `"widget"` | Login, Session | `widget` is content-sized and paints no page chrome; `page` claims the viewport, paints the surface background and loads the brand font, and on Login focuses the first field. |
+| `theme` | `"light"`, `"dark"` or `"auto"` | unset | Login, Logout, Session | Colour mode. Unset follows the tenant's branding theme on Login, then the variant default (`dark` for `page`, `auto` for `widget`); Logout defaults to `auto`. `auto` follows `prefers-color-scheme`. |
+| `suppressHeader` | `boolean` | `false` | Login, Session | Visually hides the widget's own heading block while keeping it in the accessibility tree, for pages that already carry the heading. |
+| `suppressPasswordToggle` | `boolean` | `false` | Login | Hides the show/hide button on password fields. |
+| `heading` | `string` | `"Signed in as"` | Session | Heading text override. |
+| `logoutLabel` | `string` | `"Sign out"` | Session | Logout action label override. |
+| `locales` | `Record<string, Partial<Record<string, string>>>` | unset | Login | Copy overrides merged over the builtin dictionaries, keyed by primary language subtag, for example `{ en: { "identifier.title": "Welcome back" } }`. |
+| `lang` | `string` | browser language | Login | BCP-47 language override. |
+
+Each widget event reaches the callback in the last column, which receives the event's `detail` payload.
+
+| Widget event | Fires when | Detail | Widgets | Callback |
+| --- | --- | --- | --- | --- |
+| `zitadel-flow-step` | Login shows a step, the first one included. | `{ step }` | Login | `@flowStep` |
+| `zitadel-flow-input` | The visitor edits a field. | `{ name, value }` | Login | `@flowInput` |
+| `zitadel-flow-complete` | The flow reaches a terminal step. | `{ behavior, redirect_uri?, handoff_token?, handoff_token_expires_at? }` | Login | `@flowComplete` |
+| `zitadel-flow-redirect` | The widget hands the browser to an identity provider; nobody is signed in yet. | `{ redirect_url, step }` | Login | `@flowRedirect` |
+| `zitadel-flow-error` | The flow reports an error. | `{ message }` | Login | `@flowError` |
+| `zitadel-signout` | The user signs out. | `{ display, identifier }` | Logout, Session | `@signout` |
+
+```vue
+<ZitadelLogin :project="project" theme="light" @flowComplete="track" />
+```
+
+The `zitadel-flow-complete`, `zitadel-flow-redirect` and `zitadel-signout` details carry a `waitUntil(promise)`; call it from your handler to make the widget wait for your async work before it navigates.
+
+## Read these, don't guess
+
+The SDK and this skill version independently — discover the real surface before
+writing code, and treat it as authoritative over anything here:
+
+- `node_modules/@zitadel/sdk-vue/README.md` — the installed README.
+- `node_modules/@zitadel/sdk-vue/dist/index.d.ts` — the TypeScript types: the
+  exact exports and every component prop. The public exports are
+  `ZitadelLogin`, `ZitadelLogout`, `ZitadelSession`, `configureZitadel`,
+  `getApi`, `getZitadelConfig`, the `ZitadelConfig` / `ZitadelProject` types,
+  and `businessLocales`.
+
+Check the installed version's props rather than assuming; emitted events and
+optional props (`locales`, `lang`, `theme`, `variant`, `suppressHeader`, …)
+evolve.
+
+## Gotchas
+
+- **Server rendering.** If your app renders on the server, mount the widget on the client only, after hydration (the `ZitadelLogin` wrapper sets `projectId` and `proxyPath` as element properties, so adding them to the wrapper does not put them in server markup), or use a raw `<zitadel-login>` element with `project-id` and `proxy-path` as attributes, because a widget that starts before its configuration arrives shows an error instead of the flow.
+- **Production SPA deployment is not yet supported.** The same-origin proxy path
+  must come from your hosting platform, and the CLI cannot scaffold those host
+  configs yet (see ADR 036 and zitadel/nextgen#560). The CLI dev proxy covers
+  local development only.
+- **Same-origin by default.** Unless you override `proxyPath`, the widgets
+  expect `/__nextgen` to be proxied to the backend on the same origin — a bare
+  SPA with no proxy will fail its auth calls.
+- **TypeScript ≥ 5.0 is required**; older compilers choke on the `export type *`
+  re-exports in the published type definitions.