From 758d246e98108b2c327f2bec0aa1484e97e34260 Mon Sep 17 00:00:00 2001 From: Schalli Date: Wed, 1 Jul 2026 10:25:52 +0200 Subject: [PATCH] feat(08-03): FavoriteLink schema + FavoritesModule (CRUD + SSRF icon discovery) - Add FavoriteLink Prisma model (userId/tenantId/widgetId scope, iconUrl nullable, position) - IconDiscoveryService: port SSRF-protected icon discovery with redirect: 'manual', private IP / blocked-hostname checks, 4000ms timeout, 200k HTML cap (T-08-05) - FavoritesService: list/create/update/remove all scoped by userId (T-08-06 / Pitfall 3) - FavoritesController: GET /favorites?widgetId, POST, PATCH :id, DELETE :id - FavoritesModule registered in AppModule - tsc --noEmit passes for @tessera/api --- apps/api/prisma/schema.prisma | 17 ++ apps/api/src/app.module.ts | 2 + .../src/favorites/dto/create-favorite.dto.ts | 32 ++ .../src/favorites/dto/update-favorite.dto.ts | 27 ++ .../api/src/favorites/favorites.controller.ts | 88 ++++++ apps/api/src/favorites/favorites.module.ts | 20 ++ apps/api/src/favorites/favorites.service.ts | 96 ++++++ .../src/favorites/icon-discovery.service.ts | 283 ++++++++++++++++++ 8 files changed, 565 insertions(+) create mode 100644 apps/api/src/favorites/dto/create-favorite.dto.ts create mode 100644 apps/api/src/favorites/dto/update-favorite.dto.ts create mode 100644 apps/api/src/favorites/favorites.controller.ts create mode 100644 apps/api/src/favorites/favorites.module.ts create mode 100644 apps/api/src/favorites/favorites.service.ts create mode 100644 apps/api/src/favorites/icon-discovery.service.ts diff --git a/apps/api/prisma/schema.prisma b/apps/api/prisma/schema.prisma index 05f9dd4..e471381 100644 --- a/apps/api/prisma/schema.prisma +++ b/apps/api/prisma/schema.prisma @@ -233,3 +233,20 @@ model SmtpConfig { createdAt DateTime @default(now()) updatedAt DateTime @updatedAt } + +model FavoriteLink { + id String @id @default(uuid()) + userId String + tenantId String + widgetId String + title String + url String + iconUrl String? + position Int @default(0) + createdAt DateTime @default(now()) + updatedAt DateTime @updatedAt + + @@index([userId]) + @@index([tenantId]) + @@index([widgetId]) +} diff --git a/apps/api/src/app.module.ts b/apps/api/src/app.module.ts index 5aecc53..3e5f3d1 100644 --- a/apps/api/src/app.module.ts +++ b/apps/api/src/app.module.ts @@ -12,6 +12,7 @@ import { MailModule } from './mail/mail.module'; import { CalendarModule } from './calendar/calendar.module'; import { DashboardModule } from './dashboard/dashboard.module'; import { DkvModule } from './dkv/dkv.module'; +import { FavoritesModule } from './favorites/favorites.module'; import { DomaincheckModule } from './domaincheck/domaincheck.module'; import { ModuleRegistryModule } from './module-registry/module-registry.module'; import { PrismaModule } from './prisma/prisma.module'; @@ -37,6 +38,7 @@ import { UserModule } from './user/user.module'; CalendarModule, SettingsModule, DkvModule, + FavoritesModule, ], providers: [ // Global JWT guard: all routes require auth unless @Public() diff --git a/apps/api/src/favorites/dto/create-favorite.dto.ts b/apps/api/src/favorites/dto/create-favorite.dto.ts new file mode 100644 index 0000000..8d2db34 --- /dev/null +++ b/apps/api/src/favorites/dto/create-favorite.dto.ts @@ -0,0 +1,32 @@ +import { + IsInt, + IsNotEmpty, + IsOptional, + IsString, + IsUrl, + IsUUID, +} from 'class-validator'; + +/** + * DTO for creating a new FavoriteLink. + * widgetId scopes the link to a specific widget instance (T-08-06 / Pitfall 3). + */ +export class CreateFavoriteDto { + @IsUUID() + widgetId!: string; + + @IsString() + @IsNotEmpty() + title!: string; + + @IsUrl() + url!: string; + + @IsOptional() + @IsString() + iconUrl?: string; + + @IsOptional() + @IsInt() + position?: number; +} diff --git a/apps/api/src/favorites/dto/update-favorite.dto.ts b/apps/api/src/favorites/dto/update-favorite.dto.ts new file mode 100644 index 0000000..e17c57b --- /dev/null +++ b/apps/api/src/favorites/dto/update-favorite.dto.ts @@ -0,0 +1,27 @@ +import { IsInt, IsOptional, IsString, IsUrl } from 'class-validator'; + +/** + * DTO for updating an existing FavoriteLink. + * All fields are optional — only provided fields are updated. + * iconUrl accepts null explicitly to clear a stored icon. + */ +export class UpdateFavoriteDto { + @IsOptional() + @IsString() + title?: string; + + @IsOptional() + @IsUrl() + url?: string; + + /** + * iconUrl can be a string (updated URL), null (clear icon), or absent (no change). + * No strict type validation so null passes through to Prisma. + */ + @IsOptional() + iconUrl?: string | null; + + @IsOptional() + @IsInt() + position?: number; +} diff --git a/apps/api/src/favorites/favorites.controller.ts b/apps/api/src/favorites/favorites.controller.ts new file mode 100644 index 0000000..be8c988 --- /dev/null +++ b/apps/api/src/favorites/favorites.controller.ts @@ -0,0 +1,88 @@ +import { + Body, + Controller, + Delete, + ForbiddenException, + Get, + Param, + Patch, + Post, + Query, + Req, +} from '@nestjs/common'; +import { Request } from 'express'; +import { CreateFavoriteDto } from './dto/create-favorite.dto'; +import { UpdateFavoriteDto } from './dto/update-favorite.dto'; +import { FavoritesService } from './favorites.service'; + +/** + * REST controller for per-user, per-widget favorite links. + * + * All routes are protected by the global JwtAuthGuard + TenantGuard. + * + * Routes: + * - GET /favorites?widgetId= — list favorites for a widget instance + * - POST /favorites — create a favorite (triggers server-side icon discovery) + * - PATCH /favorites/:id — update a favorite (ownership verified in service) + * - DELETE /favorites/:id — delete a favorite (ownership verified in service) + */ +@Controller('favorites') +export class FavoritesController { + constructor(private readonly favoritesService: FavoritesService) {} + + private extractContext(req: Request) { + const userId = (req as any).user?.id; + const tenantId = + (req as any).tenantId ?? (req as any).user?.tenantId; + + if (!tenantId) { + throw new ForbiddenException('No tenant context'); + } + if (!userId) { + throw new ForbiddenException('No user context'); + } + + return { userId, tenantId }; + } + + @Get() + async list( + @Query('widgetId') widgetId: string, + @Req() req: Request, + ) { + const { userId } = this.extractContext(req); + + return this.favoritesService.list(userId, widgetId); + } + + @Post() + async create( + @Body() dto: CreateFavoriteDto, + @Req() req: Request, + ) { + const { userId, tenantId } = this.extractContext(req); + + return this.favoritesService.create(userId, tenantId, dto); + } + + @Patch(':id') + async update( + @Param('id') id: string, + @Body() dto: UpdateFavoriteDto, + @Req() req: Request, + ) { + const { userId } = this.extractContext(req); + + return this.favoritesService.update(id, userId, dto); + } + + @Delete(':id') + async remove( + @Param('id') id: string, + @Req() req: Request, + ) { + const { userId } = this.extractContext(req); + + return this.favoritesService.remove(id, userId); + } +} diff --git a/apps/api/src/favorites/favorites.module.ts b/apps/api/src/favorites/favorites.module.ts new file mode 100644 index 0000000..585f7ee --- /dev/null +++ b/apps/api/src/favorites/favorites.module.ts @@ -0,0 +1,20 @@ +import { Module } from '@nestjs/common'; +import { FavoritesController } from './favorites.controller'; +import { FavoritesService } from './favorites.service'; +import { IconDiscoveryService } from './icon-discovery.service'; + +/** + * NestJS module for per-user favorite link management. + * + * Provides: + * - FavoritesController: REST API under /favorites (CRUD scoped by user + widget) + * - FavoritesService: Business logic with userId-scoped queries (T-08-06) + * - IconDiscoveryService: Server-side icon/favicon discovery with SSRF protection (T-08-05) + * + * PrismaModule is global — no need to re-import here. + */ +@Module({ + controllers: [FavoritesController], + providers: [FavoritesService, IconDiscoveryService], +}) +export class FavoritesModule {} diff --git a/apps/api/src/favorites/favorites.service.ts b/apps/api/src/favorites/favorites.service.ts new file mode 100644 index 0000000..8e4c4a0 --- /dev/null +++ b/apps/api/src/favorites/favorites.service.ts @@ -0,0 +1,96 @@ +import { Injectable, NotFoundException } from '@nestjs/common'; +import { PrismaService } from '../prisma/prisma.service'; +import { CreateFavoriteDto } from './dto/create-favorite.dto'; +import { UpdateFavoriteDto } from './dto/update-favorite.dto'; +import { IconDiscoveryService } from './icon-discovery.service'; + +/** + * Service for managing per-user, per-widget favorite links. + * + * Access control (T-08-06 / Pitfall 3): + * - Every query is scoped by userId (prevents cross-user access). + * - list() additionally scopes by widgetId so each widget instance has its own set. + * - update() and remove() verify userId ownership before mutating. + */ +@Injectable() +export class FavoritesService { + constructor( + private readonly prisma: PrismaService, + private readonly iconDiscovery: IconDiscoveryService, + ) {} + + /** + * Returns all favorites for a user's widget instance, ordered by position asc. + * Scoped by userId AND widgetId (Pitfall 3 — separate widgets must not share links). + */ + async list(userId: string, widgetId: string) { + return this.prisma.favoriteLink.findMany({ + where: { userId, widgetId }, + orderBy: [{ position: 'asc' }, { title: 'asc' }], + }); + } + + /** + * Creates a new favorite link. + * If iconUrl is not provided, triggers server-side icon discovery with SSRF protection. + */ + async create(userId: string, tenantId: string, dto: CreateFavoriteDto) { + let iconUrl = dto.iconUrl ?? null; + + // Server-side icon discovery (D-05) — only when caller did not supply an icon + if (!iconUrl) { + iconUrl = await this.iconDiscovery.discoverFavoriteIconUrl(dto.url); + } + + return this.prisma.favoriteLink.create({ + data: { + userId, + tenantId, + widgetId: dto.widgetId, + title: dto.title, + url: dto.url, + iconUrl, + position: dto.position ?? 0, + }, + }); + } + + /** + * Updates an existing favorite. + * Verifies userId ownership before applying changes (T-08-06). + * Accepts null as an explicit value for iconUrl (clears stored icon). + */ + async update(id: string, userId: string, dto: UpdateFavoriteDto) { + const link = await this.prisma.favoriteLink.findUnique({ where: { id } }); + + if (!link || link.userId !== userId) { + throw new NotFoundException('FavoriteLink not found'); + } + + const data: Record = {}; + + if (dto.title !== undefined) data.title = dto.title; + if (dto.url !== undefined) data.url = dto.url; + if ('iconUrl' in dto) data.iconUrl = dto.iconUrl; // Allows explicit null + if (dto.position !== undefined) data.position = dto.position; + + return this.prisma.favoriteLink.update({ + where: { id }, + data, + }); + } + + /** + * Deletes a favorite link. + * Verifies userId ownership before deleting (T-08-06). + */ + async remove(id: string, userId: string) { + const link = await this.prisma.favoriteLink.findUnique({ where: { id } }); + + if (!link || link.userId !== userId) { + throw new NotFoundException('FavoriteLink not found'); + } + + await this.prisma.favoriteLink.delete({ where: { id } }); + } +} diff --git a/apps/api/src/favorites/icon-discovery.service.ts b/apps/api/src/favorites/icon-discovery.service.ts new file mode 100644 index 0000000..9cb9839 --- /dev/null +++ b/apps/api/src/favorites/icon-discovery.service.ts @@ -0,0 +1,283 @@ +import { Injectable } from '@nestjs/common'; +import { lookup } from 'dns/promises'; +import { isIP } from 'net'; + +/** + * Server-side favicon / icon discovery with SSRF protection (T-08-05). + * + * Ported from personal-dashboard/src/lib/favorite-icons.ts. + * Security guards: + * - DNS resolves every URL (including redirects) and checks for private IP ranges + * - redirect: 'manual' — follows redirects manually so each hop is re-validated + * - 4000 ms AbortController timeout per request + * - 200 000 character HTML cap to prevent memory exhaustion (T-08-09) + * - Blocked hostnames: localhost, .local, 0.0.0.0 + */ + +const FALLBACK_ICON_PATH = '/favicon.ico'; +const HTML_FETCH_TIMEOUT_MS = 4000; +const MAX_REDIRECTS = 2; +const MAX_HTML_CHARS = 200000; + +type FetchHtmlResult = { + html: string; + finalUrl: string; +}; + +function isPrivateIpv4(address: string): boolean { + const parts = address.split('.').map((part) => Number.parseInt(part, 10)); + + if ( + parts.length !== 4 || + parts.some( + (part) => !Number.isInteger(part) || part < 0 || part > 255, + ) + ) { + return true; + } + + const [a, b] = parts; + + return ( + a === 0 || + a === 10 || + a === 127 || + (a === 100 && b !== undefined && b >= 64 && b <= 127) || + (a === 169 && b === 254) || + (a === 172 && b !== undefined && b >= 16 && b <= 31) || + (a === 192 && b === 168) || + (a === 192 && b === 0) || + (a === 198 && (b === 18 || b === 19)) || + a >= 224 + ); +} + +function isPrivateIpv6(address: string): boolean { + const lower = address.toLowerCase(); + + return ( + lower === '::' || + lower === '::1' || + lower.startsWith('fc') || + lower.startsWith('fd') || + lower.startsWith('fe80:') || + lower.startsWith('::ffff:127.') || + lower.startsWith('::ffff:10.') || + lower.startsWith('::ffff:192.168.') + ); +} + +function isPrivateIpAddress(address: string): boolean { + const version = isIP(address); + + if (version === 4) return isPrivateIpv4(address); + if (version === 6) return isPrivateIpv6(address); + + return true; // Unknown format → block by default +} + +function isBlockedHostname(hostname: string): boolean { + const h = hostname.trim().toLowerCase(); + + return ( + h === 'localhost' || + h.endsWith('.localhost') || + h.endsWith('.local') || + h === '0.0.0.0' + ); +} + +async function isPublicHttpUrl(url: URL): Promise { + if (url.protocol !== 'http:' && url.protocol !== 'https:') { + return false; + } + + if (isBlockedHostname(url.hostname)) { + return false; + } + + const directVersion = isIP(url.hostname); + + if (directVersion !== 0) { + return !isPrivateIpAddress(url.hostname); + } + + try { + const addresses = await lookup(url.hostname, { all: true }); + + if (addresses.length === 0) return false; + + return addresses.every((a) => !isPrivateIpAddress(a.address)); + } catch { + return false; + } +} + +function getOriginFaviconUrl(pageUrl: string): string { + try { + const url = new URL(pageUrl); + + return new URL(FALLBACK_ICON_PATH, url.origin).toString(); + } catch { + return FALLBACK_ICON_PATH; + } +} + +function parseAttributes(tag: string): Record { + const attrs: Record = {}; + const re = /([a-zA-Z_:.-]+)\s*=\s*("([^"]*)"|'([^']*)'|([^\s"'>]+))/g; + let m: RegExpExecArray | null; + + while ((m = re.exec(tag)) !== null) { + const key = m[1].toLowerCase(); + const value = m[3] ?? m[4] ?? m[5] ?? ''; + + attrs[key] = value; + } + + return attrs; +} + +function toAbsoluteUrl(value: string | undefined, base: string): string | null { + if (!value) return null; + + try { + const url = new URL(value, base); + + if (url.protocol !== 'http:' && url.protocol !== 'https:') return null; + + return url.toString(); + } catch { + return null; + } +} + +function extractIconFromHtml(html: string, baseUrl: string): string | null { + const linkTags = html.match(/]*>/gi) ?? []; + const metaTags = html.match(/]*>/gi) ?? []; + + const linkCandidates = linkTags + .map((tag) => parseAttributes(tag)) + .map((a) => ({ + rel: (a.rel ?? '').toLowerCase(), + href: toAbsoluteUrl(a.href, baseUrl), + })) + .filter((c) => c.href); + + const appleTouchIcon = linkCandidates.find((c) => + c.rel.includes('apple-touch-icon'), + )?.href; + + if (appleTouchIcon) return appleTouchIcon; + + const icon = linkCandidates.find((c) => + c.rel.split(/\s+/).includes('icon'), + )?.href; + + if (icon) return icon; + + const shortcutIcon = linkCandidates.find((c) => + c.rel.includes('shortcut icon'), + )?.href; + + if (shortcutIcon) return shortcutIcon; + + const imageSrc = linkCandidates.find((c) => + c.rel.includes('image_src'), + )?.href; + + if (imageSrc) return imageSrc; + + const metaImage = metaTags + .map((tag) => parseAttributes(tag)) + .map((a) => ({ + property: (a.property ?? a.name ?? '').toLowerCase(), + content: toAbsoluteUrl(a.content, baseUrl), + })) + .find( + (c) => + c.content && + (c.property === 'og:image' || + c.property === 'og:logo' || + c.property === 'twitter:image'), + )?.content; + + return metaImage ?? null; +} + +async function fetchHtml(pageUrl: URL): Promise { + let currentUrl = pageUrl; + + for (let redirectCount = 0; redirectCount <= MAX_REDIRECTS; redirectCount++) { + const isPublic = await isPublicHttpUrl(currentUrl); + + if (!isPublic) return null; + + const controller = new AbortController(); + const timeout = setTimeout(() => controller.abort(), HTML_FETCH_TIMEOUT_MS); + + try { + const response = await fetch(currentUrl.toString(), { + redirect: 'manual', // SSRF: follow manually so each hop is re-validated + signal: controller.signal, + headers: { + Accept: 'text/html,application/xhtml+xml,*/*', + 'User-Agent': 'tessera/1.0', + }, + }); + + if (response.status >= 300 && response.status < 400) { + const location = response.headers.get('location'); + + if (!location) return null; + + currentUrl = new URL(location, currentUrl); + continue; + } + + if (!response.ok) return null; + + const contentType = response.headers.get('content-type') ?? ''; + + if (!contentType.toLowerCase().includes('text/html')) return null; + + const html = await response.text(); + + return { + html: html.slice(0, MAX_HTML_CHARS), // T-08-09: HTML cap + finalUrl: currentUrl.toString(), + }; + } catch { + return null; + } finally { + clearTimeout(timeout); + } + } + + return null; +} + +@Injectable() +export class IconDiscoveryService { + /** + * Discover the best icon URL for a given web page URL. + * Falls back to /favicon.ico when discovery fails or URL is private. + * + * SSRF protection: every URL and redirect target is validated against + * private IP ranges, blocked hostnames, and forced-proxy vectors (T-08-05). + */ + async discoverFavoriteIconUrl(pageUrl: string): Promise { + const fallback = getOriginFaviconUrl(pageUrl); + + try { + const url = new URL(pageUrl); + const htmlResult = await fetchHtml(url); + + if (!htmlResult) return fallback; + + return extractIconFromHtml(htmlResult.html, htmlResult.finalUrl) ?? fallback; + } catch { + return fallback; + } + } +}