@pablozaiden/webapp 0.1.0 → 0.2.1

package/src/cli/api-command.ts

@@ -0,0 +1,119 @@
+import { z } from "zod";
+import { findRouteCatalogEntry, type RouteCatalogEntry } from "../server/route-catalog";
+import { getAuthorizedHeaders, refreshDeviceCredentials, type StoredDeviceCredentials } from "./device-auth";
+import { readOption, type CliCommandResult } from "./runtime";
+
+export interface ApiCliCredentialsStore {
+  read(): Promise<StoredDeviceCredentials | undefined>;
+  write(value: StoredDeviceCredentials): Promise<void>;
+}
+
+export interface ApiCliCommandOptions {
+  catalog: readonly RouteCatalogEntry[];
+  args: string[];
+  mode?: "api" | "schema";
+  baseUrl?: string;
+  credentials?: ApiCliCredentialsStore;
+  fetchFn?: typeof fetch;
+  now?: () => Date;
+}
+
+function schemaJson(schema: unknown): unknown {
+  if (!schema) return undefined;
+  try {
+    return z.toJSONSchema(schema as z.ZodTypeAny);
+  } catch {
+    return schema;
+  }
+}
+
+function listOutput(catalog: readonly RouteCatalogEntry[]): string {
+  return catalog
+    .filter((entry) => entry.path.startsWith("/api/"))
+    .map((entry) => `${entry.methods.join(", ")} ${entry.cliPath}${entry.description ? ` - ${entry.description}` : ""}`)
+    .join("\n");
+}
+
+function schemaOutput(entry: RouteCatalogEntry): string {
+  return JSON.stringify({
+    path: entry.path,
+    cliPath: entry.cliPath,
+    methods: entry.methods,
+    auth: entry.auth,
+    sameOrigin: entry.sameOrigin,
+    scopes: entry.scopes,
+    description: entry.description,
+    tags: entry.tags,
+    querySchema: schemaJson(entry.querySchema),
+    requestSchema: schemaJson(entry.requestSchema),
+    responseSchema: schemaJson(entry.responseSchema),
+  }, null, 2);
+}
+
+function endpointArg(args: string[]): string | undefined {
+  return args.find((arg) => !arg.startsWith("--"));
+}
+
+async function authHeaders(input: ApiCliCommandOptions): Promise<Headers> {
+  const headers = new Headers({ accept: "application/json" });
+  const stored = await input.credentials?.read();
+  if (!stored) return headers;
+  const refreshed = await refreshDeviceCredentials({
+    credentials: stored,
+    store: input.credentials,
+    fetchFn: input.fetchFn,
+    now: input.now,
+  });
+  return refreshed ? getAuthorizedHeaders(refreshed, headers) : headers;
+}
+
+export async function runApiCliCommand(input: ApiCliCommandOptions): Promise<CliCommandResult> {
+  const endpoint = endpointArg(input.args);
+  if (!endpoint) {
+    return { exitCode: 0, output: listOutput(input.catalog) };
+  }
+  const match = findRouteCatalogEntry(input.catalog, endpoint);
+  if (!match) {
+    return { exitCode: 1, error: `Unknown API endpoint: ${endpoint}` };
+  }
+  if (input.mode === "schema") {
+    return { exitCode: 0, output: schemaOutput(match.entry) };
+  }
+  const method = (readOption(input.args, ["--method", "-X"]) ?? match.entry.methods[0] ?? "GET").toUpperCase();
+  if (!match.entry.methods.includes(method as never)) {
+    return { exitCode: 1, error: `Method ${method} is not available for ${match.entry.cliPath}` };
+  }
+  const payload = readOption(input.args, ["--payload", "--data", "-d"]);
+  const baseUrl = (input.baseUrl ?? "http://localhost:3000").replace(/\/+$/, "");
+  const url = new URL(`${baseUrl}${match.path}`);
+  const headers = await authHeaders(input);
+  let body: string | undefined;
+  if (payload !== undefined) {
+    JSON.parse(payload) as unknown;
+    body = payload;
+    headers.set("content-type", "application/json");
+  }
+  const send = () => (input.fetchFn ?? fetch)(url, { method, headers, body });
+  let response = await send();
+  if (response.status === 401 && input.credentials) {
+    const stored = await input.credentials.read();
+    if (stored) {
+      const refreshed = await refreshDeviceCredentials({ credentials: { ...stored, accessTokenExpiresAt: new Date(0).toISOString() }, store: input.credentials, fetchFn: input.fetchFn, now: input.now });
+      if (refreshed) {
+        headers.set("authorization", `${refreshed.tokenType} ${refreshed.accessToken}`);
+      }
+      response = await send();
+    }
+  }
+  const text = await response.text();
+  let parsed: unknown = text;
+  try {
+    parsed = text ? JSON.parse(text) as unknown : null;
+  } catch {
+    parsed = text || null;
+  }
+  return {
+    exitCode: response.ok ? 0 : 1,
+    output: JSON.stringify({ status: { code: response.status, ok: response.ok, text: response.statusText }, response: parsed }, null, 2),
+  };
+}

