feedkeeper 0.0.0-stage → 0.23.1

package/server/dist/api/items.js

@@ -0,0 +1,129 @@
+import { Router } from "express";
+import rateLimit from "express-rate-limit";
+import { z } from "zod";
+import { requireSession } from "../auth/middleware.js";
+import { listItemsForUser, markAllRead, markItemRead, markItemUnread, bookmarkItem, unbookmarkItem, findItemById, } from "../feeds/repository.js";
+import { loadFullText } from "../feeds/fullText.js";
+import { fetchItemImage, pruneArchive, scheduleArchive, withArchivedImages, withProxiedImages } from "../feeds/archive.js";
+import { ImageCacheBusyError } from "../feeds/imageCache.js";
+export const FULL_TEXT_STATUS = {
+    capability_not_available: 403, paywall: 422, bot_blocked: 422, timeout: 504, partial: 422,
+    item_not_found: 404,
+    item_has_no_link: 400,
+    full_text_disabled: 409,
+    consent_wall: 422,
+    could_not_extract_content: 422,
+    extraction_failed: 502,
+};
+export const itemsRouter = Router();
+// The origin the browser used (honours TRUST_PROXY), so archive URLs work behind proxies and in development.
+function requestOrigin(req) {
+    return `${req.protocol}://${req.get("host")}`;
+}
+itemsRouter.use(requireSession);
+const listQuerySchema = z.object({
+    feedId: z.coerce.number().int().positive().optional(),
+    folderId: z.coerce.number().int().positive().optional(),
+    unreadOnly: z.enum(["true", "false"]).transform((value) => value === "true").optional(),
+    bookmarkedOnly: z.enum(["true", "false"]).transform((value) => value === "true").optional(),
+    includeMuted: z.enum(["true", "false"]).transform((value) => value === "true").optional(),
+    search: z.string().max(200).optional(),
+    limit: z.coerce.number().int().positive().max(200).optional(),
+    offset: z.coerce.number().int().min(0).max(1_000_000).optional(),
+    offline: z.enum(["true", "false"]).transform((value) => value === "true").optional(),
+});
+itemsRouter.get("/", (req, res) => {
+    const parsed = listQuerySchema.safeParse(req.query);
+    if (!parsed.success) {
+        res.status(400).json({ error: "invalid_input", details: parsed.error.flatten() });
+        return;
+    }
+    // Saved articles are served with their archived images instead of the originals.
+    const origin = requestOrigin(req);
+    const archived = withArchivedImages(listItemsForUser(req.user.id, parsed.data), origin);
+    // Offline copies also get the images of articles that are not archived, through this server.
+    const items = parsed.data.offline ? withProxiedImages(archived, origin) : archived;
+    res.json(items.map((item) => ({
+        ...item,
+        read: Boolean(item.read),
+        bookmarked: Boolean(item.bookmarked),
+    })));
+});
+const imageLimiter = rateLimit({ windowMs: 60 * 1000, limit: 600, standardHeaders: true, legacyHeaders: false });
+// Lets the web app keep an article's images for offline reading; only images the article itself shows are served.
+itemsRouter.get("/:itemId/image", imageLimiter, async (req, res) => {
+    const src = typeof req.query.src === "string" ? req.query.src : "";
+    try {
+        const image = await fetchItemImage(req.user.id, Number(req.params.itemId), src);
+        if (image === "forbidden") {
+            res.status(404).json({ error: "not_found" });
+        }
+        else if (image === "unsupported") {
+            res.status(415).json({ error: "unsupported_image" });
+        }
+        else {
+            res.setHeader("Cache-Control", "private, max-age=31536000, immutable");
+            res.type(image.mime).send(image.buffer);
+        }
+    }
+    catch (error) {
+        if (error instanceof ImageCacheBusyError) {
+            res.setHeader("Retry-After", "1");
+            res.status(503).json({ error: "image_busy" });
+            return;
+        }
+        res.status(502).json({ error: "image_unavailable" });
+    }
+});
+const markAllReadSchema = z.object({
+    feedId: z.number().int().positive().optional(),
+    folderId: z.number().int().positive().optional(),
+});
+itemsRouter.post("/mark-all-read", (req, res) => {
+    const parsed = markAllReadSchema.safeParse(req.body ?? {});
+    if (!parsed.success) {
+        res.status(400).json({ error: "invalid_input" });
+        return;
+    }
+    const count = markAllRead(req.user.id, { feedId: parsed.data.feedId, folderId: parsed.data.folderId });
+    res.json({ marked: count });
+});
+itemsRouter.post("/:itemId/read", (req, res) => {
+    markItemRead(req.user.id, Number(req.params.itemId));
+    res.status(204).end();
+});
+itemsRouter.post("/:itemId/unread", (req, res) => {
+    markItemUnread(req.user.id, Number(req.params.itemId));
+    res.status(204).end();
+});
+itemsRouter.post("/:itemId/bookmark", (req, res) => {
+    const itemId = Number(req.params.itemId);
+    if (bookmarkItem(req.user.id, itemId) > 0)
+        scheduleArchive(itemId);
+    res.status(204).end();
+});
+itemsRouter.delete("/:itemId/bookmark", (req, res) => {
+    if (unbookmarkItem(req.user.id, Number(req.params.itemId)) > 0)
+        pruneArchive();
+    res.status(204).end();
+});
+itemsRouter.post("/:itemId/extract-content", async (req, res) => {
+    const itemId = Number(req.params.itemId);
+    if (!Number.isInteger(itemId) || itemId <= 0) {
+        res.status(400).json({ error: "invalid_item_id" });
+        return;
+    }
+    const result = await loadFullText(req.user.id, itemId, { force: req.query.force === "true" });
+    if (!result.ok) {
+        res.status(FULL_TEXT_STATUS[result.error]).json({ error: result.error, ...(result.message ? { message: result.message } : {}) });
+        return;
+    }
+    const [served] = withArchivedImages([{ id: result.id, link: findItemById(result.id)?.link ?? null, full_content_html: result.fullContentHtml }], requestOrigin(req));
+    res.json({
+        id: result.id,
+        full_content_html: served.full_content_html,
+        ...(result.cached ? {} : { title: result.title, byline: result.byline }),
+        cached: result.cached,
+    });
+});
+//# sourceMappingURL=items.js.map

