@pablozaiden/webapp 1.0.0 → 1.1.0

package/README.md

@@ -1,6 +1,6 @@
 # @pablozaiden/webapp
 
-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, stateless CLI API-key auth, realtime websocket state, scoped 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 and server-managed API keys, device auth, stateless CLI API-key auth, realtime websocket state, scoped settings, binary builds and Docker images.
 
 ## Quick start
 

package/docs/auth-validation.md

@@ -39,6 +39,10 @@ Run this checklist before releasing a framework app or cutting a checkpoint.
 3. Call a protected API route with `Authorization: Bearer <token>`.
 4. Delete the key from Settings and confirm the confirmation dialog appears.
 5. Confirm the deleted token no longer authenticates.
+6. Create a managed key through the server-only helper and confirm it authenticates through the same bearer path.
+7. Confirm managed keys and `managedBy` metadata are absent from the normal API-key list and Settings UI.
+8. Restart against the same data directory and confirm a non-expired managed key still authenticates.
+9. Revoke the managed key through the server-only helper and confirm it no longer authenticates.
 
 ## CLI API-key authentication
 

package/docs/auth.md

@@ -42,6 +42,38 @@ API keys are user-owned bearer tokens for scripts and agents. They are stored ha
 
 Expired API keys do not authenticate, are omitted from user-facing lists, and are purged when key lists or expired keys are encountered.
 
+Server-side applications can create managed keys through the server-only helpers exported from
+`@pablozaiden/webapp/server`:
+
+```ts
+import { createManagedApiKey, listManagedApiKeys, revokeManagedApiKey } from "@pablozaiden/webapp/server";
+
+const created = createManagedApiKey(app.store, user, {
+  name: "Runtime credential",
+  managedBy: "my-application",
+  scopes: ["*"],
+});
+const keys = listManagedApiKeys(app.store, user.id, "my-application");
+revokeManagedApiKey(app.store, created.key.id, user.id);
+```
+
+Managed keys have an explicit `kind: "managed"` classification and optional opaque
+`managedBy` metadata. The plaintext token is returned only by creation and is never
+stored; applications must retain it securely. Managed keys use the same bearer
+authentication, ownership, scope, expiration, disabled-user, and lifecycle invalidation
+rules as user keys. They survive an ordinary restart, and applications should explicitly
+revoke each generation during their own resource cleanup.
+
+Managed keys have no browser/API CRUD endpoint. The normal `/api/api-keys` routes and
+Settings UI expose only `kind: "user"` keys, and request input cannot create or convert a
+managed key. User reset, passkey deletion, user deletion, and expiration cleanup cover
+both kinds.
+
+Custom `WebAppStore` implementations must persist `kind` and `managedBy`, migrate
+pre-managed records as `kind: "user"`, include both kinds in expiration cleanup and
+user deletion/reset cleanup, and preserve the owner filter used by the management
+helpers. The built-in SQLite store performs this migration automatically.
+
 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`.
 
 ## Device auth

package/docs/server.md

@@ -148,7 +148,7 @@ Built-in endpoints include:
 | `/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/api-keys` | Browser-managed user 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 |
@@ -162,6 +162,12 @@ The effective log level in `GET /api/config` and `GET
 to `true`. PUT remains an authenticated, same-origin admin mutation and
 returns a conflict when the environment controls the value.
 
+Server-side applications that need credentials for internal runtimes should use
+the server-only `createManagedApiKey`, `listManagedApiKeys`, and
+`revokeManagedApiKey` helpers. Managed keys are persisted in the same API-key
+store, authenticate through the normal bearer path, and are intentionally absent
+from the browser-managed endpoint and Settings summaries.
+
 ## Framework-owned web document and PWA metadata
 
 `createWebAppServer` owns the browser document. Apps do not provide `index.html`; the framework generates a Bun `HTMLBundle` internally so Bun hot reload and asset rewriting keep working. By default the frontend entrypoint is `./web/main.tsx` relative to the Bun entry file. The generated document also initializes the shared `data-wapp-mobile` state before client styles load so CSS and `WebAppRoot` use the same mobile breakpoint. The generated viewport keeps the app at `initial-scale=1` with `maximum-scale=1` and `user-scalable=no`; clients and mobile browsers that honor those viewport scaling tokens, including iPhone and iPad, cannot change the app scale with pinch-to-zoom while normal scrolling remains enabled. Clients that ignore the tokens are unaffected.