package/src/cli/credentials.ts

@@ -0,0 +1,67 @@
+import { chmodSync } from "node:fs";
+import { mkdir, readFile, rename, rm } from "node:fs/promises";
+import { dirname, join } from "node:path";
+
+export interface JsonFileStore<T> {
+  path(): string;
+  read(): Promise<T | undefined>;
+  write(value: T): Promise<void>;
+  clear(): Promise<void>;
+}
+
+function chmodIfPossible(path: string, mode: number): void {
+  try {
+    chmodSync(path, mode);
+  } catch {
+    // Not all platforms/filesystems support POSIX modes.
+  }
+}
+
+export function createJsonFileStore<T>(input: {
+  appDirectoryName: string;
+  fileName: string;
+  envHome?: string;
+  parse(value: unknown): T;
+  home?: string;
+}): JsonFileStore<T> {
+  const stateDir = () => {
+    const explicit = input.envHome ? process.env[input.envHome]?.trim() : undefined;
+    const home = input.home ?? process.env["HOME"]?.trim();
+    if (explicit) return explicit;
+    if (!home) throw new Error("HOME is not set");
+    return join(home, input.appDirectoryName);
+  };
+  const filePath = () => join(stateDir(), input.fileName);
+  return {
+    path: filePath,
+    async read() {
+      try {
+        return input.parse(JSON.parse(await readFile(filePath(), "utf8")) as unknown);
+      } catch (error) {
+        if (error && typeof error === "object" && "code" in error && error.code === "ENOENT") {
+          return undefined;
+        }
+        throw error;
+      }
+    },
+    async write(value) {
+      const target = filePath();
+      const dir = dirname(target);
+      await mkdir(dir, { recursive: true, mode: 0o700 });
+      chmodIfPossible(dir, 0o700);
+      const temp = join(dir, `.${input.fileName}.${process.pid}.${crypto.randomUUID()}.tmp`);
+      try {
+        await Bun.write(temp, `${JSON.stringify(value, null, 2)}\n`);
+        chmodIfPossible(temp, 0o600);
+        await rename(temp, target);
+        chmodIfPossible(target, 0o600);
+      } catch (error) {
+        await rm(temp, { force: true });
+        throw error;
+      }
+    },
+    async clear() {
+      await rm(filePath(), { force: true });
+    },
+  };
+}

package/src/cli/device-auth.ts

