@pablozaiden/webapp 0.0.1 → 0.2.0

package/README.md

@@ -1,10 +1,10 @@
 # @pablozaiden/webapp
 
-Opinionated Bun + React framework for single-server TypeScript webapps: one Bun process serves the React UI, API routes, passkey auth, API keys, device auth, realtime websocket state, settings, binary builds and Docker images.
+Opinionated Bun + React framework for single-server TypeScript webapps: one Bun process serves the React UI, API routes, multi-user passkey auth, user-owned API keys, device auth, realtime websocket state, scoped settings, binary builds and Docker images.
 
 ## Quick start
 
-Use one of the examples while the package is private:
+Use one of the examples during framework development:
 
 ```bash
 bun install
@@ -19,7 +19,7 @@ Both examples run with Bun native hot reload through `bun --hot`, with no standa
 | Export | Use |
 | --- | --- |
 | `@pablozaiden/webapp/server` | `createWebAppServer`, route helpers, responses, SQLite store |
-| `@pablozaiden/webapp/web` | `WebAppRoot`, sidebar types, UI controls, realtime hooks |
+| `@pablozaiden/webapp/web` | `WebAppRoot`, `renderWebApp`, sidebar types, UI controls, realtime hooks |
 | `@pablozaiden/webapp/contracts` | Shared auth/config/device/API-key types |
 | `@pablozaiden/webapp/build` | Bun single-binary compile helper |
 

package/docs/auth-validation.md

@@ -1,17 +1,36 @@
 # Auth validation checklist
 
-Run this checklist before migrating an app or cutting a checkpoint.
+Run this checklist before releasing a framework app or cutting a checkpoint.
 
 ## Passkeys
 
 1. Start the app with passkeys enabled and an empty data dir.
-2. Confirm the bootstrap screen appears before the shell.
-3. Register a passkey with the browser/platform authenticator.
-4. Confirm the app shell loads and Settings shows passkey configured.
+2. Confirm the owner bootstrap screen appears before the shell.
+3. Register the owner username and passkey with the browser/platform authenticator.
+4. Confirm the app shell loads and Settings shows the owner account and passkey configured.
 5. Click Logout and confirm reload/login requires passkey authentication.
 6. Authenticate with the registered passkey and confirm the shell loads again.
 7. Delete passkey from Settings, confirm the dialog supports Escape, X and Cancel.
-8. Confirm deleting returns to bootstrap on reload.
+8. Confirm deleting the owner passkey shows owner re-setup on reload.
+
+## Users and roles
+
+1. As owner/admin, create a non-admin user and copy the one-time setup link.
+2. Open `/setup?token=...` in a fresh context and register that user's passkey.
+3. Confirm the new user can sign in and does not see admin-only settings.
+4. Confirm app data is empty for a newly-created non-owner user unless explicitly provisioned.
+5. Promote the user to admin and confirm user management appears.
+6. Demote the user and confirm admin settings disappear.
+7. Reset the user and confirm old sessions/API keys/device sessions no longer work.
+8. Confirm owner cannot be reset, deleted, or demoted.
+
+## App data isolation
+
+1. Create data as owner and as a non-owner user.
+2. Confirm list endpoints return only the current user's data.
+3. Confirm item endpoints return 404 for another user's IDs.
+4. Confirm user-owned realtime events reach only sockets authenticated as the owning user.
+5. Confirm public endpoints intentionally attach data to the correct owner/user and never broadcast user-owned IDs globally.
 
 ## API keys
 

package/docs/auth.md

@@ -2,19 +2,43 @@
 
 The framework provides three auth modes designed to coexist.
 
-## Passkeys
+## Users and passkeys
 
-Passkeys follow a single-passkey bootstrap model:
+Passkeys are multi-user. The first run creates the immutable owner user and that user's passkey.
 
-1. If no passkey exists, registration is allowed.
-2. Once a passkey exists, protected routes require an authenticated passkey browser session, API key, or device bearer token.
-3. Additional public registration is rejected after bootstrap.
+1. If no users exist, the UI asks for the owner username and passkey.
+2. The owner cannot be deleted or demoted.
+3. Owners and admins create users from Settings, which returns a one-time 24h setup link.
+4. Users complete setup from `/setup?token=...`; usernames are lowercase, immutable and unique.
+5. Admin resets clear the user's passkey, API keys and device sessions, then issue a new one-time setup link.
+6. If the owner passkey is deleted, the owner setup screen is shown again.
 
-Settings owns passkey logout/delete UX.
+Route handlers get `ctx.auth.user` plus helpers:
+
+```ts
+const user = ctx.requireUser();
+const admin = ctx.requireAdmin();
+ctx.assertUser(userId);
+```
+
+For app-owned data, prefer the ownership helpers so every route has the same self-only behavior:
+
+```ts
+GET: (_req, ctx) => jsonResponse(ctx.filterOwned(items));
+
+PATCH: (_req, ctx) => {
+  const item = ctx.requireOwned(items.find((candidate) => candidate.id === ctx.params.id));
+  return jsonResponse(item);
+}
+```
+
+`ctx.requireOwned()` returns 404 for missing resources and for resources owned by another user, avoiding cross-user existence leaks. For user-owned realtime updates, publish through `ctx.userRealtime` instead of the global `ctx.realtime`.
+
+`{PREFIX}_DISABLE_PASSKEY=true` is an emergency bypass that logs in as the existing owner only. It does not create the owner.
 
 ## API keys
 
-API keys are bearer tokens for scripts and agents. They are stored hashed in SQLite and shown only once at creation. Route `scopes` are enforced for API-key requests; `*` grants all scopes.
+API keys are user-owned bearer tokens for scripts and agents. They are stored hashed in SQLite and shown only once at creation. Route `scopes` are enforced for API-key requests; `*` grants all scopes.
 
 Same-origin checks are skipped for API-key and device bearer requests unless a route sets `sameOrigin: "always"`, because non-browser clients usually do not send `Origin`.
 
@@ -26,9 +50,9 @@ Device auth is included in V1:
 2. Server returns `device_code`, human `user_code`, `verification_uri`, and polling interval.
 3. Browser user opens `/device?user_code=...` and approves from the same-origin UI.
 4. Client exchanges the approved code at `/api/auth/token`.
-5. Access tokens are JWT bearer tokens; refresh tokens rotate on every refresh.
+5. Access tokens are JWT bearer tokens whose `sub` is the approving user id; refresh tokens rotate on every refresh.
 
-Device codes are one-use. Reusing a consumed device code or stale refresh token returns `invalid_grant`.
+Device codes are one-use. Device sessions are self-only in Settings. Reusing a consumed device code or stale refresh token returns `invalid_grant`.
 
 ## Same-origin policy
 

package/docs/getting-started.md

@@ -4,11 +4,22 @@ Apps are one Bun application: backend routes, websocket, React UI and static ass
 
 ```ts
 import webIndex from "./index.html";