package/docs/settings.md

@@ -3,7 +3,7 @@
 Settings is framework-owned so apps stay consistent. It includes:
 
 - Account summary and passkey logout/delete
-- API key create/list/delete for the current user when enabled
+- User 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
@@ -33,7 +33,11 @@ the shared hook state after a successful save, and `fromEnv` is true when
 `{PREFIX}_LOG_LEVEL` locks the value. Applications should not add a separate
 configuration fetch or initializer component.
 
-Security lists only show useful active credentials. Expired API keys are purged before listing, and revoked or expired device-auth refresh sessions are not shown. Revoked refresh sessions may remain in storage when needed for token-reuse protection, but they are hidden from Settings.
+Security lists only show useful active user credentials. Managed API keys created by
+server-side applications, and their metadata, are not returned by the browser API-key
+list or rendered in Settings. Expired API keys are purged before listing, and revoked
+or expired device-auth refresh sessions are not shown. Revoked refresh sessions may
+remain in storage when needed for token-reuse protection, but they are hidden from Settings.
 
 Destructive actions in Settings use the framework `ConfirmDialog` before mutating. This includes deleting users, deleting API keys, deleting passkeys, revoking device-auth sessions, and killing the server.
 

package/package.json

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

package/src/contracts/index.ts

@@ -58,6 +58,8 @@ export interface PasskeyAuthStatusResponse {
   ownerPasskeySetupRequired: boolean;
 }
 