package/server/dist/api/oauth.js

@@ -0,0 +1,14 @@
+import { Router } from "express";
+import { requireSession } from "../auth/middleware.js";
+import { deleteGrant, listGrantsForUser } from "../oauth/store.js";
+/** Apps (ChatGPT, Claude, ...) that signed in through OAuth; the owner can disconnect them. */
+export const oauthGrantsRouter = Router();
+oauthGrantsRouter.use(requireSession);
+oauthGrantsRouter.get("/", (req, res) => {
+    res.json(listGrantsForUser(req.user.id));
+});
+oauthGrantsRouter.delete("/:grantId", (req, res) => {
+    deleteGrant(req.user.id, Number(req.params.grantId));
+    res.status(204).end();
+});
+//# sourceMappingURL=oauth.js.map

package/server/dist/api/onboarding.js

@@ -0,0 +1,30 @@
+import { Router } from "express";
+import { z } from "zod";
+import { hasAnyUser } from "../db/index.js";
+import { createUser } from "../auth/users.js";
+export const onboardingRouter = Router();
+onboardingRouter.get("/status", (_req, res) => {
+    res.json({ needsOnboarding: !hasAnyUser() });
+});
+const onboardingSchema = z.object({
+    email: z.string().email(),
+    password: z.string().min(10),
+    displayName: z.string().min(1).max(100),
+});
+// Creates the first admin user. Only works while the instance has zero users;
+// once an admin exists, all further accounts must be created by an admin.
+onboardingRouter.post("/", (req, res) => {
+    if (hasAnyUser()) {
+        res.status(409).json({ error: "already_onboarded" });
+        return;
+    }
+    const parsed = onboardingSchema.safeParse(req.body);
+    if (!parsed.success) {
+        res.status(400).json({ error: "invalid_input", details: parsed.error.flatten() });
+        return;
+    }
+    const user = createUser({ ...parsed.data, role: "admin" });
+    req.session.userId = user.id;
+    res.status(201).json({ id: user.id, email: user.email, displayName: user.display_name, role: user.role });
+});
+//# sourceMappingURL=onboarding.js.map

package/server/dist/api/push.js