-import { createWebAppServer, defineRoutes, jsonResponse } from "@pablozaiden/webapp/server";
+import { createWebAppServer, defineRoutes, jsonResponse, parseJson } from "@pablozaiden/webapp/server";
+
+const items: Array<{ id: string; userId: string; title: string }> = [];
 
 const routes = defineRoutes({
   "/api/items": {
-    GET: () => jsonResponse([{ id: "one", title: "One" }]),
+    auth: "user",
+    GET: (_req, ctx) => jsonResponse(ctx.filterOwned(items)),
+    async POST(req, ctx) {
+      const user = ctx.requireUser();
+      const body = await parseJson<{ title: string }>(req);
+      const item = { id: crypto.randomUUID(), userId: user.id, title: body.title };
+      items.push(item);
+      ctx.userRealtime.publishEntityChanged("items", item.id);
+      return jsonResponse(item);
+    },
   },
   "/api/webhooks/:source/:token": {
     auth: "public",
@@ -29,13 +40,28 @@ const app = createWebAppServer({
 await app.runFromCli();
 ```
 
-Frontend entrypoints should import the framework CSS explicitly so Bun hot reload observes style changes:
+Frontend entrypoints should use `renderWebApp` so Bun/browser hot reload reuses the existing React root instead of calling `createRoot()` twice. Import the framework CSS explicitly so Bun hot reload observes style changes:
 
-```ts
-import { WebAppRoot } from "@pablozaiden/webapp/web";
+```tsx
+import { WebAppRoot, renderWebApp } from "@pablozaiden/webapp/web";
 import "@pablozaiden/webapp/web/styles.css";
+
+function Home() {
+  return <main className="wapp-main-content">Hello</main>;
+}
+
+renderWebApp(
+  <WebAppRoot
+    appName="My App"
+    homeRoute={{ view: "home" }}
+    sidebar={{ getNodes: () => [] }}
+    routes={{ home: <Home /> }}
+  />,
+);
 ```
 
+`renderWebApp` renders into `#root` by default and reuses the existing React root across hot reloads. Pass a custom element id or `Element` only when the app uses a different mount point.
+
 Recommended dev script:
 
 ```json
@@ -50,11 +76,11 @@ The app configures an uppercase `envPrefix`; the framework reads only variables
 
 | Variable | Default | Description |
 | --- | --- | --- |
-| `{PREFIX}_HOST` | `127.0.0.1` | Bind host |
+| `{PREFIX}_HOST` | `localhost` | Bind host |
 | `{PREFIX}_PORT` | `3000` | Bind port |
 | `{PREFIX}_DATA_DIR` | `./data` | SQLite persistence directory |
 | `{PREFIX}_LOG_LEVEL` | `info` | `trace`, `debug`, `info`, `warn`, `error`; locks settings log-level control when set |
-| `{PREFIX}_DISABLE_PASSKEY` | unset | Development escape hatch |
+| `{PREFIX}_DISABLE_PASSKEY` | unset | Emergency bypass that logs in as the existing owner; it does not create users |
 | `{PREFIX}_DISABLE_SAME_ORIGIN_CHECK` | unset | Development/testing escape hatch |
 | `{PREFIX}_PUBLIC_BASE_URL` | request origin | External URL for device auth links |
 | `{PREFIX}_AUTH_ISSUER` | `urn:{prefix}:webapp` | JWT issuer override |

package/docs/github-actions.md

@@ -1,6 +1,6 @@
 # GitHub Actions for framework apps
 
-Use these templates for applications built with `@pablozaiden/webapp`. They follow the same deployment pattern as the reference apps:
+Use these templates for applications built with `@pablozaiden/webapp`. They follow the framework deployment pattern:
 
 1. Pull requests install, build, test and smoke-test the Bun dev server.
 2. Merges to `main` publish a `main` Docker image to GHCR.
@@ -31,6 +31,8 @@ The templates assume these package scripts:
 
 If the app uses TypeScript typechecking separately, add a `tsc` script and call it from the PR workflow before tests.
 
+The smoke templates only hit health/static/public endpoints. `MY_APP_DISABLE_PASSKEY=true` authenticates as the existing owner when one exists; it does not create an owner in an empty data directory. If a smoke test needs protected app APIs, seed a test owner in `MY_APP_DATA_DIR` first or add a deliberate public smoke endpoint.
+
 ## Dockerfile
 
 Place this at `Dockerfile` in the app repository root. It builds the app inside Docker, copies only the standalone Bun binary into a slim runtime image, runs as a non-root user, and exposes `/api/health` as the container healthcheck.
@@ -255,11 +257,11 @@ jobs:
         id: image
         run: echo "name=ghcr.io/${GITHUB_REPOSITORY,,}" >> "$GITHUB_OUTPUT"
 
-      - name: Build and push Docker image
+      - name: Build Docker image
         uses: docker/build-push-action@d08e5c354a6adb9ed34480a06d141179aa583294 # v7
         with:
           context: .
-          push: true
+          push: false
           load: true
           tags: ${{ steps.image.outputs.name }}:main
           cache-from: type=gha
@@ -286,6 +288,9 @@ jobs:
 
           test "$(docker inspect --format='{{.State.Health.Status}}' my-app-main-smoke)" = "healthy"
           curl -fsS http://127.0.0.1:8080/api/health >/dev/null
+
+      - name: Push Docker image
+        run: docker push ${{ steps.image.outputs.name }}:main
 ```
 
 ## Binary release workflow

package/docs/realtime.md

@@ -8,8 +8,9 @@ type AppEvent = ResourceRealtimeEvent;
 const routes = defineRoutes<AppEvent>({
   "/api/todos": {
     async POST(req, ctx) {
-      const todo = await createTodo(req);
-      ctx.realtime.publishEntityChanged("todos", todo.id);
+      const user = ctx.requireUser();
+      const todo = await createTodo(user.id, req);
+      ctx.userRealtime.publishEntityChanged("todos", todo.id);
       return jsonResponse(todo);
     },
   },
@@ -25,6 +26,8 @@ Standard events have `type`, `resource`, `action`, optional `id`, optional `scop
 | `publishDeleted("todos", id)` | `{ type: "todos.deleted", resource: "todos", action: "deleted", id }` |
 | `publishSettingsChanged()` | `{ type: "settings.changed", resource: "settings", action: "changed" }` |
 
+For records that belong to the signed-in user, use `ctx.userRealtime.publishChanged`, `publishEntityChanged`, `publishDeleted`, or `publishSettingsChanged`. These helpers target only websocket connections authenticated as that user, so other users do not receive entity ids or timing signals.
+
 Frontend code can refresh declaratively:
 
 ```tsx
@@ -58,4 +61,6 @@ useRealtimeRefresh({
 ctx.realtime.publishEntityChanged("todos", todo.id, { scope: workspaceId });
 ```
 
+Use scoped/global `ctx.realtime` for non-user scopes only when the server validates access to that scope. For per-user app data, prefer `ctx.userRealtime` instead of trusting a client-provided websocket filter.
+
 `ctx.realtime.publish(customEvent)` and `useRealtime({ onEvent })` still exist as low-level escape hatches. The hook reconnects with exponential backoff and uses the same origin as the page.

package/docs/server.md

@@ -5,17 +5,31 @@ Use `createWebAppServer` with `defineRoutes`. Route patterns support exact path
 ```ts
 const routes = defineRoutes<AppEvent>({
   "/api/projects": {
-    GET: () => jsonResponse(projects),
+    auth: "user",
+    GET: (_req, ctx) => {
+      return jsonResponse(ctx.filterOwned(projects));
+    },
     async POST(req, ctx) {
+      const user = ctx.requireUser();
       const body = await parseJson<{ name: string }>(req);
-      const project = createProject(body.name);
-      ctx.realtime.publishEntityChanged("projects", project.id);
+      const project = createProject(user.id, body.name);
+      ctx.userRealtime.publishEntityChanged("projects", project.id);
       return jsonResponse(project);
     },
   },
   "/api/projects/:id": {
+    auth: "user",
     scopes: ["projects:write"],
-    PATCH: updateProject,
+    async PATCH(req, ctx) {
+      const project = ctx.requireOwned(await findProject(ctx.params.id));
+      Object.assign(project, await parseJson<Partial<Project>>(req));
+      ctx.userRealtime.publishEntityChanged("projects", project.id);
+      return jsonResponse(project);
+    },
+  },
+  "/api/admin/summary": {
+    auth: "admin",
+    GET: () => jsonResponse(adminSummary()),
   },
 });
 ```
@@ -27,9 +41,26 @@ Route defaults are intentionally secure:
 | `auth` | `required` | Requires passkey session, API key or device bearer token once auth is configured |
 | `sameOrigin` | `mutations` | Requires `Origin`/`Referer` for cookie/browser mutations |
 | `scopes` | `[]` | Checked for API keys and device tokens; `*` grants all |
+| `userParam` | unset | Optional route param name that must match the current user id |
 
 Set `auth: "public", sameOrigin: "never"` only for deliberate unauthenticated endpoints such as health probes, webhooks or callback receivers.
 
+Prefer explicit `auth: "user"`, `auth: "admin"` or `auth: "owner"` on app routes. They enforce the role before the handler runs, including API-key and device bearer requests.
+
+Route context is user-aware:
+
+| Helper | Meaning |
+| --- | --- |
+| `ctx.requireUser()` | Returns the current user or throws 401 |
+| `ctx.requireAdmin()` | Returns owner/admin users or throws 403 |
+| `ctx.requireOwner()` | Returns the owner or throws 403 |
+| `ctx.assertUser(userId)` | Throws unless the current user id matches |
+| `ctx.filterOwned(records)` | Returns only records whose `userId` is the current user id |
+| `ctx.requireOwned(record)` | Returns a user-owned record or throws 404 for missing/other-user records |
+| `ctx.userRealtime.*` | Publishes realtime events only to sockets authenticated as the current user |
+
+Use `ctx.filterOwned(records, getUserId)` and `ctx.requireOwned(record, getUserId)` when app records use a different ownership field. Return 404 for other-user resources so route responses do not reveal whether another user's id exists.
+
 Built-in endpoints include:
 
 | Endpoint | Purpose |
@@ -37,8 +68,12 @@ Built-in endpoints include:
 | `GET /api/health` | Health/version |
 | `GET /api/config` | Safe framework config for UI |
 | `/api/passkey-auth/*` | Passkey bootstrap/login/logout/delete |
+| `/api/user-setup*` | One-time invite/reset setup links |
+| `/setup` | Browser setup screen for one-time invite/reset links |
+| `/api/users`, `/api/users/:id/*`, `/api/audit-events` | Admin user management and audit log |
 | `/api/api-keys` | Browser-managed API key create/list/delete |
 | `/api/auth/device`, `/api/auth/token`, `/api/auth/refresh`, `/api/auth/revoke` | Device auth and refresh-token flow |
+| `/device` | Browser device-code approval screen |
 | `/.well-known/jwks.json`, `/.well-known/openid-configuration` | Token verification metadata |
 | `/api/preferences/theme`, `/api/preferences/log-level` | Settings persistence |
 | `/api/server/kill` | Authenticated server shutdown |

package/docs/settings.md

@@ -2,11 +2,13 @@
 
 Settings is framework-owned so apps stay consistent. It includes:
 
-- Passkey logout/delete
-- API key create/list/delete when enabled
-- Theme preference: system/light/dark
-- Log-level preference unless `{PREFIX}_LOG_LEVEL` is set
-- Server kill
+- Account summary and passkey logout/delete
+- API key create/list/delete for the current user when enabled
+- Device-auth sessions for the current user when enabled
+- Theme preference: system/light/dark, stored per user
+- Admin user management
+- Admin log-level preference unless `{PREFIX}_LOG_LEVEL` is set
+- Admin server kill
 - Version/about
 
 Apps can append structured custom sections:
@@ -18,6 +20,7 @@ Apps can append structured custom sections:
       {
         id: "sync",
         title: "Sync",
+        scope: "user",
         rows: [
           {
             id: "last-sync",
@@ -28,6 +31,7 @@ Apps can append structured custom sections:
           {
             id: "disconnect",
             title: "Disconnect",
+            scope: "admin",
             description: "Stops syncing this workspace.",
             danger: true,
             actions: [{ id: "disconnect", label: "Disconnect", variant: "danger", onAction: disconnect }],
@@ -40,3 +44,5 @@ Apps can append structured custom sections:
 ```
 
 `render` remains available as an escape hatch for custom controls inside a section. Prefer structured `rows` for simple settings because the framework keeps spacing, typography and danger-zone styling consistent.
+
+`scope` can be `user`, `admin` or `owner` on both sections and rows. Omitted scope behaves like `user`. Use `admin` for global app/server settings and `user` for preferences or data that belong to the signed-in user.

package/docs/sidebar.md

@@ -9,7 +9,7 @@
   sidebar={{
     topActions: [
       { id: "activity", title: "Activity", route: { view: "home" } },
-      { id: "new", title: "New item", route: { view: "new" } },
+      { id: "inbox", title: "Inbox", route: { view: "inbox" } },
     ],
     getNodes: ({ search }) => buildSidebarNodes(search),
   }}
@@ -29,7 +29,7 @@ Sidebar nodes support:
 | `type` | `section` or `item` |
 | `route` | Hash route object used by `WebAppRoot` |
 | `children` | Collapsible nesting |
-| `action` | Per-section/item action such as `New` |
+| `action` | Single inline per-section/item action; use sparingly and prefer `actions` menus when possible |
 | `actions` | Context menu items shown on sidebar right-click |
 | `pinnable` | Enables framework Pin/Unpin actions |
 | `pinId` | Stable pin identity when it should differ from `id` |
@@ -38,7 +38,7 @@ Sidebar nodes support:
 
 Search is intentionally app-defined: `getNodes({ search })` receives raw search text and returns the tree that should be rendered.
 
-Use `actions` when an entity needs a context menu in the sidebar. The same `ActionMenuItem[]` should also be returned from `header.getActions` for that entity route so right-click actions and the title-bar three-line menu stay consistent:
+Use `actions` when an entity needs commands in the sidebar. The same `ActionMenuItem[]` should also be returned from `header.getActions` for that entity route so right-click actions and the title-bar three-line menu stay consistent:
 
 ```tsx
 const actions = projectActions(project);

package/docs/ui-guidelines.md

@@ -19,7 +19,7 @@ Use these first:
 | `Toolbar` | Page title/actions inside main content |
 | `Panel` | Cards/sections; use `actions` for a top-right menu/action area |
 | `ActionMenu` | Three-line action menu for secondary surfaces; entity-level menus should usually be exposed through `WebAppRoot.header.getActions` so they render in the fixed title bar |
-| `Button` / `IconButton` | Actions |
+| `Button` / `IconButton` | Form submission and true inline controls; prefer action menus for entity/app commands |
 | `Badge` | Status/count labels |
 | `EntityHeader` | Main-content entity title/description/actions |
 | `DataList` / `DataListRow` | Lists with title, description, metadata, badge and actions |
@@ -43,13 +43,17 @@ Generated screenshots live in `artifacts/screenshots`:
 | `notes-desktop-light.png` | Realistic app, desktop shell |
 | `notes-settings-desktop-light.png` | Framework settings |
 | `notes-mobile-light.png` | Mobile shell |
+| `notes-mobile-sidebar-light.png` | Mobile drawer/sidebar |
 | `notes-desktop-dark.png` | Dark mode |
 | `kitchen-desktop-light.png` | Kitchen sink desktop |
 | `kitchen-mobile-light.png` | Kitchen sink mobile |
 | `kitchen-sidebar-collapsed-light.png` | Collapsed sidebar title bar |
 | `kitchen-context-menu-light.png` | Sidebar context menu |
 | `kitchen-dialog-dark.png` | Confirm dialog overlay |
+| `kitchen-device-light.png` | Device auth approval flow |
 
 Use `bun run screenshots` to regenerate these captures with Playwright. Browser automation and screenshot capture must stay Playwright-based and cross-platform; do not hard-code local Chrome or OS-specific browser paths.
 
 Use these captures as the manual visual baseline before changing shell, sidebar, settings or dialog styles.
+
+Prefer the framework action-menu pattern for app commands. Actions such as New task, New note, New project, archive, delete, or state transitions should live in `SidebarNode.actions` and/or `WebAppRoot.header.getActions` so they appear behind the three-line title-bar/item action menus. Use discrete buttons mainly for form submission or inline controls that cannot reasonably live in an action menu.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pablozaiden/webapp",
-  "version": "0.0.1",
+  "version": "0.2.0",
   "description": "Opinionated Bun + React webapp framework for single-server apps",
   "license": "MIT",
   "type": "module",

package/src/contracts/index.ts

@@ -2,12 +2,60 @@ export type LogLevelName = "trace" | "debug" | "info" | "warn" | "error";
 
 export type ThemePreference = "system" | "light" | "dark";
 
+export type WebAppUserRole = "owner" | "admin" | "user";
+
+export interface CurrentUser {
+  id: string;
+  username: string;
+  role: WebAppUserRole;
+  isOwner: boolean;
+  isAdmin: boolean;
+}
+
+export interface WebAppUserSummary {
+  id: string;
+  username: string;
+  role: WebAppUserRole;
+  passkeyConfigured: boolean;
+  createdAt: string;
+  updatedAt: string;
+  lastLoginAt?: string;
+}
+
+export interface UserSetupLinkResponse {
+  url: string;
+  expiresAt: string;
+}
+
+export interface CreatedUserResponse {
+  user: WebAppUserSummary;
+  setupLink: UserSetupLinkResponse;
+}
+
+export interface UserSetupDetails {
+  username: string;
+  role: WebAppUserRole;
+  kind: "invite" | "reset";
+  expiresAt: string;
+}
+
+export interface AuditEventSummary {
+  id: string;
+  eventType: string;
+  actorUserId?: string;
+  targetUserId?: string;
+  metadata: Record<string, unknown>;
+  createdAt: string;
+}
+
 export interface PasskeyAuthStatusResponse {
   enabled: boolean;
   passkeyConfigured: boolean;
   passkeyDisabled: boolean;
   passkeyRequired: boolean;
   authenticated: boolean;
+  bootstrapRequired: boolean;
+  ownerPasskeySetupRequired: boolean;
 }
 
 export interface ApiKeySummary {
@@ -66,7 +114,12 @@ export interface AuthSessionSummary {
 export interface WebAppConfigResponse {
   appName: string;
   version: string;
+  currentUser?: CurrentUser;
   passkeyAuth: PasskeyAuthStatusResponse;
+  userManagement: {
+    enabled: boolean;
+    canManageUsers: boolean;
+  };
   logLevel: {
     level: LogLevelName;
     fromEnv: boolean;

package/src/server/auth/api-keys.ts

@@ -1,4 +1,4 @@
-import type { ApiKeySummary, CreatedApiKeyResponse } from "../../contracts";
+import type { ApiKeySummary, CreatedApiKeyResponse, CurrentUser } from "../../contracts";
 import type { WebAppStore } from "./store";
 import { nowIso, randomToken, sha256, secureEqual, isExpired } from "./crypto";
 import { AuthError } from "./types";
@@ -15,15 +15,16 @@ function summarize(record: { tokenHash?: string } & ApiKeySummary): ApiKeySummar
   };
 }
 
-export function listApiKeys(store: WebAppStore): ApiKeySummary[] {
-  return store.listApiKeys().map(summarize);
+export function listApiKeys(store: WebAppStore, userId: string): ApiKeySummary[] {
+  return store.listApiKeys(userId).map(summarize);
 }
 
-export function createApiKey(store: WebAppStore, input: { name?: string; scopes?: string[]; prefix?: string; expiresAt?: string }): CreatedApiKeyResponse {
+export function createApiKey(store: WebAppStore, user: CurrentUser, input: { name?: string; scopes?: string[]; prefix?: string; expiresAt?: string }): CreatedApiKeyResponse {
   const prefix = input.prefix ?? "wapp";
   const token = `${prefix}_${randomToken(32)}`;
   const record = {
     id: crypto.randomUUID(),
+    userId: user.id,
     name: input.name?.trim() || "API key",
     prefix,
     tokenHash: sha256(token),
@@ -35,18 +36,22 @@ export function createApiKey(store: WebAppStore, input: { name?: string; scopes?
   return { key: summarize(record), token };
 }
 
-export function deleteApiKey(store: WebAppStore, id: string): boolean {
-  return store.deleteApiKey(id);
+export function deleteApiKey(store: WebAppStore, userId: string, id: string): boolean {
+  return store.deleteApiKey(id, userId);
 }
 
-export function authenticateApiKey(store: WebAppStore, token: string): { apiKeyId: string; scopes: string[] } | undefined {
+export function authenticateApiKey(store: WebAppStore, token: string): { user: CurrentUser; apiKeyId: string; scopes: string[] } | undefined {
   const tokenHash = sha256(token);
   const record = store.getApiKeyByHash(tokenHash);
   if (!record || !secureEqual(record.tokenHash, tokenHash) || (record.expiresAt && isExpired(record.expiresAt))) {
     return undefined;
   }
+  const user = store.getUserById(record.userId);
+  if (!user) {
+    return undefined;
+  }
   store.touchApiKey(record.id, nowIso());
-  return { apiKeyId: record.id, scopes: record.scopes };
+  return { user: { id: user.id, username: user.username, role: user.role, isOwner: user.role === "owner", isAdmin: user.role === "owner" || user.role === "admin" }, apiKeyId: record.id, scopes: record.scopes };
 }
 
 export function assertScopes(actual: string[], required: string[]): void {