Add proxy hub, link preview improvements, and fetching toast

- Add ProxyHub service for routing fetches through a connected proxy agent
- Route OGS and image downloads through proxy when connected
- Add SSRF-safe safeFetchImage with private-IP blocking and DNS rebinding protection
- Backfill link previews on startup under advisory lock (idempotent)
- Add refetch-link-previews endpoint that wipes and re-runs backfill in-process
- Emit link_preview_fetching socket event so clients show a brief toast

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: alexmicuplusfour

client/src/components/LinkPreviewCard.jsx

@@ -25,14 +25,16 @@ const Card = styled.a`
 
 const CardImage = styled.div`
   width: 100%;
-  /* Basis of 130px but allowed to shrink to 0 (never grows), so the image is the
-     part that gives when previews need to fit a bounded area. */
   flex: 0 1 130px;
   min-height: 0;
   background-image: url(${props => props.$src});
   background-size: cover;
   background-position: center;
   background-color: ${props => props.theme === 'dark' ? 'rgba(255,255,255,0.05)' : 'rgba(0,0,0,0.04)'};
+
+  @media (max-width: 600px) {
+    flex-basis: 75px;
+  }
 `;
 
 const CardBody = styled.div`

client/src/components/NoteCard.jsx

@@ -527,6 +527,20 @@ const TagText = styled.span`
   min-width: 0;
 `;
 
+const TagOverflow = styled.div`
+  display: inline-flex;
+  align-items: center;
+  padding: 2px 7px;
+  border-radius: 4px;
+  font-size: 11px;
+  font-weight: 500;
+  background-color: ${props => props.theme === 'dark' ? 'rgba(255, 255, 255, 0.2)' : 'rgba(0, 0, 0, 0.08)'};
+  color: var(--text-color);
+  opacity: 0.85;
+  cursor: default;
+  user-select: none;
+`;
+
 // Holds the stack of link preview cards. A flex column with a bounded height: when
 // several (image-heavy) previews would overflow, the cards themselves shrink to fit
 // (their images compress) rather than the card spilling or the note text getting
@@ -1305,30 +1319,44 @@ const NoteCard = memo(function NoteCard({ note, searchQuery, layoutView, onPicke
               </UrlLink>
             ))}
 
-            {/* Display all tags, sorted with folders first */}
-            {[...noteTags]
-              .sort((a, b) => {
-                // Convert to boolean to handle undefined
+            {/* Display tags: all folders, then regular tags capped at 4 */}
+            {(() => {
+              const sorted = [...noteTags].sort((a, b) => {
                 const aIsFolder = !!a.is_folder;
                 const bIsFolder = !!b.is_folder;
                 if (aIsFolder && !bIsFolder) return -1;
                 if (!aIsFolder && bIsFolder) return 1;
                 return a.name.localeCompare(b.name);
-              })
-              .map(tag => (
-                <Tag
-                  key={tag.id}
-                  theme={isDarkTheme ? 'dark' : 'light'}
-                  $isFolder={tag.is_folder}
-                  title={`${tag.name}${tag.is_folder ? ' (folder)' : ''}`}
-                  onClick={(e) => handleTagClick(e, tag)}
-                  name={tag.name}
-                >
-                  {tag.visible === false && <Icon name="eye-slash" size={10} style={{ marginRight: 4, flexShrink: 0, opacity: 0.6 }} />}
-                  {tag.is_folder && <Icon name="folder" size={11} style={{ marginRight: 4, flexShrink: 0 }} />}
-                  <TagText>{tag.name.length > 12 ? `${tag.name.substring(0, 12)}...` : tag.name}</TagText>
-                </Tag>
-              ))}
+              });
+              const folderTags = sorted.filter(t => t.is_folder);
+              const regularTags = sorted.filter(t => !t.is_folder);
+              const visibleRegular = regularTags.slice(0, 3);
+              const overflow = regularTags.length - visibleRegular.length;
+              const visible = [...folderTags, ...visibleRegular];
+              return (
+                <>
+                  {visible.map(tag => (
+                    <Tag
+                      key={tag.id}
+                      theme={isDarkTheme ? 'dark' : 'light'}
+                      $isFolder={tag.is_folder}
+                      title={`${tag.name}${tag.is_folder ? ' (folder)' : ''}`}
+                      onClick={(e) => handleTagClick(e, tag)}
+                      name={tag.name}
+                    >
+                      {tag.visible === false && <Icon name="eye-slash" size={10} style={{ marginRight: 4, flexShrink: 0, opacity: 0.6 }} />}
+                      {tag.is_folder && <Icon name="folder" size={11} style={{ marginRight: 4, flexShrink: 0 }} />}
+                      <TagText>{tag.name.length > 12 ? `${tag.name.substring(0, 12)}...` : tag.name}</TagText>
+                    </Tag>
+                  ))}
+                  {overflow > 0 && (
+                    <TagOverflow theme={isDarkTheme ? 'dark' : 'light'}>
+                      +{overflow}
+                    </TagOverflow>
+                  )}
+                </>
+              );
+            })()}
           </TagsContainer>
         )}
 

