@isomoes/iread 0.2.4 → 0.2.6

package/README.md

@@ -2,7 +2,7 @@
 
 A concise, local, single-user RSS/Atom reader inspired by newsboat. Keyboard-first three-pane UI, TypeScript end to end. You add feeds by URL, refresh them on demand, and read server-sanitized article bodies in a calm, terminal-quiet reading surface with light, dark, and system themes.
 
-There is no auth, no multi-user, no cloud sync, and no background scheduler. Refresh is always user-initiated. All data lives in a single local SQLite file — by default `~/.config/iread/iread.db` — which is the trust boundary.
+Optional token authentication supports private access over a public network. There is no multi-user, no cloud sync, and no background scheduler. Refresh is always user-initiated. All data lives in a single local SQLite file — by default `~/.config/iread/iread.db`.
 
 ![iread UI](https://github.com/user-attachments/assets/ca9489c9-630f-4a67-9cd5-60c18ce3544e)
 
@@ -21,6 +21,7 @@ Usage: iread [options]
 
 Options:
   -p, --port <port>  Port to listen on (default: $PORT or 8787)
+      --auth-token <token>  Require a bearer token (default: $AUTH_TOKEN; unset disables auth)
       --db <path>    SQLite database file
                      (default: $DB_PATH or ~/.config/iread/iread.db)
       --opml <path>  OPML file auto-saved on every subscription change
@@ -50,6 +51,20 @@ Build the image from the checkout instead of pulling it with `docker compose up
 
 `PORT` (default 8787), `HOST` (default all interfaces), `DB_PATH` (default `/data/iread.db`), and `OPML_PATH` (default `/data/feeds.opml`) are configurable via `-e`/`environment:`. With host networking, set `HOST=127.0.0.1` to restrict access to localhost; with bridge networking, leave `HOST` unset and restrict the published port instead. To store data in a host directory instead of a named volume, bind-mount it and make it writable by the image's unprivileged `node` user (uid 1000), e.g. `mkdir iread-data && sudo chown 1000:1000 iread-data` then `-v "$PWD/iread-data:/data"`.
 
+## Public network access
+
+Authentication is **disabled by default**. Set `AUTH_TOKEN` to a long, random secret to protect every API endpoint:
+
+```sh
+AUTH_TOKEN='your-long-random-secret' npx @isomoes/iread
+```
+
+You can also use `--auth-token <token>`. Environment variables are preferable to putting secrets in command-line arguments. For Compose, set `AUTH_TOKEN` in your environment or Compose `.env` file before `docker compose up -d`. For `docker run`, pass `-e AUTH_TOKEN='your-long-random-secret'`.
+
+The web UI prompts for the token and remembers it for the current browser tab using sessionStorage. API clients must send `Authorization: Bearer <token>`, including for OPML export. The static UI remains public but no feed or article data is accessible without the token. Changing the server token requires restarting the server; clients with the old token must sign in again.
+
+Use HTTPS through a reverse proxy for public access, and configure proxy-side rate limiting against token guessing. Never expose an instance without a token unless access is restricted by another trusted layer. `AUTH_TOKEN` unset or empty preserves the existing unauthenticated behavior. `config/.env.example` documents the settings; the server reads environment variables, not that file automatically.
+
 ## Features
 
 - Add a feed by URL (title resolved from feed metadata), delete a feed.
@@ -149,3 +164,7 @@ pnpm start
 Open http://localhost:8787
 
 `PORT` (default 8787), `HOST` (default all interfaces; set `127.0.0.1` for localhost only), `DB_PATH` (default `~/.config/iread/iread.db`), and `OPML_PATH` (default `feeds.opml` next to the database; set empty to disable the auto-saved mirror) are read from the environment. See `config/.env.example`.
+
+Feeds are fetched directly by default. To go through an outbound HTTP proxy, set `HTTPS_PROXY` / `HTTP_PROXY` (an `http://host:port` URL, optionally with `user:pass@`) and optionally `NO_PROXY` (comma-separated hosts/domains to bypass). HTTPS feeds are tunnelled with `CONNECT`. Note that the SSRF guard still validates the feed host's DNS answer locally, but with a proxy the proxy does the final connect, so DNS-rebinding pinning cannot apply.
+
+Each fetch attempt has a 30-second timeout. Transient network failures and HTTP 408/429/500/502/503/504 are retried once, normally after one second. A valid `Retry-After` is honored up to five seconds; longer delays are not retried automatically. Permanent HTTP errors, unsafe URLs, and oversized feeds are not retried. Run fetch regression tests with `pnpm test`.

package/dist/server/auth.js

@@ -0,0 +1,18 @@
+import { createHash, timingSafeEqual } from 'node:crypto';
+import { createMiddleware } from 'hono/factory';
+export function tokenAuth(token) {
+    const expected = token ? createHash('sha256').update(token).digest() : undefined;
+    return createMiddleware(async (c, next) => {
+        c.header('Cache-Control', 'no-store');
+        if (expected) {
+            const authorization = c.req.header('Authorization') ?? '';
+            const match = /^Bearer ([^\s]+)$/i.exec(authorization);
+            const supplied = createHash('sha256').update(match?.[1] ?? '').digest();
+            if (!match || !timingSafeEqual(expected, supplied)) {
+                c.header('WWW-Authenticate', 'Bearer realm="iread"');
+                return c.json({ error: { message: 'Authentication required', code: 'UNAUTHORIZED' } }, 401);
+            }
+        }
+        await next();
+    });
+}

package/dist/server/cli.js

@@ -28,6 +28,7 @@ Usage: iread [options]
 
 Options:
   -p, --port <port>  Port to listen on (default: $PORT or 8787)
+      --auth-token <token>  Require a bearer token (default: $AUTH_TOKEN; unset disables auth)
       --db <path>    SQLite database file
                      (default: $DB_PATH or ~/.config/iread/iread.db)
       --opml <path>  OPML file auto-saved on every subscription change
@@ -70,6 +71,13 @@ for (let i = 0; i < args.length; i++) {
             process.env.PORT = value;
             break;
         }
+        case '--auth-token': {
+            const value = args[++i];
+            if (!value || /\s/.test(value))
+                fail('--auth-token requires a non-empty token without whitespace');
+            process.env.AUTH_TOKEN = value;
+            break;
+        }
         case '--db': {
             const value = args[++i];
             if (!value)

package/dist/server/fetch-feed.js

@@ -3,9 +3,36 @@
 // The body is read incrementally and the request is aborted the moment cumulative
 // bytes exceed MAX_BYTES; the whole response is never buffered before the check.
 import { fetchWithGuardedRedirects } from './ssrf.js';
+import { setTimeout as delay } from 'node:timers/promises';
 const USER_AGENT = 'iread/1.0 (+local RSS reader)';
-const FETCH_TIMEOUT_MS = 15_000;
+const FETCH_TIMEOUT_MS = 30_000;
 const MAX_BYTES = 10 * 1024 * 1024; // 10 MB
+const RETRY_CODES = new Set([
+    'ECONNRESET',
+    'ECONNREFUSED',
+    'ETIMEDOUT',
+    'EAI_AGAIN',
+    'ENETUNREACH',
+    'EHOSTUNREACH',
+    'EPIPE',
+    'ERR_STREAM_PREMATURE_CLOSE',
+]);
+class RetryableFetchError extends Error {
+    retryDelay;
+    constructor(message, retryDelay = 1000) {
+        super(message);
+        this.retryDelay = retryDelay;
+    }
+}
+function isTransient(err) {
+    if (err instanceof RetryableFetchError)
+        return true;
+    if (err instanceof AggregateError)
+        return err.errors.length > 0 && err.errors.every(isTransient);
+    if (!(err instanceof Error))
+        return false;
+    return RETRY_CODES.has(err.code ?? '') || isTransient(err.cause);
+}
 function concat(chunks, total) {
     const out = new Uint8Array(total);
     let offset = 0;
@@ -16,6 +43,18 @@ function concat(chunks, total) {
     return out;
 }
 export async function fetchFeed(input) {
+    for (let attempt = 0;; attempt++) {
+        try {
+            return await fetchAttempt(input);
+        }
+        catch (err) {
+            if (attempt >= 1 || !isTransient(err))
+                throw err;
+            await delay(err instanceof RetryableFetchError ? err.retryDelay : 1000);
+        }
+    }
+}
+async function fetchAttempt(input) {
     const ctrl = new AbortController();
     const timer = setTimeout(() => ctrl.abort(), FETCH_TIMEOUT_MS);
     try {
@@ -39,7 +78,18 @@ export async function fetchFeed(input) {
         }
         if (!res.ok) {
             await res.body?.cancel().catch(() => { });
-            throw new Error(`HTTP ${res.status} ${res.statusText}`);
+            const message = `HTTP ${res.status} ${res.statusText}`;
+            const retryAfter = res.headers.get('retry-after');
+            const retryDelay = retryAfter === null
+                ? 1000
+                : /^\d+$/.test(retryAfter)
+                    ? Number(retryAfter) * 1000
+                    : Math.max(0, Date.parse(retryAfter) - Date.now());
+            if ([408, 429, 500, 502, 503, 504].includes(res.status) &&
+                Number.isFinite(retryDelay) && retryDelay <= 5000) {
+                throw new RetryableFetchError(message, retryDelay);
+            }
+            throw new Error(message);
         }
         // Fast reject on advertised Content-Length (untrusted but cheap).
         const cl = Number(res.headers.get('content-length'));
@@ -76,6 +126,12 @@ export async function fetchFeed(input) {
             lastModified: res.headers.get('last-modified'),
         };
     }
+    catch (err) {
+        if (ctrl.signal.aborted && err instanceof Error && err.name === 'AbortError') {
+            throw new RetryableFetchError(`Feed request timed out after ${FETCH_TIMEOUT_MS / 1000}s`);
+        }
+        throw err;
+    }
     finally {
         clearTimeout(timer);
     }

package/dist/server/index.js

@@ -12,6 +12,7 @@ import { serveStatic } from '@hono/node-server/serve-static';
 import { feeds } from './routes/feeds.js';
 import { items } from './routes/items.js';
 import { opml } from './routes/opml.js';
+import { tokenAuth } from './auth.js';
 const PORT = Number(process.env.PORT ?? 8787);
 const HOST = process.env.HOST || undefined;
 const IS_PROD = process.env.NODE_ENV === 'production';
@@ -21,6 +22,9 @@ import './db.js';
 import { syncOpmlMirror } from './feed-service.js';
 syncOpmlMirror();
 const app = new Hono();
+app.use('/api/*', tokenAuth(process.env.AUTH_TOKEN));
+app.use('/api', tokenAuth(process.env.AUTH_TOKEN));
+app.get('/api/auth', (c) => c.body(null, 204));
 // --- API routes (registered FIRST) -----------------------------------------
 const api = new Hono();
 api.route('/feeds', feeds);

package/dist/server/proxy.js

@@ -0,0 +1,114 @@
+// src/server/proxy.ts
+// Optional outbound HTTP(S) proxy support for feed fetching, driven by the usual
+// HTTPS_PROXY / HTTP_PROXY / NO_PROXY environment variables (either case).
+// Only `http://` proxy URLs are supported (HTTPS targets are tunnelled via CONNECT).
+import { request as httpRequest } from 'node:http';
+import { connect as tlsConnect } from 'node:tls';
+function env(name) {
+    return process.env[name] ?? process.env[name.toLowerCase()] ?? undefined;
+}
+function bypassed(host, port, noProxy) {
+    const h = host.toLowerCase();
+    for (const raw of noProxy.split(',')) {
+        let entry = raw.trim().toLowerCase();
+        if (!entry)
+            continue;
+        if (entry === '*')
+            return true;
+        const colon = entry.lastIndexOf(':');
+        if (colon > 0 && !entry.endsWith(']') && /^\d+$/.test(entry.slice(colon + 1))) {
+            if (entry.slice(colon + 1) !== port)
+                continue;
+            entry = entry.slice(0, colon);
+        }
+        entry = entry.replace(/^\*?\./, '');
+        if (h === entry || h.endsWith(`.${entry}`))
+            return true;
+    }
+    return false;
+}
+/** Proxy to use for `target`, or null for a direct connection. */
+export function proxyFor(target) {
+    const isHttps = target.protocol === 'https:';
+    const value = isHttps ? (env('HTTPS_PROXY') ?? env('HTTP_PROXY')) : env('HTTP_PROXY');
+    if (!value)
+        return null;
+    const port = target.port || (isHttps ? '443' : '80');
+    const host = target.hostname.replace(/^\[|\]$/g, '');
+    if (bypassed(host, port, env('NO_PROXY') ?? ''))
+        return null;
+    let p;
+    try {
+        p = new URL(value.includes('://') ? value : `http://${value}`);
+    }
+    catch {
+        return null;
+    }
+    if (p.protocol !== 'http:')
+        return null;
+    const auth = p.username
+        ? `${decodeURIComponent(p.username)}:${decodeURIComponent(p.password)}`
+        : null;
+    return { host: p.hostname.replace(/^\[|\]$/g, ''), port: Number(p.port || 80), auth };
+}
+function proxyAuthHeader(proxy) {
+    return proxy.auth
+        ? { 'Proxy-Authorization': `Basic ${Buffer.from(proxy.auth).toString('base64')}` }
+        : {};
+}
+/** Headers to add when sending an absolute-URI request to the proxy (http targets). */
+export function plainProxyHeaders(proxy) {
+    return proxyAuthHeader(proxy);
+}
+/**
+ * Open a CONNECT tunnel through `proxy` to target host:port and wrap it in TLS
+ * (SNI = target hostname). Honors `signal` for cancellation.
+ */
+export function tunnelTls(proxy, target, signal) {
+    const port = target.port || '443';
+    const hostname = target.hostname.replace(/^\[|\]$/g, '');
+    const authority = `${target.hostname}:${port}`;
+    return new Promise((resolve, reject) => {
+        const req = httpRequest({
+            host: proxy.host,
+            port: proxy.port,
+            method: 'CONNECT',
+            path: authority,
+            headers: { Host: authority, ...proxyAuthHeader(proxy) },
+        });
+        let tunnel;
+        const cleanup = () => signal?.removeEventListener('abort', abort);
+        const fail = (err) => {
+            cleanup();
+            reject(err);
+        };
+        const abort = () => {
+            const err = new DOMException('Aborted', 'AbortError');
+            tunnel?.destroy(err);
+            req.destroy(err);
+            fail(err);
+        };
+        if (signal) {
+            if (signal.aborted)
+                abort();
+            else
+                signal.addEventListener('abort', abort, { once: true });
+        }
+        req.once('connect', (res, socket) => {
+            if (res.statusCode !== 200) {
+                socket.destroy();
+                fail(new Error(`proxy CONNECT failed: HTTP ${res.statusCode ?? 0}`));
+                return;
+            }
+            const tls = tlsConnect({ socket, servername: hostname });
+            tunnel = tls;
+            tls.once('secureConnect', () => {
+                cleanup();
+                resolve(tls);
+            });
+            tls.once('error', fail);
+        });
+        req.once('error', fail);
+        req.end();
+    });
+}

package/dist/server/ssrf.js

@@ -7,6 +7,7 @@ import { isIP } from 'node:net';
 import { request as httpRequest } from 'node:http';
 import { request as httpsRequest } from 'node:https';
 import { Readable } from 'node:stream';
+import { plainProxyHeaders, proxyFor, tunnelTls } from './proxy.js';
 const MAX_REDIRECTS = 5;
 export class SsrfError extends Error {
     name = 'SsrfError';
@@ -190,48 +191,73 @@ function pinnedFetch(url, validated, init) {
     const isHttps = parsed.protocol === 'https:';
     const requestFn = isHttps ? httpsRequest : httpRequest;
     const signal = init.signal ?? undefined;
-    return new Promise((resolve, reject) => {
-        const req = requestFn(parsed, {
-            method: (init.method ?? 'GET').toUpperCase(),
-            headers: headersToObject(init.headers),
-            lookup: pinnedLookup(validated),
-            // servername defaults to the URL hostname for https, preserving SNI.
-        }, (msg) => {
-            const headers = new Headers();
-            for (const [k, v] of Object.entries(msg.headers)) {
-                if (v === undefined)
-                    continue;
-                if (Array.isArray(v))
-                    for (const one of v)
-                        headers.append(k, one);
-                else
-                    headers.set(k, v);
+    const proxy = proxyFor(parsed);
+    return (async () => {
+        // Via a proxy the destination was still validated (assertSafeFeedUrl) but the
+        // proxy performs the final resolve+connect, so IP pinning cannot apply.
+        let tunnel;
+        if (proxy && isHttps)
+            tunnel = await tunnelTls(proxy, parsed, signal);
+        return send(tunnel);
+    })();
+    function send(tunnel) {
+        return new Promise((resolve, reject) => {
+            const headers = headersToObject(init.headers);
+            let target = parsed;
+            let extra = { lookup: pinnedLookup(validated) };
+            let fn = requestFn;
+            if (tunnel) {
+                extra = { createConnection: () => tunnel };
             }
-            const status = msg.statusCode ?? 0;
-            // 204/304 must not carry a body in a Response.
-            const nullBody = status === 204 || status === 304;
-            const body = nullBody
-                ? null
-                : Readable.toWeb(msg);
-            resolve(new Response(body, {
-                status,
-                statusText: msg.statusMessage ?? '',
-                headers,
-            }));
-        });
-        if (signal) {
-            if (signal.aborted) {
-                req.destroy(new DOMException('Aborted', 'AbortError'));
+            else if (proxy) {
+                // Plain-http target: absolute-URI request to the proxy.
+                fn = httpRequest;
+                target = new URL(`http://${proxy.host.includes(':') ? `[${proxy.host}]` : proxy.host}:${proxy.port}`);
+                extra = { path: parsed.href, setHost: false };
+                Object.assign(headers, { host: parsed.host }, plainProxyHeaders(proxy));
             }
-            else {
-                signal.addEventListener('abort', () => req.destroy(new DOMException('Aborted', 'AbortError')), {
-                    once: true,
-                });
+            const req = fn(target, {
+                method: (init.method ?? 'GET').toUpperCase(),
+                headers,
+                ...extra,
+                // servername defaults to the URL hostname for https, preserving SNI.
+            }, (msg) => {
+                const headers = new Headers();
+                for (const [k, v] of Object.entries(msg.headers)) {
+                    if (v === undefined)
+                        continue;
+                    if (Array.isArray(v))
+                        for (const one of v)
+                            headers.append(k, one);
+                    else
+                        headers.set(k, v);
+                }
+                const status = msg.statusCode ?? 0;
+                // 204/304 must not carry a body in a Response.
+                const nullBody = status === 204 || status === 304;
+                const body = nullBody
+                    ? null
+                    : Readable.toWeb(msg);
+                resolve(new Response(body, {
+                    status,
+                    statusText: msg.statusMessage ?? '',
+                    headers,
+                }));
+            });
+            if (signal) {
+                if (signal.aborted) {
+                    req.destroy(new DOMException('Aborted', 'AbortError'));
+                }
+                else {
+                    signal.addEventListener('abort', () => req.destroy(new DOMException('Aborted', 'AbortError')), {
+                        once: true,
+                    });
+                }
             }
-        }
-        req.on('error', reject);
-        req.end();
-    });
+            req.on('error', reject);
+            req.end();
+        });
+    }
 }
 /**
  * fetch() that follows redirects manually (max 5 hops), re-running the SSRF