Skip to content

armgit / kaneo

Public Imported from GitHub
0

⚡ Project management that doesn't become the project. Boards, Gantt charts, and GitHub integration. Self-host it or use Kaneo Cloud.

feat(admin): add system status and test email endpoints

Tin04af5cc7d0c7
diff --git a/apps/api/src/admin/controllers/get-system-status.ts b/apps/api/src/admin/controllers/get-system-status.ts
new file mode 100644
index 000000000..53b92fddb
--- /dev/null
+++ b/apps/api/src/admin/controllers/get-system-status.ts
@@ -0,0 +1,47 @@
+import { readAppVersion } from "../../app-version";
+import { getLocalRealtimeStats } from "../../ws";
+import { describeAuth } from "../system/describe-auth";
+import { listIntegrationProviders } from "../system/list-integration-providers";
+import { probeDatabase } from "../system/probe-database";
+import { probeEmail } from "../system/probe-email";
+import { probeRedis } from "../system/probe-redis";
+import { probeStorage } from "../system/probe-storage";
+import { realtimeStatus } from "../system/realtime-status";
+
+const PROBE_TIMEOUT_MS = 3_000;
+
+async function getSystemStatus() {
+ const [database, redis, email, storage, integrations] = await Promise.all([
+ probeDatabase(PROBE_TIMEOUT_MS),
+ probeRedis(PROBE_TIMEOUT_MS),
+ probeEmail(PROBE_TIMEOUT_MS),
+ probeStorage(PROBE_TIMEOUT_MS),
+ listIntegrationProviders(PROBE_TIMEOUT_MS),
+ ]);
+ const realtime = getLocalRealtimeStats();
+
+ return {
+ checkedAt: new Date().toISOString(),
+ version: readAppVersion(),
+ api: {
+ status: "ok" as const,
+ uptimeSeconds: Math.floor(process.uptime()),
+ nodeVersion: process.version,
+ },
+ database,
+ realtime: {
+ status: realtimeStatus({
+ adapter: realtime.adapter,
+ redisStatus: redis.status,
+ }),
+ ...realtime,
+ },
+ redis,
+ email,
+ storage,
+ auth: describeAuth(),
+ integrations,
+ };
+}
+
+export default getSystemStatus;
diff --git a/apps/api/src/admin/controllers/send-test-email.ts b/apps/api/src/admin/controllers/send-test-email.ts
new file mode 100644
index 000000000..0d47244a6
--- /dev/null
+++ b/apps/api/src/admin/controllers/send-test-email.ts
@@ -0,0 +1,74 @@
+import {
+ getSmtpErrorDetails,
+ isSmtpConfigured,
+ sendTestEmail,
+} from "@kaneo/email";
+import { HTTPException } from "hono/http-exception";
+import { ApiError } from "../../errors/api-error";
+import { createAttemptLimiter } from "../system/attempt-limiter";
+
+const testEmailLimiter = createAttemptLimiter({
+ max: 5,
+ windowMs: 10 * 60 * 1000,
+});
+
+function notConfigured() {
+ return new ApiError(409, {
+ message:
+ "Email is not configured on this instance. Set SMTP_HOST and SMTP_FROM, then restart Kaneo.",
+ code: "SMTP_NOT_CONFIGURED",
+ });
+}
+
+type SendTestEmailInput = {
+ userId: string;
+ email: string;
+};
+
+/**
+ * Send an SMTP test to the calling administrator's own address. There is no
+ * recipient parameter, so this can't be used to relay mail to anyone else.
+ */
+async function sendAdminTestEmail({ userId, email }: SendTestEmailInput) {
+ if (!isSmtpConfigured()) throw notConfigured();
+
+ const decision = testEmailLimiter.take(userId);
+ if (!decision.allowed) {
+ throw new HTTPException(429, {
+ res: Response.json(
+ {
+ message: `Too many test emails. Try again in ${decision.retryAfterSeconds} seconds.`,
+ code: "RATE_LIMITED",
+ },
+ {
+ status: 429,
+ headers: { "Retry-After": String(decision.retryAfterSeconds) },
+ },
+ ),
+ });
+ }
+
+ let result: Awaited<ReturnType<typeof sendTestEmail>>;
+ try {
+ result = await sendTestEmail(email, "Kaneo test email", {
+ requestedAt: new Date(),
+ });
+ } catch (error) {
+ const details = getSmtpErrorDetails(error);
+ console.error("Error sending admin test email", details);
+ const reason =
+ "responseCode" in details
+ ? `${details.code} ${details.responseCode}`
+ : details.code;
+ throw new ApiError(502, {
+ message: `The mail server did not accept the test email (${reason}). Check the SMTP settings and the API logs.`,
+ code: "SMTP_SEND_FAILED",
+ });
+ }
+
+ if (!result.success) throw notConfigured();
+
+ return { sent: true as const, to: email };
+}
+
+export default sendAdminTestEmail;
diff --git a/apps/api/src/admin/index.ts b/apps/api/src/admin/index.ts
index 1f1d8b4f3..1856a92e5 100644
--- a/apps/api/src/admin/index.ts
+++ b/apps/api/src/admin/index.ts
@@ -9,11 +9,13 @@ import { requireUserSession } from "../utils/require-user-session";
import { adminAuditRequest } from "./audit/admin-audit-request";
import addWorkspaceMember from "./controllers/add-workspace-member";
import listAuditLog from "./controllers/list-audit-log";
+import getSystemStatus from "./controllers/get-system-status";
import listUsers from "./controllers/list-users";
import listWorkspaceMembers from "./controllers/list-workspace-members";
import listWorkspaceRoles from "./controllers/list-workspace-roles";
import listWorkspaces from "./controllers/list-workspaces";
import removeWorkspaceMember from "./controllers/remove-workspace-member";
+import sendAdminTestEmail from "./controllers/send-test-email";
import transferWorkspaceOwnership from "./controllers/transfer-workspace-ownership";
import updateWorkspaceMemberRole from "./controllers/update-workspace-member-role";
import adminUserRoutes from "./user-routes";
@@ -34,6 +36,10 @@ import {
transferAdminWorkspaceOwnershipBody,
updateAdminWorkspaceMemberRoleBody,
} from "./schema";
+import {
+ adminSystemStatusSchema,
+ adminTestEmailResultSchema,
+} from "./system/response";
import { adminUserSecurityRoutes } from "./user-security-routes";
const forbidden = errorResponse(
@@ -236,6 +242,42 @@ const listAuditLogRoute = createRoute({
},
});
+const getSystemStatusRoute = createRoute({
+ method: "get",
+ operationId: "getAdminSystemStatus",
+ path: "/system",
+ tags: ["Admin"],
+ summary: "Get system status",
+ description:
+ "Check this API instance and the services it uses: version, uptime, database, WebSockets, Redis fan-out, SMTP, object storage, sign-in providers and integration providers. Each check gives up after a few seconds, so one unreachable service can't block the response. Only statuses, counts and short error categories are returned, never hosts, credentials or secrets. Requires an instance administrator session; API keys are rejected.",
+ middleware: [requireUserSession, requireInstanceAdmin] as const,
+ responses: {
+ 200: jsonResponse("Status of this instance", adminSystemStatusSchema),
+ 403: forbidden,
+ },
+});
+
+const sendTestEmailRoute = createRoute({
+ method: "post",
+ operationId: "sendAdminTestEmail",
+ path: "/system/test-email",
+ tags: ["Admin"],
+ summary: "Send a test email",
+ description:
+ "Send a test email to the calling administrator's own address to check the SMTP settings. There is no recipient parameter. Limited to 5 per administrator every 10 minutes on each API instance.",
+ middleware: [requireUserSession, requireInstanceAdmin] as const,
+ responses: {
+ 200: jsonResponse(
+ "The mail server accepted the test email",
+ adminTestEmailResultSchema,
+ ),
+ 403: forbidden,
+ 409: errorResponse("SMTP is not configured on this instance"),
+ 429: errorResponse("Too many test emails; retry after Retry-After seconds"),
+ 502: errorResponse("The mail server did not accept the test email"),
+ },
+});
+
const admin = apiRouter()
.openapi(listUsersRoute, async (c) =>
c.json(await listUsers(c.req.valid("query")), 200),
@@ -276,6 +318,18 @@ const admin = apiRouter()
200,
),
)
+ .openapi(getSystemStatusRoute, async (c) =>
+ c.json(await getSystemStatus(), 200),
+ )
+ .openapi(sendTestEmailRoute, async (c) =>
+ c.json(
+ await sendAdminTestEmail({
+ userId: c.get("userId"),
+ email: c.get("userEmail"),
+ }),
+ 200,
+ ),
+ )
.openapi(transferWorkspaceOwnershipRoute, async (c) =>
c.json(
await transferWorkspaceOwnership(
diff --git a/apps/api/src/admin/system/attempt-limiter.test.ts b/apps/api/src/admin/system/attempt-limiter.test.ts
new file mode 100644
index 000000000..4a151a340
--- /dev/null
+++ b/apps/api/src/admin/system/attempt-limiter.test.ts
@@ -0,0 +1,43 @@
+import { describe, expect, it } from "vite-plus/test";
+import { createAttemptLimiter } from "./attempt-limiter";
+
+describe("createAttemptLimiter", () => {
+ it("allows up to the limit inside the window, then reports when to retry", () => {
+ let now = 0;
+ const limiter = createAttemptLimiter({
+ max: 2,
+ windowMs: 60_000,
+ now: () => now,
+ });
+
+ expect(limiter.take("a")).toEqual({ allowed: true });
+ now = 10_000;
+ expect(limiter.take("a")).toEqual({ allowed: true });
+ now = 15_000;
+ expect(limiter.take("a")).toEqual({
+ allowed: false,
+ retryAfterSeconds: 45,
+ });
+ });
+
+ it("counts each key separately", () => {
+ const limiter = createAttemptLimiter({ max: 1, windowMs: 60_000 });
+ expect(limiter.take("a").allowed).toBe(true);
+ expect(limiter.take("b").allowed).toBe(true);
+ expect(limiter.take("a").allowed).toBe(false);
+ });
+
+ it("allows again once the oldest attempt leaves the window", () => {
+ let now = 0;
+ const limiter = createAttemptLimiter({
+ max: 1,
+ windowMs: 1_000,
+ now: () => now,
+ });
+ limiter.take("a");
+ now = 999;
+ expect(limiter.take("a").allowed).toBe(false);
+ now = 1_000;
+ expect(limiter.take("a").allowed).toBe(true);
+ });
+});
diff --git a/apps/api/src/admin/system/attempt-limiter.ts b/apps/api/src/admin/system/attempt-limiter.ts
new file mode 100644
index 000000000..56a144d15
--- /dev/null
+++ b/apps/api/src/admin/system/attempt-limiter.ts
@@ -0,0 +1,44 @@
+type AttemptLimiterOptions = {
+ max: number;
+ windowMs: number;
+ now?: () => number;
+};
+
+export type AttemptDecision =
+ | { allowed: true }
+ | { allowed: false; retryAfterSeconds: number };
+
+/**
+ * A per-key sliding window kept in memory. Each API instance counts on its
+ * own, which is enough to stop an administrator from flooding a mailbox.
+ */
+export function createAttemptLimiter({
+ max,
+ windowMs,
+ now = Date.now,
+}: AttemptLimiterOptions) {
+ const attempts = new Map<string, number[]>();
+
+ return {
+ take(key: string): AttemptDecision {
+ const current = now();
+ const recent = (attempts.get(key) ?? []).filter(
+ (at) => current - at < windowMs,
+ );
+ if (recent.length >= max) {
+ attempts.set(key, recent);
+ const oldest = recent[0] ?? current;
+ return {
+ allowed: false,
+ retryAfterSeconds: Math.max(
+ 1,
+ Math.ceil((oldest + windowMs - current) / 1000),
+ ),
+ };
+ }
+ recent.push(current);
+ attempts.set(key, recent);
+ return { allowed: true };
+ },
+ };
+}
diff --git a/apps/api/src/admin/system/credential-set-status.test.ts b/apps/api/src/admin/system/credential-set-status.test.ts
new file mode 100644
index 000000000..a2d6dfaea
--- /dev/null
+++ b/apps/api/src/admin/system/credential-set-status.test.ts
@@ -0,0 +1,17 @@
+import { describe, expect, it } from "vite-plus/test";
+import { credentialSetStatus } from "./credential-set-status";
+
+describe("credentialSetStatus", () => {
+ it("is ok when every value is set", () => {
+ expect(credentialSetStatus(["id", "secret"])).toBe("ok");
+ });
+
+ it("is not configured when nothing is set", () => {
+ expect(credentialSetStatus([undefined, "", " "])).toBe("not_configured");
+ });
+
+ it("warns about a half-finished configuration", () => {
+ expect(credentialSetStatus(["id", undefined])).toBe("warning");
+ expect(credentialSetStatus(["", "secret", "key"])).toBe("warning");
+ });
+});
diff --git a/apps/api/src/admin/system/credential-set-status.ts b/apps/api/src/admin/system/credential-set-status.ts
new file mode 100644
index 000000000..88554db89
--- /dev/null
+++ b/apps/api/src/admin/system/credential-set-status.ts
@@ -0,0 +1,13 @@
+import type { ServiceStatus } from "./service-status";
+
+/**
+ * A feature that needs several settings is configured when all are present,
+ * not configured when none are, and a configuration warning in between.
+ */
+export function credentialSetStatus(values: unknown[]): ServiceStatus {
+ const present = values.filter(
+ (value) => typeof value === "string" && value.trim() !== "",
+ ).length;
+ if (present === 0) return "not_configured";
+ return present === values.length ? "ok" : "warning";
+}
diff --git a/apps/api/src/admin/system/describe-auth.ts b/apps/api/src/admin/system/describe-auth.ts
new file mode 100644
index 000000000..3f6c42c57
--- /dev/null
+++ b/apps/api/src/admin/system/describe-auth.ts
@@ -0,0 +1,84 @@
+import getSettings from "../../utils/get-settings";
+import { resolveFileSecret } from "../../utils/file-secret";
+import { credentialSetStatus } from "./credential-set-status";
+import type { ServiceStatus } from "./service-status";
+
+export type AuthProvider = {
+ id: "github" | "google" | "discord" | "custom";
+ name: string;
+ status: ServiceStatus;
+};
+
+function env(name: string) {
+ return process.env[name]?.trim() ?? "";
+}
+
+// An unreadable *_FILE secret counts as missing instead of failing the page.
+function customOAuthSecret() {
+ try {
+ return resolveFileSecret("CUSTOM_OAUTH_CLIENT_SECRET");
+ } catch {
+ return undefined;
+ }
+}
+
+function customOAuthEndpoint() {
+ if (env("CUSTOM_OAUTH_DISCOVERY_URL")) return "discovery";
+ return env("CUSTOM_OAUTH_AUTHORIZATION_URL") && env("CUSTOM_OAUTH_TOKEN_URL")
+ ? "manual"
+ : "";
+}
+
+/**
+ * Which sign-in paths this instance offers. Only booleans and display names
+ * leave here: never client ids, secrets, or provider URLs.
+ */
+export function describeAuth() {
+ const settings = getSettings();
+ const providers: AuthProvider[] = [
+ {
+ id: "github",
+ name: "GitHub",
+ status: credentialSetStatus([
+ env("GITHUB_OAUTH_CLIENT_ID") || env("GITHUB_CLIENT_ID"),
+ env("GITHUB_OAUTH_CLIENT_SECRET") || env("GITHUB_CLIENT_SECRET"),
+ ]),
+ },
+ {
+ id: "google",
+ name: "Google",
+ status: credentialSetStatus([
+ env("GOOGLE_CLIENT_ID"),
+ env("GOOGLE_CLIENT_SECRET"),
+ ]),
+ },
+ {
+ id: "discord",
+ name: "Discord",
+ status: credentialSetStatus([
+ env("DISCORD_CLIENT_ID"),
+ env("DISCORD_CLIENT_SECRET"),
+ ]),
+ },
+ {
+ id: "custom",
+ name: settings.customOAuthName ?? "OIDC",
+ status: credentialSetStatus([
+ env("CUSTOM_OAUTH_CLIENT_ID"),
+ customOAuthSecret(),
+ customOAuthEndpoint(),
+ ]),
+ },
+ ];
+
+ return {
+ passwordSignIn: !settings.disableLoginForm,
+ emailOtpSignIn: !settings.disableEmailOtpSignIn && settings.hasSmtp,
+ registration: !settings.disableRegistration,
+ passwordRegistration:
+ !settings.disableRegistration && !settings.disablePasswordRegistration,
+ guestAccess: settings.hasGuestAccess,
+ workspaceCreation: !settings.disableWorkspaceCreation,
+ providers,
+ };
+}
diff --git a/apps/api/src/admin/system/list-integration-providers.ts b/apps/api/src/admin/system/list-integration-providers.ts
new file mode 100644
index 000000000..47b76f660
--- /dev/null
+++ b/apps/api/src/admin/system/list-integration-providers.ts
@@ -0,0 +1,62 @@
+import { count, eq } from "drizzle-orm";
+import db from "../../database";
+import { integrationTable } from "../../database/schema";
+import { integrationPlugins } from "../../plugins";
+import { resolveGithubPrivateKey } from "../../plugins/github/utils/github-app";
+import { credentialSetStatus } from "./credential-set-status";
+import type { ServiceStatus } from "./service-status";
+import { withTimeout } from "./with-timeout";
+
+type IntegrationProvider = {
+ type: string;
+ name: string;
+ status: ServiceStatus;
+ requiresInstanceSetup: boolean;
+ connectedProjects: number | null;
+};
+
+// Only the GitHub App is set up on the instance. Every other provider is
+// connected per project with that project's own credentials.
+function instanceSetupStatus(type: string): ServiceStatus | null {
+ if (type !== "github") return null;
+ return credentialSetStatus([
+ process.env.GITHUB_APP_ID,
+ process.env.GITHUB_WEBHOOK_SECRET,
+ resolveGithubPrivateKey(),
+ ]);
+}
+
+async function countConnectedProjects(timeoutMs: number) {
+ try {
+ const rows = await withTimeout(
+ () =>
+ db
+ .select({ type: integrationTable.type, value: count() })
+ .from(integrationTable)
+ .where(eq(integrationTable.isActive, true))
+ .groupBy(integrationTable.type),
+ timeoutMs,
+ );
+ return new Map(rows.map((row) => [row.type, row.value]));
+ } catch {
+ return null;
+ }
+}
+
+export async function listIntegrationProviders(
+ timeoutMs: number,
+): Promise<IntegrationProvider[]> {
+ // Without the database the providers are still listed, with unknown counts.
+ const connected = await countConnectedProjects(timeoutMs);
+
+ return integrationPlugins.map(({ type, name }) => {
+ const setup = instanceSetupStatus(type);
+ return {
+ type,
+ name,
+ status: setup ?? "ok",
+ requiresInstanceSetup: setup !== null,
+ connectedProjects: connected ? (connected.get(type) ?? 0) : null,
+ };
+ });
+}
diff --git a/apps/api/src/admin/system/probe-database.ts b/apps/api/src/admin/system/probe-database.ts
new file mode 100644
index 000000000..2a3da646e
--- /dev/null
+++ b/apps/api/src/admin/system/probe-database.ts
@@ -0,0 +1,57 @@
+import { sql } from "drizzle-orm";
+import db from "../../database";
+import { safeErrorCode } from "./safe-error-code";
+import type { ServiceStatus } from "./service-status";
+import { withTimeout } from "./with-timeout";
+
+type DatabaseProbe = {
+ status: ServiceStatus;
+ serverVersion: string | null;
+ latencyMs: number | null;
+ migrationsApplied: number | null;
+ errorCode: string | null;
+};
+
+async function countAppliedMigrations(timeoutMs: number) {
+ try {
+ const result = await withTimeout(
+ () =>
+ db.execute<{ applied: number }>(
+ sql`select count(*)::int as applied from drizzle.__drizzle_migrations`,
+ ),
+ timeoutMs,
+ );
+ return result.rows[0]?.applied ?? null;
+ } catch {
+ return null;
+ }
+}
+
+export async function probeDatabase(timeoutMs: number): Promise<DatabaseProbe> {
+ const started = performance.now();
+ try {
+ const result = await withTimeout(
+ () =>
+ db.execute<{ version: string }>(
+ sql`select current_setting('server_version') as version`,
+ ),
+ timeoutMs,
+ );
+ const latencyMs = Math.round(performance.now() - started);
+ return {
+ status: "ok",
+ serverVersion: result.rows[0]?.version ?? null,
+ latencyMs,
+ migrationsApplied: await countAppliedMigrations(timeoutMs),
+ errorCode: null,
+ };
+ } catch (error) {
+ return {
+ status: "down",
+ serverVersion: null,
+ latencyMs: null,
+ migrationsApplied: null,
+ errorCode: safeErrorCode(error),
+ };
+ }
+}
diff --git a/apps/api/src/admin/system/probe-email.ts b/apps/api/src/admin/system/probe-email.ts
new file mode 100644
index 000000000..d70f1c7fe
--- /dev/null
+++ b/apps/api/src/admin/system/probe-email.ts
@@ -0,0 +1,33 @@
+import { verifySmtpConnection } from "@kaneo/email";
+import { safeErrorCode } from "./safe-error-code";
+import type { ServiceStatus } from "./service-status";
+import { withTimeout } from "./with-timeout";
+
+type EmailProbe = {
+ status: ServiceStatus;
+ configured: boolean;
+ errorCode: string | null;
+};
+
+export async function probeEmail(timeoutMs: number): Promise<EmailProbe> {
+ try {
+ // nodemailer bounds each phase itself; the outer limit covers DNS.
+ const result = await withTimeout(
+ () => verifySmtpConnection(timeoutMs),
+ timeoutMs + 500,
+ );
+ if (result.status === "not_configured") {
+ return { status: "not_configured", configured: false, errorCode: null };
+ }
+ if (result.status === "ok") {
+ return { status: "ok", configured: true, errorCode: null };
+ }
+ return { status: "down", configured: true, errorCode: result.code };
+ } catch (error) {
+ return {
+ status: "down",
+ configured: true,
+ errorCode: safeErrorCode(error),
+ };
+ }
+}
diff --git a/apps/api/src/admin/system/probe-redis.ts b/apps/api/src/admin/system/probe-redis.ts
new file mode 100644
index 000000000..c8380c736
--- /dev/null
+++ b/apps/api/src/admin/system/probe-redis.ts
@@ -0,0 +1,32 @@
+import { getRedisPub, isRedisConfigured, resolveRedisMode } from "../../redis";
+import { safeErrorCode } from "./safe-error-code";
+import type { ServiceStatus } from "./service-status";
+import { withTimeout } from "./with-timeout";
+
+type RedisProbe = {
+ status: ServiceStatus;
+ mode: "standalone" | "sentinel" | "cluster" | null;
+ errorCode: string | null;
+};
+
+// Redis only fans realtime events out across API instances. A single
+// instance runs without it, so "not configured" is a healthy answer.
+export async function probeRedis(timeoutMs: number): Promise<RedisProbe> {
+ if (!isRedisConfigured()) {
+ return { status: "not_configured", mode: null, errorCode: null };
+ }
+
+ let mode: RedisProbe["mode"];
+ try {
+ mode = resolveRedisMode().mode;
+ } catch {
+ return { status: "down", mode: null, errorCode: "INVALID_CONFIG" };
+ }
+
+ try {
+ await withTimeout(() => getRedisPub().ping(), timeoutMs);
+ return { status: "ok", mode, errorCode: null };
+ } catch (error) {
+ return { status: "down", mode, errorCode: safeErrorCode(error) };
+ }
+}
diff --git a/apps/api/src/admin/system/probe-storage.test.ts b/apps/api/src/admin/system/probe-storage.test.ts
new file mode 100644
index 000000000..dacf5a0bf
--- /dev/null
+++ b/apps/api/src/admin/system/probe-storage.test.ts
@@ -0,0 +1,21 @@
+import { describe, expect, it } from "vite-plus/test";
+import { storageFailureStatus } from "./probe-storage";
+
+describe("storageFailureStatus", () => {
+ it("warns when the bucket refuses to be listed", () => {
+ expect(storageFailureStatus({ $metadata: { httpStatusCode: 403 } })).toBe(
+ "warning",
+ );
+ });
+
+ it("is down for a missing bucket or an unreachable endpoint", () => {
+ expect(storageFailureStatus({ $metadata: { httpStatusCode: 404 } })).toBe(
+ "down",
+ );
+ expect(
+ storageFailureStatus(
+ Object.assign(new Error(), { code: "ECONNREFUSED" }),
+ ),
+ ).toBe("down");
+ });
+});
diff --git a/apps/api/src/admin/system/probe-storage.ts b/apps/api/src/admin/system/probe-storage.ts
new file mode 100644
index 000000000..6d10bf056
--- /dev/null
+++ b/apps/api/src/admin/system/probe-storage.ts
@@ -0,0 +1,52 @@
+import { headStorageBucket, isStorageConfigured } from "../../storage/s3";
+import { safeErrorCode } from "./safe-error-code";
+import type { ServiceStatus } from "./service-status";
+import { withTimeout } from "./with-timeout";
+
+type StorageProbe = {
+ status: ServiceStatus;
+ configured: boolean;
+ errorCode: string | null;
+};
+
+const STORAGE_ENV = [
+ "S3_ENDPOINT",
+ "S3_BUCKET",
+ "S3_ACCESS_KEY_ID",
+ "S3_SECRET_ACCESS_KEY",
+];
+
+function httpStatus(error: unknown) {
+ const status = (error as { $metadata?: { httpStatusCode?: unknown } })
+ ?.$metadata?.httpStatusCode;
+ return typeof status === "number" ? status : undefined;
+}
+
+/**
+ * A 403 means the bucket answered but these credentials may not list it,
+ * which upload-only IAM policies do on purpose. Report that as a warning.
+ */
+export function storageFailureStatus(error: unknown): ServiceStatus {
+ return httpStatus(error) === 403 ? "warning" : "down";
+}
+
+export async function probeStorage(timeoutMs: number): Promise<StorageProbe> {
+ if (!isStorageConfigured()) {
+ const partlySet = STORAGE_ENV.some((name) => process.env[name]?.trim());
+ return partlySet
+ ? { status: "warning", configured: false, errorCode: "INCOMPLETE_CONFIG" }
+ : { status: "not_configured", configured: false, errorCode: null };
+ }
+
+ try {
+ await withTimeout((signal) => headStorageBucket(signal), timeoutMs);
+ return { status: "ok", configured: true, errorCode: null };
+ } catch (error) {
+ const status = httpStatus(error);
+ return {
+ status: storageFailureStatus(error),
+ configured: true,
+ errorCode: status ? `HTTP_${status}` : safeErrorCode(error),
+ };
+ }
+}
diff --git a/apps/api/src/admin/system/realtime-status.test.ts b/apps/api/src/admin/system/realtime-status.test.ts
new file mode 100644
index 000000000..a62a92a63
--- /dev/null
+++ b/apps/api/src/admin/system/realtime-status.test.ts
@@ -0,0 +1,26 @@
+import { describe, expect, it } from "vite-plus/test";
+import { realtimeStatus } from "./realtime-status";
+
+describe("realtimeStatus", () => {
+ it("is healthy on a single instance without Redis", () => {
+ expect(
+ realtimeStatus({ adapter: "in-memory", redisStatus: "not_configured" }),
+ ).toBe("ok");
+ });
+
+ it("is healthy when Redis fan-out answers", () => {
+ expect(realtimeStatus({ adapter: "redis", redisStatus: "ok" })).toBe("ok");
+ });
+
+ it("warns when Redis fan-out is down but local sockets still work", () => {
+ expect(realtimeStatus({ adapter: "redis", redisStatus: "down" })).toBe(
+ "warning",
+ );
+ });
+
+ it("is down before the WebSocket adapter starts", () => {
+ expect(
+ realtimeStatus({ adapter: null, redisStatus: "not_configured" }),
+ ).toBe("down");
+ });
+});
diff --git a/apps/api/src/admin/system/realtime-status.ts b/apps/api/src/admin/system/realtime-status.ts
new file mode 100644
index 000000000..30812e684
--- /dev/null
+++ b/apps/api/src/admin/system/realtime-status.ts
@@ -0,0 +1,19 @@
+import type { ServiceStatus } from "./service-status";
+
+type RealtimeStatusInput = {
+ adapter: "redis" | "in-memory" | null;
+ redisStatus: ServiceStatus;
+};
+
+/**
+ * Sockets on this instance keep working while Redis is down; only delivery
+ * to clients on other instances stops. Without an adapter nothing is sent.
+ */
+export function realtimeStatus({
+ adapter,
+ redisStatus,
+}: RealtimeStatusInput): ServiceStatus {
+ if (adapter === null) return "down";
+ if (adapter === "redis" && redisStatus !== "ok") return "warning";
+ return "ok";
+}
diff --git a/apps/api/src/admin/system/response.ts b/apps/api/src/admin/system/response.ts
new file mode 100644
index 000000000..78ce92854
--- /dev/null
+++ b/apps/api/src/admin/system/response.ts
@@ -0,0 +1,96 @@
+import { z } from "../../openapi";
+import { serviceStatusSchema } from "./service-status";
+
+const errorCode = z.string().nullable().openapi({
+ description:
+ "Short failure category such as TIMEOUT, ECONNREFUSED or HTTP_403. Never contains hosts, credentials or server messages.",
+});
+
+export const adminSystemStatusSchema = z
+ .object({
+ checkedAt: z.string().openapi({ format: "date-time" }),
+ version: z.string().nullable().openapi({
+ description: "Kaneo release version of this API instance.",
+ }),
+ api: z.object({
+ status: serviceStatusSchema,
+ uptimeSeconds: z.number().int(),
+ nodeVersion: z.string(),
+ }),
+ database: z.object({
+ status: serviceStatusSchema,
+ serverVersion: z.string().nullable(),
+ latencyMs: z.number().int().nullable(),
+ migrationsApplied: z.number().int().nullable(),
+ errorCode,
+ }),
+ realtime: z.object({
+ status: serviceStatusSchema,
+ adapter: z.enum(["in-memory", "redis"]).nullable().openapi({
+ description:
+ "How events reach WebSocket clients: in-memory for a single instance, redis to fan out across instances. Null before WebSockets start.",
+ }),
+ connections: z.number().int().openapi({
+ description: "Open WebSocket connections on this API instance.",
+ }),
+ connectedUsers: z.number().int().openapi({
+ description:
+ "Distinct people with an open connection to this instance.",
+ }),
+ }),
+ redis: z.object({
+ status: serviceStatusSchema,
+ mode: z.enum(["standalone", "sentinel", "cluster"]).nullable(),
+ errorCode,
+ }),
+ email: z.object({
+ status: serviceStatusSchema,
+ configured: z.boolean(),
+ errorCode,
+ }),
+ storage: z.object({
+ status: serviceStatusSchema,
+ configured: z.boolean(),
+ errorCode,
+ }),
+ auth: z.object({
+ passwordSignIn: z.boolean(),
+ emailOtpSignIn: z.boolean(),
+ registration: z.boolean(),
+ passwordRegistration: z.boolean(),
+ guestAccess: z.boolean(),
+ workspaceCreation: z.boolean(),
+ providers: z.array(
+ z.object({
+ id: z.enum(["github", "google", "discord", "custom"]),
+ name: z.string(),
+ status: serviceStatusSchema,
+ }),
+ ),
+ }),
+ integrations: z.array(
+ z.object({
+ type: z.string(),
+ name: z.string(),
+ status: serviceStatusSchema,
+ requiresInstanceSetup: z.boolean().openapi({
+ description:
+ "Whether the provider needs instance settings. Others are connected per project.",
+ }),
+ connectedProjects: z.number().int().nullable().openapi({
+ description:
+ "Projects with an active connection to this provider. Null when the database could not be read.",
+ }),
+ }),
+ ),
+ })
+ .openapi("AdminSystemStatus");
+
+export const adminTestEmailResultSchema = z
+ .object({
+ sent: z.literal(true),
+ to: z.string().openapi({
+ description: "The administrator's own address, the only recipient.",
+ }),
+ })
+ .openapi("AdminTestEmailResult");
diff --git a/apps/api/src/admin/system/safe-error-code.test.ts b/apps/api/src/admin/system/safe-error-code.test.ts
new file mode 100644
index 000000000..3177df468
--- /dev/null
+++ b/apps/api/src/admin/system/safe-error-code.test.ts
@@ -0,0 +1,31 @@
+import { describe, expect, it } from "vite-plus/test";
+import { safeErrorCode } from "./safe-error-code";
+import { ProbeTimeoutError } from "./with-timeout";
+
+describe("safeErrorCode", () => {
+ it("names timeouts", () => {
+ expect(safeErrorCode(new ProbeTimeoutError())).toBe("TIMEOUT");
+ });
+
+ it("keeps driver codes and specific error names", () => {
+ expect(
+ safeErrorCode(Object.assign(new Error("x"), { code: "ECONNREFUSED" })),
+ ).toBe("ECONNREFUSED");
+ expect(
+ safeErrorCode(Object.assign(new Error("x"), { code: "28P01" })),
+ ).toBe("28P01");
+ const notFound = new Error("bucket missing");
+ notFound.name = "NoSuchBucket";
+ expect(safeErrorCode(notFound)).toBe("NoSuchBucket");
+ });
+
+ it("never returns the message or malformed codes", () => {
+ const error = Object.assign(
+ new Error("password authentication failed for user admin"),
+ { code: "connect to redis://:hunter2@cache:6379 failed" },
+ );
+ expect(safeErrorCode(error)).toBe("UNKNOWN");
+ expect(safeErrorCode("redis://:hunter2@cache")).toBe("UNKNOWN");
+ expect(safeErrorCode(null)).toBe("UNKNOWN");
+ });
+});
diff --git a/apps/api/src/admin/system/safe-error-code.ts b/apps/api/src/admin/system/safe-error-code.ts
new file mode 100644
index 000000000..4624851a3
--- /dev/null
+++ b/apps/api/src/admin/system/safe-error-code.ts
@@ -0,0 +1,19 @@
+import { ProbeTimeoutError } from "./with-timeout";
+
+const CODE_PATTERN = /^[A-Za-z0-9][A-Za-z0-9_.-]{0,63}$/;
+
+/**
+ * A short identifier for a failed probe. Driver messages can include hosts,
+ * user names or credentials, so only well-formed codes and error names are
+ * kept; anything else becomes UNKNOWN.
+ */
+export function safeErrorCode(error: unknown): string {
+ if (error instanceof ProbeTimeoutError) return "TIMEOUT";
+ if (typeof error !== "object" || error === null) return "UNKNOWN";
+ const { code, name } = error as { code?: unknown; name?: unknown };
+ if (typeof code === "string" && CODE_PATTERN.test(code)) return code;
+ if (typeof name === "string" && name !== "Error" && CODE_PATTERN.test(name)) {
+ return name;
+ }
+ return "UNKNOWN";
+}
diff --git a/apps/api/src/admin/system/service-status.ts b/apps/api/src/admin/system/service-status.ts
new file mode 100644
index 000000000..419adbf94
--- /dev/null
+++ b/apps/api/src/admin/system/service-status.ts
@@ -0,0 +1,15 @@
+import { z } from "../../openapi";
+
+export const SERVICE_STATUSES = [
+ "ok",
+ "warning",
+ "not_configured",
+ "down",
+] as const;
+
+export type ServiceStatus = (typeof SERVICE_STATUSES)[number];
+
+export const serviceStatusSchema = z.enum(SERVICE_STATUSES).openapi({
+ description:
+ "ok: working. warning: works with a problem, or is only partly configured. not_configured: optional and switched off, which is a healthy state. down: configured but not reachable.",
+});
diff --git a/apps/api/src/admin/system/with-timeout.test.ts b/apps/api/src/admin/system/with-timeout.test.ts
new file mode 100644
index 000000000..22386ec6d
--- /dev/null
+++ b/apps/api/src/admin/system/with-timeout.test.ts
@@ -0,0 +1,32 @@
+import { describe, expect, it } from "vite-plus/test";
+import { ProbeTimeoutError, withTimeout } from "./with-timeout";
+
+describe("withTimeout", () => {
+ it("returns the result when the work finishes in time", async () => {
+ await expect(withTimeout(async () => "ok", 50)).resolves.toBe("ok");
+ });
+
+ it("passes the work's own error through", async () => {
+ await expect(
+ withTimeout(async () => {
+ throw new Error("boom");
+ }, 50),
+ ).rejects.toThrow("boom");
+ });
+
+ it("rejects and aborts the work when it takes too long", async () => {
+ let aborted = false;
+ const result = withTimeout(
+ (signal) =>
+ new Promise((_, reject) => {
+ signal.addEventListener("abort", () => {
+ aborted = true;
+ reject(new Error("late failure"));
+ });
+ }),
+ 10,
+ );
+ await expect(result).rejects.toBeInstanceOf(ProbeTimeoutError);
+ expect(aborted).toBe(true);
+ });
+});
diff --git a/apps/api/src/admin/system/with-timeout.ts b/apps/api/src/admin/system/with-timeout.ts
new file mode 100644
index 000000000..f89f77d5e
--- /dev/null
+++ b/apps/api/src/admin/system/with-timeout.ts
@@ -0,0 +1,30 @@
+export class ProbeTimeoutError extends Error {
+ constructor() {
+ super("Timed out");
+ this.name = "ProbeTimeoutError";
+ }
+}
+
+/**
+ * Resolve with `work`, or reject with ProbeTimeoutError after `ms`. The
+ * abandoned promise keeps running, so its later rejection is swallowed here
+ * instead of surfacing as an unhandled rejection.
+ */
+export function withTimeout<T>(
+ work: (signal: AbortSignal) => Promise<T>,
+ ms: number,
+): Promise<T> {
+ const controller = new AbortController();
+ let timer: ReturnType<typeof setTimeout> | undefined;
+ const pending = work(controller.signal);
+ pending.catch(() => {});
+ const timeout = new Promise<never>((_, reject) => {
+ timer = setTimeout(() => {
+ // Settle first: aborting can reject `work` synchronously, and that
+ // abort error must not win the race over the timeout.
+ reject(new ProbeTimeoutError());
+ controller.abort();
+ }, ms);
+ });
+ return Promise.race([pending, timeout]).finally(() => clearTimeout(timer));
+}
diff --git a/apps/api/src/app-version.ts b/apps/api/src/app-version.ts
new file mode 100644
index 000000000..161479196
--- /dev/null
+++ b/apps/api/src/app-version.ts
@@ -0,0 +1,24 @@
+import { readFileSync } from "node:fs";
+
+/**
+ * The release version from the root package.json. This file and the bundled
+ * dist/index.js both sit one level below apps/api, so the same relative path
+ * works in development and in the Docker image.
+ */
+function loadAppVersion(): string | null {
+ try {
+ const pkg = JSON.parse(
+ readFileSync(new URL("../../../package.json", import.meta.url), "utf8"),
+ );
+ return typeof pkg.version === "string" ? pkg.version : null;
+ } catch {
+ return null;
+ }
+}
+
+let cached: { version: string | null } | undefined;
+
+export function readAppVersion(): string | null {
+ cached ??= { version: loadAppVersion() };
+ return cached.version;
+}
diff --git a/apps/api/src/instrument.ts b/apps/api/src/instrument.ts
index b368c2cd9..fa871ab3a 100644
--- a/apps/api/src/instrument.ts
+++ b/apps/api/src/instrument.ts
@@ -1,6 +1,6 @@
-import { readFileSync } from "node:fs";
import * as Sentry from "@sentry/node";
import { nodeProfilingIntegration } from "@sentry/profiling-node";
+import { readAppVersion } from "./app-version";
import { isSensitiveOutboundRequest } from "./utils/sensitive-outbound";
function parseSampleRate(value: string | undefined) {
@@ -14,23 +14,12 @@ const profilesSampleRate = parseSampleRate(
process.env.SENTRY_PROFILES_SAMPLE_RATE,
);
-function readAppVersion() {
- try {
- const pkg = JSON.parse(
- readFileSync(new URL("../../../package.json", import.meta.url), "utf8"),
- );
- return typeof pkg.version === "string" ? pkg.version : undefined;
- } catch {
- return undefined;
- }
-}
-
if (process.env.SENTRY_DSN) {
Sentry.init({
dsn: process.env.SENTRY_DSN,
environment:
process.env.SENTRY_ENVIRONMENT ?? process.env.NODE_ENV ?? "production",
- release: process.env.SENTRY_RELEASE ?? readAppVersion(),
+ release: process.env.SENTRY_RELEASE ?? readAppVersion() ?? undefined,
dataCollection: {
userInfo: false,
cookies: false,
diff --git a/apps/api/src/plugins/index.ts b/apps/api/src/plugins/index.ts
index f05e8695e..fb46fca39 100644
--- a/apps/api/src/plugins/index.ts
+++ b/apps/api/src/plugins/index.ts
@@ -8,17 +8,23 @@ import { initializeEventSubscriptions, registerPlugin } from "./registry";
import { slackPlugin } from "./slack";
import { telegramPlugin } from "./telegram";
+export const integrationPlugins = [
+ githubPlugin,
+ giteaPlugin,
+ gitlabPlugin,
+ slackPlugin,
+ mattermostPlugin,
+ discordPlugin,
+ genericWebhookPlugin,
+ telegramPlugin,
+];
+
export function initializePlugins() {
console.log("Initializing plugins...");
- registerPlugin(githubPlugin);
- registerPlugin(giteaPlugin);
- registerPlugin(gitlabPlugin);
- registerPlugin(slackPlugin);
- registerPlugin(mattermostPlugin);
- registerPlugin(discordPlugin);
- registerPlugin(genericWebhookPlugin);
- registerPlugin(telegramPlugin);
+ for (const plugin of integrationPlugins) {
+ registerPlugin(plugin);
+ }
initializeGitHubPlugin();
initializeEventSubscriptions();
diff --git a/apps/api/src/storage/s3.ts b/apps/api/src/storage/s3.ts
index b22191288..8d04d5ab8 100644
--- a/apps/api/src/storage/s3.ts
+++ b/apps/api/src/storage/s3.ts
@@ -3,6 +3,7 @@ import {
CopyObjectCommand,
DeleteObjectCommand,
GetObjectCommand,
+ HeadBucketCommand,
type HeadObjectCommandOutput,
PutObjectCommand,
S3Client,
@@ -495,6 +496,17 @@ export function isStorageConfigured() {
}
}
+/** Check that the bucket answers with the configured credentials. */
+export async function headStorageBucket(abortSignal: AbortSignal) {
+ const config = getStorageConfig();
+ await getClient(config).send(
+ new HeadBucketCommand({ Bucket: config.bucket }),
+ {
+ abortSignal,
+ },
+ );
+}
+
export function assertTaskImageKeyMatchesContext(
key: string,
context: Omit<TaskImageUploadContext, "filename" | "contentType">,
diff --git a/apps/api/src/ws/index.ts b/apps/api/src/ws/index.ts
index 49539dd56..4a61209ab 100644
--- a/apps/api/src/ws/index.ts
+++ b/apps/api/src/ws/index.ts
@@ -249,6 +249,33 @@ const projectBroadcastTimeouts = new Map<
let adapter: BroadcastAdapter | null = null;
+/** Open sockets on this API instance, for the admin system page. */
+export function getLocalRealtimeStats() {
+ const users = new Set<string>();
+ let connections = 0;
+ for (const [userId, sockets] of userConnections) {
+ if (sockets.size === 0) continue;
+ users.add(userId);
+ connections += sockets.size;
+ }
+ for (const sockets of projectConnections.values()) {
+ for (const socket of sockets) {
+ users.add(socket.userId);
+ connections += 1;
+ }
+ }
+ return {
+ adapter:
+ adapter === null
+ ? null
+ : adapter instanceof RedisBroadcastAdapter
+ ? ("redis" as const)
+ : ("in-memory" as const),
+ connections,
+ connectedUsers: users.size,
+ };
+}
+
// --- Subscribe to incoming broadcasts and deliver to local connections ---
export async function initializeWebSocketAdapter() {
if (adapter) return;
diff --git a/apps/docs/openapi.json b/apps/docs/openapi.json
index d7cabdc6c..96cbe27ae 100644
--- a/apps/docs/openapi.json
+++ b/apps/docs/openapi.json
@@ -5619,6 +5619,375 @@
"joinedAt"
]
},
+ "AdminSystemStatus": {
+ "type": "object",
+ "properties": {
+ "checkedAt": {
+ "type": "string",
+ "format": "date-time"
+ },
+ "version": {
+ "type": [
+ "string",
+ "null"
+ ],
+ "description": "Kaneo release version of this API instance."
+ },
+ "api": {
+ "type": "object",
+ "properties": {
+ "status": {
+ "type": "string",
+ "enum": [
+ "ok",
+ "warning",
+ "not_configured",
+ "down"
+ ],
+ "description": "ok: working. warning: works with a problem, or is only partly configured. not_configured: optional and switched off, which is a healthy state. down: configured but not reachable."
+ },
+ "uptimeSeconds": {
+ "type": "integer"
+ },
+ "nodeVersion": {
+ "type": "string"
+ }
+ },
+ "required": [
+ "status",
+ "uptimeSeconds",
+ "nodeVersion"
+ ]
+ },
+ "database": {
+ "type": "object",
+ "properties": {
+ "status": {
+ "type": "string",
+ "enum": [
+ "ok",
+ "warning",
+ "not_configured",
+ "down"
+ ],
+ "description": "ok: working. warning: works with a problem, or is only partly configured. not_configured: optional and switched off, which is a healthy state. down: configured but not reachable."
+ },
+ "serverVersion": {
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "latencyMs": {
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "migrationsApplied": {
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "errorCode": {
+ "type": [
+ "string",
+ "null"
+ ],
+ "description": "Short failure category such as TIMEOUT, ECONNREFUSED or HTTP_403. Never contains hosts, credentials or server messages."
+ }
+ },
+ "required": [
+ "status",
+ "serverVersion",
+ "latencyMs",
+ "migrationsApplied",
+ "errorCode"
+ ]
+ },
+ "realtime": {
+ "type": "object",
+ "properties": {
+ "status": {
+ "type": "string",
+ "enum": [
+ "ok",
+ "warning",
+ "not_configured",
+ "down"
+ ],
+ "description": "ok: working. warning: works with a problem, or is only partly configured. not_configured: optional and switched off, which is a healthy state. down: configured but not reachable."
+ },
+ "adapter": {
+ "type": [
+ "string",
+ "null"
+ ],
+ "enum": [
+ "in-memory",
+ "redis",
+ null
+ ],
+ "description": "How events reach WebSocket clients: in-memory for a single instance, redis to fan out across instances. Null before WebSockets start."
+ },
+ "connections": {
+ "type": "integer",
+ "description": "Open WebSocket connections on this API instance."
+ },
+ "connectedUsers": {
+ "type": "integer",
+ "description": "Distinct people with an open connection to this instance."
+ }
+ },
+ "required": [
+ "status",
+ "adapter",
+ "connections",
+ "connectedUsers"
+ ]
+ },
+ "redis": {
+ "type": "object",
+ "properties": {
+ "status": {
+ "type": "string",
+ "enum": [
+ "ok",
+ "warning",
+ "not_configured",
+ "down"
+ ],
+ "description": "ok: working. warning: works with a problem, or is only partly configured. not_configured: optional and switched off, which is a healthy state. down: configured but not reachable."
+ },
+ "mode": {
+ "type": [
+ "string",
+ "null"
+ ],
+ "enum": [
+ "standalone",
+ "sentinel",
+ "cluster",
+ null
+ ]
+ },
+ "errorCode": {
+ "type": [
+ "string",
+ "null"
+ ],
+ "description": "Short failure category such as TIMEOUT, ECONNREFUSED or HTTP_403. Never contains hosts, credentials or server messages."
+ }
+ },
+ "required": [
+ "status",
+ "mode",
+ "errorCode"
+ ]
+ },
+ "email": {
+ "type": "object",
+ "properties": {
+ "status": {
+ "type": "string",
+ "enum": [
+ "ok",
+ "warning",
+ "not_configured",
+ "down"
+ ],
+ "description": "ok: working. warning: works with a problem, or is only partly configured. not_configured: optional and switched off, which is a healthy state. down: configured but not reachable."
+ },
+ "configured": {
+ "type": "boolean"
+ },
+ "errorCode": {
+ "type": [
+ "string",
+ "null"
+ ],
+ "description": "Short failure category such as TIMEOUT, ECONNREFUSED or HTTP_403. Never contains hosts, credentials or server messages."
+ }
+ },
+ "required": [
+ "status",
+ "configured",
+ "errorCode"
+ ]
+ },
+ "storage": {
+ "type": "object",
+ "properties": {
+ "status": {
+ "type": "string",
+ "enum": [
+ "ok",
+ "warning",
+ "not_configured",
+ "down"
+ ],
+ "description": "ok: working. warning: works with a problem, or is only partly configured. not_configured: optional and switched off, which is a healthy state. down: configured but not reachable."
+ },
+ "configured": {
+ "type": "boolean"
+ },
+ "errorCode": {
+ "type": [
+ "string",
+ "null"
+ ],
+ "description": "Short failure category such as TIMEOUT, ECONNREFUSED or HTTP_403. Never contains hosts, credentials or server messages."
+ }
+ },
+ "required": [
+ "status",
+ "configured",
+ "errorCode"
+ ]
+ },
+ "auth": {
+ "type": "object",
+ "properties": {
+ "passwordSignIn": {
+ "type": "boolean"
+ },
+ "emailOtpSignIn": {
+ "type": "boolean"
+ },
+ "registration": {
+ "type": "boolean"
+ },
+ "passwordRegistration": {
+ "type": "boolean"
+ },
+ "guestAccess": {
+ "type": "boolean"
+ },
+ "workspaceCreation": {
+ "type": "boolean"
+ },
+ "providers": {
+ "type": "array",
+ "items": {
+ "type": "object",
+ "properties": {
+ "id": {
+ "type": "string",
+ "enum": [
+ "github",
+ "google",
+ "discord",
+ "custom"
+ ]
+ },
+ "name": {
+ "type": "string"
+ },
+ "status": {
+ "type": "string",
+ "enum": [
+ "ok",
+ "warning",
+ "not_configured",
+ "down"
+ ],
+ "description": "ok: working. warning: works with a problem, or is only partly configured. not_configured: optional and switched off, which is a healthy state. down: configured but not reachable."
+ }
+ },
+ "required": [
+ "id",
+ "name",
+ "status"
+ ]
+ }
+ }
+ },
+ "required": [
+ "passwordSignIn",
+ "emailOtpSignIn",
+ "registration",
+ "passwordRegistration",
+ "guestAccess",
+ "workspaceCreation",
+ "providers"
+ ]
+ },
+ "integrations": {
+ "type": "array",
+ "items": {
+ "type": "object",
+ "properties": {
+ "type": {
+ "type": "string"
+ },
+ "name": {
+ "type": "string"
+ },
+ "status": {
+ "type": "string",
+ "enum": [
+ "ok",
+ "warning",
+ "not_configured",
+ "down"
+ ],
+ "description": "ok: working. warning: works with a problem, or is only partly configured. not_configured: optional and switched off, which is a healthy state. down: configured but not reachable."
+ },
+ "requiresInstanceSetup": {
+ "type": "boolean",
+ "description": "Whether the provider needs instance settings. Others are connected per project."
+ },
+ "connectedProjects": {
+ "type": [
+ "integer",
+ "null"
+ ],
+ "description": "Projects with an active connection to this provider. Null when the database could not be read."
+ }
+ },
+ "required": [
+ "type",
+ "name",
+ "status",
+ "requiresInstanceSetup",
+ "connectedProjects"
+ ]
+ }
+ }
+ },
+ "required": [
+ "checkedAt",
+ "version",
+ "api",
+ "database",
+ "realtime",
+ "redis",
+ "email",
+ "storage",
+ "auth",
+ "integrations"
+ ]
+ },
+ "AdminTestEmailResult": {
+ "type": "object",
+ "properties": {
+ "sent": {
+ "type": "boolean",
+ "enum": [
+ true
+ ]
+ },
+ "to": {
+ "type": "string",
+ "description": "The administrator's own address, the only recipient."
+ }
+ },
+ "required": [
+ "sent",
+ "to"
+ ]
+ },
"AdminAuditLog": {
"type": "object",
"properties": {
@@ -25236,6 +25605,123 @@
}
}
},
+ "/admin/system": {
+ "get": {
+ "operationId": "getAdminSystemStatus",
+ "tags": [
+ "Admin"
+ ],
+ "summary": "Get system status",
+ "description": "Check this API instance and the services it uses: version, uptime, database, WebSockets, Redis fan-out, SMTP, object storage, sign-in providers and integration providers. Each check gives up after a few seconds, so one unreachable service can't block the response. Only statuses, counts and short error categories are returned, never hosts, credentials or secrets. Requires an instance administrator session; API keys are rejected.",
+ "responses": {
+ "200": {
+ "description": "Status of this instance",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/AdminSystemStatus"
+ }
+ }
+ }
+ },
+ "401": {
+ "description": "Missing or invalid credentials",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ApiError"
+ }
+ }
+ }
+ },
+ "403": {
+ "description": "The caller is not an instance administrator or is authenticated with an API key",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ApiError"
+ }
+ }
+ }
+ },
+ "429": {
+ "$ref": "#/components/responses/ApiKeyRateLimited"
+ }
+ }
+ }
+ },
+ "/admin/system/test-email": {
+ "post": {
+ "operationId": "sendAdminTestEmail",
+ "tags": [
+ "Admin"
+ ],
+ "summary": "Send a test email",
+ "description": "Send a test email to the calling administrator's own address to check the SMTP settings. There is no recipient parameter. Limited to 5 per administrator every 10 minutes on each API instance.",
+ "responses": {
+ "200": {
+ "description": "The mail server accepted the test email",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/AdminTestEmailResult"
+ }
+ }
+ }
+ },
+ "401": {
+ "description": "Missing or invalid credentials",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ApiError"
+ }
+ }
+ }
+ },
+ "403": {
+ "description": "The caller is not an instance administrator or is authenticated with an API key",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ApiError"
+ }
+ }
+ }
+ },
+ "409": {
+ "description": "SMTP is not configured on this instance",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ApiError"
+ }
+ }
+ }
+ },
+ "429": {
+ "description": "Too many test emails; retry after Retry-After seconds",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ApiError"
+ }
+ }
+ }
+ },
+ "502": {
+ "description": "The mail server did not accept the test email",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ApiError"
+ }
+ }
+ }
+ }
+ }
+ }
+ },
"/admin/workspaces/{workspaceId}/owner": {
"put": {
"operationId": "transferAdminWorkspaceOwnership",
diff --git a/tests/api-integration/admin-system-status.test.ts b/tests/api-integration/admin-system-status.test.ts
new file mode 100644
index 000000000..8cc852e6e
--- /dev/null
+++ b/tests/api-integration/admin-system-status.test.ts
@@ -0,0 +1,370 @@
+import { createHash, randomUUID } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { beforeEach, describe, expect, it, vi } from "vite-plus/test";
+import db, { schema } from "../../apps/api/src/database";
+import { mockAnonymousSession, mockAuthenticatedSession } from "./helpers/auth";
+import { createInstanceAdmin } from "./helpers/admin/create-instance-admin";
+import { resetTestDatabase } from "./helpers/database";
+import { createRestrictedWorkspace } from "./helpers/project-access/create-restricted-workspace";
+import { projectAccessApi } from "./helpers/project-access/project-access-api";
+
+const smtp = vi.hoisted(() => ({
+ configured: vi.fn(() => false),
+ send: vi.fn(async () => ({ success: true })),
+ verify: vi.fn(async () => ({ status: "not_configured" })),
+}));
+
+const redis = vi.hoisted(() => ({
+ ping: vi.fn(async () => "PONG"),
+}));
+
+vi.mock("@kaneo/email", async (importOriginal) => ({
+ ...(await importOriginal<Record<string, unknown>>()),
+ isSmtpConfigured: smtp.configured,
+ sendTestEmail: smtp.send,
+ verifySmtpConnection: smtp.verify,
+}));
+
+// Keeps the real configuration parsing but never opens a Redis connection.
+vi.mock("../../apps/api/src/redis", async (importOriginal) => ({
+ ...(await importOriginal<Record<string, unknown>>()),
+ getRedisPub: () => ({ ping: redis.ping }),
+}));
+
+beforeEach(async () => {
+ await resetTestDatabase();
+ smtp.configured.mockReset().mockReturnValue(false);
+ smtp.send.mockReset().mockResolvedValue({ success: true });
+ smtp.verify.mockReset().mockResolvedValue({ status: "not_configured" });
+ redis.ping.mockReset().mockResolvedValue("PONG");
+});
+
+type SystemStatus = {
+ version: string | null;
+ api: { status: string; uptimeSeconds: number };
+ database: {
+ status: string;
+ serverVersion: string | null;
+ migrationsApplied: number | null;
+ };
+ realtime: { status: string; connections: number };
+ redis: { status: string; mode: string | null; errorCode: string | null };
+ email: { status: string; configured: boolean; errorCode: string | null };
+ storage: { status: string; configured: boolean; errorCode: string | null };
+ auth: {
+ passwordSignIn: boolean;
+ registration: boolean;
+ providers: { id: string; name: string; status: string }[];
+ };
+ integrations: {
+ type: string;
+ status: string;
+ requiresInstanceSetup: boolean;
+ connectedProjects: number | null;
+ }[];
+};
+
+async function withEnv<T>(
+ values: Record<string, string>,
+ run: () => Promise<T>,
+): Promise<T> {
+ const previous = Object.fromEntries(
+ Object.keys(values).map((key) => [key, process.env[key]]),
+ );
+ Object.assign(process.env, values);
+ try {
+ return await run();
+ } finally {
+ for (const [key, value] of Object.entries(previous)) {
+ if (value === undefined) delete process.env[key];
+ else process.env[key] = value;
+ }
+ }
+}
+
+async function createAdminApiKey(userId: string) {
+ const key = `test_${randomUUID()}`;
+ await db.insert(schema.apikeyTable).values({
+ referenceId: userId,
+ userId,
+ key: createHash("sha256").update(key).digest("base64url"),
+ enabled: true,
+ createdAt: new Date(),
+ updatedAt: new Date(),
+ });
+ return key;
+}
+
+describe("admin system status", () => {
+ it("requires a signed-in instance administrator session", async () => {
+ mockAnonymousSession();
+ expect((await projectAccessApi()("/admin/system")).status).toBe(401);
+ expect(
+ (await projectAccessApi()("/admin/system/test-email", { method: "POST" }))
+ .status,
+ ).toBe(401);
+
+ const ctx = await createRestrictedWorkspace();
+ mockAuthenticatedSession(ctx.owner);
+ smtp.configured.mockReturnValue(true);
+ expect((await projectAccessApi()("/admin/system")).status).toBe(403);
+ expect(
+ (await projectAccessApi()("/admin/system/test-email", { method: "POST" }))
+ .status,
+ ).toBe(403);
+ expect(smtp.send).not.toHaveBeenCalled();
+ });
+
+ it("rejects API keys even when they belong to an administrator", async () => {
+ const admin = await createInstanceAdmin();
+ const key = await createAdminApiKey(admin.id);
+ mockAnonymousSession();
+ smtp.configured.mockReturnValue(true);
+ const request = projectAccessApi({ "x-api-key": key });
+
+ expect((await request("/admin/system")).status).toBe(403);
+ expect(
+ (await request("/admin/system/test-email", { method: "POST" })).status,
+ ).toBe(403);
+ expect(smtp.send).not.toHaveBeenCalled();
+ });
+
+ it("reports each service, treating optional ones as not configured", async () => {
+ const ctx = await createRestrictedWorkspace();
+ const activeProject = ctx.alpha;
+ const inactiveProject = ctx.beta;
+ await db.insert(schema.integrationTable).values([
+ { projectId: activeProject.id, type: "gitea", config: "{}" },
+ {
+ projectId: inactiveProject.id,
+ type: "gitea",
+ config: "{}",
+ isActive: false,
+ },
+ { projectId: inactiveProject.id, type: "slack", config: "{}" },
+ ]);
+ const admin = await createInstanceAdmin();
+ mockAuthenticatedSession(admin);
+
+ const response = await projectAccessApi()("/admin/system");
+
+ expect(response.status).toBe(200);
+ expect(response.headers.get("cache-control")).toBe("no-store");
+ const body = (await response.json()) as SystemStatus;
+ const rootPackage = JSON.parse(
+ readFileSync(new URL("../../package.json", import.meta.url), "utf8"),
+ ) as { version: string };
+ expect(body.version).toBe(rootPackage.version);
+ expect(body.api.status).toBe("ok");
+ expect(body.api.uptimeSeconds).toBeGreaterThanOrEqual(0);
+ expect(body.database.status).toBe("ok");
+ expect(body.database.serverVersion).toMatch(/^\d+/);
+ expect(body.database.migrationsApplied).toBeGreaterThan(0);
+ expect(body.redis).toEqual({
+ status: "not_configured",
+ mode: null,
+ errorCode: null,
+ });
+ expect(body.realtime.connections).toBe(0);
+ expect(body.email).toEqual({
+ status: "not_configured",
+ configured: false,
+ errorCode: null,
+ });
+ expect(body.storage).toEqual({
+ status: "not_configured",
+ configured: false,
+ errorCode: null,
+ });
+ expect(body.auth.passwordSignIn).toBe(true);
+ expect(body.auth.registration).toBe(true);
+ expect(body.auth.providers.map((provider) => provider.id)).toEqual([
+ "github",
+ "google",
+ "discord",
+ "custom",
+ ]);
+ expect(
+ body.auth.providers.every(
+ (provider) => provider.status === "not_configured",
+ ),
+ ).toBe(true);
+
+ const integrations = new Map(
+ body.integrations.map((provider) => [provider.type, provider]),
+ );
+ expect(integrations.get("gitea")).toMatchObject({
+ status: "ok",
+ requiresInstanceSetup: false,
+ connectedProjects: 1,
+ });
+ expect(integrations.get("slack")?.connectedProjects).toBe(1);
+ expect(integrations.get("github")).toMatchObject({
+ status: "not_configured",
+ requiresInstanceSetup: true,
+ connectedProjects: 0,
+ });
+ });
+
+ it("never returns configured secrets, and reports unreachable services as down", async () => {
+ const secrets = {
+ GOOGLE_CLIENT_ID: "google-client-id-value",
+ GOOGLE_CLIENT_SECRET: "google-secret-value",
+ DISCORD_CLIENT_ID: "discord-client-id-value",
+ GITHUB_OAUTH_CLIENT_ID: "github-oauth-id-value",
+ GITHUB_OAUTH_CLIENT_SECRET: "github-oauth-secret-value",
+ CUSTOM_OAUTH_CLIENT_ID: "oidc-client-id-value",
+ CUSTOM_OAUTH_CLIENT_SECRET: "oidc-secret-value",
+ CUSTOM_OAUTH_DISCOVERY_URL:
+ "https://oidc-user:[email protected]/.well-known/openid-configuration",
+ CUSTOM_OAUTH_NAME: "Company SSO",
+ GITHUB_APP_ID: "424242",
+ GITHUB_WEBHOOK_SECRET: "github-webhook-secret-value",
+ GITHUB_PRIVATE_KEY: "github-private-key-value",
+ REDIS_URL: "redis://:[email protected]:6379",
+ S3_ENDPOINT: "http://127.0.0.1:1",
+ S3_BUCKET: "private-bucket-name",
+ S3_ACCESS_KEY_ID: "s3-access-key-value",
+ S3_SECRET_ACCESS_KEY: "s3-secret-value",
+ };
+ smtp.configured.mockReturnValue(true);
+ smtp.verify.mockResolvedValue({ status: "failed", code: "EAUTH" });
+ redis.ping.mockRejectedValue(
+ Object.assign(
+ new Error(
+ "connect ECONNREFUSED redis://:[email protected]",
+ ),
+ { code: "ECONNREFUSED" },
+ ),
+ );
+ const admin = await createInstanceAdmin();
+ mockAuthenticatedSession(admin);
+
+ const response = await withEnv(secrets, () =>
+ projectAccessApi()("/admin/system"),
+ );
+
+ expect(response.status).toBe(200);
+ const text = await response.text();
+ for (const [name, value] of Object.entries(secrets)) {
+ if (name === "CUSTOM_OAUTH_NAME" || name === "GITHUB_APP_ID") continue;
+ expect(text, name).not.toContain(value);
+ }
+ expect(text).not.toContain("redis.internal.test");
+ expect(text).not.toContain("idp.example.test");
+ expect(text).not.toContain("127.0.0.1");
+
+ const body = JSON.parse(text) as SystemStatus;
+ expect(body.redis).toEqual({
+ status: "down",
+ mode: "standalone",
+ errorCode: "ECONNREFUSED",
+ });
+ expect(body.realtime.status).not.toBe("ok");
+ expect(body.email).toEqual({
+ status: "down",
+ configured: true,
+ errorCode: "EAUTH",
+ });
+ expect(body.storage).toMatchObject({ status: "down", configured: true });
+ expect(body.database.status).toBe("ok");
+ const providers = new Map(
+ body.auth.providers.map((provider) => [provider.id, provider]),
+ );
+ expect(providers.get("google")?.status).toBe("ok");
+ expect(providers.get("github")?.status).toBe("ok");
+ expect(providers.get("discord")?.status).toBe("warning");
+ expect(providers.get("custom")).toEqual({
+ id: "custom",
+ name: "Company SSO",
+ status: "ok",
+ });
+ expect(
+ body.integrations.find((provider) => provider.type === "github")?.status,
+ ).toBe("ok");
+ });
+});
+
+describe("admin test email", () => {
+ it("explains that SMTP is not configured without trying to send", async () => {
+ const admin = await createInstanceAdmin();
+ mockAuthenticatedSession(admin);
+
+ const response = await projectAccessApi()("/admin/system/test-email", {
+ method: "POST",
+ });
+
+ expect(response.status).toBe(409);
+ expect(await response.json()).toMatchObject({
+ code: "SMTP_NOT_CONFIGURED",
+ });
+ expect(smtp.send).not.toHaveBeenCalled();
+ });
+
+ it("only ever sends to the calling administrator", async () => {
+ smtp.configured.mockReturnValue(true);
+ const admin = await createInstanceAdmin();
+ mockAuthenticatedSession(admin);
+
+ const response = await projectAccessApi()("/admin/system/test-email", {
+ method: "POST",
+ body: { to: "[email protected]", email: "[email protected]" },
+ });
+
+ expect(response.status).toBe(200);
+ expect(await response.json()).toEqual({ sent: true, to: admin.email });
+ expect(smtp.send).toHaveBeenCalledTimes(1);
+ expect(smtp.send.mock.calls[0]?.[0]).toBe(admin.email);
+ const calls = JSON.stringify(smtp.send.mock.calls);
+ expect(calls).not.toContain("someone-else@");
+ expect(calls).not.toContain("victim@");
+ });
+
+ it("returns a safe error when the mail server rejects the message", async () => {
+ smtp.configured.mockReturnValue(true);
+ smtp.send.mockRejectedValue(
+ Object.assign(
+ new Error(
+ "535 Authentication failed for smtp-user:smtp-password-value",
+ ),
+ { code: "EAUTH", responseCode: 535 },
+ ),
+ );
+ vi.spyOn(console, "error").mockImplementation(() => {});
+ const admin = await createInstanceAdmin();
+ mockAuthenticatedSession(admin);
+
+ const response = await projectAccessApi()("/admin/system/test-email", {
+ method: "POST",
+ });
+
+ expect(response.status).toBe(502);
+ const text = await response.text();
+ expect(text).toContain("EAUTH 535");
+ expect(text).not.toContain("smtp-password-value");
+ expect(JSON.stringify(vi.mocked(console.error).mock.calls)).not.toContain(
+ "smtp-password-value",
+ );
+ });
+
+ it("limits how often one administrator can send", async () => {
+ smtp.configured.mockReturnValue(true);
+ const admin = await createInstanceAdmin();
+ mockAuthenticatedSession(admin);
+ const request = projectAccessApi();
+
+ for (let attempt = 0; attempt < 5; attempt++) {
+ expect(
+ (await request("/admin/system/test-email", { method: "POST" })).status,
+ ).toBe(200);
+ }
+ const limited = await request("/admin/system/test-email", {
+ method: "POST",
+ });
+
+ expect(limited.status).toBe(429);
+ expect(Number(limited.headers.get("retry-after"))).toBeGreaterThan(0);
+ expect(await limited.json()).toMatchObject({ code: "RATE_LIMITED" });
+ expect(smtp.send).toHaveBeenCalledTimes(5);
+ });
+});
diff --git a/tests/api-integration/mocks/email.ts b/tests/api-integration/mocks/email.ts
index 3aaad14ea..15634e3c9 100644
--- a/tests/api-integration/mocks/email.ts
+++ b/tests/api-integration/mocks/email.ts
@@ -1,6 +1,8 @@
import type { EmailResult } from "../../../packages/email/src/send-email";
+import type { SmtpVerification } from "../../../packages/email/src/verify-smtp-connection";
export { OTP_EXPIRY_SECONDS } from "../../../packages/email/src/otp-expiry";
+export { getSmtpErrorDetails } from "../../../packages/email/src/smtp-error-details";
export async function sendMagicLinkEmail(
_to: string,
@@ -53,3 +55,17 @@ export async function sendEmailVerificationEmail(
): Promise<EmailResult> {
return { success: true };
}
+
+export async function sendTestEmail(
+ _to: string,
+ _subject: string,
+ _data: unknown,
+): Promise<EmailResult> {
+ return { success: false, reason: "SMTP_NOT_CONFIGURED" };
+}
+
+export async function verifySmtpConnection(
+ _timeoutMs: number,
+): Promise<SmtpVerification> {
+ return { status: "not_configured" };
+}