dorfteich/packages/shared/src/branding.ts

/**
 * Instance and pond branding assets — logo and favicon (issues #306/#307).
 *
 * The bytes live on disk under `BRANDING_DIR`; only metadata (present/absent,
 * dimensions, a content hash for cache busting) goes into settings. Cropping,
 * scaling and the conversion to PNG happen in the BROWSER on a canvas: adding
 * a native image library to the api would put a decoder in front of
 * attacker-supplied bytes and would have to be carried through the
 * `--network none` offline build (96-offline-build-protokoll.md).
 *
 * The api therefore never decodes an image. It checks the PNG signature, reads
 * the fixed-offset IHDR fields for the dimensions, and enforces the caps —
 * which is exactly as far as one can go without a decoder.
 */
import { z } from 'zod';

/** Logo variants. A set belongs to one level and is never mixed across levels
 *  (#307): a pond with only a light logo shows THAT logo in dark mode rather
 *  than silently borrowing the instance's dark one. */
export const LOGO_VARIANTS = ['light', 'dark'] as const;
export type LogoVariant = (typeof LOGO_VARIANTS)[number];

/** Favicon sizes emitted by the browser-side crop: the tab icon and the
 *  home-screen icon. No `.ico` — every current browser accepts PNG. */
export const FAVICON_SIZES = [32, 180] as const;
export type FaviconSize = (typeof FAVICON_SIZES)[number];

/** Longest edge of an uploaded logo. Beyond this the browser downscales
 *  before uploading; the api rejects anything larger as a backstop. */
export const MAX_LOGO_EDGE = 512;

/** Per-file cap. A 512px PNG is tens of KB; 2 MiB leaves room for a
 *  needlessly lossless export without inviting abuse. */
export const MAX_BRANDING_BYTES = 2 * 1024 * 1024;

/** Formats a source image may have in the browser. SVG is deliberately absent:
 *  it can carry script, and serving it from our own origin would be a
 *  cross-site-scripting vector (security.md §Uploads). What leaves the canvas
 *  is PNG regardless. */
export const BRANDING_SOURCE_TYPES = ['image/png', 'image/jpeg', 'image/webp'] as const;

const PNG_MAGIC = [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a];

/** True when `bytes` starts with the PNG signature. */
export function hasPngMagic(bytes: Uint8Array): boolean {
  if (bytes.length < PNG_MAGIC.length) return false;
  return PNG_MAGIC.every((byte, index) => bytes[index] === byte);
}

/** True when the bytes look like SVG (XML declaration or an `<svg` tag near
 *  the start). Only used to answer a rejected upload with the real reason
 *  instead of a generic "not a PNG". */
export function looksLikeSvg(bytes: Uint8Array): boolean {
  const head = Buffer.from(bytes.subarray(0, 256)).toString('latin1').toLowerCase();
  return head.includes('<svg') || (head.includes('<?xml') && head.includes('svg'));
}

/**
 * Width and height from a PNG's IHDR, which is at a FIXED offset directly
 * after the signature. Reading two big-endian integers is not decoding —
 * nothing is decompressed and no attacker-controlled length drives a loop.
 * Returns null when the bytes are not a PNG with an IHDR first.
 */
export function pngDimensions(bytes: Uint8Array): { width: number; height: number } | null {
  if (!hasPngMagic(bytes) || bytes.length < 33) return null;
  const buf = Buffer.from(bytes.subarray(0, 33));
  if (buf.subarray(12, 16).toString('latin1') !== 'IHDR') return null;
  const width = buf.readUInt32BE(16);
  const height = buf.readUInt32BE(20);
  if (width === 0 || height === 0) return null;
  return { width, height };
}

/** What is stored per asset. The bytes stay on disk; `hash` goes into the
 *  serving URL so a replaced logo is picked up without fighting caches. */
export const brandingAssetSchema = z.object({
  hash: z
    .string()
    .trim()
    .toLowerCase()
    .regex(/^[a-f0-9]{16,64}$/),
  width: z.number().int().min(1),
  height: z.number().int().min(1),
  /** Stored bytes. Needed so a pond's quota can be released exactly when the
   *  asset is replaced or removed (issue #307) — optional because instance
   *  assets predating it are not charged to anything. */
  byteSize: z.number().int().min(0).optional(),
});
export type BrandingAsset = z.infer<typeof brandingAssetSchema>;

/** What the api reports about the branding in force. Every field may be null —
 *  an instance without branding renders its name as text and the shipped
 *  default favicon. */
export interface BrandingView {
  logo: BrandingAsset | null;
  logoDark: BrandingAsset | null;
  favicon: BrandingAsset | null;
  /** The instance name, so the logo link has an accessible name and the
   *  logo-less case has something to render. Public on purpose: the login
   *  screen carries the branding. */
  instanceName: string;
}

/** A pond's own branding (issue #307), stored in its settings. Null per slot
 *  means "not set at this level". */
export const pondBrandingSchema = z.object({
  logo: brandingAssetSchema.nullable().default(null),
  logoDark: brandingAssetSchema.nullable().default(null),
  favicon: brandingAssetSchema.nullable().default(null),
});
export type PondBranding = z.infer<typeof pondBrandingSchema>;

/** What a pond page should actually show. */
export interface ResolvedBranding {
  logo: BrandingAsset | null;
  logoDark: BrandingAsset | null;
  favicon: BrandingAsset | null;
  /** Which level the LOGO came from — the link's accessible name follows it:
   *  a pond logo is named by the pond, an instance logo by the instance. */
  logoLevel: 'pond' | 'instance' | 'none';
  faviconLevel: 'pond' | 'instance' | 'default';
}

/**
 * The single place that decides which asset applies (issues #306/#307):
 * the pond's own, else the instance's, else the shipped default (favicon) or
 * the instance name as text (logo).
 *
 * **A logo set belongs to one level — variants are NEVER mixed across
 * levels.** A pond that uploaded only a light logo shows THAT logo in dark
 * mode; it does not fall back to the instance's dark variant. Decided
 * 2026-08-01: a logo silently swapping to a different image when the viewer
 * switches theme is a change nobody ordered, and a design that looks wrong is
 * more honest than one that is quietly substituted — the pond admin can see
 * it and fix it. Only a pond with NO logo at all inherits the instance's set,
 * again as a set.
 */
export function resolveBranding(
  instance: Pick<BrandingView, 'logo' | 'logoDark' | 'favicon'>,
  pond?: PondBranding | null,
): ResolvedBranding {
  const pondHasLogo = Boolean(pond && (pond.logo || pond.logoDark));
  const logoLevel = pondHasLogo ? 'pond' : instance.logo || instance.logoDark ? 'instance' : 'none';
  const source = pondHasLogo ? pond! : instance;
  const faviconLevel = pond?.favicon ? 'pond' : instance.favicon ? 'instance' : 'default';
  return {
    logo: logoLevel === 'none' ? null : source.logo,
    logoDark: logoLevel === 'none' ? null : source.logoDark,
    favicon: pond?.favicon ?? instance.favicon ?? null,
    logoLevel,
    faviconLevel,
  };
}