@@ -0,0 +1,179 @@
+import { createJsonFileStore, type JsonFileStore } from "./credentials";
+
+export interface StoredDeviceCredentials {
+  baseUrl: string;
+  clientId: string;
+  accessToken: string;
+  refreshToken: string;
+  tokenType: "Bearer";
+  scope: string;
+  accessTokenExpiresAt: string;
+  createdAt: string;
+  updatedAt: string;
+}
+
+export function normalizeBaseUrl(value: string): string {
+  const url = new URL(value.trim());
+  if (url.protocol !== "http:" && url.protocol !== "https:") {
+    throw new Error(`Invalid base URL protocol: ${url.protocol}`);
+  }
+  return url.toString().replace(/\/+$/, "");
+}
+
+export function parseStoredDeviceCredentials(value: unknown): StoredDeviceCredentials {
+  if (!value || typeof value !== "object") {
+    throw new Error("Stored credentials must be an object");
+  }
+  const record = value as Record<string, unknown>;
+  const credentials = {
+    baseUrl: String(record["baseUrl"] ?? ""),
+    clientId: String(record["clientId"] ?? ""),
+    accessToken: String(record["accessToken"] ?? ""),
+    refreshToken: String(record["refreshToken"] ?? ""),
+    tokenType: record["tokenType"],
+    scope: String(record["scope"] ?? ""),
+    accessTokenExpiresAt: String(record["accessTokenExpiresAt"] ?? ""),
+    createdAt: String(record["createdAt"] ?? ""),
+    updatedAt: String(record["updatedAt"] ?? ""),
+  };
+  if (!credentials.baseUrl || !credentials.clientId || !credentials.accessToken || !credentials.refreshToken || credentials.tokenType !== "Bearer") {
+    throw new Error("Stored credentials are invalid");
+  }
+  return credentials as StoredDeviceCredentials;
+}
+
+export function createDeviceCredentialsStore(input: {
+  appDirectoryName: string;
+  envHome?: string;
+  fileName?: string;
+  home?: string;
+}): JsonFileStore<StoredDeviceCredentials> {
+  return createJsonFileStore({
+    appDirectoryName: input.appDirectoryName,
+    fileName: input.fileName ?? "device-auth.json",
+    envHome: input.envHome,
+    home: input.home,
+    parse: parseStoredDeviceCredentials,
+  });
+}
+
+export function getAuthorizedHeaders(credentials: StoredDeviceCredentials, headers?: HeadersInit): Headers {
+  const result = new Headers(headers);
+  result.set("authorization", `${credentials.tokenType} ${credentials.accessToken}`);
+  return result;
+}
+
+function isExpired(credentials: StoredDeviceCredentials, now: Date): boolean {
+  return new Date(credentials.accessTokenExpiresAt).getTime() <= now.getTime();
+}
+
+async function requestJson(fetchFn: typeof fetch, url: string, init?: RequestInit): Promise<{ response: Response; body: unknown }> {
+  const headers = new Headers(init?.headers);
+  headers.set("accept", "application/json");
+  const response = await fetchFn(url, { ...init, headers });
+  const text = await response.text();
+  if (!text) {
+    return { response, body: undefined };
+  }
+  try {
+    return { response, body: JSON.parse(text) as unknown };
+  } catch {
+    return { response, body: text };
+  }
+}
+
+function tokenError(body: unknown, status: number): string {
+  if (body && typeof body === "object") {
+    const record = body as Record<string, unknown>;
+    return String(record["error_description"] ?? record["message"] ?? record["error"] ?? `Request failed with status ${status}`);
+  }
+  return `Request failed with status ${status}`;
+}
+
+function tokenCredentials(baseUrl: string, clientId: string, tokenSet: Record<string, unknown>, now: Date): StoredDeviceCredentials {
+  const expiresIn = Number(tokenSet["expires_in"] ?? 0);
+  return {
+    baseUrl,
+    clientId,
+    accessToken: String(tokenSet["access_token"] ?? ""),
+    refreshToken: String(tokenSet["refresh_token"] ?? ""),
+    tokenType: "Bearer",
+    scope: String(tokenSet["scope"] ?? ""),
+    accessTokenExpiresAt: new Date(now.getTime() + expiresIn * 1000).toISOString(),
+    createdAt: now.toISOString(),
+    updatedAt: now.toISOString(),
+  };
+}
+
+export async function refreshDeviceCredentials(input: {
+  credentials: StoredDeviceCredentials;
+  store?: { write(value: StoredDeviceCredentials): Promise<void> };
+  fetchFn?: typeof fetch;
+  now?: () => Date;
+}): Promise<StoredDeviceCredentials | undefined> {
+  if (!isExpired(input.credentials, (input.now ?? (() => new Date()))())) {
+    return input.credentials;
+  }
+  const now = input.now?.() ?? new Date();
+  const { response, body } = await requestJson(input.fetchFn ?? fetch, `${input.credentials.baseUrl}/api/auth/token`, {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify({
+      grant_type: "refresh_token",
+      refresh_token: input.credentials.refreshToken,
+      client_id: input.credentials.clientId,
+    }),
+  });
+  if (!response.ok) {
+    return undefined;
+  }
+  const next = tokenCredentials(input.credentials.baseUrl, input.credentials.clientId, body as Record<string, unknown>, now);
+  await input.store?.write(next);
+  return next;
+}
+
+export async function runDeviceAuthCommand(input: {
+  baseUrl: string;
+  clientId: string;
+  store: JsonFileStore<StoredDeviceCredentials>;
+  scope?: string;
+  fetchFn?: typeof fetch;
+  sleep?: (ms: number) => Promise<void>;
+  now?: () => Date;
+  out?: (message: string) => void;
+}): Promise<number> {
+  const baseUrl = normalizeBaseUrl(input.baseUrl);
+  const fetchFn = input.fetchFn ?? fetch;
+  const now = input.now ?? (() => new Date());
+  const out = input.out ?? console.log;
+  const start = await requestJson(fetchFn, `${baseUrl}/api/auth/device`, {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify({ clientId: input.clientId, scope: input.scope }),
+  });
+  if (!start.response.ok) throw new Error(tokenError(start.body, start.response.status));
+  const started = start.body as Record<string, unknown>;
+  out(`Open: ${String(started["verification_uri_complete"] ?? started["verification_uri"])}`);
+  out(`Code: ${String(started["user_code"] ?? "")}`);
+  const interval = Number(started["interval"] ?? 5) * 1000;
+  while (true) {
+    await (input.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms))))(interval);
+    const token = await requestJson(fetchFn, `${baseUrl}/api/auth/token`, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({
+        grant_type: "urn:ietf:params:oauth:grant-type:device_code",
+        device_code: started["device_code"],
+        client_id: input.clientId,
+      }),
+    });
+    if (token.response.ok) {
+      await input.store.write(tokenCredentials(baseUrl, input.clientId, token.body as Record<string, unknown>, now()));
+      out(`Authenticated with ${baseUrl}`);
+      return 0;
+    }
+    const error = (token.body as Record<string, unknown> | undefined)?.["error"];
+    if (error === "authorization_pending" || error === "slow_down") continue;
+    throw new Error(tokenError(token.body, token.response.status));
+  }
+}