+export type ApiKeyKind = "user" | "managed";
+
 export interface ApiKeySummary {
   id: string;
   name: string;

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

@@ -1,9 +1,30 @@
 import type { ApiKeySummary, CreatedApiKeyResponse, CurrentUser } from "../../contracts";
-import type { WebAppStore } from "./store";
+import type { ApiKeyRecord, WebAppStore } from "./store";
 import { nowIso, randomToken, sha256, secureEqual, isExpired } from "./crypto";
 import { AuthError } from "./types";
 
-function summarize(record: { tokenHash?: string } & ApiKeySummary): ApiKeySummary {
+export interface ManagedApiKeySummary extends ApiKeySummary {
+  kind: "managed";
+  managedBy?: string;
+}
+
+export interface CreatedManagedApiKeyResponse {
+  key: ManagedApiKeySummary;
+  token: string;
+}
+
+export interface ApiKeyCreationOptions {
+  name?: string;
+  scopes?: string[];
+  prefix?: string;
+  expiresAt?: string;
+}
+
+export interface ManagedApiKeyCreationOptions extends ApiKeyCreationOptions {
+  managedBy?: string;
+}
+
+function summarize(record: ApiKeyRecord): ApiKeySummary {
   return {
     id: record.id,
     name: record.name,
@@ -15,17 +36,31 @@ function summarize(record: { tokenHash?: string } & ApiKeySummary): ApiKeySummar
   };
 }
 
+function summarizeManaged(record: ApiKeyRecord): ManagedApiKeySummary {
+  return {
+    ...summarize(record),
+    kind: "managed",
+    managedBy: record.managedBy,
+  };
+}
+
 export function listApiKeys(store: WebAppStore, userId: string): ApiKeySummary[] {
   store.deleteExpiredApiKeys?.(nowIso());
   return store.listApiKeys(userId)
+    .filter((record) => record.userId === userId && record.kind === "user")
     .filter((record) => !record.expiresAt || !isExpired(record.expiresAt))
     .map(summarize);
 }
 
-export function createApiKey(store: WebAppStore, user: CurrentUser, input: { name?: string; scopes?: string[]; prefix?: string; expiresAt?: string }): CreatedApiKeyResponse {
+function createApiKeyRecord(
+  user: CurrentUser,
+  input: ApiKeyCreationOptions,
+  kind: ApiKeyRecord["kind"],
+  managedBy?: string,
+): { record: ApiKeyRecord; token: string } {
   const prefix = input.prefix ?? "wapp";
   const token = `${prefix}_${randomToken(32)}`;
-  const record = {
+  const record: ApiKeyRecord = {
     id: crypto.randomUUID(),
     userId: user.id,
     name: input.name?.trim() || "API key",
@@ -34,15 +69,53 @@ export function createApiKey(store: WebAppStore, user: CurrentUser, input: { nam
     scopes: input.scopes?.length ? input.scopes : ["*"],
     createdAt: nowIso(),
     expiresAt: input.expiresAt,
+    kind,
+    managedBy,
   };
+  return { record, token };
+}
+
+export function createApiKey(store: WebAppStore, user: CurrentUser, input: ApiKeyCreationOptions): CreatedApiKeyResponse {
+  const { record, token } = createApiKeyRecord(user, input, "user");
   store.saveApiKey(record);
   return { key: summarize(record), token };
 }
 
 export function deleteApiKey(store: WebAppStore, userId: string, id: string): boolean {
+  const record = store.listApiKeys(userId).find((candidate) => candidate.id === id && candidate.userId === userId);
+  if (!record || record.kind !== "user") {
+    return false;
+  }
   return store.deleteApiKey(id, userId);
 }
 
+export function createManagedApiKey(store: WebAppStore, user: CurrentUser, input: ManagedApiKeyCreationOptions = {}): CreatedManagedApiKeyResponse {
+  const { record, token } = createApiKeyRecord(user, input, "managed", input.managedBy);
+  store.saveApiKey(record);
+  return { key: summarizeManaged(record), token };
+}
+
+export function listManagedApiKeys(store: WebAppStore, userId: string, managedBy?: string): ManagedApiKeySummary[] {
+  store.deleteExpiredApiKeys?.(nowIso());
+  return store.listApiKeys(userId)
+    .filter((record) => record.userId === userId && record.kind === "managed")
+    .filter((record) => managedBy === undefined || record.managedBy === managedBy)
+    .filter((record) => !record.expiresAt || !isExpired(record.expiresAt))
+    .map(summarizeManaged);
+}
+
+export function revokeManagedApiKey(store: WebAppStore, id: string, userId?: string): boolean {
+  const record = store.listApiKeys(userId).find((candidate) =>
+    candidate.id === id
+    && candidate.kind === "managed"
+    && (userId === undefined || candidate.userId === userId)
+  );
+  if (!record) {
+    return false;
+  }
+  return store.deleteApiKey(id, record.userId);
+}
+
 export function authenticateApiKey(store: WebAppStore, token: string): { user: CurrentUser; apiKeyId: string; scopes: string[] } | undefined {
   const tokenHash = sha256(token);
   const record = store.getApiKeyByHash(tokenHash);
@@ -53,7 +126,7 @@ export function authenticateApiKey(store: WebAppStore, token: string): { user: C
     return undefined;
   }
   const user = store.getUserById(record.userId);
-  if (!user) {
+  if (!user || user.disabledAt) {
     return undefined;
   }
   store.touchApiKey(record.id, nowIso());

package/src/server/auth/sqlite-store.ts

@@ -11,7 +11,7 @@ import type {
   UserSetupLinkRecord,
   WebAppStore,
 } from "./store";
-import type { LogLevelName, ThemePreference, WebAppUserRole } from "../../contracts";
+import type { ApiKeyKind, LogLevelName, ThemePreference, WebAppUserRole } from "../../contracts";
 import { createUserRecord } from "./users";
 
 type Row = Record<string, unknown>;
@@ -132,6 +132,8 @@ export function sqliteWebAppStore(options: { dataDir?: string; fileName?: string
         created_at TEXT NOT NULL,
         last_used_at TEXT,
         expires_at TEXT,
+        kind TEXT NOT NULL DEFAULT 'user',
+        managed_by TEXT,
         FOREIGN KEY (user_id) REFERENCES webapp_users(id) ON DELETE CASCADE
       );
       CREATE TABLE IF NOT EXISTS webapp_device_auth_requests (
@@ -175,6 +177,19 @@ export function sqliteWebAppStore(options: { dataDir?: string; fileName?: string
     `);
   }
 
+  function migrateApiKeySchema(): void {
+    if (!tableExists("webapp_api_keys")) {
+      return;
+    }
+    if (!hasColumn("webapp_api_keys", "kind")) {
+      db.exec("ALTER TABLE webapp_api_keys ADD COLUMN kind TEXT NOT NULL DEFAULT 'user';");
+    }
+    if (!hasColumn("webapp_api_keys", "managed_by")) {
+      db.exec("ALTER TABLE webapp_api_keys ADD COLUMN managed_by TEXT;");
+    }
+    db.exec("CREATE INDEX IF NOT EXISTS idx_webapp_api_keys_managed ON webapp_api_keys(user_id, kind, managed_by);");
+  }
+
   function migrateSingleUserSchema(): void {
     const legacySources = [
       ["webapp_preferences", tableExists("webapp_preferences") && !hasColumn("webapp_preferences", "user_id")],
@@ -277,6 +292,7 @@ export function sqliteWebAppStore(options: { dataDir?: string; fileName?: string
   function initialize(): void {
     migrateSingleUserSchema();
     createSchema();
+    migrateApiKeySchema();
     db.exec("PRAGMA foreign_keys = ON;");
   }
 
@@ -356,6 +372,7 @@ export function sqliteWebAppStore(options: { dataDir?: string; fileName?: string
   }
 
   function mapApiKey(row: Row): ApiKeyRecord {
+    const kind: ApiKeyKind = row["kind"] === "managed" ? "managed" : "user";
     return {
       id: text(row["id"]),
       userId: text(row["user_id"]),
@@ -366,6 +383,8 @@ export function sqliteWebAppStore(options: { dataDir?: string; fileName?: string
       createdAt: text(row["created_at"]),
       lastUsedAt: optionalText(row["last_used_at"]),
       expiresAt: optionalText(row["expires_at"]),
+      kind,
+      managedBy: optionalText(row["managed_by"]),
     };
   }
 
@@ -544,9 +563,22 @@ export function sqliteWebAppStore(options: { dataDir?: string; fileName?: string
     },
     saveApiKey: (record) => {
       db.query(`
-        INSERT INTO webapp_api_keys (id, user_id, name, prefix, token_hash, scopes, created_at, last_used_at, expires_at)
-        VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
-      `).run(record.id, record.userId, record.name, record.prefix, record.tokenHash, JSON.stringify(record.scopes), record.createdAt, record.lastUsedAt ?? null, record.expiresAt ?? null);
+        INSERT INTO webapp_api_keys
+        (id, user_id, name, prefix, token_hash, scopes, created_at, last_used_at, expires_at, kind, managed_by)
+        VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+      `).run(
+        record.id,
+        record.userId,
+        record.name,
+        record.prefix,
+        record.tokenHash,
+        JSON.stringify(record.scopes),
+        record.createdAt,
+        record.lastUsedAt ?? null,
+        record.expiresAt ?? null,
+        record.kind,
+        record.managedBy ?? null,
+      );
     },
     touchApiKey: (id, lastUsedAt) => {
       db.query("UPDATE webapp_api_keys SET last_used_at = ? WHERE id = ?").run(lastUsedAt, id);

package/src/server/auth/store.ts

@@ -1,4 +1,4 @@
-import type { ApiKeySummary, AuditEventSummary, LogLevelName, ThemePreference, WebAppUserRole, WebAppUserSummary } from "../../contracts";
+import type { ApiKeyKind, ApiKeySummary, AuditEventSummary, LogLevelName, ThemePreference, WebAppUserRole, WebAppUserSummary } from "../../contracts";
 
 export interface UserRecord extends WebAppUserSummary {
   authVersion: number;
@@ -36,6 +36,8 @@ export interface StoredPasskey {
 export interface ApiKeyRecord extends ApiKeySummary {
   userId: string;
   tokenHash: string;
+  kind: ApiKeyKind;
+  managedBy?: string;
 }
 
 export interface DeviceAuthRequestRecord {

package/src/server/framework-endpoints.ts

@@ -386,6 +386,7 @@ export function createFrameworkEndpointHandler(dependencies: FrameworkEndpointDe
         const target = store.getUserById(userId);
         if (!target) return notFound();
         if (target.role === "owner") return errorResponse(409, "owner_immutable", "Owner cannot be deleted");
+        store.deleteApiKeysForUser(userId);
         if (!store.deleteUser(userId)) return notFound();
         audit(store, { eventType: "user_deleted", actorUserId: actor.id, metadata: { deletedUserId: userId, username: target.username } });
         return successResponse();

package/src/server/index.ts

@@ -5,6 +5,7 @@ export * from "./responses";
 export * from "./public-assets";
 export * from "./create-web-app-server";
 export { getRequestBaseUrl, getRequestOriginInfo, type RequestOriginInfo } from "./auth/request-origin";
+export * from "./auth/api-keys";
 export * from "./auth/store";
 export * from "./auth/sqlite-store";
 export * from "./realtime/bus";