client/src/components/SettingsModal.jsx

@@ -144,6 +144,8 @@ const DEFAULT_SETTINGS = {
   FOXIT_ENABLED: false,
   FOXIT_SNOOPER_URL: '',
   FOXIT_SNOOPER_TOKEN: '',
+  PROXY_ENABLED: 'false',
+  PROXY_TOKEN: '',
   CACHE_MAX_SIZE: '1000',
   PREFETCH_BATCH_SIZE: '10',
   BATCH_DELAY_MS: '300',
@@ -335,7 +337,7 @@ const SettingsModal = ({ onClose }) => {
       case 'advanced':
         return <AdvancedTab settings={settings} onChange={handleChange} onCacheSettingChange={handleCacheSettingChange} />;
       case 'maintenance':
-        return <MaintenanceTab settings={settings} onChange={handleChange} commit={commit} />;
+        return <MaintenanceTab settings={settings} onChange={handleChange} commit={commit} isDarkTheme={isDarkTheme} />;
       case 'integrations':
         return <IntegrationsTab settings={settings} onChange={handleChange} commit={commit} isDarkTheme={isDarkTheme} />;
       case 'help':

client/src/components/settings/IntegrationsTab.jsx

@@ -13,11 +13,50 @@ import CopyableField from './CopyableField';
 
 const IntegrationsTab = ({ settings, onChange, commit, isDarkTheme }) => {
   const foxitEnabled = settings.FOXIT_ENABLED === true || settings.FOXIT_ENABLED === 'true';
+  const proxyEnabled = settings.PROXY_ENABLED === true || settings.PROXY_ENABLED === 'true';
   const { showToast } = useToast();
 
   const [jinaLoading, setJinaLoading] = useState(false);
   const [tmdbTesting, setTmdbTesting] = useState(false);
   const [foxitTokenCopied, setFoxitTokenCopied] = useState(false);
+  const [proxyTokenCopied, setProxyTokenCopied] = useState(false);
+  const [proxyTesting, setProxyTesting] = useState(false);
+
+  const serverOrigin = typeof window !== 'undefined' ? window.location.origin : '';
+
+  const generateProxyToken = useCallback(() => {
+    const bytes = new Uint8Array(24);
+    window.crypto.getRandomValues(bytes);
+    const token = Array.from(bytes, (b) => b.toString(16).padStart(2, '0')).join('');
+    commit({ ...settings, PROXY_TOKEN: token });
+    if (navigator.clipboard) {
+      navigator.clipboard.writeText(token).then(
+        () => { setProxyTokenCopied(true); setTimeout(() => setProxyTokenCopied(false), 2500); },
+        () => {}
+      );
+    }
+  }, [settings, commit]);
+
+  const clearProxyToken = useCallback(() => {
+    setProxyTokenCopied(false);
+    commit({ ...settings, PROXY_TOKEN: '' });
+  }, [settings, commit]);
+
+  const testProxyConnection = useCallback(async () => {
+    setProxyTesting(true);
+    try {
+      const data = await notesApi.testProxyConnection();
+      if (data.connected) {
+        showToast('Proxy agent is connected', { variant: 'success' });
+      } else {
+        showToast('No proxy agent connected', { variant: 'error' });
+      }
+    } catch (e) {
+      showToast('Could not reach server', { variant: 'error' });
+    } finally {
+      setProxyTesting(false);
+    }
+  }, [showToast]);
 
   // Fill the Foxit snooper token with a fresh random secret and copy it, since
   // the same value has to be pasted into the snooper on the other machine.
@@ -44,8 +83,8 @@ const IntegrationsTab = ({ settings, onChange, commit, isDarkTheme }) => {
   const [extLoading, setExtLoading] = useState(false);
   const [extToken, setExtToken] = useState(null);
   const [extError, setExtError] = useState(null);
-  // The address the extension should point at — this app's own origin.
-  const serverOrigin = typeof window !== 'undefined' ? window.location.origin : '';
+  // The address the extension (and proxy agent) should point at — this app's own origin.
+  // serverOrigin is already declared above.
 
   const generateExtensionToken = useCallback(async () => {
     setExtLoading(true);
@@ -100,6 +139,99 @@ const IntegrationsTab = ({ settings, onChange, commit, isDarkTheme }) => {
 
   return (
     <>
+      <SectionContainer>
+        <div style={{ display: 'flex', alignItems: 'center', justifyContent: 'space-between', marginBottom: '8px' }}>
+          <SectionTitle style={{ margin: 0 }}>Proxy</SectionTitle>
+          <button
+            onClick={testProxyConnection}
+            disabled={proxyTesting}
+            style={{
+              background: 'none',
+              border: '1px solid var(--border-color)',
+              borderRadius: '6px',
+              padding: '4px 10px',
+              fontSize: '12px',
+              cursor: proxyTesting ? 'not-allowed' : 'pointer',
+              color: 'var(--text-secondary-color)',
+              opacity: proxyTesting ? 0.6 : 1,
+            }}
+          >
+            {proxyTesting ? 'Testing…' : 'Test connection'}
+          </button>
+        </div>
+        <p style={{ fontSize: '14px', color: 'var(--text-secondary-color)' }}>
+          Route URL fetches (link previews, article extraction) through a proxy instead of the server.
+          Useful when the server's IP is blocked by certain sites &mdash; YouTube thumbnails, geo-restricted content, etc.
+          The proxy connects outbound; no port forwarding needed.
+        </p>
+        <FormGroup style={{ display: 'flex', alignItems: 'center', justifyContent: 'space-between' }}>
+          <Label style={{ marginBottom: 0 }}>Enable proxy</Label>
+          <Switch
+            id="proxy-enabled-toggle"
+            checked={proxyEnabled}
+            onChange={() => commit({ ...settings, PROXY_ENABLED: !proxyEnabled })}
+          />
+        </FormGroup>
+        {proxyEnabled && (
+          <>
+            <FormGroup>
+              <CopyableField
+                label="Server URL"
+                value={serverOrigin}
+                isDark={isDarkTheme}
+                copyTitle="Copy server URL"
+              />
+            </FormGroup>
+            <FormGroup>
+              {settings.PROXY_TOKEN ? (
+                <>
+                  <CopyableField
+                    label="Proxy token"
+                    value={settings.PROXY_TOKEN}
+                    isDark={isDarkTheme}
+                    copyTitle="Copy token"
+                  />
+                  <div style={{ display: 'flex', alignItems: 'center', gap: '8px', marginTop: '8px' }}>
+                    <button
+                      onClick={generateProxyToken}
+                      style={{ background: 'none', border: '1px solid var(--border-color)', borderRadius: '6px', padding: '4px 10px', fontSize: '12px', color: 'var(--text-secondary-color)', cursor: 'pointer' }}
+                    >
+                      Regenerate
+                    </button>
+                    <button
+                      onClick={clearProxyToken}
+                      style={{ background: 'none', border: '1px solid var(--border-color)', borderRadius: '6px', padding: '4px 10px', fontSize: '12px', color: 'var(--text-secondary-color)', cursor: 'pointer' }}
+                    >
+                      Clear
+                    </button>
+                    <span style={{ fontSize: '12px', color: 'var(--text-secondary-color)' }}>
+                      {proxyTokenCopied ? 'Copied!' : 'Keep this secret.'}
+                    </span>
+                  </div>
+                </>
+              ) : (
+                <>
+                  <Label>Proxy token</Label>
+                  <button
+                    onClick={generateProxyToken}
+                    style={{
+                      background: 'none',
+                      border: '1px solid var(--border-color)',
+                      borderRadius: '6px',
+                      padding: '8px 14px',
+                      fontSize: '13px',
+                      cursor: 'pointer',
+                      color: 'var(--text-secondary-color)',
+                    }}
+                  >
+                    Generate token
+                  </button>
+                </>
+              )}
+            </FormGroup>
+          </>
+        )}
+      </SectionContainer>
       <SectionContainer>
         <SectionTitle>Browser Extension (itsnotes clipper)</SectionTitle>
         <p style={{ fontSize: '14px', color: 'var(--text-secondary-color)' }}>

client/src/components/settings/MaintenanceTab.jsx

@@ -1,13 +1,16 @@
-import React from 'react';
+import React, { useState } from 'react';
 import styled from 'styled-components';
 import Switch from '../Switch';
 import Icon from '../Icons';
+import { notesApi } from '../../services/api';
+import { useToast } from '../../contexts/ToastContext';
 import {
   SectionContainer,
   SectionTitle,
   FormGroup,
   Label,
   Input,
+  Button,
 } from './styles';
 
 const Description = styled.p`
@@ -25,6 +28,15 @@ const Card = styled.div`
   gap: 14px;
 `;
 
+const PlainCard = styled.div`
+  background-color: ${props => props.$isDark ? 'rgba(255, 255, 255, 0.03)' : 'rgba(0, 0, 0, 0.02)'};
+  border-radius: 8px;
+  padding: 16px;
+  display: flex;
+  flex-direction: column;
+  gap: 14px;
+`;
+
 const CardHeader = styled.div`
   display: flex;
   align-items: center;
@@ -61,11 +73,23 @@ const DaysSuffix = styled.span`
   color: var(--text-color);
 `;
 
-const MaintenanceTab = ({ settings, onChange, commit }) => {
-  // Trash auto-delete is opt-out: anything other than the string 'false' is on.
+const MaintenanceTab = ({ settings, onChange, commit, isDarkTheme }) => {
   const trashEnabled = settings.TRASH_CLEANUP_ENABLED !== 'false';
-  // Auto-archive is opt-in: off unless explicitly 'true'.
   const archiveEnabled = settings.AUTO_ARCHIVE_ENABLED === 'true';
+  const { showToast } = useToast();
+  const [refetching, setRefetching] = useState(false);
+
+  const handleRefetchLinkPreviews = async () => {
+    setRefetching(true);
+    try {
+      await notesApi.refetchLinkPreviews();
+      showToast('Refetch started — previews will update as they come in', { variant: 'success' });
+    } catch (e) {
+      showToast('Failed to start refetch', { variant: 'error' });
+    } finally {
+      setRefetching(false);
+    }
+  };
 
   return (
     <SectionContainer>
@@ -152,6 +176,24 @@ const MaintenanceTab = ({ settings, onChange, commit }) => {
           </FormGroup>
         )}
       </Card>
+      <PlainCard $isDark={isDarkTheme}>
+        <CardHeader>
+          <div>
+            <CardTitle><Icon name="link" size={18} />Refetch link previews</CardTitle>
+          </div>
+          <Button
+            $color="danger"
+            $size="small"
+            onClick={handleRefetchLinkPreviews}
+            disabled={refetching}
+          >
+            {refetching ? 'Starting…' : 'Refetch all'}
+          </Button>
+        </CardHeader>
+        <Description>
+          Clears all cached link previews and re-fetches them from scratch. Previews update in the background as they come in.
+        </Description>
+      </PlainCard>
     </SectionContainer>
   );
 };

client/src/contexts/NotesContext.jsx

@@ -2427,11 +2427,15 @@ export const NotesProvider = ({ children }) => {
       'bulk_tags_updated': handleBulkTagsUpdated, // Add the new handler
       'note_operation': (data) => console.log('[SOCKET] Note Operation:', data),
       'mirror_imported': handleMirrorImported,
+      'link_preview_fetching': ({ count = 1 }) => {
+        const msg = count > 1 ? `Fetching ${count} link previews…` : 'Fetching link preview…';
+        showToast(msg, { duration: 'short' });
+      },
     };
   }, [handleSocketNoteCreated, handleSocketNoteUpdated, handleSocketNoteDeleted,
       handleSocketNotesBulkUpdated, handleSocketNotesBulkDeleted,
       handleSocketObjectUpdated, handleSocketNoteTagChange, handleSocketNoteImageChange,
-      handleSocketTagUpdated, handleBulkTagsUpdated, handleMirrorImported]);
+      handleSocketTagUpdated, handleBulkTagsUpdated, handleMirrorImported, showToast]);
 
   // Set up effect to handle pending tag changes after getNoteTags is defined
   useEffect(() => {