Skip to content

AI-native knowledge base & Evernote/Obsidian alternative with instant sync & native MCP. Free on Cloudflare or self-hosted via Docker.

refactor: extract API auth and resource routes

tianma-if8ede5c0de3e1
diff --git a/apps/api/src/auth-routes.test.mjs b/apps/api/src/auth-routes.test.mjs
new file mode 100644
index 00000000..124fdba4
--- /dev/null
+++ b/apps/api/src/auth-routes.test.mjs
@@ -0,0 +1,97 @@
+import { describe, expect, test } from "bun:test";
+import { Hono } from "hono";
+import { registerAuthRoutes } from "./auth-routes.ts";
+
+const interactiveAuth = {
+ kind: "user",
+ actorType: "user",
+ actorId: "usr_owner",
+ username: "owner",
+ displayName: "Owner",
+ scopes: [],
+ workspaceId: "ws_owner",
+ role: "owner",
+ sessionId: "session_current",
+};
+
+const environment = {
+ storage: {
+ db: {
+ prepare: () => {
+ throw new Error("Database access was not expected");
+ },
+ batch: async () => [],
+ },
+ resources: {},
+ },
+};
+
+const createApp = (overrides = {}) => {
+ const app = new Hono();
+ registerAuthRoutes(app, {
+ authenticateRequest: async () => null,
+ authenticateSession: async () => null,
+ createSession: async () => ({ id: "session", token: "token", maxAge: 60 }),
+ ensureUserWorkspace: async () => ({ workspaceId: "workspace", role: "owner" }),
+ getBearerToken: () => null,
+ getInstanceAuthMode: async () => "required",
+ getLoginAttemptKeys: async () => [],
+ isDemoEnvironment: () => false,
+ isDemoMode: () => false,
+ revokeSession: async () => undefined,
+ setSessionCookie: () => undefined,
+ tooManyLoginAttempts: () => new Response(null, { status: 429 }),
+ verifyLogin: async () => null,
+ ...overrides,
+ });
+ return app;
+};
+
+describe("auth route contracts", () => {
+ test("reports the local owner when authentication is disabled", async () => {
+ const app = createApp({
+ getInstanceAuthMode: async () => "disabled",
+ isDemoEnvironment: () => true,
+ });
+ const response = await app.request("/api/v1/auth/session", {}, environment);
+
+ expect(response.status).toBe(200);
+ expect(await response.json()).toEqual({
+ authRequired: false,
+ authenticated: true,
+ demoMode: true,
+ user: {
+ id: "local",
+ username: "owner",
+ displayName: "Owner",
+ role: "owner",
+ },
+ });
+ });
+
+ test("reports an anonymous required-auth session without touching storage", async () => {
+ const app = createApp();
+ const response = await app.request("/api/v1/auth/session", {}, environment);
+
+ expect(response.status).toBe(200);
+ expect(await response.json()).toMatchObject({
+ authRequired: true,
+ authenticated: false,
+ user: null,
+ });
+ });
+
+ test("does not allow the current session to revoke itself", async () => {
+ const app = createApp({ authenticateRequest: async () => interactiveAuth });
+ const response = await app.request(
+ "/api/v1/auth/sessions/session_current",
+ { method: "DELETE" },
+ environment,
+ );
+
+ expect(response.status).toBe(400);
+ expect(await response.json()).toMatchObject({
+ error: { code: "current_session_cannot_be_revoked" },
+ });
+ });
+});
diff --git a/apps/api/src/auth-routes.ts b/apps/api/src/auth-routes.ts
new file mode 100644
index 00000000..50b092db
--- /dev/null
+++ b/apps/api/src/auth-routes.ts
@@ -0,0 +1,347 @@
+import {
+ ChangePasswordSchema,
+ LoginDeviceSessionUpdateSchema,
+ LoginSchema,
+} from "@edgeever/shared";
+import { zValidator } from "@hono/zod-validator";
+import type { Hono } from "hono";
+import { deleteCookie, getCookie } from "hono/cookie";
+import { audit, auditStatement } from "./audit";
+import {
+ checkLoginRateLimit,
+ clearLoginAttempts,
+ recordLoginFailure,
+ resolveLoginRateLimitConfig,
+ type LoginAttemptKey,
+} from "./auth-login-limiter";
+import {
+ groupLoginDeviceSessions,
+ type LoginDeviceSessionRow,
+} from "./auth-session-devices";
+import type {
+ AppContext,
+ AppEnv,
+ AuthContext,
+ Bindings,
+} from "./api-context";
+import { hashPassword, verifyPassword } from "./auth-crypto";
+import type { InstanceAuthMode } from "./auth-state";
+import { isoNow } from "./entity-utils";
+import {
+ apiError,
+ authNotConfigured,
+ forbidden,
+ notFound,
+ unauthorized,
+} from "./http-errors";
+import type { DatabaseAdapter } from "./storage-contract";
+
+export type UserRow = {
+ id: string;
+ username: string;
+ password_hash: string;
+ display_name: string | null;
+ is_disabled: number;
+};
+
+type LoginSession = {
+ id: string;
+ token: string;
+ maxAge: number;
+};
+
+type UserWorkspace = {
+ workspaceId: string;
+ role: "owner" | "member";
+};
+
+type AuthRouteDependencies = {
+ authenticateRequest: (context: AppContext, touch: boolean) => Promise<AuthContext | null>;
+ authenticateSession: (context: AppContext, touch: boolean) => Promise<AuthContext | null>;
+ createSession: (context: AppContext, user: UserRow, requestedDeviceId?: string) => Promise<LoginSession>;
+ ensureUserWorkspace: (database: DatabaseAdapter, userId: string, username: string) => Promise<UserWorkspace>;
+ getBearerToken: (context: AppContext) => string | null;
+ getInstanceAuthMode: (environment: Bindings) => Promise<InstanceAuthMode>;
+ getLoginAttemptKeys: (context: AppContext, username: string) => Promise<LoginAttemptKey[]>;
+ isDemoEnvironment: (environment: Bindings) => boolean;
+ isDemoMode: (environment: Bindings) => boolean;
+ revokeSession: (database: DatabaseAdapter, token: string) => Promise<void>;
+ setSessionCookie: (context: AppContext, token: string, maxAge: number) => void;
+ tooManyLoginAttempts: (context: AppContext, retryAfterSeconds: number) => Response;
+ verifyLogin: (environment: Bindings, username: string, password: string) => Promise<UserRow | null>;
+};
+
+type InteractiveAuthContext = AuthContext & {
+ actorId: string;
+ sessionId: string;
+};
+
+const requireInteractiveSession = async (
+ context: AppContext,
+ authenticate: AuthRouteDependencies["authenticateRequest"],
+): Promise<InteractiveAuthContext | null> => {
+ const auth = await authenticate(context, true);
+ if (auth?.kind !== "user" || !auth.actorId || !auth.sessionId) return null;
+ return { ...auth, actorId: auth.actorId, sessionId: auth.sessionId };
+};
+
+export const registerAuthRoutes = (
+ app: Hono<AppEnv>,
+ dependencies: AuthRouteDependencies,
+) => {
+ app.get("/api/v1/auth/session", async (context) => {
+ const authMode = await dependencies.getInstanceAuthMode(context.env);
+
+ if (authMode === "unconfigured") return authNotConfigured(context);
+ if (authMode === "disabled") {
+ return context.json({
+ authRequired: false,
+ authenticated: true,
+ demoMode: dependencies.isDemoEnvironment(context.env),
+ user: {
+ id: "local",
+ username: "owner",
+ displayName: "Owner",
+ role: "owner",
+ },
+ });
+ }
+
+ const auth = await dependencies.authenticateRequest(context, false);
+ return context.json({
+ authRequired: true,
+ authenticated: Boolean(auth && auth.kind === "user"),
+ demoMode: dependencies.isDemoEnvironment(context.env),
+ user: auth?.kind === "user" ? {
+ id: auth.actorId,
+ username: auth.username,
+ displayName: auth.displayName,
+ role: auth.role,
+ } : null,
+ });
+ });
+
+ app.get("/api/v1/auth/sessions", async (context) => {
+ const auth = await requireInteractiveSession(context, dependencies.authenticateRequest);
+ if (!auth) return unauthorized(context, "An interactive user session is required.");
+
+ const now = isoNow();
+ const rows = await context.env.storage.db.prepare(
+ `SELECT id, device_id, user_agent, device_label, ip_address, ip_country, ip_region, expires_at, created_at, last_seen_at
+ FROM sessions
+ WHERE user_id = ?
+ AND revoked_at IS NULL
+ AND expires_at > ?
+ ORDER BY COALESCE(last_seen_at, created_at) DESC
+ LIMIT 200`,
+ ).bind(auth.actorId, now).all<LoginDeviceSessionRow>();
+
+ return context.json({
+ sessions: groupLoginDeviceSessions(rows.results, auth.sessionId).slice(0, 50),
+ });
+ });
+
+ app.patch(
+ "/api/v1/auth/sessions/:sessionId",
+ zValidator("json", LoginDeviceSessionUpdateSchema),
+ async (context) => {
+ const auth = await requireInteractiveSession(context, dependencies.authenticateRequest);
+ if (!auth) return unauthorized(context, "An interactive user session is required.");
+
+ const sessionId = context.req.param("sessionId");
+ const input = context.req.valid("json");
+ const now = isoNow();
+ const session = await context.env.storage.db.prepare(
+ `SELECT id, device_id FROM sessions
+ WHERE id = ? AND user_id = ? AND revoked_at IS NULL AND expires_at > ?`,
+ ).bind(sessionId, auth.actorId, now).first<{ id: string; device_id: string | null }>();
+
+ if (!session) return notFound(context, "Login session not found.");
+
+ const statement = session.device_id
+ ? context.env.storage.db.prepare(
+ `UPDATE sessions SET device_label = ?
+ WHERE user_id = ? AND device_id = ? AND revoked_at IS NULL`,
+ ).bind(input.label || null, auth.actorId, session.device_id)
+ : context.env.storage.db.prepare(
+ `UPDATE sessions SET device_label = ? WHERE id = ?`,
+ ).bind(input.label || null, session.id);
+
+ await context.env.storage.db.batch([
+ statement,
+ auditStatement(context.env.storage.db, "user", auth.actorId, "auth.session_label_update", "session", session.id, {
+ label: input.label || null,
+ }),
+ ]);
+ return context.json({ ok: true });
+ },
+ );
+
+ app.delete("/api/v1/auth/sessions", async (context) => {
+ const auth = await requireInteractiveSession(context, dependencies.authenticateRequest);
+ if (!auth) return unauthorized(context, "An interactive user session is required.");
+
+ const now = isoNow();
+ await context.env.storage.db.batch([
+ context.env.storage.db.prepare(
+ `UPDATE sessions
+ SET revoked_at = ?
+ WHERE user_id = ? AND id != ? AND revoked_at IS NULL AND expires_at > ?`,
+ ).bind(now, auth.actorId, auth.sessionId, now),
+ auditStatement(context.env.storage.db, "user", auth.actorId, "auth.sessions_revoke_others", "session", auth.sessionId, {}),
+ ]);
+ return context.json({ ok: true });
+ });
+
+ app.delete("/api/v1/auth/sessions/:sessionId", async (context) => {
+ const auth = await requireInteractiveSession(context, dependencies.authenticateRequest);
+ if (!auth) return unauthorized(context, "An interactive user session is required.");
+
+ const sessionId = context.req.param("sessionId");
+ if (sessionId === auth.sessionId) {
+ return apiError(context, "current_session_cannot_be_revoked", "The current session cannot be revoked here.", 400);
+ }
+
+ const now = isoNow();
+ const session = await context.env.storage.db.prepare(
+ `SELECT id, device_id FROM sessions
+ WHERE id = ? AND user_id = ? AND revoked_at IS NULL AND expires_at > ?`,
+ ).bind(sessionId, auth.actorId, now).first<{ id: string; device_id: string | null }>();
+ if (!session) return notFound(context, "Login session not found.");
+
+ const currentSession = await context.env.storage.db.prepare(
+ `SELECT device_id FROM sessions WHERE id = ? AND user_id = ?`,
+ ).bind(auth.sessionId, auth.actorId).first<{ device_id: string | null }>();
+ if (session.device_id && currentSession?.device_id === session.device_id) {
+ return apiError(context, "current_session_cannot_be_revoked", "The current device cannot be revoked here.", 400);
+ }
+
+ await context.env.storage.db.batch([
+ session.device_id
+ ? context.env.storage.db.prepare(
+ `UPDATE sessions SET revoked_at = ?
+ WHERE user_id = ? AND device_id = ? AND revoked_at IS NULL`,
+ ).bind(now, auth.actorId, session.device_id)
+ : context.env.storage.db.prepare(
+ `UPDATE sessions SET revoked_at = ? WHERE id = ? AND revoked_at IS NULL`,
+ ).bind(now, session.id),
+ auditStatement(context.env.storage.db, "user", auth.actorId, "auth.session_revoke", "session", session.id, {}),
+ ]);
+ return context.json({ ok: true });
+ });
+
+ app.post("/api/v1/auth/login", zValidator("json", LoginSchema), async (context) => {
+ const authMode = await dependencies.getInstanceAuthMode(context.env);
+ if (authMode === "unconfigured") return authNotConfigured(context);
+
+ const input = context.req.valid("json");
+ const loginAttemptKeys = await dependencies.getLoginAttemptKeys(context, input.username);
+ const rateLimitConfig = resolveLoginRateLimitConfig(context.env);
+ const currentRateLimit = await checkLoginRateLimit(
+ context.env.storage.db,
+ loginAttemptKeys,
+ rateLimitConfig,
+ );
+ if (currentRateLimit.retryAfterSeconds > 0) {
+ return dependencies.tooManyLoginAttempts(context, currentRateLimit.retryAfterSeconds);
+ }
+
+ const user = await dependencies.verifyLogin(context.env, input.username, input.password);
+ if (!user) {
+ const updatedRateLimit = await recordLoginFailure(
+ context.env.storage.db,
+ loginAttemptKeys,
+ rateLimitConfig,
+ );
+ if (updatedRateLimit.retryAfterSeconds > 0) {
+ await audit(
+ context.env.storage.db,
+ "system",
+ null,
+ "auth.login_rate_limited",
+ "auth",
+ loginAttemptKeys[0]?.key ?? "unknown",
+ { retryAfterSeconds: updatedRateLimit.retryAfterSeconds },
+ );
+ return dependencies.tooManyLoginAttempts(context, updatedRateLimit.retryAfterSeconds);
+ }
+ return unauthorized(context, "Username or password is incorrect.");
+ }
+
+ await clearLoginAttempts(context.env.storage.db, loginAttemptKeys);
+ const workspace = await dependencies.ensureUserWorkspace(
+ context.env.storage.db,
+ user.id,
+ user.username,
+ );
+ const session = await dependencies.createSession(context, user, input.deviceId);
+ dependencies.setSessionCookie(context, session.token, session.maxAge);
+
+ const now = isoNow();
+ await context.env.storage.db.batch([
+ context.env.storage.db.prepare(
+ `UPDATE users SET last_login_at = ?, updated_at = ? WHERE id = ?`,
+ ).bind(now, now, user.id),
+ auditStatement(context.env.storage.db, "user", user.id, "auth.login", "session", session.id, {
+ username: user.username,
+ }),
+ ]);
+
+ return context.json({
+ authRequired: true,
+ authenticated: true,
+ demoMode: dependencies.isDemoEnvironment(context.env),
+ sessionToken: session.token,
+ user: {
+ id: user.id,
+ username: user.username,
+ displayName: user.display_name,
+ role: workspace.role,
+ },
+ });
+ });
+
+ app.post(
+ "/api/v1/auth/change-password",
+ zValidator("json", ChangePasswordSchema),
+ async (context) => {
+ const auth = await requireInteractiveSession(context, dependencies.authenticateSession);
+ if (!auth) return unauthorized(context, "An interactive user session is required.");
+ if (dependencies.isDemoMode(context.env)) {
+ return forbidden(context, "The demo environment does not allow changing login passwords.");
+ }
+
+ const input = context.req.valid("json");
+ const user = await context.env.storage.db.prepare(
+ `SELECT id, username, password_hash, display_name, is_disabled
+ FROM users
+ WHERE id = ? AND is_disabled = 0`,
+ ).bind(auth.actorId).first<UserRow>();
+ if (!user || !(await verifyPassword(input.currentPassword, user.password_hash))) {
+ return apiError(context, "invalid_current_password", "Current password is incorrect.", 400);
+ }
+
+ const now = isoNow();
+ const passwordHash = await hashPassword(input.newPassword);
+ await context.env.storage.db.batch([
+ context.env.storage.db.prepare(
+ `UPDATE users SET password_hash = ?, updated_at = ? WHERE id = ?`,
+ ).bind(passwordHash, now, user.id),
+ context.env.storage.db.prepare(
+ `UPDATE sessions SET revoked_at = ?
+ WHERE user_id = ? AND id != ? AND revoked_at IS NULL`,
+ ).bind(now, user.id, auth.sessionId),
+ auditStatement(context.env.storage.db, "user", user.id, "auth.password_change", "user", user.id, {}),
+ ]);
+ return context.json({ ok: true });
+ },
+ );
+
+ app.post("/api/v1/auth/logout", async (context) => {
+ const token = getCookie(context, "edgeever_session") ?? dependencies.getBearerToken(context);
+ if (token) await dependencies.revokeSession(context.env.storage.db, token);
+
+ deleteCookie(context, "edgeever_session", { path: "/" });
+ return context.json({ ok: true });
+ });
+};
diff --git a/apps/api/src/index.ts b/apps/api/src/index.ts
index f56e79fe..233ce635 100644
--- a/apps/api/src/index.ts
+++ b/apps/api/src/index.ts
@@ -5,10 +5,7 @@ import {
docToText,
emptyDoc,
ApiTokenCreateSchema,
- ChangePasswordSchema,
DeleteMemosSchema,
- LoginSchema,
- LoginDeviceSessionUpdateSchema,
markdownToDoc,
mergeMemoDocs,
resolveMemoContentDoc,
@@ -21,11 +18,8 @@ import {
MergeMemosSchema,
MoveMemosSchema,
normalizeTags,
- UserCreateSchema,
- UserUpdateSchema,
RestoreJsonMemosSchema,
RestoreJsonNotebooksSchema,
- ResourceUpdateSchema,
ObjectStorageConnectionTestSchema,
ObjectStorageSettingsUpdateSchema,
type ApiToken,
@@ -40,15 +34,12 @@ import {
type JsonBackupResource,
type JsonBackupRevision,
type Resource,
- type ResourceListItem,
- type ResourceStorageSummary,
type TiptapDoc,
- type InstanceUser,
} from "@edgeever/shared";
import { zValidator } from "@hono/zod-validator";
import type { Context } from "hono";
import { Hono } from "hono";
-import { deleteCookie, getCookie, setCookie } from "hono/cookie";
+import { getCookie, setCookie } from "hono/cookie";
import { cors } from "hono/cors";
import openApiSpec from "../../../docs/openapi.json";
import packageMetadata from "../../../package.json";
@@ -61,20 +52,13 @@ import {
} from "./auth-state";
import {
isDemoModeEnabled,
- isProtectedDemoAccount,
resolveDemoPasswordHash,
shouldUpsertDemoSeedRecord,
} from "./demo-mode";
import {
- groupLoginDeviceSessions,
resolveSessionDeviceId,
- type LoginDeviceSessionRow,
} from "./auth-session-devices";
import {
- checkLoginRateLimit,
- clearLoginAttempts,
- recordLoginFailure,
- resolveLoginRateLimitConfig,
type LoginAttemptKey,
} from "./auth-login-limiter";
import {
@@ -155,6 +139,12 @@ import {
} from "./request-auth";
import { registerTagRoutes } from "./tag-routes";
import { registerTemplateRoutes } from "./template-routes";
+import { registerAuthRoutes, type UserRow } from "./auth-routes";
+import { registerResourceRoutes } from "./resource-routes";
+import {
+ registerUserRoutes,
+ type InstanceUserRow,
+} from "./user-routes";
import { registerNotebookRoutes } from "./notebook-routes";
import { registerMemoShareRoutes, registerPublicShareRoutes } from "./share-routes";
import { decryptSecret, encryptSecret } from "./secret-encryption";
@@ -169,6 +159,21 @@ import {
resolveObjectStorage,
} from "./object-storage";
import { testWorkerS3Connection } from "./worker-s3-blob-store";
+import {
+ MAX_ATTACHMENT_UPLOAD_BYTES,
+ MAX_IMAGE_UPLOAD_BYTES,
+ inferImageExtension,
+ mapResource,
+ mapResourceListItem,
+ mapResourceStorageSummary,
+ normalizeFilename,
+ prepareImageForStorage,
+ validateAttachmentUpload,
+ validateImageUpload,
+ type ResourceListRow,
+ type ResourceRow,
+ type ResourceStatsRow,
+} from "./resource-service";
// Compatibility aliases keep the existing SQL-heavy implementation small
// while routing its dependency through the platform-neutral contract above.
@@ -249,20 +254,6 @@ type MemoEditSessionRow = {
expires_at: string;
};
-type UserRow = {
- id: string;
- username: string;
- password_hash: string;
- display_name: string | null;
- is_disabled: number;
-};
-
-type InstanceUserRow = UserRow & {
- last_login_at: string | null;
- created_at: string;
- role: "owner" | "member";
-};
-
type SessionRow = {
id: string;
user_id: string;
@@ -299,37 +290,6 @@ type MemoImportSourceRow = {
source_updated_at: string | null;
};
-type ResourceRow = {
- id: string;
- memo_id: string;
- original_memo_id: string | null;
- bucket_name: string;
- object_key: string;
- storage_config_id: string;
- kind: "image" | "attachment";
- mime_type: string | null;
- filename: string | null;
- byte_size: number;
- sha256: string | null;
- width: number | null;
- height: number | null;
- created_at: string;
- updated_at: string;
-};
-
-type ResourceListRow = ResourceRow & {
- memo_title: string | null;
- memo_excerpt: string | null;
- memo_is_deleted: number | null;
-};
-
-type ResourceStatsRow = {
- total_count: number;
- total_bytes: number;
- image_count: number;
- attachment_count: number;
-};
-
const SESSION_COOKIE = "edgeever_session";
const DEFAULT_WORKSPACE_ID = "ws_default";
const DEFAULT_MEMO_LIST_LIMIT = 100;
@@ -337,19 +297,9 @@ const MAX_MEMO_LIST_LIMIT = 200;
const DEFAULT_SESSION_TTL_DAYS = 400;
const MAX_SESSION_TTL_DAYS = 400;
const DEFAULT_R2_BUCKET_NAME = "edgeever-resources";
-const MAX_IMAGE_UPLOAD_BYTES = 100 * 1024 * 1024;
-const MAX_ATTACHMENT_UPLOAD_BYTES = 100 * 1024 * 1024;
const REVISION_SNAPSHOT_INTERVAL_MS = 5 * 60 * 1000;
const API_TOKEN_BYTES = 32;
const API_TOKEN_PREFIX = "eev";
-const SUPPORTED_IMAGE_MIME_TYPES = new Set([
- "image/png",
- "image/jpeg",
- "image/gif",
- "image/webp",
- "image/avif",
-]);
-
const app = new Hono<AppEnv>();
app.use(
@@ -391,401 +341,25 @@ app.get("/api/openapi.json", (c) => c.json(openApiSpec));
registerPublicShareRoutes(app);
-app.get("/api/v1/auth/session", async (c) => {
- const authMode = await getInstanceAuthMode(c.env);
-
- if (authMode === "unconfigured") {
- return authNotConfigured(c);
- }
-
- if (authMode === "disabled") {
- return c.json({
- authRequired: false,
- authenticated: true,
- demoMode: isDemoMode(c.env) || isLocalDemoSeedEnabled(c.env),
- user: {
- id: "local",
- username: "owner",
- displayName: "Owner",
- role: "owner",
- },
- });
- }
-
- const auth = await authenticateRequest(c, false);
-
- return c.json({
- authRequired: true,
- authenticated: Boolean(auth && auth.kind === "user"),
- demoMode: isDemoMode(c.env) || isLocalDemoSeedEnabled(c.env),
- user:
- auth && auth.kind === "user"
- ? {
- id: auth.actorId,
- username: auth.username,
- displayName: auth.displayName,
- role: auth.role,
- }
- : null,
- });
+registerAuthRoutes(app, {
+ authenticateRequest: (...args) => authenticateRequest(...args),
+ authenticateSession: (...args) => authenticateSession(...args),
+ createSession: (...args) => createSession(...args),
+ ensureUserWorkspace: (...args) => ensureUserWorkspace(...args),
+ getBearerToken: (...args) => getBearerToken(...args),
+ getInstanceAuthMode: (...args) => getInstanceAuthMode(...args),
+ getLoginAttemptKeys: (...args) => getLoginAttemptKeys(...args),
+ isDemoEnvironment: (environment) => isDemoMode(environment) || isLocalDemoSeedEnabled(environment),
+ isDemoMode: (...args) => isDemoMode(...args),
+ revokeSession: (...args) => revokeSession(...args),
+ setSessionCookie: (...args) => setSessionCookie(...args),
+ tooManyLoginAttempts: (...args) => tooManyLoginAttempts(...args),
+ verifyLogin: (...args) => verifyLogin(...args),
});
-
-app.get("/api/v1/auth/sessions", async (c) => {
- const auth = await authenticateRequest(c, true);
-
- if (!auth || auth.kind !== "user" || !auth.actorId || !auth.sessionId) {
- return unauthorized(c, "An interactive user session is required.");
- }
-
- const now = isoNow();
- const rows = await c.env.storage.db.prepare(
- `SELECT id, device_id, user_agent, device_label, ip_address, ip_country, ip_region, expires_at, created_at, last_seen_at
- FROM sessions
- WHERE user_id = ?
- AND revoked_at IS NULL
- AND expires_at > ?
- ORDER BY COALESCE(last_seen_at, created_at) DESC
- LIMIT 200`
- )
- .bind(auth.actorId, now)
- .all<LoginDeviceSessionRow>();
-
- return c.json({
- sessions: groupLoginDeviceSessions(rows.results, auth.sessionId).slice(0, 50),
- });
-});
-
-app.patch("/api/v1/auth/sessions/:sessionId", zValidator("json", LoginDeviceSessionUpdateSchema), async (c) => {
- const auth = await authenticateRequest(c, true);
-
- if (!auth || auth.kind !== "user" || !auth.actorId || !auth.sessionId) {
- return unauthorized(c, "An interactive user session is required.");
- }
-
- const sessionId = c.req.param("sessionId");
- const input = c.req.valid("json");
- const now = isoNow();
- const session = await c.env.storage.db.prepare(
- `SELECT id, device_id FROM sessions
- WHERE id = ? AND user_id = ? AND revoked_at IS NULL AND expires_at > ?`
- ).bind(sessionId, auth.actorId, now).first<{ id: string; device_id: string | null }>();
-
- if (!session) return notFound(c, "Login session not found.");
-
- const statement = session.device_id
- ? c.env.storage.db.prepare(
- `UPDATE sessions SET device_label = ?
- WHERE user_id = ? AND device_id = ? AND revoked_at IS NULL`
- ).bind(input.label || null, auth.actorId, session.device_id)
- : c.env.storage.db.prepare(`UPDATE sessions SET device_label = ? WHERE id = ?`).bind(input.label || null, session.id);
-
- await c.env.storage.db.batch([
- statement,
- auditStatement(c.env.storage.db, "user", auth.actorId, "auth.session_label_update", "session", session.id, {
- label: input.label || null,
- }),
- ]);
-
- return c.json({ ok: true });
-});
-
-app.delete("/api/v1/auth/sessions", async (c) => {
- const auth = await authenticateRequest(c, true);
-
- if (!auth || auth.kind !== "user" || !auth.actorId || !auth.sessionId) {
- return unauthorized(c, "An interactive user session is required.");
- }
-
- const now = isoNow();
- await c.env.storage.db.batch([
- c.env.storage.db.prepare(
- `UPDATE sessions
- SET revoked_at = ?
- WHERE user_id = ? AND id != ? AND revoked_at IS NULL AND expires_at > ?`
- ).bind(now, auth.actorId, auth.sessionId, now),
- auditStatement(c.env.storage.db, "user", auth.actorId, "auth.sessions_revoke_others", "session", auth.sessionId, {}),
- ]);
-
- return c.json({ ok: true });
-});
-
-app.delete("/api/v1/auth/sessions/:sessionId", async (c) => {
- const auth = await authenticateRequest(c, true);
-
- if (!auth || auth.kind !== "user" || !auth.actorId || !auth.sessionId) {
- return unauthorized(c, "An interactive user session is required.");
- }
-
- const sessionId = c.req.param("sessionId");
- if (sessionId === auth.sessionId) {
- return apiError(c, "current_session_cannot_be_revoked", "The current session cannot be revoked here.", 400);
- }
-
- const now = isoNow();
- const session = await c.env.storage.db.prepare(
- `SELECT id, device_id FROM sessions
- WHERE id = ? AND user_id = ? AND revoked_at IS NULL AND expires_at > ?`
- )
- .bind(sessionId, auth.actorId, now)
- .first<{ id: string; device_id: string | null }>();
-
- if (!session) {
- return notFound(c, "Login session not found.");
- }
-
- const currentSession = await c.env.storage.db.prepare(`SELECT device_id FROM sessions WHERE id = ? AND user_id = ?`)
- .bind(auth.sessionId, auth.actorId)
- .first<{ device_id: string | null }>();
-
- if (session.device_id && currentSession?.device_id === session.device_id) {
- return apiError(c, "current_session_cannot_be_revoked", "The current device cannot be revoked here.", 400);
- }
-
- await c.env.storage.db.batch([
- session.device_id
- ? c.env.storage.db.prepare(
- `UPDATE sessions SET revoked_at = ?
- WHERE user_id = ? AND device_id = ? AND revoked_at IS NULL`
- ).bind(now, auth.actorId, session.device_id)
- : c.env.storage.db.prepare(`UPDATE sessions SET revoked_at = ? WHERE id = ? AND revoked_at IS NULL`).bind(now, session.id),
- auditStatement(c.env.storage.db, "user", auth.actorId, "auth.session_revoke", "session", session.id, {}),
- ]);
-
- return c.json({ ok: true });
-});
-
-app.post("/api/v1/auth/login", zValidator("json", LoginSchema), async (c) => {
- const authMode = await getInstanceAuthMode(c.env);
- if (authMode === "unconfigured") {
- return authNotConfigured(c);
- }
-
- const input = c.req.valid("json");
- const loginAttemptKeys = await getLoginAttemptKeys(c, input.username);
- const loginRateLimitConfig = resolveLoginRateLimitConfig(c.env);
- const currentRateLimit = await checkLoginRateLimit(c.env.storage.db, loginAttemptKeys, loginRateLimitConfig);
-
- if (currentRateLimit.retryAfterSeconds > 0) {
- return tooManyLoginAttempts(c, currentRateLimit.retryAfterSeconds);
- }
-
- const user = await verifyLogin(c.env, input.username, input.password);
-
- if (!user) {
- const updatedRateLimit = await recordLoginFailure(
- c.env.storage.db,
- loginAttemptKeys,
- loginRateLimitConfig,
- );
-
- if (updatedRateLimit.retryAfterSeconds > 0) {
- await audit(
- c.env.storage.db,
- "system",
- null,
- "auth.login_rate_limited",
- "auth",
- loginAttemptKeys[0]?.key ?? "unknown",
- { retryAfterSeconds: updatedRateLimit.retryAfterSeconds },
- );
- return tooManyLoginAttempts(c, updatedRateLimit.retryAfterSeconds);
- }
-
- return unauthorized(c, "Username or password is incorrect.");
- }
-
- await clearLoginAttempts(c.env.storage.db, loginAttemptKeys);
-
- const workspace = await ensureUserWorkspace(c.env.storage.db, user.id, user.username);
- const session = await createSession(c, user, input.deviceId);
- setSessionCookie(c, session.token, session.maxAge);
-
- await c.env.storage.db.batch([
- c.env.storage.db.prepare(`UPDATE users SET last_login_at = ?, updated_at = ? WHERE id = ?`).bind(
- isoNow(),
- isoNow(),
- user.id
- ),
- auditStatement(c.env.storage.db, "user", user.id, "auth.login", "session", session.id, {
- username: user.username,
- }),
- ]);
-
- return c.json({
- authRequired: true,
- authenticated: true,
- demoMode: isDemoMode(c.env) || isLocalDemoSeedEnabled(c.env),
- sessionToken: session.token,
- user: {
- id: user.id,
- username: user.username,
- displayName: user.display_name,
- role: workspace.role,
- },
- });
-});
-
-app.post("/api/v1/auth/change-password", zValidator("json", ChangePasswordSchema), async (c) => {
- const auth = await authenticateSession(c, true);
-
- if (!auth || auth.kind !== "user" || !auth.actorId || !auth.sessionId) {
- return unauthorized(c, "An interactive user session is required.");
- }
-
- if (isDemoMode(c.env)) {
- return forbidden(c, "The demo environment does not allow changing login passwords.");
- }
-
- const input = c.req.valid("json");
- const user = await c.env.storage.db.prepare(
- `SELECT id, username, password_hash, display_name, is_disabled
- FROM users
- WHERE id = ? AND is_disabled = 0`
- )
- .bind(auth.actorId)
- .first<UserRow>();
-
- if (!user || !(await verifyPassword(input.currentPassword, user.password_hash))) {
- return apiError(c, "invalid_current_password", "Current password is incorrect.", 400);
- }
-
- const now = isoNow();
- const passwordHash = await hashPassword(input.newPassword);
-
- await c.env.storage.db.batch([
- c.env.storage.db.prepare(`UPDATE users SET password_hash = ?, updated_at = ? WHERE id = ?`).bind(
- passwordHash,
- now,
- user.id
- ),
- c.env.storage.db.prepare(
- `UPDATE sessions SET revoked_at = ?
- WHERE user_id = ? AND id != ? AND revoked_at IS NULL`
- ).bind(now, user.id, auth.sessionId),
- auditStatement(c.env.storage.db, "user", user.id, "auth.password_change", "user", user.id, {}),
- ]);
-
- return c.json({ ok: true });
-});
-
-app.get("/api/v1/users", async (c) => {
- const auth = await authenticateRequest(c, true);
- if (!auth) return unauthorized(c, "Authentication required.");
- c.set("auth", auth);
- const denied = requireOwner(c);
- if (denied) return denied;
-
- const rows = await c.env.storage.db.prepare(
- `SELECT u.id, u.username, u.password_hash, u.display_name, u.is_disabled,
- u.last_login_at, u.created_at, wm.role
- FROM users u
- INNER JOIN workspace_members wm ON wm.user_id = u.id
- ORDER BY wm.role = 'owner' DESC, u.created_at ASC`
- ).all<InstanceUserRow>();
-
- return c.json({ users: rows.results.map(mapInstanceUser) });
-});
-
-app.post("/api/v1/users", zValidator("json", UserCreateSchema), async (c) => {
- const auth = await authenticateRequest(c, true);
- if (!auth) return unauthorized(c, "Authentication required.");
- c.set("auth", auth);
- const denied = requireOwner(c);
- if (denied) return denied;
-
- const input = c.req.valid("json");
- const existing = await c.env.storage.db.prepare(`SELECT id FROM users WHERE username = ?`).bind(input.username).first();
- if (existing) return conflict(c, "username_exists", "Username already exists.");
-
- const userId = createId("usr");
- const workspaceId = createId("ws");
- const now = isoNow();
- const passwordHash = await hashPassword(input.password);
- const notebooks = createDefaultNotebookRows(workspaceId, now);
- const statements = [
- c.env.storage.db.prepare(
- `INSERT INTO users (id, username, password_hash, display_name, created_at, updated_at)
- VALUES (?, ?, ?, ?, ?, ?)`
- ).bind(userId, input.username, passwordHash, input.displayName ?? input.username, now, now),
- c.env.storage.db.prepare(`INSERT INTO workspaces (id, name, is_personal, created_at, updated_at) VALUES (?, ?, 1, ?, ?)`)
- .bind(workspaceId, `${input.displayName ?? input.username}'s workspace`, now, now),
- c.env.storage.db.prepare(`INSERT INTO workspace_members (workspace_id, user_id, role, created_at) VALUES (?, ?, 'member', ?)`)
- .bind(workspaceId, userId, now),
- ...notebooks.map((notebook) => c.env.storage.db.prepare(
- `INSERT INTO notebooks (id, workspace_id, parent_id, name, slug, icon, color, sort_order, created_at, updated_at)
- VALUES (?, ?, NULL, ?, ?, 'notebook', ?, ?, ?, ?)`
- ).bind(notebook.id, workspaceId, notebook.name, notebook.slug, notebook.color, notebook.sortOrder, now, now)),
- auditStatement(c.env.storage.db, "user", c.get("auth").actorId, "user.create", "user", userId, { username: input.username }),
- ];
- await c.env.storage.db.batch(statements);
-
- const user = await getInstanceUser(c.env.storage.db, userId);
- return c.json({ user: user ? mapInstanceUser(user) : null }, 201);
-});
-
-app.patch("/api/v1/users/:id", zValidator("json", UserUpdateSchema), async (c) => {
- const auth = await authenticateRequest(c, true);
- if (!auth) return unauthorized(c, "Authentication required.");
- c.set("auth", auth);
- const denied = requireOwner(c);
- if (denied) return denied;
-
- const userId = c.req.param("id");
- const input = c.req.valid("json");
- const current = await getInstanceUser(c.env.storage.db, userId);
- if (!current) return notFound(c, "User not found");
- if (
- isProtectedDemoAccount(c.env.EDGE_EVER_DEMO_MODE, c.env.EDGE_EVER_AUTH_USERNAME, current.username)
- && (input.password !== undefined || input.isDisabled !== undefined)
- ) {
- return forbidden(c, "The demo owner account uses fixed credentials and cannot be modified.");
- }
- if (current.role === "owner" && input.isDisabled === true) {
- return badRequest(c, "The instance owner cannot be disabled.");
- }
-
- const updates: string[] = [];
- const binds: unknown[] = [];
- if (input.displayName !== undefined) {
- updates.push("display_name = ?");
- binds.push(input.displayName);
- }
- if (input.password !== undefined) {
- updates.push("password_hash = ?");
- binds.push(await hashPassword(input.password));
- }
- if (input.isDisabled !== undefined) {
- updates.push("is_disabled = ?");
- binds.push(input.isDisabled ? 1 : 0);
- }
- updates.push("updated_at = ?");
- binds.push(isoNow(), userId);
-
- const statements = [
- c.env.storage.db.prepare(`UPDATE users SET ${updates.join(", ")} WHERE id = ?`).bind(...binds),
- auditStatement(c.env.storage.db, "user", c.get("auth").actorId, "user.update", "user", userId, {
- passwordReset: input.password !== undefined,
- isDisabled: input.isDisabled,
- }),
- ];
- if (input.password !== undefined || input.isDisabled === true) {
- statements.push(c.env.storage.db.prepare(`UPDATE sessions SET revoked_at = ? WHERE user_id = ? AND revoked_at IS NULL`).bind(isoNow(), userId));
- }
- await c.env.storage.db.batch(statements);
-
- const user = await getInstanceUser(c.env.storage.db, userId);
- return c.json({ user: user ? mapInstanceUser(user) : null });
-});
-
-app.post("/api/v1/auth/logout", async (c) => {
- const token = getCookie(c, SESSION_COOKIE) ?? getBearerToken(c);
-
- if (token) {
- await revokeSession(c.env.storage.db, token);
- }
-
- deleteCookie(c, SESSION_COOKIE, { path: "/" });
- return c.json({ ok: true });
+registerUserRoutes(app, {
+ authenticateRequest: (...args) => authenticateRequest(...args),
+ createDefaultNotebookRows: (...args) => createDefaultNotebookRows(...args),
+ getInstanceUser: (...args) => getInstanceUser(...args),
});
app.use("/api/v1/*", async (c, next) => {
@@ -1904,97 +1478,12 @@ app.put("/api/v1/restores/json/resources/:id", async (c) => {
return c.json({ ok: true });
});
-app.get("/api/v1/resources", async (c) => {
- const denied = requireScopes(c, "read:resources");
-
- if (denied) {
- return denied;
- }
-
- const limit = clampNumber(Number(c.req.query("limit") ?? 500), 1, 500);
- const [rows, stats] = await Promise.all([
- c.env.storage.db.prepare(
- `SELECT r.id, r.memo_id, r.original_memo_id, r.bucket_name, r.object_key, r.storage_config_id, r.kind,
- r.mime_type, r.filename, r.byte_size, r.sha256, r.width, r.height,
- r.created_at, r.updated_at, m.title AS memo_title, m.excerpt AS memo_excerpt,
- m.is_deleted AS memo_is_deleted
- FROM resources r
- INNER JOIN memos m ON m.id = r.memo_id
- WHERE m.workspace_id = ? AND r.is_deleted = 0
- ORDER BY r.created_at DESC
- LIMIT ?`
- )
- .bind(getWorkspaceId(c), limit)
- .all<ResourceListRow>(),
- c.env.storage.db.prepare(
- `SELECT COUNT(*) AS total_count,
- COALESCE(SUM(byte_size), 0) AS total_bytes,
- COALESCE(SUM(CASE WHEN kind = 'image' THEN 1 ELSE 0 END), 0) AS image_count,
- COALESCE(SUM(CASE WHEN kind = 'attachment' THEN 1 ELSE 0 END), 0) AS attachment_count
- FROM resources r
- INNER JOIN memos m ON m.id = r.memo_id
- WHERE m.workspace_id = ? AND r.is_deleted = 0`
- ).bind(getWorkspaceId(c)).first<ResourceStatsRow>(),
- ]);
-
- return c.json({
- resources: rows.results.map(mapResourceListItem),
- summary: mapResourceStorageSummary(stats),
- });
-});
-
-app.post("/api/v1/memos/:id/resources", async (c) => {
- const denied = requireScopes(c, "write:resources");
-
- if (denied) {
- return denied;
- }
-
- const memoId = c.req.param("id");
- const memo = await getMemoDetail(c.env.storage.db, getWorkspaceId(c), memoId);
-
- if (!memo) {
- return notFound(c, "Memo not found");
- }
-
- const form = await c.req.raw.formData();
- const file = form.get("file");
-
- if (!(file instanceof File)) {
- return badRequest(c, "Expected multipart form field named file.");
- }
-
- const actor = getAuditActor(c);
- const bytes = new Uint8Array(await file.arrayBuffer());
- const mimeType = file.type || "application/octet-stream";
- let resource: Resource;
-
- try {
- resource = SUPPORTED_IMAGE_MIME_TYPES.has(mimeType)
- ? await createImageResource(c, {
- memoId,
- filename: file.name,
- mimeType,
- bytes,
- actor,
- source: "upload",
- })
- : await createAttachmentResource(c, {
- memoId,
- filename: file.name,
- mimeType,
- bytes,
- actor,
- });
- } catch (error) {
- if (error instanceof AppError) {
- return apiError(c, error.code, error.message, error.status);
- }
-
- throw error;
- }
-
- return c.json({ resource }, 201);
+registerResourceRoutes(app, {
+ clampNumber: (...args) => clampNumber(...args),
+ createAttachmentResource: (...args) => createAttachmentResource(...args),
+ createImageResource: (...args) => createImageResource(...args),
+ getMemoDetail: (...args) => getMemoDetail(...args),
+ getResourceRow: (...args) => getResourceRow(...args),
});
const createImageResource = async (
@@ -2151,161 +1640,6 @@ const createAttachmentResource = async (
return mapResource(resource);
};
-const validateImageUpload = (mimeType: string, size: number) => {
- if (!SUPPORTED_IMAGE_MIME_TYPES.has(mimeType)) {
- throw new AppError("unsupported_media_type", "Only PNG, JPEG, GIF, WebP and AVIF images are supported.", 415);
- }
-
- if (size <= 0 || size > MAX_IMAGE_UPLOAD_BYTES) {
- throw new AppError("upload_too_large", "Image must be between 1 byte and 50 MB.", 413);
- }
-};
-
-const validateAttachmentUpload = (size: number) => {
- if (size <= 0 || size > MAX_ATTACHMENT_UPLOAD_BYTES) {
- throw new AppError("upload_too_large", "Attachment must be between 1 byte and 100 MB.", 413);
- }
-};
-
-type PreparedImage = {
- bytes: Uint8Array;
- mimeType: string;
- filename: string;
- width: number | null;
- height: number | null;
- compressed: boolean;
- metadata: Record<string, unknown>;
-};
-
-const prepareImageForStorage = (input: {
- bytes: Uint8Array;
- filename: string;
- mimeType: string;
- source: "upload" | "mcp";
-}): PreparedImage => ({
- bytes: input.bytes,
- mimeType: input.mimeType,
- filename: input.filename,
- width: null,
- height: null,
- compressed: false,
- metadata: {
- source: input.source,
- originalFilename: normalizeFilename(input.filename) || null,
- originalMimeType: input.mimeType,
- originalByteSize: input.bytes.byteLength,
- compression: "disabled",
- },
-});
-
-app.get("/api/v1/resources/:id/blob", async (c) => {
- const denied = requireScopes(c, "read:resources");
-
- if (denied) {
- return denied;
- }
-
- const resource = await getResourceRow(c.env.storage.db, getWorkspaceId(c), c.req.param("id"));
-
- if (!resource) {
- return notFound(c, "Resource not found");
- }
-
- const source = await resolveObjectStorage(c.env, resource.storage_config_id);
- const object = await source.store.get(resource.object_key);
-
- if (!object) {
- return notFound(c, "Resource object not found");
- }
-
- const headers = new Headers();
- object.writeHttpMetadata(headers);
- headers.set("Content-Type", resource.mime_type ?? headers.get("Content-Type") ?? "application/octet-stream");
- headers.set("Cache-Control", headers.get("Cache-Control") ?? "private, max-age=3600");
- headers.set("Content-Length", String(object.size));
- headers.set(
- "Content-Disposition",
- resource.kind === "image"
- ? contentDispositionInline(resource.filename)
- : contentDispositionAttachment(resource.filename)
- );
- headers.set("X-Content-Type-Options", "nosniff");
-
- return new Response(object.body, { headers });
-});
-
-app.patch("/api/v1/resources/:id", zValidator("json", ResourceUpdateSchema), async (c) => {
- const denied = requireScopes(c, "write:resources");
-
- if (denied) {
- return denied;
- }
-
- const resourceId = c.req.param("id");
- const resource = await getResourceRow(c.env.storage.db, getWorkspaceId(c), resourceId);
-
- if (!resource) {
- return notFound(c, "Resource not found");
- }
-
- const filename = normalizeFilename(c.req.valid("json").filename);
- if (!filename) {
- return badRequest(c, "Resource filename is required.");
- }
-
- const now = isoNow();
- const actor = getAuditActor(c);
- await c.env.storage.db.batch([
- c.env.storage.db.prepare(
- `UPDATE resources SET filename = ?, updated_at = ? WHERE id = ?`
- ).bind(filename, now, resourceId),
- auditStatement(c.env.storage.db, actor.actorType, actor.actorId, "resource.rename", "resource", resourceId, {
- memoId: resource.memo_id,
- previousFilename: resource.filename,
- filename,
- }),
- ]);
-
- const updated = await getResourceRow(c.env.storage.db, getWorkspaceId(c), resourceId);
- if (!updated) {
- return notFound(c, "Resource not found");
- }
-
- return c.json({ resource: mapResource(updated) });
-});
-
-app.delete("/api/v1/resources/:id", async (c) => {
- const denied = requireScopes(c, "write:resources");
-
- if (denied) {
- return denied;
- }
-
- const resourceId = c.req.param("id");
- const resource = await getResourceRow(c.env.storage.db, getWorkspaceId(c), resourceId);
-
- if (!resource) {
- return notFound(c, "Resource not found");
- }
-
- const now = isoNow();
- const actor = getAuditActor(c);
- await c.env.storage.db.batch([
- c.env.storage.db.prepare(
- `UPDATE resources SET is_deleted = 1, deleted_at = ?, updated_at = ? WHERE id = ?`
- ).bind(now, now, resourceId),
- auditStatement(c.env.storage.db, actor.actorType, actor.actorId, "resource.delete", "resource", resourceId, {
- memoId: resource.memo_id,
- filename: resource.filename,
- byteSize: resource.byte_size,
- }),
- ]);
- const source = await resolveObjectStorage(c.env, resource.storage_config_id);
- await source.store.delete(resource.object_key);
-
- return c.json({ ok: true });
-});
-
app.post("/api/v1/demo/reset", async (c) => {
if (!isDemoMode(c.env) && !isLocalDemoSeedEnabled(c.env)) {
return c.json(
@@ -3433,16 +2767,6 @@ const getInstanceUser = (db: D1Database, userId: string) =>
WHERE u.id = ?`
).bind(userId).first<InstanceUserRow>();
-const mapInstanceUser = (row: InstanceUserRow): InstanceUser => ({
- id: row.id,
- username: row.username,
- displayName: row.display_name,
- role: row.role,
- isDisabled: Boolean(row.is_disabled),
- lastLoginAt: row.last_login_at,
- createdAt: row.created_at,
-});
-
const ensureUserWorkspace = async (db: D1Database, userId: string, username: string) => {
const existing = await db.prepare(
`SELECT workspace_id, role FROM workspace_members WHERE user_id = ? LIMIT 1`
@@ -3922,36 +3246,6 @@ const assertNotebookIdsInWorkspace = async (db: D1Database, workspaceId: string,
}
};
-const mapResource = (row: ResourceRow): Resource => ({
- id: row.id,
- memoId: row.memo_id,
- originalMemoId: row.original_memo_id,
- kind: row.kind,
- mimeType: row.mime_type,
- filename: row.filename,
- byteSize: row.byte_size,
- sha256: row.sha256,
- width: row.width,
- height: row.height,
- createdAt: row.created_at,
- updatedAt: row.updated_at,
- url: `/api/v1/resources/${row.id}/blob`,
-});
-
-const mapResourceListItem = (row: ResourceListRow): ResourceListItem => ({
- ...mapResource(row),
- memoTitle: row.memo_title,
- memoExcerpt: row.memo_excerpt,
- memoDeleted: Boolean(row.memo_is_deleted),
-});
-
-const mapResourceStorageSummary = (row: ResourceStatsRow | null): ResourceStorageSummary => ({
- totalCount: row?.total_count ?? 0,
- totalBytes: row?.total_bytes ?? 0,
- imageCount: row?.image_count ?? 0,
- attachmentCount: row?.attachment_count ?? 0,
-});
-
const mapApiToken = (row: ApiTokenRow): ApiToken => ({
id: row.id,
name: row.name,
@@ -5799,51 +5093,3 @@ const sha256Bytes = async (bytes: Uint8Array) => {
}
return hexString;
};
-
-const inferImageExtension = (filename: string, mimeType: string) => {
- const extension = /\.(png|jpe?g|gif|webp|avif)$/i.exec(filename)?.[0]?.toLowerCase();
-
- if (extension) {
- return extension === ".jpeg" ? ".jpg" : extension;
- }
-
- switch (mimeType) {
- case "image/png":
- return ".png";
- case "image/jpeg":
- return ".jpg";
- case "image/gif":
- return ".gif";
- case "image/webp":
- return ".webp";
- case "image/avif":
- return ".avif";
- default:
- return "";
- }
-};
-
-const normalizeFilename = (filename: string) =>
- filename
- .trim()
- .replace(/[\\/]/g, "-")
- .replace(/[\u0000-\u001f\u007f]/g, "")
- .slice(0, 160);
-
-const contentDispositionInline = (filename: string | null) => {
- if (!filename) {
- return "inline";
- }
-
- const fallback = normalizeFilename(filename).replace(/"/g, "'");
- return `inline; filename="${fallback}"; filename*=UTF-8''${encodeURIComponent(filename)}`;
-};
-
-const contentDispositionAttachment = (filename: string | null) => {
- if (!filename) {
- return "attachment";
- }
-
- const fallback = normalizeFilename(filename).replace(/"/g, "'");
- return `attachment; filename="${fallback}"; filename*=UTF-8''${encodeURIComponent(filename)}`;
-};
diff --git a/apps/api/src/resource-routes.test.mjs b/apps/api/src/resource-routes.test.mjs
new file mode 100644
index 00000000..8d4a0715
--- /dev/null
+++ b/apps/api/src/resource-routes.test.mjs
@@ -0,0 +1,108 @@
+import { describe, expect, test } from "bun:test";
+import { Hono } from "hono";
+import { registerResourceRoutes } from "./resource-routes.ts";
+
+const resourceRow = {
+ id: "res_1",
+ memo_id: "memo_1",
+ original_memo_id: null,
+ bucket_name: "resources",
+ object_key: "resource-key",
+ storage_config_id: "builtin",
+ kind: "attachment",
+ mime_type: "application/pdf",
+ filename: "report.pdf",
+ byte_size: 256,
+ sha256: "checksum",
+ width: null,
+ height: null,
+ created_at: "2026-08-08T00:00:00.000Z",
+ updated_at: "2026-08-08T00:00:00.000Z",
+ memo_title: "Report",
+ memo_excerpt: "Quarterly report",
+ memo_is_deleted: 0,
+};
+
+const agentAuth = {
+ kind: "agent",
+ actorType: "agent",
+ actorId: "token_1",
+ username: "automation",
+ displayName: null,
+ scopes: ["read:resources"],
+ workspaceId: "ws_1",
+ role: "member",
+};
+
+const createEnvironment = () => ({
+ storage: {
+ db: {
+ prepare: (sql) => ({
+ bind: () => ({
+ all: async () => ({ results: sql.includes("ORDER BY r.created_at") ? [resourceRow] : [] }),
+ first: async () => sql.includes("COUNT(*)") ? {
+ total_count: 1,
+ total_bytes: 256,
+ image_count: 0,
+ attachment_count: 1,
+ } : null,
+ }),
+ }),
+ batch: async () => [],
+ },
+ resources: {},
+ },
+});
+
+const createApp = (auth = agentAuth) => {
+ const app = new Hono();
+ app.use("/api/v1/*", async (context, next) => {
+ context.set("auth", auth);
+ await next();
+ });
+ registerResourceRoutes(app, {
+ clampNumber: (value, min, max) => Math.min(Math.max(value, min), max),
+ createAttachmentResource: async () => { throw new Error("Unexpected upload"); },
+ createImageResource: async () => { throw new Error("Unexpected upload"); },
+ getMemoDetail: async () => null,
+ getResourceRow: async () => null,
+ });
+ return app;
+};
+
+describe("resource route contracts", () => {
+ test("returns mapped resources and aggregate storage usage", async () => {
+ const response = await createApp().request(
+ "/api/v1/resources?limit=9999",
+ {},
+ createEnvironment(),
+ );
+
+ expect(response.status).toBe(200);
+ expect(await response.json()).toMatchObject({
+ resources: [{
+ id: "res_1",
+ memoId: "memo_1",
+ filename: "report.pdf",
+ memoTitle: "Report",
+ }],
+ summary: {
+ totalCount: 1,
+ totalBytes: 256,
+ imageCount: 0,
+ attachmentCount: 1,
+ },
+ });
+ });
+
+ test("enforces write scope before parsing an upload", async () => {
+ const response = await createApp().request(
+ "/api/v1/memos/memo_1/resources",
+ { method: "POST" },
+ createEnvironment(),
+ );
+
+ expect(response.status).toBe(403);
+ expect(await response.json()).toMatchObject({ error: { code: "forbidden" } });
+ });
+});
diff --git a/apps/api/src/resource-routes.ts b/apps/api/src/resource-routes.ts
new file mode 100644
index 00000000..42001206
--- /dev/null
+++ b/apps/api/src/resource-routes.ts
@@ -0,0 +1,233 @@
+import { ResourceUpdateSchema, type MemoDetail, type Resource } from "@edgeever/shared";
+import { zValidator } from "@hono/zod-validator";
+import type { Hono } from "hono";
+import { auditStatement } from "./audit";
+import type { AppContext, AppEnv, AuditActor } from "./api-context";
+import { AppError } from "./app-error";
+import { isoNow } from "./entity-utils";
+import { apiError, badRequest, notFound } from "./http-errors";
+import { resolveObjectStorage } from "./object-storage";
+import {
+ SUPPORTED_IMAGE_MIME_TYPES,
+ contentDispositionAttachment,
+ contentDispositionInline,
+ mapResource,
+ mapResourceListItem,
+ mapResourceStorageSummary,
+ normalizeFilename,
+ type ResourceListRow,
+ type ResourceRow,
+ type ResourceStatsRow,
+} from "./resource-service";
+import { getAuditActor, getWorkspaceId, requireScopes } from "./request-auth";
+import type { DatabaseAdapter } from "./storage-contract";
+
+type ResourceRouteDependencies = {
+ clampNumber: (value: number, min: number, max: number) => number;
+ createAttachmentResource: (context: AppContext, input: {
+ memoId: string;
+ filename: string;
+ mimeType: string;
+ bytes: Uint8Array;
+ actor: AuditActor;
+ }) => Promise<Resource>;
+ createImageResource: (context: AppContext, input: {
+ memoId: string;
+ filename: string;
+ mimeType: string;
+ bytes: Uint8Array;
+ actor: AuditActor;
+ source: "upload" | "mcp";
+ }) => Promise<Resource>;
+ getMemoDetail: (
+ database: DatabaseAdapter,
+ workspaceId: string,
+ memoId: string,
+ ) => Promise<MemoDetail | null>;
+ getResourceRow: (
+ database: DatabaseAdapter,
+ workspaceId: string,
+ resourceId: string,
+ ) => Promise<ResourceRow | null>;
+};
+
+export const registerResourceRoutes = (
+ app: Hono<AppEnv>,
+ dependencies: ResourceRouteDependencies,
+) => {
+ app.get("/api/v1/resources", async (context) => {
+ const denied = requireScopes(context, "read:resources");
+ if (denied) return denied;
+
+ const limit = dependencies.clampNumber(Number(context.req.query("limit") ?? 500), 1, 500);
+ const workspaceId = getWorkspaceId(context);
+ const [rows, stats] = await Promise.all([
+ context.env.storage.db.prepare(
+ `SELECT r.id, r.memo_id, r.original_memo_id, r.bucket_name, r.object_key, r.storage_config_id, r.kind,
+ r.mime_type, r.filename, r.byte_size, r.sha256, r.width, r.height,
+ r.created_at, r.updated_at, m.title AS memo_title, m.excerpt AS memo_excerpt,
+ m.is_deleted AS memo_is_deleted
+ FROM resources r
+ INNER JOIN memos m ON m.id = r.memo_id
+ WHERE m.workspace_id = ? AND r.is_deleted = 0
+ ORDER BY r.created_at DESC
+ LIMIT ?`,
+ ).bind(workspaceId, limit).all<ResourceListRow>(),
+ context.env.storage.db.prepare(
+ `SELECT COUNT(*) AS total_count,
+ COALESCE(SUM(byte_size), 0) AS total_bytes,
+ COALESCE(SUM(CASE WHEN kind = 'image' THEN 1 ELSE 0 END), 0) AS image_count,
+ COALESCE(SUM(CASE WHEN kind = 'attachment' THEN 1 ELSE 0 END), 0) AS attachment_count
+ FROM resources r
+ INNER JOIN memos m ON m.id = r.memo_id
+ WHERE m.workspace_id = ? AND r.is_deleted = 0`,
+ ).bind(workspaceId).first<ResourceStatsRow>(),
+ ]);
+
+ return context.json({
+ resources: rows.results.map(mapResourceListItem),
+ summary: mapResourceStorageSummary(stats),
+ });
+ });
+
+ app.post("/api/v1/memos/:id/resources", async (context) => {
+ const denied = requireScopes(context, "write:resources");
+ if (denied) return denied;
+
+ const memoId = context.req.param("id");
+ const memo = await dependencies.getMemoDetail(
+ context.env.storage.db,
+ getWorkspaceId(context),
+ memoId,
+ );
+ if (!memo) return notFound(context, "Memo not found");
+
+ const form = await context.req.raw.formData();
+ const file = form.get("file");
+ if (!(file instanceof File)) {
+ return badRequest(context, "Expected multipart form field named file.");
+ }
+
+ const input = {
+ memoId,
+ filename: file.name,
+ mimeType: file.type || "application/octet-stream",
+ bytes: new Uint8Array(await file.arrayBuffer()),
+ actor: getAuditActor(context),
+ };
+ let resource: Resource;
+ try {
+ resource = SUPPORTED_IMAGE_MIME_TYPES.has(input.mimeType)
+ ? await dependencies.createImageResource(context, { ...input, source: "upload" })
+ : await dependencies.createAttachmentResource(context, input);
+ } catch (error) {
+ if (error instanceof AppError) {
+ return apiError(context, error.code, error.message, error.status);
+ }
+ throw error;
+ }
+
+ return context.json({ resource }, 201);
+ });
+
+ app.get("/api/v1/resources/:id/blob", async (context) => {
+ const denied = requireScopes(context, "read:resources");
+ if (denied) return denied;
+
+ const resource = await dependencies.getResourceRow(
+ context.env.storage.db,
+ getWorkspaceId(context),
+ context.req.param("id"),
+ );
+ if (!resource) return notFound(context, "Resource not found");
+
+ const source = await resolveObjectStorage(context.env, resource.storage_config_id);
+ const object = await source.store.get(resource.object_key);
+ if (!object) return notFound(context, "Resource object not found");
+
+ const headers = new Headers();
+ object.writeHttpMetadata(headers);
+ headers.set("Content-Type", resource.mime_type ?? headers.get("Content-Type") ?? "application/octet-stream");
+ headers.set("Cache-Control", headers.get("Cache-Control") ?? "private, max-age=3600");
+ headers.set("Content-Length", String(object.size));
+ headers.set(
+ "Content-Disposition",
+ resource.kind === "image"
+ ? contentDispositionInline(resource.filename)
+ : contentDispositionAttachment(resource.filename),
+ );
+ headers.set("X-Content-Type-Options", "nosniff");
+ return new Response(object.body, { headers });
+ });
+
+ app.patch(
+ "/api/v1/resources/:id",
+ zValidator("json", ResourceUpdateSchema),
+ async (context) => {
+ const denied = requireScopes(context, "write:resources");
+ if (denied) return denied;
+
+ const resourceId = context.req.param("id");
+ const workspaceId = getWorkspaceId(context);
+ const resource = await dependencies.getResourceRow(
+ context.env.storage.db,
+ workspaceId,
+ resourceId,
+ );
+ if (!resource) return notFound(context, "Resource not found");
+
+ const filename = normalizeFilename(context.req.valid("json").filename);
+ if (!filename) return badRequest(context, "Resource filename is required.");
+
+ const now = isoNow();
+ const actor = getAuditActor(context);
+ await context.env.storage.db.batch([
+ context.env.storage.db.prepare(
+ `UPDATE resources SET filename = ?, updated_at = ? WHERE id = ?`,
+ ).bind(filename, now, resourceId),
+ auditStatement(context.env.storage.db, actor.actorType, actor.actorId, "resource.rename", "resource", resourceId, {
+ memoId: resource.memo_id,
+ previousFilename: resource.filename,
+ filename,
+ }),
+ ]);
+
+ const updated = await dependencies.getResourceRow(
+ context.env.storage.db,
+ workspaceId,
+ resourceId,
+ );
+ if (!updated) return notFound(context, "Resource not found");
+ return context.json({ resource: mapResource(updated) });
+ },
+ );
+
+ app.delete("/api/v1/resources/:id", async (context) => {
+ const denied = requireScopes(context, "write:resources");
+ if (denied) return denied;
+
+ const resourceId = context.req.param("id");
+ const resource = await dependencies.getResourceRow(
+ context.env.storage.db,
+ getWorkspaceId(context),
+ resourceId,
+ );
+ if (!resource) return notFound(context, "Resource not found");
+
+ const now = isoNow();
+ const actor = getAuditActor(context);
+ await context.env.storage.db.batch([
+ context.env.storage.db.prepare(
+ `UPDATE resources SET is_deleted = 1, deleted_at = ?, updated_at = ? WHERE id = ?`,
+ ).bind(now, now, resourceId),
+ auditStatement(context.env.storage.db, actor.actorType, actor.actorId, "resource.delete", "resource", resourceId, {
+ memoId: resource.memo_id,
+ filename: resource.filename,
+ byteSize: resource.byte_size,
+ }),
+ ]);
+ const source = await resolveObjectStorage(context.env, resource.storage_config_id);
+ await source.store.delete(resource.object_key);
+ return context.json({ ok: true });
+ });
+};
diff --git a/apps/api/src/resource-service.test.mjs b/apps/api/src/resource-service.test.mjs
new file mode 100644
index 00000000..07c23086
--- /dev/null
+++ b/apps/api/src/resource-service.test.mjs
@@ -0,0 +1,74 @@
+import { describe, expect, test } from "bun:test";
+import {
+ MAX_ATTACHMENT_UPLOAD_BYTES,
+ MAX_IMAGE_UPLOAD_BYTES,
+ contentDispositionAttachment,
+ inferImageExtension,
+ mapResourceListItem,
+ normalizeFilename,
+ validateAttachmentUpload,
+ validateImageUpload,
+} from "./resource-service.ts";
+
+const resourceRow = {
+ id: "res_1",
+ memo_id: "memo_1",
+ original_memo_id: null,
+ bucket_name: "resources",
+ object_key: "workspaces/ws/memos/memo_1/res_1",
+ storage_config_id: "builtin",
+ kind: "image",
+ mime_type: "image/png",
+ filename: "diagram.png",
+ byte_size: 128,
+ sha256: "checksum",
+ width: 640,
+ height: 480,
+ created_at: "2026-08-08T00:00:00.000Z",
+ updated_at: "2026-08-08T01:00:00.000Z",
+ memo_title: "Architecture",
+ memo_excerpt: "System overview",
+ memo_is_deleted: 0,
+};
+
+describe("resource service contracts", () => {
+ test("maps storage-only fields out of public resource responses", () => {
+ expect(mapResourceListItem(resourceRow)).toEqual({
+ id: "res_1",
+ memoId: "memo_1",
+ originalMemoId: null,
+ kind: "image",
+ mimeType: "image/png",
+ filename: "diagram.png",
+ byteSize: 128,
+ sha256: "checksum",
+ width: 640,
+ height: 480,
+ createdAt: "2026-08-08T00:00:00.000Z",
+ updatedAt: "2026-08-08T01:00:00.000Z",
+ url: "/api/v1/resources/res_1/blob",
+ memoTitle: "Architecture",
+ memoExcerpt: "System overview",
+ memoDeleted: false,
+ });
+ });
+
+ test("normalizes filenames and keeps UTF-8 download names", () => {
+ expect(normalizeFilename(" reports/季度\u0000.pdf ")).toBe("reports-季度.pdf");
+ expect(contentDispositionAttachment("季度报告.pdf")).toContain(
+ "filename*=UTF-8''%E5%AD%A3%E5%BA%A6%E6%8A%A5%E5%91%8A.pdf",
+ );
+ });
+
+ test("infers normalized image extensions", () => {
+ expect(inferImageExtension("photo.JPEG", "application/octet-stream")).toBe(".jpg");
+ expect(inferImageExtension("photo", "image/avif")).toBe(".avif");
+ });
+
+ test("enforces upload type and size boundaries", () => {
+ expect(() => validateImageUpload("image/png", MAX_IMAGE_UPLOAD_BYTES)).not.toThrow();
+ expect(() => validateAttachmentUpload(MAX_ATTACHMENT_UPLOAD_BYTES)).not.toThrow();
+ expect(() => validateImageUpload("image/svg+xml", 128)).toThrow();
+ expect(() => validateAttachmentUpload(MAX_ATTACHMENT_UPLOAD_BYTES + 1)).toThrow();
+ });
+});
diff --git a/apps/api/src/resource-service.ts b/apps/api/src/resource-service.ts
new file mode 100644
index 00000000..621579de
--- /dev/null
+++ b/apps/api/src/resource-service.ts
@@ -0,0 +1,160 @@
+import type {
+ Resource,
+ ResourceListItem,
+ ResourceStorageSummary,
+} from "@edgeever/shared";
+import { AppError } from "./app-error";
+
+export const MAX_IMAGE_UPLOAD_BYTES = 100 * 1024 * 1024;
+export const MAX_ATTACHMENT_UPLOAD_BYTES = 100 * 1024 * 1024;
+
+export const SUPPORTED_IMAGE_MIME_TYPES = new Set([
+ "image/png",
+ "image/jpeg",
+ "image/gif",
+ "image/webp",
+ "image/avif",
+]);
+
+export type ResourceRow = {
+ id: string;
+ memo_id: string;
+ original_memo_id: string | null;
+ bucket_name: string;
+ object_key: string;
+ storage_config_id: string;
+ kind: "image" | "attachment";
+ mime_type: string | null;
+ filename: string | null;
+ byte_size: number;
+ sha256: string | null;
+ width: number | null;
+ height: number | null;
+ created_at: string;
+ updated_at: string;
+};
+
+export type ResourceListRow = ResourceRow & {
+ memo_title: string | null;
+ memo_excerpt: string | null;
+ memo_is_deleted: number | null;
+};
+
+export type ResourceStatsRow = {
+ total_count: number;
+ total_bytes: number;
+ image_count: number;
+ attachment_count: number;
+};
+
+type PreparedImage = {
+ bytes: Uint8Array;
+ mimeType: string;
+ filename: string;
+ width: number | null;
+ height: number | null;
+ compressed: boolean;
+ metadata: Record<string, unknown>;
+};
+
+export const mapResource = (row: ResourceRow): Resource => ({
+ id: row.id,
+ memoId: row.memo_id,
+ originalMemoId: row.original_memo_id,
+ kind: row.kind,
+ mimeType: row.mime_type,
+ filename: row.filename,
+ byteSize: row.byte_size,
+ sha256: row.sha256,
+ width: row.width,
+ height: row.height,
+ createdAt: row.created_at,
+ updatedAt: row.updated_at,
+ url: `/api/v1/resources/${row.id}/blob`,
+});
+
+export const mapResourceListItem = (row: ResourceListRow): ResourceListItem => ({
+ ...mapResource(row),
+ memoTitle: row.memo_title,
+ memoExcerpt: row.memo_excerpt,
+ memoDeleted: Boolean(row.memo_is_deleted),
+});
+
+export const mapResourceStorageSummary = (
+ row: ResourceStatsRow | null,
+): ResourceStorageSummary => ({
+ totalCount: row?.total_count ?? 0,
+ totalBytes: row?.total_bytes ?? 0,
+ imageCount: row?.image_count ?? 0,
+ attachmentCount: row?.attachment_count ?? 0,
+});
+
+export const validateImageUpload = (mimeType: string, size: number) => {
+ if (!SUPPORTED_IMAGE_MIME_TYPES.has(mimeType)) {
+ throw new AppError(
+ "unsupported_media_type",
+ "Only PNG, JPEG, GIF, WebP and AVIF images are supported.",
+ 415,
+ );
+ }
+ if (size <= 0 || size > MAX_IMAGE_UPLOAD_BYTES) {
+ throw new AppError("upload_too_large", "Image must be between 1 byte and 50 MB.", 413);
+ }
+};
+
+export const validateAttachmentUpload = (size: number) => {
+ if (size <= 0 || size > MAX_ATTACHMENT_UPLOAD_BYTES) {
+ throw new AppError("upload_too_large", "Attachment must be between 1 byte and 100 MB.", 413);
+ }
+};
+
+export const normalizeFilename = (filename: string) => filename
+ .trim()
+ .replace(/[\\/]/g, "-")
+ .replace(/[\u0000-\u001f\u007f]/g, "")
+ .slice(0, 160);
+
+export const inferImageExtension = (filename: string, mimeType: string) => {
+ const extension = /\.(png|jpe?g|gif|webp|avif)$/i.exec(filename)?.[0]?.toLowerCase();
+ if (extension) return extension === ".jpeg" ? ".jpg" : extension;
+
+ switch (mimeType) {
+ case "image/png": return ".png";
+ case "image/jpeg": return ".jpg";
+ case "image/gif": return ".gif";
+ case "image/webp": return ".webp";
+ case "image/avif": return ".avif";
+ default: return "";
+ }
+};
+
+export const prepareImageForStorage = (input: {
+ bytes: Uint8Array;
+ filename: string;
+ mimeType: string;
+ source: "upload" | "mcp";
+}): PreparedImage => ({
+ bytes: input.bytes,
+ mimeType: input.mimeType,
+ filename: input.filename,
+ width: null,
+ height: null,
+ compressed: false,
+ metadata: {
+ source: input.source,
+ originalFilename: normalizeFilename(input.filename) || null,
+ originalMimeType: input.mimeType,
+ originalByteSize: input.bytes.byteLength,
+ compression: "disabled",
+ },
+});
+
+const contentDisposition = (kind: "inline" | "attachment", filename: string | null) => {
+ if (!filename) return kind;
+ const fallback = normalizeFilename(filename).replace(/"/g, "'");
+ return `${kind}; filename="${fallback}"; filename*=UTF-8''${encodeURIComponent(filename)}`;
+};
+
+export const contentDispositionInline = (filename: string | null) => contentDisposition("inline", filename);
+
+export const contentDispositionAttachment = (filename: string | null) => contentDisposition("attachment", filename);
diff --git a/apps/api/src/user-routes.test.mjs b/apps/api/src/user-routes.test.mjs
new file mode 100644
index 00000000..70316179
--- /dev/null
+++ b/apps/api/src/user-routes.test.mjs
@@ -0,0 +1,81 @@
+import { describe, expect, test } from "bun:test";
+import { Hono } from "hono";
+import { registerUserRoutes } from "./user-routes.ts";
+
+const ownerAuth = {
+ kind: "user",
+ actorType: "user",
+ actorId: "usr_owner",
+ username: "owner",
+ displayName: "Owner",
+ scopes: [],
+ workspaceId: "ws_owner",
+ role: "owner",
+};
+
+const createEnvironment = (rows = []) => ({
+ storage: {
+ db: {
+ prepare: () => ({
+ all: async () => ({ results: rows }),
+ }),
+ batch: async () => [],
+ },
+ resources: {},
+ },
+});
+
+const createApp = (authenticateRequest) => {
+ const app = new Hono();
+ registerUserRoutes(app, {
+ authenticateRequest,
+ createDefaultNotebookRows: () => [],
+ getInstanceUser: async () => null,
+ });
+ return app;
+};
+
+describe("user route contracts", () => {
+ test("rejects unauthenticated user listing", async () => {
+ const app = createApp(async () => null);
+ const response = await app.request("/api/v1/users", {}, createEnvironment());
+
+ expect(response.status).toBe(401);
+ expect(await response.json()).toMatchObject({ error: { code: "unauthorized" } });
+ });
+
+ test("rejects non-owner user listing", async () => {
+ const app = createApp(async () => ({ ...ownerAuth, role: "member" }));
+ const response = await app.request("/api/v1/users", {}, createEnvironment());
+
+ expect(response.status).toBe(403);
+ expect(await response.json()).toMatchObject({ error: { code: "forbidden" } });
+ });
+
+ test("maps owner-visible users at the HTTP boundary", async () => {
+ const app = createApp(async () => ownerAuth);
+ const response = await app.request("/api/v1/users", {}, createEnvironment([{
+ id: "usr_member",
+ username: "writer",
+ password_hash: "hidden",
+ display_name: "Writer",
+ is_disabled: 0,
+ last_login_at: null,
+ created_at: "2026-08-08T00:00:00.000Z",
+ role: "member",
+ }]));
+
+ expect(response.status).toBe(200);
+ expect(await response.json()).toEqual({
+ users: [{
+ id: "usr_member",
+ username: "writer",
+ displayName: "Writer",
+ role: "member",
+ isDisabled: false,
+ lastLoginAt: null,
+ createdAt: "2026-08-08T00:00:00.000Z",
+ }],
+ });
+ });
+});
diff --git a/apps/api/src/user-routes.ts b/apps/api/src/user-routes.ts
new file mode 100644
index 00000000..6c5fadf4
--- /dev/null
+++ b/apps/api/src/user-routes.ts
@@ -0,0 +1,174 @@
+import { UserCreateSchema, UserUpdateSchema, type InstanceUser } from "@edgeever/shared";
+import { zValidator } from "@hono/zod-validator";
+import type { Hono } from "hono";
+import { auditStatement } from "./audit";
+import type { AppContext, AppEnv, AuthContext } from "./api-context";
+import { hashPassword } from "./auth-crypto";
+import { isProtectedDemoAccount } from "./demo-mode";
+import { createId, isoNow } from "./entity-utils";
+import { badRequest, conflict, forbidden, notFound, unauthorized } from "./http-errors";
+import { requireOwner } from "./request-auth";
+import type { DatabaseAdapter } from "./storage-contract";
+
+export type InstanceUserRow = {
+ id: string;
+ username: string;
+ password_hash: string;
+ display_name: string | null;
+ is_disabled: number;
+ last_login_at: string | null;
+ created_at: string;
+ role: "owner" | "member";
+};
+
+type DefaultNotebookRow = {
+ id: string;
+ name: string;
+ slug: string;
+ color: string;
+ sortOrder: number;
+};
+
+type UserRouteDependencies = {
+ authenticateRequest: (context: AppContext, touch: boolean) => Promise<AuthContext | null>;
+ createDefaultNotebookRows: (workspaceId: string, now: string) => DefaultNotebookRow[];
+ getInstanceUser: (database: DatabaseAdapter, userId: string) => Promise<InstanceUserRow | null>;
+};
+
+export const mapInstanceUser = (row: InstanceUserRow): InstanceUser => ({
+ id: row.id,
+ username: row.username,
+ displayName: row.display_name,
+ role: row.role,
+ isDisabled: Boolean(row.is_disabled),
+ lastLoginAt: row.last_login_at,
+ createdAt: row.created_at,
+});
+
+const requireOwnerRequest = async (
+ context: AppContext,
+ authenticateRequest: UserRouteDependencies["authenticateRequest"],
+) => {
+ const auth = await authenticateRequest(context, true);
+ if (!auth) return unauthorized(context, "Authentication required.");
+ context.set("auth", auth);
+ return requireOwner(context);
+};
+
+export const registerUserRoutes = (
+ app: Hono<AppEnv>,
+ dependencies: UserRouteDependencies,
+) => {
+ app.get("/api/v1/users", async (context) => {
+ const denied = await requireOwnerRequest(context, dependencies.authenticateRequest);
+ if (denied) return denied;
+
+ const rows = await context.env.storage.db.prepare(
+ `SELECT u.id, u.username, u.password_hash, u.display_name, u.is_disabled,
+ u.last_login_at, u.created_at, wm.role
+ FROM users u
+ INNER JOIN workspace_members wm ON wm.user_id = u.id
+ ORDER BY wm.role = 'owner' DESC, u.created_at ASC`,
+ ).all<InstanceUserRow>();
+
+ return context.json({ users: rows.results.map(mapInstanceUser) });
+ });
+
+ app.post("/api/v1/users", zValidator("json", UserCreateSchema), async (context) => {
+ const denied = await requireOwnerRequest(context, dependencies.authenticateRequest);
+ if (denied) return denied;
+
+ const input = context.req.valid("json");
+ const existing = await context.env.storage.db.prepare(`SELECT id FROM users WHERE username = ?`)
+ .bind(input.username)
+ .first();
+ if (existing) return conflict(context, "username_exists", "Username already exists.");
+
+ const userId = createId("usr");
+ const workspaceId = createId("ws");
+ const now = isoNow();
+ const passwordHash = await hashPassword(input.password);
+ const notebooks = dependencies.createDefaultNotebookRows(workspaceId, now);
+ const statements = [
+ context.env.storage.db.prepare(
+ `INSERT INTO users (id, username, password_hash, display_name, created_at, updated_at)
+ VALUES (?, ?, ?, ?, ?, ?)`,
+ ).bind(userId, input.username, passwordHash, input.displayName ?? input.username, now, now),
+ context.env.storage.db.prepare(
+ `INSERT INTO workspaces (id, name, is_personal, created_at, updated_at) VALUES (?, ?, 1, ?, ?)`,
+ ).bind(workspaceId, `${input.displayName ?? input.username}'s workspace`, now, now),
+ context.env.storage.db.prepare(
+ `INSERT INTO workspace_members (workspace_id, user_id, role, created_at) VALUES (?, ?, 'member', ?)`,
+ ).bind(workspaceId, userId, now),
+ ...notebooks.map((notebook) => context.env.storage.db.prepare(
+ `INSERT INTO notebooks (id, workspace_id, parent_id, name, slug, icon, color, sort_order, created_at, updated_at)
+ VALUES (?, ?, NULL, ?, ?, 'notebook', ?, ?, ?, ?)`,
+ ).bind(notebook.id, workspaceId, notebook.name, notebook.slug, notebook.color, notebook.sortOrder, now, now)),
+ auditStatement(context.env.storage.db, "user", context.get("auth").actorId, "user.create", "user", userId, {
+ username: input.username,
+ }),
+ ];
+ await context.env.storage.db.batch(statements);
+
+ const user = await dependencies.getInstanceUser(context.env.storage.db, userId);
+ return context.json({ user: user ? mapInstanceUser(user) : null }, 201);
+ });
+
+ app.patch("/api/v1/users/:id", zValidator("json", UserUpdateSchema), async (context) => {
+ const denied = await requireOwnerRequest(context, dependencies.authenticateRequest);
+ if (denied) return denied;
+
+ const userId = context.req.param("id");
+ const input = context.req.valid("json");
+ const current = await dependencies.getInstanceUser(context.env.storage.db, userId);
+ if (!current) return notFound(context, "User not found");
+ if (
+ isProtectedDemoAccount(
+ context.env.EDGE_EVER_DEMO_MODE,
+ context.env.EDGE_EVER_AUTH_USERNAME,
+ current.username,
+ ) && (input.password !== undefined || input.isDisabled !== undefined)
+ ) {
+ return forbidden(context, "The demo owner account uses fixed credentials and cannot be modified.");
+ }
+ if (current.role === "owner" && input.isDisabled === true) {
+ return badRequest(context, "The instance owner cannot be disabled.");
+ }
+
+ const updates: string[] = [];
+ const binds: unknown[] = [];
+ if (input.displayName !== undefined) {
+ updates.push("display_name = ?");
+ binds.push(input.displayName);
+ }
+ if (input.password !== undefined) {
+ updates.push("password_hash = ?");
+ binds.push(await hashPassword(input.password));
+ }
+ if (input.isDisabled !== undefined) {
+ updates.push("is_disabled = ?");
+ binds.push(input.isDisabled ? 1 : 0);
+ }
+ updates.push("updated_at = ?");
+ binds.push(isoNow(), userId);
+
+ const statements = [
+ context.env.storage.db.prepare(`UPDATE users SET ${updates.join(", ")} WHERE id = ?`).bind(...binds),
+ auditStatement(context.env.storage.db, "user", context.get("auth").actorId, "user.update", "user", userId, {
+ passwordReset: input.password !== undefined,
+ isDisabled: input.isDisabled,
+ }),
+ ];
+ if (input.password !== undefined || input.isDisabled === true) {
+ statements.push(
+ context.env.storage.db.prepare(
+ `UPDATE sessions SET revoked_at = ? WHERE user_id = ? AND revoked_at IS NULL`,
+ ).bind(isoNow(), userId),
+ );
+ }
+ await context.env.storage.db.batch(statements);
+
+ const user = await dependencies.getInstanceUser(context.env.storage.db, userId);
+ return context.json({ user: user ? mapInstanceUser(user) : null });
+ });
+};