@@ -0,0 +1,51 @@
+import { Router } from "express";
+import { z } from "zod";
+import { requireSession } from "../auth/middleware.js";
+import { assertPublicHttpUrl } from "../feeds/ssrfGuard.js";
+import { hasDevice, removeDevice, saveDevice, sendToUser, vapidPublicKey } from "../push.js";
+export const pushRouter = Router();
+pushRouter.use(requireSession);
+const subscriptionSchema = z.object({
+    endpoint: z.string().url().max(2000).refine((value) => value.startsWith("https://"), "https only"),
+    keys: z.object({ p256dh: z.string().min(1).max(500), auth: z.string().min(1).max(500) }),
+});
+pushRouter.get("/key", (_req, res) => {
+    res.json({ publicKey: vapidPublicKey() });
+});
+pushRouter.post("/devices", async (req, res) => {
+    const parsed = subscriptionSchema.safeParse(req.body);
+    if (!parsed.success) {
+        res.status(400).json({ error: "invalid_input" });
+        return;
+    }
+    try {
+        await assertPublicHttpUrl(parsed.data.endpoint);
+    }
+    catch {
+        res.status(400).json({ error: "invalid_input" });
+        return;
+    }
+    saveDevice(req.user.id, parsed.data);
+    res.status(204).end();
+});
+pushRouter.post("/devices/check", (req, res) => {
+    const endpoint = typeof req.body?.endpoint === "string" ? req.body.endpoint : "";
+    res.json({ registered: hasDevice(req.user.id, endpoint) });
+});
+pushRouter.post("/devices/remove", (req, res) => {
+    const endpoint = typeof req.body?.endpoint === "string" ? req.body.endpoint : "";
+    removeDevice(req.user.id, endpoint);
+    res.status(204).end();
+});
+const TEST_TEXT = {
+    en: "Notifications work.",
+    de: "Benachrichtigungen funktionieren.",
+    ja: "通知は正常に動作しています。",
+};
+pushRouter.post("/test", async (req, res) => {
+    // The test message follows the language of the app on the device that asked for it.
+    const language = typeof req.body?.language === "string" ? req.body.language.slice(0, 2) : "en";
+    const delivered = await sendToUser(req.user.id, { title: "FeedKeeper", body: TEST_TEXT[language] ?? TEST_TEXT.en, url: "/items", tag: "test" });
+    res.json({ delivered });
+});
+//# sourceMappingURL=push.js.map

package/server/dist/api/system.js

@@ -0,0 +1,42 @@
+import { Router } from "express";
+import { z } from "zod";
+import { requireSession, requireAdmin } from "../auth/middleware.js";
+import { getRetentionSettings, updateRetentionSettings, getDatabaseStats, runCleanup, } from "../feeds/cleanup.js";
+export const systemRouter = Router();
+systemRouter.use(requireSession);
+systemRouter.use(requireAdmin);
+systemRouter.get("/retention", (_req, res) => {
+    const settings = getRetentionSettings();
+    const stats = getDatabaseStats();
+    res.json({ settings, stats });
+});
+const updateRetentionSchema = z.object({
+    retentionReadDays: z.number().int().min(0).max(3650).optional(),
+    retentionMaxDays: z.number().int().min(0).max(3650).optional(),
+    retentionMaxItemsPerFeed: z.number().int().min(0).max(100000).optional(),
+    autoCleanupEnabled: z.boolean().optional(),
+});
+systemRouter.patch("/retention", (req, res) => {
+    const parsed = updateRetentionSchema.safeParse(req.body);
+    if (!parsed.success) {
+        res.status(400).json({ error: "invalid_input", details: parsed.error.flatten() });
+        return;
+    }
+    const settings = updateRetentionSettings(parsed.data);
+    const stats = getDatabaseStats();
+    res.json({ settings, stats });
+});
+systemRouter.post("/cleanup", (_req, res) => {
+    try {
+        const result = runCleanup();
+        const stats = getDatabaseStats();
+        res.json({ result, stats });
+    }
+    catch (error) {
+        res.status(500).json({
+            error: "cleanup_failed",
+            message: error instanceof Error ? error.message : String(error),
+        });
+    }
+});
+//# sourceMappingURL=system.js.map

package/server/dist/api/tokens.js

