@linkforty/core 1.41.3 → 1.42.0

package/dist/lib/not-found-page.js

@@ -0,0 +1,212 @@
+/**
+ * The page a browser gets when a short link can't be served.
+ *
+ * Several different things end here: a code that never existed, one that expired
+ * or was switched off, a link on another organization's host, a visitor outside
+ * the link's targeting rules, and a link with nowhere to send this device. They
+ * all render the SAME page. An expired or switched-off link must not be told
+ * apart from a code that never existed (see the safety gate in
+ * routes/redirect.ts), and a page that varied its copy by reason would do exactly
+ * that. The reason decides whose settings apply, never what the page says.
+ *
+ * What the page says, or where the visitor is sent instead, comes from the first
+ * of these that answers:
+ *
+ *   1. the `notFound` hook, for a deployment that needs logic;
+ *   2. the organization's `settings.notFound`, read by Core itself;
+ *   3. the instance's defaults: the `notFound` section of linkforty.config.json
+ *      (lib/config.ts), passed to the routes as `notFoundDefaults`;
+ *   4. the built-in page.
+ *
+ * The organization is the one the request's host belongs to. Failing that, for a
+ * live link that just has nothing for this visitor (a targeting miss, no
+ * destination), it is the link's own organization. An unknown, expired or
+ * switched-off code on a shared host has no organization to speak for it and gets
+ * the instance's page.
+ *
+ * A link withdrawn for abuse is not a not-found: it keeps its own 410 notice
+ * (generateBlockedLinkHTML in link-safety.ts) and never reaches this module.
+ *
+ * Clients that don't ask for HTML — API callers, scripts, health checks — keep
+ * the JSON body they have always had.
+ */
+import { escapeHtml, safeHref } from './link-safety.js';
+export const NOT_FOUND_DEFAULTS = {
+    title: 'Link not found',
+    message: "This link doesn't exist or is no longer available.",
+};
+/** JSON bodies kept for clients that don't accept HTML. */
+export const NOT_FOUND_JSON = {
+    default: { error: 'Link not found' },
+    no_destination: { error: 'No destination URL configured for this link' },
+};
+const TITLE_MAX = 120;
+const MESSAGE_MAX = 500;
+const BUTTON_LABEL_MAX = 60;
+const HEX_COLOR = /^#(?:[0-9a-f]{3,4}|[0-9a-f]{6}|[0-9a-f]{8})$/i;
+/** True when the request will render HTML — a browser navigation. */
+export function wantsHtml(accept) {
+    const value = Array.isArray(accept) ? accept.join(',') : accept ?? '';
+    return value.toLowerCase().includes('text/html');
+}
+/**
+ * The page's content-security policy. It runs no script at all, so none is
+ * allowed; images may come from any https origin because the logo is the host's.
+ */
+export function notFoundContentSecurityPolicy() {
+    return [
+        "default-src 'none'",
+        "img-src https: data:",
+        "style-src 'unsafe-inline'",
+        "base-uri 'none'",
+        "form-action 'none'",
+    ].join('; ');
+}
+/** A redirect target from the host's hook, or null when it isn't http(s). */
+export function safeNotFoundRedirect(url) {
+    return typeof url === 'string' ? safeHref(url) : null;
+}
+function text(value, max) {
+    if (typeof value !== 'string')
+        return null;
+    const trimmed = value.trim();
+    return trimmed ? trimmed.slice(0, max) : null;
+}
+function color(value) {
+    return typeof value === 'string' && HEX_COLOR.test(value.trim()) ? value.trim() : null;
+}
+const SETTING_KEYS = [
+    'redirectUrl',
+    'title',
+    'message',
+    'logoUrl',
+    'accentColor',
+    'backgroundColor',
+    'buttonLabel',
+    'buttonUrl',
+];
+/**
+ * Settings from stored JSON (an organization's `settings`): keeps the known
+ * string fields and returns null when none is set. Lenient on purpose, since a
+ * bad value in the database must not break a redirect; values are checked
+ * again where they are used. The config file is validated strictly instead
+ * (lib/config.ts).
+ */
+export function readNotFoundSettings(raw) {
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw))
+        return null;
+    const settings = {};
+    for (const key of SETTING_KEYS) {
+        const value = raw[key];
+        if (typeof value === 'string' && value.trim())
+            settings[key] = value.trim();
+    }
+    return Object.keys(settings).length > 0 ? settings : null;
+}
+/** An organization's not-found settings, from its `settings` column. */
+export function readOrganizationNotFoundSettings(orgSettings) {
+    if (!orgSettings || typeof orgSettings !== 'object')
+        return null;
+    return readNotFoundSettings(orgSettings.notFound);
+}
+/** How long an organization's settings are reused before being read again. */
+export const NOT_FOUND_SETTINGS_TTL_MS = 60000;
+const NOT_FOUND_SETTINGS_MAX_ENTRIES = 1000;
+/**
+ * Read an organization's not-found settings, reusing each answer for a minute.
+ *
+ * Only an unknown code on an organization's host needs this: every other case
+ * already has the link row, which carries its organization's settings. Unknown
+ * codes are what scanners hit, so the answer is held rather than read per
+ * request. A change to the settings shows within NOT_FOUND_SETTINGS_TTL_MS.
+ *
+ * A factory rather than module state, so each registration (and each test) has
+ * its own. A failed read resolves to null and is not held.
+ */
+export function createOrganizationNotFoundSettingsLookup(deps) {
+    const held = new Map();
+    const now = deps.now ?? Date.now;
+    return async (organizationId) => {
+        const hit = held.get(organizationId);
+        if (hit && hit.until > now())
+            return hit.settings;
+        try {
+            const result = await deps.query('SELECT settings FROM organizations WHERE id = $1', [organizationId]);
+            const settings = readOrganizationNotFoundSettings(result.rows[0]?.settings);
+            if (held.size >= NOT_FOUND_SETTINGS_MAX_ENTRIES)
+                held.clear();
+            held.set(organizationId, { settings, until: now() + NOT_FOUND_SETTINGS_TTL_MS });
+            return settings;
+        }
+        catch (error) {
+            deps.onError?.(error);
+            return null;
+        }
+    };
+}
+/** What settings ask for: a redirect when they name a valid URL, otherwise the page. */
+export function resolveNotFoundSettings(settings) {
+    const target = settings.redirectUrl ? safeNotFoundRedirect(settings.redirectUrl) : null;
+    if (target)
+        return { kind: 'redirect', url: target };
+    const { redirectUrl: _ignored, ...content } = settings;
+    return { kind: 'page', content };
+}
+export function renderNotFoundPage(content = {}) {
+    const title = escapeHtml(text(content.title, TITLE_MAX) ?? NOT_FOUND_DEFAULTS.title);
+    const message = escapeHtml(text(content.message, MESSAGE_MAX) ?? NOT_FOUND_DEFAULTS.message);
+    const logoUrl = typeof content.logoUrl === 'string' ? safeHref(content.logoUrl.trim()) : null;
+    const buttonUrl = typeof content.buttonUrl === 'string' ? safeHref(content.buttonUrl.trim()) : null;
+    const buttonLabel = text(content.buttonLabel, BUTTON_LABEL_MAX);
+    const accent = color(content.accentColor);
+    const background = color(content.backgroundColor);
+    // Written after the dark-mode block so the accent wins in both schemes. The
+    // background applies in light mode only: a brand background is almost always
+    // light, and behind the dark-mode card it would show as a bright frame.
+    const brandStyles = [
+        accent ? `.button { background:${accent}; color:#fff; }` : '',
+        background ? `@media (prefers-color-scheme: light) { body { background:${background}; } }` : '',
+    ].join('\n  ');
+    const logo = logoUrl
+        ? `<img class="logo" src="${escapeHtml(logoUrl)}" alt="" referrerpolicy="no-referrer">\n    `
+        : '';
+    const button = buttonUrl && buttonLabel
+        ? `\n    <a class="button" href="${escapeHtml(buttonUrl)}" rel="noopener noreferrer">${escapeHtml(buttonLabel)}</a>`
+        : '';
+    return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width,initial-scale=1">
+<meta name="robots" content="noindex,nofollow">
+<title>${title}</title>
+<style>
+  :root { color-scheme: light dark; }
+  body { margin:0; min-height:100vh; display:flex; align-items:center; justify-content:center;
+         background:#f6f7f8; color:#16191d; padding:24px; box-sizing:border-box;
+         font:16px/1.55 -apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,sans-serif; }
+  .card { max-width:30rem; width:100%; background:#fff; border:1px solid #e3e6ea;
+          border-radius:10px; padding:28px; text-align:center; box-sizing:border-box; }
+  .logo { display:block; max-height:48px; max-width:60%; margin:0 auto 18px; }
+  h1 { margin:0 0 10px; font-size:1.25rem; line-height:1.3; }
+  p { margin:0; color:#5b636d; }
+  .button { display:inline-block; margin-top:20px; padding:10px 18px; border-radius:8px;
+         background:#16191d; color:#fff; text-decoration:none; font-weight:600; }
+  @media (prefers-color-scheme: dark) {
+    body { background:#14171a; color:#e8eaed; }
+    .card { background:#1d2126; border-color:#2c3238; }
+    p { color:#98a1ab; }
+    .button { background:#e8eaed; color:#14171a; }
+  }
+  ${brandStyles}
+</style>
+</head>
+<body>
+  <main class="card">
+    ${logo}<h1>${title}</h1>
+    <p>${message}</p>${button}
+  </main>
+</body>
+</html>`;
+}
+//# sourceMappingURL=not-found-page.js.map

package/dist/lib/not-found-page.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"not-found-page.js","sourceRoot":"","sources":["../../src/lib/not-found-page.ts"],"names":[],"mappings":"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"}

package/dist/lib/not-found-page.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=not-found-page.test.d.ts.map

package/dist/lib/not-found-page.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"not-found-page.test.d.ts","sourceRoot":"","sources":["../../src/lib/not-found-page.test.ts"],"names":[],"mappings":""}

package/dist/lib/not-found-page.test.js

@@ -0,0 +1,151 @@
+import { describe, it, expect, vi } from 'vitest';
+import { NOT_FOUND_DEFAULTS, NOT_FOUND_SETTINGS_TTL_MS, createOrganizationNotFoundSettingsLookup, readNotFoundSettings, readOrganizationNotFoundSettings, resolveNotFoundSettings, notFoundContentSecurityPolicy, renderNotFoundPage, safeNotFoundRedirect, wantsHtml, } from './not-found-page.js';
+describe('wantsHtml', () => {
+    it('is true for a browser navigation', () => {
+        expect(wantsHtml('text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8')).toBe(true);
+    });
+    it('is false for JSON clients, wildcards and a missing header', () => {
+        expect(wantsHtml('application/json')).toBe(false);
+        expect(wantsHtml('*/*')).toBe(false);
+        expect(wantsHtml(undefined)).toBe(false);
+    });
+    it('reads a repeated header', () => {
+        expect(wantsHtml(['application/json', 'text/html'])).toBe(true);
+    });
+});
+describe('renderNotFoundPage', () => {
+    it('renders the default copy with no content', () => {
+        const html = renderNotFoundPage();
+        expect(html).toContain(`<title>${NOT_FOUND_DEFAULTS.title}</title>`);
+        expect(html).toContain('doesn&#39;t exist or is no longer available.');
+        expect(html).not.toContain('<a ');
+        expect(html).not.toContain('<img');
+    });
+    it('runs no script', () => {
+        expect(renderNotFoundPage({ title: 'x' })).not.toContain('<script');
+        expect(notFoundContentSecurityPolicy()).not.toContain('script-src');
+        expect(notFoundContentSecurityPolicy()).toContain("default-src 'none'");
+    });
+    it('renders host content', () => {
+        const html = renderNotFoundPage({
+            title: 'Nothing here',
+            message: 'Try our homepage.',
+            logoUrl: 'https://cdn.example.com/logo.png',
+            accentColor: '#0d9488',
+            backgroundColor: '#fafafa',
+            buttonLabel: 'Go home',
+            buttonUrl: 'https://example.com/',
+        });
+        expect(html).toContain('<h1>Nothing here</h1>');
+        expect(html).toContain('<p>Try our homepage.</p>');
+        expect(html).toContain('src="https://cdn.example.com/logo.png"');
+        expect(html).toContain('href="https://example.com/"');
+        expect(html).toContain('>Go home</a>');
+        expect(html).toContain('background:#0d9488');
+        expect(html).toContain('background:#fafafa');
+    });
+    it('applies the brand background in light mode only', () => {
+        const html = renderNotFoundPage({ backgroundColor: '#ecfdf5' });
+        expect(html).toContain('@media (prefers-color-scheme: light) { body { background:#ecfdf5; } }');
+        expect(html.match(/background:#ecfdf5/g)).toHaveLength(1);
+    });
+    it('escapes host copy', () => {
+        const html = renderNotFoundPage({ title: '<script>alert(1)</script>', message: '"><img src=x>' });
+        expect(html).not.toContain('<script>alert(1)');
+        expect(html).toContain('&lt;script&gt;alert(1)&lt;/script&gt;');
+        expect(html).not.toContain('"><img src=x>');
+    });
+    it('drops non-http URLs', () => {
+        const html = renderNotFoundPage({
+            logoUrl: 'javascript:alert(1)',
+            buttonLabel: 'Click',
+            buttonUrl: 'javascript:alert(1)',
+        });
+        expect(html).not.toContain('javascript:');
+        expect(html).not.toContain('<a ');
+        expect(html).not.toContain('<img');
+    });
+    it('needs both a label and a URL for the button', () => {
+        expect(renderNotFoundPage({ buttonUrl: 'https://example.com/' })).not.toContain('<a ');
+        expect(renderNotFoundPage({ buttonLabel: 'Go' })).not.toContain('<a ');
+    });
+    it('drops colors that are not hex', () => {
+        const html = renderNotFoundPage({ accentColor: 'red;}body{display:none', backgroundColor: 'url(x)' });
+        expect(html).not.toContain('display:none');
+        expect(html).not.toContain('url(x)');
+    });
+    it('treats blank copy as absent', () => {
+        expect(renderNotFoundPage({ title: '   ' })).toContain(`<h1>${NOT_FOUND_DEFAULTS.title}</h1>`);
+    });
+    it('caps long copy', () => {
+        const html = renderNotFoundPage({ title: 'x'.repeat(1000) });
+        expect(html).not.toContain('x'.repeat(121));
+    });
+});
+describe('safeNotFoundRedirect', () => {
+    it('accepts http(s)', () => {
+        expect(safeNotFoundRedirect('https://example.com/a?b=1')).toBe('https://example.com/a?b=1');
+    });
+    it('rejects everything else', () => {
+        expect(safeNotFoundRedirect('javascript:alert(1)')).toBeNull();
+        expect(safeNotFoundRedirect('/relative')).toBeNull();
+        expect(safeNotFoundRedirect(undefined)).toBeNull();
+    });
+});
+describe('readNotFoundSettings', () => {
+    it('keeps known, non-empty string fields', () => {
+        expect(readNotFoundSettings({ title: ' Hi ', message: '', logoUrl: 42, extra: 'x', redirectUrl: 'https://a.example' }))
+            .toEqual({ title: 'Hi', redirectUrl: 'https://a.example' });
+    });
+    it('is null when nothing is set', () => {
+        expect(readNotFoundSettings({})).toBeNull();
+        expect(readNotFoundSettings(null)).toBeNull();
+        expect(readNotFoundSettings(['title'])).toBeNull();
+    });
+    it('reads an organization settings column', () => {
+        expect(readOrganizationNotFoundSettings({ notFound: { title: 'Org' }, launchpad: {} })).toEqual({ title: 'Org' });
+        expect(readOrganizationNotFoundSettings({ launchpad: {} })).toBeNull();
+    });
+});
+describe('resolveNotFoundSettings', () => {
+    it('redirects when the settings name a valid URL', () => {
+        expect(resolveNotFoundSettings({ redirectUrl: 'https://example.com/', title: 'x' }))
+            .toEqual({ kind: 'redirect', url: 'https://example.com/' });
+    });
+    it('renders the page when the redirect is not http(s)', () => {
+        expect(resolveNotFoundSettings({ redirectUrl: 'javascript:alert(1)', title: 'x' }))
+            .toEqual({ kind: 'page', content: { title: 'x' } });
+    });
+});
+describe('createOrganizationNotFoundSettingsLookup', () => {
+    it('holds an answer for the TTL, then reads again', async () => {
+        let clock = 0;
+        const query = vi.fn(async () => ({ rows: [{ settings: { notFound: { title: 'Org' } } }] }));
+        const lookup = createOrganizationNotFoundSettingsLookup({ query, now: () => clock });
+        expect(await lookup('org-a')).toEqual({ title: 'Org' });
+        await lookup('org-a');
+        expect(query).toHaveBeenCalledTimes(1);
+        clock += NOT_FOUND_SETTINGS_TTL_MS + 1;
+        await lookup('org-a');
+        expect(query).toHaveBeenCalledTimes(2);
+    });
+    it('holds a "no settings" answer too', async () => {
+        const query = vi.fn(async () => ({ rows: [] }));
+        const lookup = createOrganizationNotFoundSettingsLookup({ query });
+        expect(await lookup('org-a')).toBeNull();
+        await lookup('org-a');
+        expect(query).toHaveBeenCalledTimes(1);
+    });
+    it('does not hold a failed read', async () => {
+        const onError = vi.fn();
+        const query = vi
+            .fn()
+            .mockRejectedValueOnce(new Error('db down'))
+            .mockResolvedValueOnce({ rows: [{ settings: { notFound: { title: 'Org' } } }] });
+        const lookup = createOrganizationNotFoundSettingsLookup({ query, onError });
+        expect(await lookup('org-a')).toBeNull();
+        expect(onError).toHaveBeenCalledOnce();
+        expect(await lookup('org-a')).toEqual({ title: 'Org' });
+    });
+});
+//# sourceMappingURL=not-found-page.test.js.map

package/dist/lib/not-found-page.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"not-found-page.test.js","sourceRoot":"","sources":["../../src/lib/not-found-page.test.ts"],"names":[],"mappings":"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"}

package/dist/routes/redirect.d.ts

@@ -1,5 +1,6 @@
 import { FastifyInstance, FastifyRequest } from 'fastify';
 import { type LaunchpadContent, type LaunchpadContentContext, type LaunchpadSettings } from '../lib/launchpad.js';
+import { type NotFoundContext, type NotFoundResolution, type NotFoundSettings } from '../lib/not-found-page.js';
 /**
  * Detect iOS in-app browsers where Universal Links don't fire.
  * These browsers use WKWebView which bypasses the Universal Links mechanism.
@@ -86,6 +87,26 @@ export interface RedirectRouteOptions {
      * claim its URLs either. A hook that throws is logged and treated as false.
      */
     isWebLinkRequest?: (request: FastifyRequest) => Promise<boolean> | boolean;
+    /**
+     * The instance's not-found page, or a URL to send browsers to instead, used
+     * when the organization has no `settings.notFound` of its own
+     * (lib/not-found-page.ts). createServer() fills it from the `notFound`
+     * section of linkforty.config.json.
+     */
+    notFoundDefaults?: NotFoundSettings;
+    /**
+     * Decide the not-found response in code, ahead of the organization's settings
+     * and `notFoundDefaults`: page content, a URL to redirect to, or null to fall
+     * through to them. Called only for requests that accept HTML; other clients
+     * keep the JSON 404. Not called for a link withdrawn for abuse, which keeps its
+     * own notice.
+     *
+     * `context.reason` is for the host's own decisions. Whatever the host returns,
+     * return the same thing for every reason it treats alike: an expired link must
+     * not be told apart from a code that never existed. A hook that throws is
+     * logged and treated as null.
+     */
+    notFound?: (request: FastifyRequest, context: NotFoundContext) => Promise<NotFoundResolution | null> | NotFoundResolution | null;
 }
 export declare function redirectRoutes(fastify: FastifyInstance, options?: RedirectRouteOptions): Promise<void>;
 //# sourceMappingURL=redirect.d.ts.map

package/dist/routes/redirect.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"redirect.d.ts","sourceRoot":"","sources":["../../src/routes/redirect.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAiB1D,OAAO,EASL,KAAK,gBAAgB,EACrB,KAAK,uBAAuB,EAC5B,KAAK,iBAAiB,EACvB,MAAM,qBAAqB,CAAC;AAK7B;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAa5D;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAiBhE;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,KAAK,GAAG,SAAS,EACzB,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,GAAG,IAAI,EACrB,UAAU,EAAE,MAAM,GAAG,IAAI,EACzB,cAAc,EAAE,MAAM,GAAG,IAAI,GAC5B;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAexC;AAKD;;;;;;;;;;GAUG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAMlD;AAED;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAiB5E;AAmID,MAAM,WAAW,oBAAoB;IACnC;;;OAGG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;;OAGG;IACH,SAAS,CAAC,EAAE;QACV;;;;WAIG;QACH,cAAc,CAAC,EAAE,CACf,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EACzB,QAAQ,EAAE,iBAAiB,EAC3B,OAAO,EAAE,uBAAuB,KAC7B,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC,GAAG,gBAAgB,GAAG,IAAI,CAAC;QAChE;;;;;;WAMG;QACH,SAAS,CAAC,EAAE,MAAM,CAAC;KACpB,CAAC;IACF;;;;;;;OAOG;IACH,gBAAgB,CAAC,EAAE,CAAC,OAAO,EAAE,cAAc,KAAK,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC;CAC5E;AAED,wBAAsB,cAAc,CAClC,OAAO,EAAE,eAAe,EACxB,OAAO,GAAE,oBAAyB,iBAmyBnC"}
+{"version":3,"file":"redirect.d.ts","sourceRoot":"","sources":["../../src/routes/redirect.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAiB1D,OAAO,EASL,KAAK,gBAAgB,EACrB,KAAK,uBAAuB,EAC5B,KAAK,iBAAiB,EACvB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAUL,KAAK,eAAe,EAEpB,KAAK,kBAAkB,EACvB,KAAK,gBAAgB,EACtB,MAAM,0BAA0B,CAAC;AAKlC;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAa5D;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAiBhE;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,KAAK,GAAG,SAAS,EACzB,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,GAAG,IAAI,EACrB,UAAU,EAAE,MAAM,GAAG,IAAI,EACzB,cAAc,EAAE,MAAM,GAAG,IAAI,GAC5B;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAexC;AAKD;;;;;;;;;;GAUG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAMlD;AAED;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAiB5E;AAmID,MAAM,WAAW,oBAAoB;IACnC;;;OAGG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;;OAGG;IACH,SAAS,CAAC,EAAE;QACV;;;;WAIG;QACH,cAAc,CAAC,EAAE,CACf,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EACzB,QAAQ,EAAE,iBAAiB,EAC3B,OAAO,EAAE,uBAAuB,KAC7B,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC,GAAG,gBAAgB,GAAG,IAAI,CAAC;QAChE;;;;;;WAMG;QACH,SAAS,CAAC,EAAE,MAAM,CAAC;KACpB,CAAC;IACF;;;;;;;OAOG;IACH,gBAAgB,CAAC,EAAE,CAAC,OAAO,EAAE,cAAc,KAAK,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC;IAC3E;;;;;OAKG;IACH,gBAAgB,CAAC,EAAE,gBAAgB,CAAC;IACpC;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,EAAE,CACT,OAAO,EAAE,cAAc,EACvB,OAAO,EAAE,eAAe,KACrB,OAAO,CAAC,kBAAkB,GAAG,IAAI,CAAC,GAAG,kBAAkB,GAAG,IAAI,CAAC;CACrE;AAED,wBAAsB,cAAc,CAClC,OAAO,EAAE,eAAe,EACxB,OAAO,GAAE,oBAAyB,iBAi3BnC"}

package/dist/routes/redirect.js

@@ -8,6 +8,7 @@ import { emitClickEvent } from '../lib/event-emitter.js';
 import { classifyBot, edgeBotSignal } from '../lib/bot-detection.js';
 import { evaluateLinkSafetyDecision, blockCauseIsAbuse, generateWarningLinkHTML, generateBlockedLinkHTML, createOwnerSuspensionSelect, escapeHtml, safeSchemeHref, } from '../lib/link-safety.js';
 import { createLaunchpadNonce, defaultLaunchpadContent, launchpadContentSecurityPolicy, readLaunchpadLinkMode, readLaunchpadSettings, renderLaunchpadPage, shouldServeLaunchpadOnDesktop, shouldServeLaunchpadOnMobile, } from '../lib/launchpad.js';
+import { NOT_FOUND_JSON, createOrganizationNotFoundSettingsLookup, notFoundContentSecurityPolicy, readNotFoundSettings, readOrganizationNotFoundSettings, renderNotFoundPage, resolveNotFoundSettings, safeNotFoundRedirect, wantsHtml, } from '../lib/not-found-page.js';
 /** Longest query string the Launchpad page carries into its QR code and og:url. */
 const MAX_PAGE_URL_SEARCH = 512;
 /**
@@ -299,6 +300,68 @@ export async function redirectRoutes(fastify, options = {}) {
             fastify.log.warn({ err: error }, 'Bare code ownership check failed');
         }
     }
+    /**
+     * Answer a link that can't be served. Browsers get the not-found page (or the
+     * host's redirect); everything else gets the JSON body it always has. Records
+     * nothing: whether a click was already written is up to the caller.
+     */
+    const notFoundDefaults = readNotFoundSettings(options.notFoundDefaults);
+    const lookupOrganizationNotFoundSettings = createOrganizationNotFoundSettingsLookup({
+        query: (sql, params) => db.query(sql, params),
+        onError: (err) => fastify.log.warn({ err }, 'Reading not-found settings failed; using the instance page'),
+    });
+    /**
+     * The settings that speak for this not-found: the host's organization, or for
+     * a live link with nothing for this visitor, the link's own organization;
+     * then the instance's. See lib/not-found-page.ts.
+     */
+    async function notFoundSettingsFor(reason, link, scope) {
+        const linkSpeaks = reason === 'not_targeted' || reason === 'no_destination';
+        const organizationId = scope ?? (linkSpeaks ? link?.organization_id ?? null : null);
+        if (organizationId) {
+            const own = link && link.organization_id === organizationId
+                ? readOrganizationNotFoundSettings(link.org_settings)
+                : await lookupOrganizationNotFoundSettings(organizationId);
+            if (own)
+                return own;
+        }
+        return notFoundDefaults;
+    }
+    async function sendNotFound(request, reply, reason, link, scope) {
+        if (!wantsHtml(request.headers.accept)) {
+            return reply
+                .status(404)
+                .send(reason === 'no_destination' ? NOT_FOUND_JSON.no_destination : NOT_FOUND_JSON.default);
+        }
+        let resolution = null;
+        if (options.notFound) {
+            try {
+                resolution = (await options.notFound(request, { reason, link, scope })) ?? null;
+            }
+            catch (err) {
+                fastify.log.error({ err, reason }, 'notFound hook threw; using the configured page');
+            }
+        }
+        if (!resolution) {
+            const settings = await notFoundSettingsFor(reason, link, scope);
+            if (settings)
+                resolution = resolveNotFoundSettings(settings);
+        }
+        if (resolution?.kind === 'redirect') {
+            const target = safeNotFoundRedirect(resolution.url);
+            if (target) {
+                return reply.header('Cache-Control', 'no-store').redirect(302, target);
+            }
+            fastify.log.warn({ reason }, 'Not-found redirect is not http(s); using the default page');
+        }
+        return reply
+            .status(404)
+            .header('X-Robots-Tag', 'noindex, nofollow')
+            .header('Cache-Control', 'no-store')
+            .header('Content-Security-Policy', notFoundContentSecurityPolicy())
+            .type('text/html')
+            .send(renderNotFoundPage(resolution?.kind === 'page' ? resolution.content : {}));
+    }
     // Helper function to handle the actual redirect logic
     async function handleRedirect(request, reply, shortCode, templateSlug) {
         let linkData = null;
@@ -360,7 +423,7 @@ export async function redirectRoutes(fastify, options = {}) {
             if (result.rows.length === 0) {
                 if (scope)
                     await logOtherOrganizationCode(shortCode, scope);
-                return reply.status(404).send({ error: 'Link not found' });
+                return sendNotFound(request, reply, 'unknown', null, hostScope);
             }
             linkData = JSON.stringify(result.rows[0]);
             // Cache for 5 minutes if Redis is available
@@ -378,7 +441,9 @@ export async function redirectRoutes(fastify, options = {}) {
         // URL form names them. Checked after the cache read, which is shared by hosts.
         if (hostScope && link.organization_id !== hostScope) {
             logOtherOrganizationLink(shortCode, hostScope);
-            return reply.status(404).send({ error: 'Link not found' });
+            // Indistinguishable from a code that doesn't exist, and the row is not
+            // this host's to hand to the hook.
+            return sendNotFound(request, reply, 'unknown', null, hostScope);
         }
         // Safety gate, applied after the cache read so it covers cached rows too.
         //
@@ -417,7 +482,7 @@ export async function redirectRoutes(fastify, options = {}) {
                     .type('text/html')
                     .send(generateBlockedLinkHTML());
             }
-            return reply.status(404).send({ error: 'Link not found' });
+            return sendNotFound(request, reply, 'disabled', link, hostScope);
         }
         if (safety.outcome === 'warn') {
             // No click is recorded here. A warning view is not a click on the link, and
@@ -464,7 +529,7 @@ export async function redirectRoutes(fastify, options = {}) {
             }
             // If targeting rules exist but user doesn't match, return 404
             if (!isTargeted) {
-                return reply.status(404).send({ error: 'Link not found' });
+                return sendNotFound(request, reply, 'not_targeted', link, hostScope);
             }
         }
         // Asked once per click: the async click record and the response below
@@ -900,8 +965,8 @@ export async function redirectRoutes(fastify, options = {}) {
          * No destination at any level of the chain.
          *
          * On desktop this is a real person who clicked a real link, so serve a page
-         * rather than a JSON error body. Mobile keeps the 404: the branches above
-         * already offer a store URL to a device that could install the app, so
+         * rather than a JSON error body. Mobile gets the not-found page: the branches
+         * above already offer a store URL to a device that could install the app, so
          * reaching here means the link has nothing at all.
          *
          * Unlike the warning page earlier in this handler, this does NOT suppress
@@ -922,7 +987,7 @@ export async function redirectRoutes(fastify, options = {}) {
                     androidUrl,
                 }));
             }
-            return reply.status(404).send({ error: 'No destination URL configured for this link' });
+            return sendNotFound(request, reply, 'no_destination', link, hostScope);
         }
         // Build final URL with parameters
         let finalUrl = redirectUrl;