package/src/cli/index.ts

@@ -0,0 +1,4 @@
+export * from "./runtime";
+export * from "./credentials";
+export * from "./device-auth";
+export * from "./api-command";

package/src/cli/runtime.ts

@@ -0,0 +1,51 @@
+export interface CliCommandResult {
+  exitCode: number;
+  output?: string;
+  error?: string;
+}
+
+export type CliCommandHandler = (args: string[]) => CliCommandResult | Promise<CliCommandResult>;
+
+export function printCliResult(result: CliCommandResult, output: Pick<Console, "log" | "error"> = console): number {
+  if (result.output) {
+    output.log(result.output);
+  }
+  if (result.error) {
+    output.error(result.error);
+  }
+  return result.exitCode;
+}
+
+export function readOption(args: readonly string[], names: readonly string[]): string | undefined {
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (!arg) continue;
+    for (const name of names) {
+      if (arg === name) return args[index + 1];
+      if (arg.startsWith(`${name}=`)) return arg.slice(name.length + 1);
+    }
+  }
+  return undefined;
+}
+
+export function hasFlag(args: readonly string[], names: readonly string[]): boolean {
+  return args.some((arg) => names.includes(arg));
+}
+
+export async function dispatchCliCommand(input: {
+  args: string[];
+  commands: Record<string, CliCommandHandler>;
+  defaultCommand?: string;
+  help: string;
+}): Promise<CliCommandResult> {
+  const [rawCommand, ...rest] = input.args;
+  const command = rawCommand && !rawCommand.startsWith("-") ? rawCommand : input.defaultCommand;
+  if (!command || rawCommand === "help" || rawCommand === "--help" || rawCommand === "-h") {
+    return { exitCode: rawCommand ? 0 : 1, output: input.help };
+  }
+  const handler = input.commands[command];
+  if (!handler) {
+    return { exitCode: 1, error: `Unknown command: ${command}`, output: input.help };
+  }
+  return await handler(rawCommand === command ? rest : input.args);
+}

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 {