@@ -0,0 +1,28 @@
+import { Router } from "express";
+import { z } from "zod";
+import { requireSession } from "../auth/middleware.js";
+import { createPersonalAccessToken, deleteToken, listTokensForUser } from "../auth/tokens.js";
+export const tokensRouter = Router();
+tokensRouter.use(requireSession);
+tokensRouter.get("/", (req, res) => {
+    res.json(listTokensForUser(req.user.id));
+});
+const createSchema = z.object({
+    name: z.string().trim().min(1).max(100),
+    scope: z.enum(["read", "write"]).default("read"),
+});
+tokensRouter.post("/", (req, res) => {
+    const parsed = createSchema.safeParse(req.body);
+    if (!parsed.success) {
+        res.status(400).json({ error: "invalid_input" });
+        return;
+    }
+    // The plaintext token is only ever returned here, right after creation.
+    const { id, token } = createPersonalAccessToken(req.user.id, parsed.data.name, parsed.data.scope);
+    res.status(201).json({ id, token });
+});
+tokensRouter.delete("/:tokenId", (req, res) => {
+    deleteToken(req.user.id, Number(req.params.tokenId));
+    res.status(204).end();
+});
+//# sourceMappingURL=tokens.js.map

package/server/dist/api/v1/index.js

@@ -0,0 +1,178 @@
+import { Router } from "express";
+import rateLimit from "express-rate-limit";
+import { z } from "zod";
+import { createPairingCode, redeemPairingCode } from "../../auth/pairing.js";
+import { requireSession, requireSessionOrDevice } from "../../auth/middleware.js";
+import { deleteDevice, listDevicesForUser } from "../../auth/tokens.js";
+import { findUserById } from "../../auth/users.js";
+import { config } from "../../config.js";
+import { getRetentionSettings } from "../../feeds/cleanup.js";
+import { APP_VERSION } from "../../version.js";
+import { ResyncRequired, currentSeq, listChanges } from "../../sync/changeLog.js";
+import { applyMutations } from "../../sync/mutations.js";
+import { getUserCapabilities, requireCapability } from "../../auth/capabilities.js";
+import { resourcesRouter } from "./resources.js";
+/** The API for native apps. See docs/design/native-api.md for the contract and what is still to come. */
+export const v1Router = Router();
+// Features grow with the implementation; clients look here instead of guessing from the version.
+const FEATURES = [
+    "pairing",
+    "sync",
+    "mutations",
+    "subscriptions",
+    "folders",
+    "items",
+    "fulltext",
+    "content.revisions",
+    "content.prepare",
+    "images",
+    "muted-keywords",
+    "opml",
+    "retention",
+    "feed-icons",
+    "folder-icons",
+    "notes",
+    "edition",
+    "edition.automatic",
+    "edition.revisions",
+    "native-preferences",
+    "native-preferences.edition-size",
+    "edition.overview",
+    "search.fts",
+    "account-capabilities",
+    "mcp",
+    "inbox",
+];
+v1Router.get("/meta", (_req, res) => {
+    const retention = getRetentionSettings();
+    res.json({
+        apiVersion: 1,
+        serverVersion: APP_VERSION,
+        features: FEATURES,
+        limits: {
+            maxMutationsPerRequest: 200,
+            // Kept for clients that only know the maximum age.
+            retentionDays: retention.retentionMaxDays,
+            // Deletions caused by retention are not announced through /sync, so clients apply the same rules
+            // to their local copy. A value of 0 switches that rule off; saved articles are never removed.
+            retention: {
+                enabled: retention.autoCleanupEnabled,
+                readDays: retention.retentionReadDays,
+                maxDays: retention.retentionMaxDays,
+                maxItemsPerFeed: retention.retentionMaxItemsPerFeed,
+                protectActiveEdition: true,
+            },
+        },
+        minClientVersion: null,
+    });
+});
+// The web app creates the code; the app redeems it. Rate limited, as the code is the only secret.
+v1Router.post("/pairing-codes", requireSession, (req, res) => {
+    const { code, expiresAt } = createPairingCode(req.user.id);
+    const pairingUrl = `feedkeeper://pair?server=${encodeURIComponent(config.publicUrl)}&code=${encodeURIComponent(code)}`;
+    res.status(201).json({ code, expiresAt, pairingUrl });
+});
+const pairSchema = z.object({
+    code: z.string().min(8).max(40),
+    deviceName: z.string().trim().min(1).max(100),
+    platform: z.string().trim().min(1).max(40),
+    appVersion: z.string().trim().max(40).optional(),
+});
+v1Router.post("/devices/pair", rateLimit({ windowMs: 60 * 1000, limit: 10, standardHeaders: true, legacyHeaders: false }), (req, res) => {
+    const parsed = pairSchema.safeParse(req.body);
+    if (!parsed.success) {
+        res.status(400).json({ error: "invalid_input" });
+        return;
+    }
+    const paired = redeemPairingCode(parsed.data.code, { name: parsed.data.deviceName, platform: parsed.data.platform, appVersion: parsed.data.appVersion ?? null });
+    if (!paired) {
+        res.status(400).json({ error: "invalid_or_expired_code" });
+        return;
+    }
+    const user = findUserById(paired.userId);
+    // The token is shown here once; only its hash is stored.
+    res.status(201).json({
+        deviceId: paired.deviceId,
+        token: paired.token,
+        user: { id: user.id, email: user.email, displayName: user.display_name },
+    });
+});
+v1Router.use(requireSessionOrDevice);
+// A read-only token may look at everything but change nothing.
+v1Router.use((req, res, next) => {
+    if (req.method !== "GET" && req.tokenScope === "read") {
+        res.status(403).json({ error: "read_only_token" });
+        return;
+    }
+    next();
+});
+v1Router.get("/me", (req, res) => {
+    res.setHeader("Cache-Control", "private, no-store");
+    const { id, email, display_name, role } = req.user;
+    res.json({
+        id,
+        email,
+        displayName: display_name,
+        role,
+        scope: req.tokenScope ?? "write",
+        deviceId: req.tokenKind === "device" ? req.tokenId : null,
+        capabilities: getUserCapabilities(id),
+    });
+});
+v1Router.get("/devices", (req, res) => {
+    res.json(listDevicesForUser(req.user.id).map((device) => ({
+        id: device.id,
+        name: device.name,
+        platform: device.platform,
+        appVersion: device.app_version,
+        createdAt: device.created_at,
+        lastUsedAt: device.last_used_at,
+        current: req.tokenKind === "device" && req.tokenId === device.id,
+    })));
+});
+v1Router.delete("/devices/:deviceId", (req, res) => {
+    if (!deleteDevice(req.user.id, Number(req.params.deviceId))) {
+        res.status(404).json({ error: "not_found" });
+        return;
+    }
+    res.status(204).end();
+});
+const syncQuery = z.object({
+    since: z.coerce.number().int().min(0).default(0),
+    limit: z.coerce.number().int().min(1).max(500).default(200),
+});
+// Changes to the user's own data (articles' state, subscriptions, folders, keywords) since `since`.
+// since=0 delivers the complete state, as the log holds one entry per object.
+v1Router.get("/sync", requireCapability("sync"), (req, res) => {
+    const parsed = syncQuery.safeParse(req.query);
+    if (!parsed.success) {
+        res.status(400).json({ error: "invalid_input" });
+        return;
+    }
+    try {
+        res.json(listChanges(req.user.id, parsed.data.since, parsed.data.limit));
+    }
+    catch (error) {
+        if (error instanceof ResyncRequired) {
+            res.status(410).json({ error: "resync_required", message: "Drop the local copy and sync again from since=0." });
+            return;
+        }
+        throw error;
+    }
+});
+// Changes made offline; every one carries a client id, so retrying a request is safe.
+v1Router.post("/mutations", (req, res) => {
+    if (req.tokenScope === "read") {
+        res.status(403).json({ error: "read_only_token" });
+        return;
+    }
+    const mutations = req.body?.mutations;
+    if (!Array.isArray(mutations) || mutations.length === 0 || mutations.length > 200) {
+        res.status(400).json({ error: "invalid_input", message: "Send 1 to 200 mutations." });
+        return;
+    }
+    const results = applyMutations(req.user.id, mutations);
+    res.json({ results, seq: currentSeq(req.user.id) });
+});
+v1Router.use(resourcesRouter);
+//# sourceMappingURL=index.js.map