first commit

docs/api-stack/api/api-plugin-auth/src/schemas/routes/session.md

@@ -0,0 +1,64 @@
+# schemas/routes/session
+
+## Purpose
+
+Response schema for `GET /auth/session`. Returns the current
+authenticated `Principal` and the matching Better-Auth session row, or
+`null` for both fields when the request is anonymous. The endpoint is
+the canonical "who am I" call for client SDKs and SSR hydration.
+
+## Features
+
+- `GetSessionResponseSchema` — `{ user: PrincipalSchema | null;
+  session: SessionSchema | null }` so the response carries the exact
+  same wire shape as `c.get("user")` plus the session row.
+- Anonymous callers see `{ user: null, session: null }` — a 200 with
+  null fields rather than a 401, so client SDKs can probe identity
+  without error handling.
+
+## Usage: Basic
+
+```ts
+import { GetSessionResponseSchema } from "@suaveplan/api-plugin-auth/schemas/routes";
+
+const parsed = GetSessionResponseSchema.parse({ user: null, session: null });
+```
+
+## Usage: Advanced
+
+Pair the schema with a route definition that lists both anonymous and
+authenticated cases in the OpenAPI document so consumers know the
+endpoint never 401s:
+
+```ts
+import { GET, successResponse } from "@suaveplan/api-openapi";
+import {
+    GetSessionResponseSchema,
+} from "@suaveplan/api-plugin-auth/schemas/routes";
+
+const sessionRoute = GET("/auth/session")
+    .tags("auth")
+    .summary("Resolve the current session, if any")
+    .response(successResponse(GetSessionResponseSchema))
+    .build();
+```
+
+## API Reference
+
+### `GetSessionResponseSchema`
+
+`{ user: PrincipalSchema | null; session: SessionSchema | null }`.
+Inferred type `GetSessionResponse`.
+
+## Implementation Notes
+
+- Returning `null` for the anonymous case keeps the endpoint cacheable
+  per cookie — a 401 response would force the CDN to either skip caching
+  or treat the page as private. Some host setups place this endpoint
+  behind a Service-Worker cache.
+- The schema mirrors the runtime shape installed by the session
+  middleware so consumers can use the same type to read either the HTTP
+  response body or `c.get("user")` / `c.get("session")`.
+- Better-Auth's session row carries plugin-extended fields (org
+  membership, impersonation) — those are tolerated via the loose schema
+  shape on `SessionSchema` so the API is forward-compatible.