diff --git a/apps/web/src/routes/(protected)/page.test.ts b/apps/web/src/routes/(protected)/page.test.ts
index c62bbdb..2e309d2 100644
--- a/apps/web/src/routes/(protected)/page.test.ts
+++ b/apps/web/src/routes/(protected)/page.test.ts
@@ -7,6 +7,7 @@ import { actions, load } from './+page.server.js';
function eventFor(query = '', withAuth = false) {
const configuration: Record
= {
site: {
+ ...(withAuth ? { url: 'https://private-auth.example.test' } : {}),
title: 'Home Server',
description: 'Useful things running at home.',
footer: 'Ask the household for help.',
@@ -33,7 +34,6 @@ function eventFor(query = '', withAuth = false) {
};
if (withAuth) {
configuration.auth = {
- origin: 'https://private-auth.example.test',
secret: 'PRIVATE_SESSION_SECRET_AT_LEAST_32_CHARACTERS',
credentials: { username: 'PRIVATE_USERNAME', password: 'PRIVATE_PASSWORD' }
};
diff --git a/apps/web/src/routes/(public)/favicon/server.test.ts b/apps/web/src/routes/(public)/favicon/server.test.ts
index f9356c9..fea6366 100644
--- a/apps/web/src/routes/(public)/favicon/server.test.ts
+++ b/apps/web/src/routes/(public)/favicon/server.test.ts
@@ -48,8 +48,8 @@ describe('public favicon alias', () => {
it.each([
['GET', undefined],
['HEAD', undefined],
- ['GET', '/favicon.svg'],
- ['HEAD', '/favicon.svg']
+ ['GET', '/favicon.png'],
+ ['HEAD', '/favicon.png']
] as const)('returns 404 before I/O for %s with bundled selection %s', async (method, source) => {
const response = await GET(event(method, snapshot(source)));
expect(readMountedImage).not.toHaveBeenCalled();
diff --git a/apps/web/src/routes/(public)/images/og.png/+server.ts b/apps/web/src/routes/(public)/images/og.png/+server.ts
new file mode 100644
index 0000000..0e3690d
--- /dev/null
+++ b/apps/web/src/routes/(public)/images/og.png/+server.ts
@@ -0,0 +1,31 @@
+import { readMountedImage } from '../../../../lib/server/images/read-mounted-image.js';
+import { imageResponse } from '../../../../lib/server/images/image-response.js';
+import { renderOpenGraph } from '../../../../lib/server/images/render-open-graph.js';
+import { logger } from '../../../../lib/server/logger.js';
+import type { RequestHandler } from './$types';
+
+export const GET: RequestHandler = async ({ locals, request }) => {
+ const { site, appearance } = locals.snapshot.configuration;
+ const favicon = site.favicon_path.startsWith('/public/')
+ ? await readMountedImage(locals.publicDir, site.favicon_path)
+ : undefined;
+ try {
+ const bytes = await renderOpenGraph({
+ url: site.url,
+ title: site.title,
+ description: site.description,
+ primaryLightColor: appearance.primary_light_color,
+ primaryDarkColor: appearance.primary_dark_color,
+ favicon: favicon?.bytes
+ });
+ return imageResponse(request.method, { bytes, contentType: 'image/png' });
+ } catch {
+ logger.error('Open Graph image rendering failed (og_render_failed).');
+ return new Response(request.method === 'HEAD' ? null : 'Image unavailable', {
+ status: 503,
+ headers: { 'cache-control': 'private, no-store', 'x-content-type-options': 'nosniff' }
+ });
+ }
+};
+
+export const HEAD = GET;
diff --git a/apps/web/src/routes/(public)/images/og.png/server.test.ts b/apps/web/src/routes/(public)/images/og.png/server.test.ts
new file mode 100644
index 0000000..e5da7e0
--- /dev/null
+++ b/apps/web/src/routes/(public)/images/og.png/server.test.ts
@@ -0,0 +1,261 @@
+import { validateConfig } from '@directory/config';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { prepareSnapshot } from '../../../../lib/server/directory/snapshot.js';
+import { readMountedImage } from '../../../../lib/server/images/read-mounted-image.js';
+import { renderOpenGraph } from '../../../../lib/server/images/render-open-graph.js';
+import { logger } from '../../../../lib/server/logger.js';
+import { GET, HEAD } from './+server.js';
+
+vi.mock('../../../../lib/server/images/read-mounted-image.js', () => ({
+ readMountedImage: vi.fn()
+}));
+vi.mock('../../../../lib/server/images/render-open-graph.js', () => ({ renderOpenGraph: vi.fn() }));
+vi.mock('../../../../lib/server/logger.js', () => ({ logger: { error: vi.fn() } }));
+
+const publicDir = '/PRIVATE_MOUNTED_ROOT';
+const faviconPath = '/public/café family.svg';
+const favicon = { bytes: new TextEncoder().encode(''), contentType: 'image/svg+xml' };
+const png = new Uint8Array([137, 80, 78, 71, 13, 10, 26, 10, 255, 0]);
+const appearance = { primary_light_color: '#123456', primary_dark_color: '#abc' };
+const branding = {
+ url: 'https://private.example',
+ title: 'Captured home',
+ description: 'Useful household services.',
+ primaryLightColor: '#123456',
+ primaryDarkColor: '#abc'
+};
+
+function snapshot(site: Record = {}, colors = appearance) {
+ return prepareSnapshot(
+ validateConfig(
+ {
+ site: {
+ url: branding.url,
+ title: branding.title,
+ description: branding.description,
+ footer: 'PRIVATE_FOOTER',
+ logo_path: '/public/private-logo.png',
+ ...site
+ },
+ appearance: colors,
+ auth: {
+ secret: 'PRIVATE_SESSION_SECRET_12345678901234567890',
+ credentials: { username: 'PRIVATE_USER', password: 'PRIVATE_PASSWORD' }
+ },
+ links: {
+ private: {
+ title: 'PRIVATE_LINK',
+ url: 'https://private.example/secret',
+ description: 'PRIVATE_LINK_DESCRIPTION',
+ group: 'PRIVATE_GROUP',
+ tags: ['PRIVATE_TAG'],
+ logo_path: '/public/private-link.png',
+ requires_auth: true,
+ internal_only: true,
+ admin_only: true
+ }
+ }
+ },
+ { env: {} }
+ )
+ );
+}
+
+function event(method: 'GET' | 'HEAD', captured = snapshot({ favicon_path: faviconPath })) {
+ return {
+ params: {},
+ locals: { snapshot: captured, publicDir, session: null, authentication: undefined },
+ url: new URL('http://localhost/images/og.png'),
+ request: new Request('http://localhost/images/og.png', { method })
+ } as Parameters[0];
+}
+
+async function expectPNG(response: Response, method: 'GET' | 'HEAD') {
+ expect(response.status).toBe(200);
+ expect(response.headers.get('content-type')).toBe('image/png');
+ expect(response.headers.get('content-length')).toBe(String(png.byteLength));
+ expect(response.headers.get('cache-control')).toBe('private, no-store');
+ expect(response.headers.get('x-content-type-options')).toBe('nosniff');
+ if (method === 'HEAD') expect(response.body).toBeNull();
+ expect(new Uint8Array(await response.arrayBuffer())).toEqual(
+ method === 'HEAD' ? new Uint8Array() : png
+ );
+}
+
+beforeEach(() => {
+ vi.mocked(readMountedImage).mockReset().mockResolvedValue(favicon);
+ vi.mocked(renderOpenGraph).mockReset().mockResolvedValue(png);
+ vi.mocked(logger.error).mockReset();
+});
+
+describe('public generated Open Graph image', () => {
+ it.each(['GET', 'HEAD'] as const)(
+ 'reads only the configured favicon and generates a PNG for %s',
+ async (method) => {
+ const response = await (method === 'HEAD' ? HEAD : GET)(event(method));
+ expect(readMountedImage).toHaveBeenCalledExactlyOnceWith(publicDir, faviconPath);
+ expect(renderOpenGraph).toHaveBeenCalledExactlyOnceWith({
+ ...branding,
+ favicon: favicon.bytes
+ });
+ expect(vi.mocked(renderOpenGraph).mock.calls[0]?.[0].favicon).toBe(favicon.bytes);
+ await expectPNG(response, method);
+ expect(logger.error).not.toHaveBeenCalled();
+ }
+ );
+
+ it.each([
+ ['GET', undefined],
+ ['HEAD', undefined],
+ ['GET', '/favicon.png'],
+ ['HEAD', '/favicon.png']
+ ] as const)(
+ 'generates %s without reading the bundled favicon selection %s',
+ async (method, path) => {
+ const config =
+ path === undefined ? { links: {} } : { site: { favicon_path: path }, links: {} };
+ const captured = prepareSnapshot(validateConfig(config, { env: {} }));
+ await expectPNG(await (method === 'HEAD' ? HEAD : GET)(event(method, captured)), method);
+ expect(readMountedImage).not.toHaveBeenCalled();
+ expect(renderOpenGraph).toHaveBeenCalledExactlyOnceWith({
+ url: 'http://localhost:3000',
+ title: 'Directory',
+ description: '',
+ primaryLightColor: '#0f766e',
+ primaryDarkColor: '#5eead4',
+ favicon: undefined
+ });
+ }
+ );
+
+ it.each(['GET', 'HEAD'] as const)(
+ 'passes an unavailable favicon as undefined for %s',
+ async (method) => {
+ vi.mocked(readMountedImage).mockResolvedValue(undefined);
+ await expectPNG(await (method === 'HEAD' ? HEAD : GET)(event(method)), method);
+ expect(readMountedImage).toHaveBeenCalledExactlyOnceWith(publicDir, faviconPath);
+ expect(renderOpenGraph).toHaveBeenCalledExactlyOnceWith({ ...branding, favicon: undefined });
+ }
+ );
+
+ it.each([
+ ['GET', '/favicon.png'],
+ ['HEAD', '/favicon.png'],
+ ['GET', faviconPath],
+ ['HEAD', faviconPath]
+ ] as const)(
+ 'always generates %s, even with a static OG image and favicon %s',
+ async (method, path) => {
+ const captured = snapshot({ favicon_path: path, og_image_path: '/public/static-share.jpg' });
+ await expectPNG(await (method === 'HEAD' ? HEAD : GET)(event(method, captured)), method);
+ expect(vi.mocked(readMountedImage).mock.calls).toEqual(
+ path === '/favicon.png' ? [] : [[publicDir, faviconPath]]
+ );
+ expect(renderOpenGraph).toHaveBeenCalledExactlyOnceWith({
+ ...branding,
+ favicon: path === '/favicon.png' ? undefined : favicon.bytes
+ });
+ }
+ );
+
+ it.each(['GET', 'HEAD'] as const)(
+ 'ignores request path, queries and headers for %s',
+ async (method) => {
+ for (const path of [
+ '/images/og.png?file=/public/other.jpg&publicDir=/outside&title=ATTACKER&url=https://attacker.example',
+ '/images/og.png?favicon_path=/public/other.svg&og_image_path=/public/other.jpg&primary_light_color=%23fff&primary_dark_color=%23000',
+ '/images/other.png?source=%252e%252e%252fsecret.svg&title=OTHER'
+ ]) {
+ const request = event(method);
+ request.url = new URL(path, 'http://attacker.example');
+ request.request = new Request(request.url, {
+ method,
+ headers: {
+ 'x-public-dir': '/outside',
+ 'x-favicon-path': '/public/other.svg',
+ 'x-title': 'HEADER_TITLE',
+ 'x-primary-light-color': '#fff',
+ 'x-primary-dark-color': '#000',
+ accept: 'image/jpeg',
+ range: 'bytes=0-1',
+ 'if-none-match': '*'
+ }
+ });
+ await expectPNG(await (method === 'HEAD' ? HEAD : GET)(request), method);
+ }
+ expect(vi.mocked(readMountedImage).mock.calls).toEqual(
+ Array.from({ length: 3 }, () => [publicDir, faviconPath])
+ );
+ expect(vi.mocked(renderOpenGraph).mock.calls).toEqual(
+ Array.from({ length: 3 }, () => [{ ...branding, favicon: favicon.bytes }])
+ );
+ }
+ );
+
+ it('keeps captured branding coherent across an async read, excluding display, assets and private data', async () => {
+ const replacement = event(
+ 'GET',
+ snapshot(
+ {
+ url: 'https://replacement.example',
+ title: 'Replacement',
+ description: 'Another household.',
+ favicon_path: '/public/replacement.png'
+ },
+ { primary_light_color: '#fed', primary_dark_color: '#654321' }
+ )
+ );
+ const captured = event('GET');
+ captured.locals.snapshot = {
+ ...captured.locals.snapshot,
+ display: replacement.locals.snapshot.display,
+ assets: { referencedPaths: [], brandingPaths: [], bookmarkLogos: {} }
+ };
+ const replacementFavicon = { bytes: new Uint8Array([1, 2, 3]), contentType: 'image/png' };
+ vi.mocked(readMountedImage).mockImplementationOnce(async () => {
+ captured.locals.snapshot = replacement.locals.snapshot;
+ return favicon;
+ });
+ await expectPNG(await GET(captured), 'GET');
+ vi.mocked(readMountedImage).mockResolvedValue(replacementFavicon);
+ await expectPNG(await GET(replacement), 'GET');
+ expect(vi.mocked(readMountedImage).mock.calls).toEqual([
+ [publicDir, faviconPath],
+ [publicDir, '/public/replacement.png']
+ ]);
+ expect(vi.mocked(renderOpenGraph).mock.calls).toEqual([
+ [{ ...branding, favicon: favicon.bytes }],
+ [
+ {
+ url: 'https://replacement.example',
+ title: 'Replacement',
+ description: 'Another household.',
+ primaryLightColor: '#fed',
+ primaryDarkColor: '#654321',
+ favicon: replacementFavicon.bytes
+ }
+ ]
+ ]);
+ });
+
+ it.each(['GET', 'HEAD'] as const)(
+ 'returns a generic 503 and fixed log message on %s rendering failure',
+ async (method) => {
+ const error = new Error(`PRIVATE_RENDER_SECRET ${publicDir}`);
+ error.stack = 'PRIVATE_STACK_TRACE';
+ vi.mocked(renderOpenGraph).mockRejectedValue(error);
+ const response = await (method === 'HEAD' ? HEAD : GET)(event(method));
+ expect(response.status).toBe(503);
+ expect(response.headers.get('cache-control')).toBe('private, no-store');
+ expect(response.headers.get('x-content-type-options')).toBe('nosniff');
+ if (method === 'HEAD') expect(response.body).toBeNull();
+ expect(await response.text()).toBe(method === 'HEAD' ? '' : 'Image unavailable');
+ expect(logger.error).toHaveBeenCalledExactlyOnceWith(
+ 'Open Graph image rendering failed (og_render_failed).'
+ );
+ expect(
+ JSON.stringify([...response.headers, ...vi.mocked(logger.error).mock.calls])
+ ).not.toContain('PRIVATE');
+ }
+ );
+});
diff --git a/apps/web/src/routes/(public)/logo/server.test.ts b/apps/web/src/routes/(public)/logo/server.test.ts
index 1718e3f..60c25af 100644
--- a/apps/web/src/routes/(public)/logo/server.test.ts
+++ b/apps/web/src/routes/(public)/logo/server.test.ts
@@ -48,8 +48,8 @@ describe('public selected-logo alias', () => {
it.each([
['GET', undefined],
['HEAD', undefined],
- ['GET', '/favicon.svg'],
- ['HEAD', '/favicon.svg']
+ ['GET', '/favicon.png'],
+ ['HEAD', '/favicon.png']
] as const)('returns 404 before I/O for %s with bundled selection %s', async (method, source) => {
const response = await GET(event(method, snapshot(source)));
expect(readMountedImage).not.toHaveBeenCalled();
diff --git a/apps/web/src/routes/(public)/signin/+page.svelte b/apps/web/src/routes/(public)/signin/+page.svelte
index bec8c8d..323d6f9 100644
--- a/apps/web/src/routes/(public)/signin/+page.svelte
+++ b/apps/web/src/routes/(public)/signin/+page.svelte
@@ -26,7 +26,7 @@
diff --git a/apps/web/src/routes/(public)/signin/page.test.ts b/apps/web/src/routes/(public)/signin/page.test.ts
index c4fef83..8c63d48 100644
--- a/apps/web/src/routes/(public)/signin/page.test.ts
+++ b/apps/web/src/routes/(public)/signin/page.test.ts
@@ -12,12 +12,12 @@ function eventFor(query = '', strategy: Authentication['strategy'] = 'credential
validateConfig(
{
site: {
+ url: 'https://private-auth.example.test',
title: 'Home Server',
description: 'PRIVATE_DESCRIPTION',
logo_path: '/public/private.svg'
},
auth: {
- origin: 'https://private-auth.example.test',
secret: 'PRIVATE_SESSION_SECRET_AT_LEAST_32_CHARACTERS',
credentials: { username: 'PRIVATE_USERNAME', password: 'PRIVATE_PASSWORD' }
},
diff --git a/apps/web/src/routes/+layout.server.ts b/apps/web/src/routes/+layout.server.ts
index 01f3eb9..a40a2ab 100644
--- a/apps/web/src/routes/+layout.server.ts
+++ b/apps/web/src/routes/+layout.server.ts
@@ -1,10 +1,23 @@
+import { readMountedImage } from '../lib/server/images/read-mounted-image.js';
+import { documentMetadata } from '../lib/server/document.js';
import type { LayoutServerLoad } from './$types';
-export const load = (({ locals }) => {
+export const load = (async ({ locals }) => {
const { site } = locals.snapshot.configuration;
+ const supplied = site.og_image_path
+ ? await readMountedImage(locals.publicDir, site.og_image_path)
+ : undefined;
let faviconPath = site.favicon_path;
if (faviconPath.startsWith('/public/')) faviconPath = '/favicon';
let logoPath = site.logo_path;
if (logoPath.startsWith('/public/')) logoPath = '/logo';
- return { faviconPath, logoPath };
+ return {
+ faviconPath,
+ logoPath,
+ document: documentMetadata(
+ site,
+ site.url,
+ supplied && { path: site.og_image_path!, contentType: supplied.contentType }
+ )
+ };
}) satisfies LayoutServerLoad;
diff --git a/apps/web/src/routes/+layout.svelte b/apps/web/src/routes/+layout.svelte
index 0409b45..9c210ce 100644
--- a/apps/web/src/routes/+layout.svelte
+++ b/apps/web/src/routes/+layout.svelte
@@ -2,6 +2,7 @@
import { onMount, type Snippet } from 'svelte';
import { page } from '$app/state';
import ConfigUpdateNotice from '$lib/components/ConfigUpdateNotice.svelte';
+ import DocumentHead from '$lib/components/DocumentHead.svelte';
import type { LayoutData } from './$types';
import '../lib/styles/reset.css';
import '../lib/styles/theme.css';
@@ -21,9 +22,7 @@
});
-
-
-
+
{@render children()}
diff --git a/apps/web/src/routes/layout.test.ts b/apps/web/src/routes/layout.test.ts
index ac7635f..e7921ff 100644
--- a/apps/web/src/routes/layout.test.ts
+++ b/apps/web/src/routes/layout.test.ts
@@ -1,25 +1,58 @@
import { validateConfig } from '@directory/config';
-import { describe, expect, it } from 'vitest';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
import { prepareSnapshot } from '../lib/server/directory/snapshot.js';
+import { readMountedImage } from '../lib/server/images/read-mounted-image.js';
import { load } from './+layout.server.js';
-function event(site: Record = {}) {
+vi.mock('../lib/server/images/read-mounted-image.js', () => ({ readMountedImage: vi.fn() }));
+
+function event(
+ site: Record = {},
+ {
+ siteUrl = 'https://directory.example.test',
+ url = 'https://internal.example.test/signin?callbackUrl=%2Fprivate&link=PRIVATE_QUERY#PRIVATE_FRAGMENT',
+ withAuth = true,
+ env = {}
+ }: {
+ siteUrl?: string | null;
+ url?: string;
+ withAuth?: boolean;
+ env?: Record;
+ } = {}
+) {
const snapshot = prepareSnapshot(
validateConfig(
{
- site: { title: 'PRIVATE_LAYOUT_TITLE', description: 'PRIVATE_DESCRIPTION', ...site },
- appearance: { primary_light_color: '#13579b', primary_dark_color: '#c4d6e8' },
- auth: {
- origin: 'https://private-auth.example.test',
- secret: 'PRIVATE_SESSION_SECRET_AT_LEAST_32_CHARACTERS',
- credentials: { username: 'PRIVATE_USERNAME', password: 'PRIVATE_PASSWORD' }
+ site: {
+ ...(siteUrl === null ? {} : { url: siteUrl }),
+ title: 'Home Server',
+ description: 'Public site description',
+ footer: 'PRIVATE_FOOTER',
+ ...site
},
- links: { private: { title: 'PRIVATE_LINK', url: 'https://private.example.test' } }
+ appearance: { primary_light_color: '#13579b', primary_dark_color: '#c4d6e8' },
+ ...(!withAuth
+ ? {}
+ : {
+ auth: {
+ secret: 'PRIVATE_SESSION_SECRET_AT_LEAST_32_CHARACTERS',
+ credentials: { username: 'PRIVATE_USERNAME', password: 'PRIVATE_PASSWORD' }
+ }
+ }),
+ links: {
+ private: {
+ title: 'PRIVATE_LINK',
+ url: 'https://private.example.test',
+ description: 'PRIVATE_LINK_DESCRIPTION',
+ group: 'PRIVATE_GROUP'
+ }
+ }
},
- { env: {} }
+ { env }
)
);
return {
+ url: new URL(url),
locals: {
snapshot,
publicDir: '/PRIVATE_PUBLIC_ROOT',
@@ -30,59 +63,174 @@ function event(site: Record = {}) {
} as unknown as Parameters[0];
}
+function expectedData(faviconPath = '/favicon.png', logoPath = '/favicon.png') {
+ return {
+ faviconPath,
+ logoPath,
+ document: {
+ title: 'Home Server',
+ description: 'Public site description',
+ url: 'https://directory.example.test/',
+ image: {
+ url: 'https://directory.example.test/images/og.png',
+ type: 'image/png',
+ width: 1200,
+ height: 630
+ }
+ }
+ };
+}
+
+beforeEach(() => {
+ vi.mocked(readMountedImage).mockReset();
+});
+
describe('public branding layout data', () => {
- it('returns only constant aliases, with no appearance or private payload', () => {
+ it('publishes only public branding metadata, never private directory data', async () => {
const captured = event();
const before = JSON.stringify(captured.locals);
- const data = load(captured);
- expect(data).toEqual({ faviconPath: '/favicon.svg', logoPath: '/favicon.svg' });
+ const data = await load(captured);
+ expect(data).toEqual(expectedData());
+ for (const privateValue of ['PRIVATE_', 'private.example.test', '2099-01-01', '#13579b']) {
+ expect(JSON.stringify(data)).not.toContain(privateValue);
+ }
expect(JSON.stringify(captured.locals)).toBe(before);
+ expect(readMountedImage).not.toHaveBeenCalled();
});
- it('passes explicit resolved bundled selections through without mounted aliases', () => {
- const captured = event({ logo_path: '/favicon.svg', favicon_path: '/favicon.svg' });
- expect(load(captured)).toEqual({ faviconPath: '/favicon.svg', logoPath: '/favicon.svg' });
+ it.each([
+ { name: 'public text', description: 'Public site description' },
+ { name: 'empty text', description: '' },
+ { name: 'whitespace', description: ' \t\n ' },
+ {
+ name: 'full, unescaped text',
+ description: ` & "family"\n${'Full text. '.repeat(200)} `
+ }
+ ])('publishes the public site description with $name', async ({ description }) => {
+ const data = await load(event({ description }));
+ expect(data).toEqual({
+ ...expectedData(),
+ document: { ...expectedData().document, description }
+ });
+ });
+
+ it('preserves explicit bundled favicon and logo selections', async () => {
+ expect(await load(event({ logo_path: '/favicon.png', favicon_path: '/favicon.png' }))).toEqual(
+ expectedData()
+ );
});
it.each(['/public/PRIVATE_SOURCE.png', '/public/café family.svg'])(
- 'publishes constant aliases, never configured source %s or image bytes',
- (source) => {
- const captured = event({ logo_path: source, favicon_path: source });
- captured.locals.snapshot = {
- ...captured.locals.snapshot,
- assets: {
- referencedPaths: [source],
- brandingPaths: [source],
- bookmarkLogos: { private: 'PRIVATE_SVG_BYTES' }
- }
- };
- const data = load(captured);
- expect(data).toEqual({ faviconPath: '/favicon', logoPath: '/logo' });
+ 'keeps existing favicon/logo aliases for %s unchanged',
+ async (source) => {
+ const data = await load(event({ logo_path: source, favicon_path: source }));
+ expect(data).toEqual(expectedData('/favicon', '/logo'));
expect(JSON.stringify(data)).not.toContain(source);
- expect(JSON.stringify(data)).not.toContain('PRIVATE_');
+ expect(readMountedImage).not.toHaveBeenCalled();
}
);
- it('selects aliases only from captured configuration without reading display data', () => {
- const captured = event({ logo_path: '/public/PRIVATE_LOGO.svg' });
+ it('does not read directory display data or prepared asset registries', async () => {
+ const captured = event();
captured.locals.snapshot = {
...captured.locals.snapshot,
get display(): never {
throw new Error('Root layout must not read display data');
+ },
+ get assets(): never {
+ throw new Error('Root layout must not read image assets');
}
};
- expect(load(captured)).toEqual({ faviconPath: '/favicon.svg', logoPath: '/logo' });
+ expect(await load(captured)).toEqual(expectedData());
});
- it('preserves the immutable request capture when a later request gets a replacement', () => {
+ it.each([
+ {
+ siteUrl: 'https://directory.example.test',
+ url: 'http://internal.test:8080/signin?callbackUrl=%2Fsecret#private',
+ withAuth: true
+ },
+ {
+ siteUrl: 'http://localhost:3000',
+ url: 'https://internal.test/signin?callbackUrl=%2Fsecret#private',
+ withAuth: true
+ },
+ {
+ siteUrl: 'https://public.example.test:8443',
+ url: 'http://localhost:5173/private/path?link=secret#private',
+ withAuth: false
+ },
+ {
+ siteUrl: 'http://public.test:8080',
+ url: 'https://untrusted.test/private?tracking=ignored#fragment',
+ withAuth: false
+ }
+ ])(
+ 'uses configured site URL $siteUrl rather than request $url (auth: $withAuth)',
+ async ({ siteUrl, url, withAuth }) => {
+ const captured = event({}, { siteUrl, url, withAuth });
+ const metadata = (await load(captured)).document;
+ expect(metadata.url).toBe(`${siteUrl}/`);
+ expect(metadata.image.url).toBe(`${siteUrl}/images/og.png`);
+ }
+ );
+
+ it.each([
+ { env: {}, expected: 'http://localhost:3000' },
+ { env: { PORT: '5173' }, expected: 'http://localhost:5173' },
+ { env: { PORT: '8080' }, expected: 'http://localhost:8080' }
+ ])('uses the resolved default site URL $expected', async ({ env, expected }) => {
+ const captured = event(
+ {},
+ {
+ siteUrl: null,
+ withAuth: false,
+ url: 'https://untrusted.test:8443/private?tracking=ignored#fragment',
+ env
+ }
+ );
+ expect(captured.locals.snapshot.configuration.site.url).toBe(expected);
+ const metadata = (await load(captured)).document;
+ expect(metadata.url).toBe(`${expected}/`);
+ expect(metadata.image.url).toBe(`${expected}/images/og.png`);
+ });
+
+ it('uses a readable custom image at its own URL, preserving its actual MIME type', async () => {
+ vi.mocked(readMountedImage).mockResolvedValue({
+ bytes: new TextEncoder().encode(''),
+ contentType: 'image/svg+xml'
+ });
+ const source = '/public/images/café family.svg';
+ const data = await load(event({ og_image_path: source }));
+ expect(readMountedImage).toHaveBeenCalledExactlyOnceWith('/PRIVATE_PUBLIC_ROOT', source);
+ expect(data.document.image.url).toBe(
+ 'https://directory.example.test/public/images/caf%C3%A9%20family.svg'
+ );
+ expect(data.document.image.type).toBe('image/svg+xml');
+ expect(data.document.image).not.toHaveProperty('width');
+ expect(data.document.image).not.toHaveProperty('height');
+ expect(JSON.stringify(data)).not.toContain(' {
+ const captured = event({ og_image_path: '/public/share.png' });
+ expect(await load(captured)).toEqual(expectedData());
+ vi.mocked(readMountedImage).mockResolvedValue({
+ bytes: new Uint8Array([1]),
+ contentType: 'image/png'
+ });
+ expect((await load(captured)).document.image.url).toBe(
+ 'https://directory.example.test/public/share.png'
+ );
+ });
+
+ it('keeps the captured snapshot immutable across later config publications', async () => {
const captured = event({ favicon_path: '/public/PRIVATE_ICON.svg' });
const snapshot = captured.locals.snapshot;
const before = JSON.stringify(snapshot);
- const data = load(captured);
- const replacement = event();
- expect(load(replacement)).not.toEqual(data);
- expect(load(captured)).toEqual(data);
- expect(data).toEqual({ faviconPath: '/favicon', logoPath: '/favicon.svg' });
+ const data = await load(captured);
+ expect((await load(event({ title: 'Updated title' }))).document.title).toBe('Updated title');
+ expect(await load(captured)).toEqual(data);
expect(captured.locals.snapshot).toBe(snapshot);
expect(Object.isFrozen(snapshot)).toBe(true);
expect(JSON.stringify(snapshot)).toBe(before);
diff --git a/apps/web/static/favicon.png b/apps/web/static/favicon.png
new file mode 100644
index 0000000..9a1454e
Binary files /dev/null and b/apps/web/static/favicon.png differ
diff --git a/apps/web/static/favicon.svg b/apps/web/static/favicon.svg
deleted file mode 100644
index 4c322cc..0000000
--- a/apps/web/static/favicon.svg
+++ /dev/null
@@ -1 +0,0 @@
-
diff --git a/apps/web/vite.config.ts b/apps/web/vite.config.ts
index 8a619b3..137fcf3 100644
--- a/apps/web/vite.config.ts
+++ b/apps/web/vite.config.ts
@@ -3,17 +3,30 @@ import { defineConfig, loadEnv } from 'vite';
import { prepareRuntimeEnvironment } from './src/lib/server/runtime-environment.js';
import Icons from 'unplugin-icons/vite';
-export default defineConfig(async ({ command, mode, isPreview }) => {
- if (command === 'serve' && !isPreview) {
+export default defineConfig(({ command, mode, isPreview }) => {
+ const development = command === 'serve' && !isPreview;
+ if (development) {
Object.assign(process.env, loadEnv(mode, process.cwd(), ''));
- await prepareRuntimeEnvironment();
- // Empty overrides stop Vite from restoring legacy URL values from dotenv files.
- process.env.ORIGIN ??= '';
- process.env.AUTH_URL ??= '';
}
+ const port = Number(process.env.PORT ?? 5173);
return {
+ server: { port, strictPort: true },
optimizeDeps: { include: ['fuse.js'] },
plugins: [
+ {
+ name: 'directory-dev-environment',
+ enforce: 'pre',
+ config: {
+ order: 'pre',
+ async handler(config) {
+ if (!development) return;
+ // CLI overrides are merged before config hooks. Kit snapshots env in its own
+ // config hook, so configResolved would leave $env/dynamic/private stale.
+ process.env.PORT = String(config.server?.port ?? 5173);
+ await prepareRuntimeEnvironment();
+ }
+ }
+ },
sveltekit(),
Icons({ compiler: 'svelte' }),
// Kit's SSR loader does not run import.meta.hot.dispose.
diff --git a/docs/compose.yaml b/docs/compose.yaml
index 23137a2..755ab34 100644
--- a/docs/compose.yaml
+++ b/docs/compose.yaml
@@ -7,10 +7,13 @@ services:
env_file:
- path: .env
required: false
+ environment:
+ PORT: ${PORT:-3000}
ports:
# Localhost only. Use '3000:3000' for LAN access; restrict it with your firewall.
# Change the left port to use a different host port, e.g. '127.0.0.1:8080:3000'.
- - '127.0.0.1:3000:3000'
+ # Set site.url explicitly when the external address differs.
+ - '127.0.0.1:${PORT:-3000}:${PORT:-3000}'
volumes:
- ./config:/app/config:ro
- ./public:/app/public:ro
@@ -27,7 +30,7 @@ services:
- CMD
- node
- --eval
- - fetch('http://localhost:3000/healthz').then(r=>process.exit(r.ok?0:1)).catch(()=>process.exit(1))
+ - fetch('http://localhost:'+(process.env.PORT || '3000')+'/healthz').then(r=>process.exit(r.ok?0:1)).catch(()=>process.exit(1))
interval: 30s
timeout: 3s
start_period: 5s
@@ -39,9 +42,12 @@ services:
platform: linux/amd64
profiles:
- tools
+ # Optional values for ${VAR} references in directory.yaml.
env_file:
- path: .env
required: false
+ environment:
+ PORT: ${PORT:-3000}
volumes:
- ./config:/app/config:ro
read_only: true
diff --git a/docs/config.md b/docs/config.md
index 2c5cbde..344d833 100644
--- a/docs/config.md
+++ b/docs/config.md
@@ -20,14 +20,16 @@ Defaults apply when you leave a field out. Unknown fields and `null` are errors.
### site
-| Field | Value | Default |
-| ----------------------- | ------------------------------------------------------------------- | -------------- |
-| `title` | Nonblank text, e.g. `Home`. | `Directory` |
-| `description` | Text below the title. | Empty |
-| `footer` | Text at the bottom of the page. | Empty |
-| `logo_path` | [Image path](#images), e.g. `/public/house.svg`, or `/favicon.svg`. | `/favicon.svg` |
-| `favicon_path` | Browser tab icon. Same path options as `logo_path`. | `/favicon.svg` |
-| `open_links_in_new_tab` | `true` or `false`. Applies to every destination. | `true` |
+| Field | Value | Default |
+| ----------------------- | ------------------------------------------------------------------------------------------------------- | ------------------------------------------------------ |
+| `url` | Public HTTP(S) origin; no credentials, path, query, fragment or trailing slash. Restart after changing. | `http://localhost:PORT` (dev `5173`, otherwise `3000`) |
+| `title` | Nonblank text, e.g. `Home`. | `Directory` |
+| `description` | Text below the title; public in Open Graph previews. | Empty |
+| `footer` | Text at the bottom of the page. | Empty |
+| `logo_path` | [Image path](#images), e.g. `/public/house.svg`, or `/favicon.png`. | `/favicon.png` |
+| `favicon_path` | Browser tab icon. Same path options as `logo_path`. | `/favicon.png` |
+| `og_image_path` | Public Open Graph [image path](#images), e.g. `/public/share.png`. | Auto-generated |
+| `open_links_in_new_tab` | `true` or `false`. Applies to every destination. | `true` |
### appearance
@@ -73,18 +75,18 @@ Omit this section to share your directory with the world.
Use `credentials` for a basic username and password or `oidc` to turn it up to
11 and wire into your authentication fiefdom. Choose one.
-| Field | Value | Default |
-| ---------------------- | -------------------------------------------------------------------------------------------------------------------------- | ----------------------------- |
-| `origin` | Your directory's public origin, e.g. `https://home.example.com`. No credentials, path, query, fragment, or trailing slash. | Required when auth is enabled |
-| `secret` | Optional random string of at least 32 characters. Keeps sessions across restarts. | Generated at each startup |
-| `credentials.username` | Shared username, e.g. `family`. | Required for credentials |
-| `credentials.password` | Password, or `'${DIRECTORY_PASSWORD}'`. | Required for credentials |
-| `oidc.issuer` | Your provider’s full HTTP(S) issuer URL. | Required for OIDC |
-| `oidc.client_id` | Client ID registered with your provider. | Required for OIDC |
-| `oidc.client_secret` | Secret, or `'${DIRECTORY_OIDC_CLIENT_SECRET}'`. | Required for OIDC |
+| Field | Value | Default |
+| ---------------------- | --------------------------------------------------------------------------------- | ------------------------- |
+| `secret` | Optional random string of at least 32 characters. Keeps sessions across restarts. | Generated at each startup |
+| `credentials.username` | Shared username, e.g. `family`. | Required for credentials |
+| `credentials.password` | Password, or `'${DIRECTORY_PASSWORD}'`. | Required for credentials |
+| `oidc.issuer` | Your provider’s full HTTP(S) issuer URL. | Required for OIDC |
+| `oidc.client_id` | Client ID registered with your provider. | Required for OIDC |
+| `oidc.client_secret` | Secret, or `'${DIRECTORY_OIDC_CLIENT_SECRET}'`. | Required for OIDC |
-Use HTTPS, except for local testing at `http://localhost:3000` (or your dev port).
-OIDC's callback is your `origin` followed by `/auth/callback/oidc`.
+With auth enabled, `site.url` must use HTTPS, except for local testing at
+`http://localhost:3000` (or your dev port).
+OIDC's callback is your `site.url` followed by `/auth/callback/oidc`.
By default, restarting Directory signs everyone out. Set `secret` if you'd rather
keep sessions; generate it once with `openssl rand -base64 32`. Changing it signs
diff --git a/docs/directory.example.yaml b/docs/directory.example.yaml
index 506a8bf..0c0368e 100644
--- a/docs/directory.example.yaml
+++ b/docs/directory.example.yaml
@@ -2,18 +2,21 @@
# Sign-in is disabled. Uncomment one auth example below to enable it.
version: 1
site:
+ # Set your public origin when deploying beyond localhost (no trailing slash).
+ # url: https://directory.example.com
title: Home Server
description: Useful things running at home.
footer: Something not working? Ask your household maintainer.
+ # Optional public Open Graph image; generated when omitted.
+ # og_image_path: /public/share.png
appearance:
primary_light_color: '#0f766e'
primary_dark_color: '#5eead4'
-# Shared sign-in. Use your directory's HTTPS address, with no trailing slash.
+# Shared sign-in. Set site.url above to your directory's HTTPS origin.
# HTTP localhost is allowed for local testing. Restart after changing auth.
# auth:
-# origin: https://directory.example.com
# credentials:
# username: admin
# password: replace-with-your-own-password
@@ -21,7 +24,6 @@ appearance:
# Or SSO. Register this callback with your provider:
# https://directory.example.com/auth/callback/oidc
# auth:
-# origin: https://directory.example.com
# oidc:
# issuer: https://identity.example.com
# client_id: directory
diff --git a/packages/config/src/auth.test.ts b/packages/config/src/auth.test.ts
index af6d2a9..6d95689 100644
--- a/packages/config/src/auth.test.ts
+++ b/packages/config/src/auth.test.ts
@@ -2,7 +2,7 @@ import { inspect } from 'node:util';
import { describe, expect, expectTypeOf, it } from 'vitest';
import { ConfigError } from './errors.js';
import { validateConfig } from './load.js';
-import type { DirectoryAuth } from './types.js';
+import type { DirectoryAuth, DirectorySite } from './types.js';
const origin = 'https://directory.example.com';
const secret = 'test-only-secret-0123456789abcdef';
@@ -25,9 +25,16 @@ const acceptedOrigins = [
'http://localhost',
'http://localhost:3000',
'http://localhost:443',
- 'http://localhost:0',
'http://localhost:65535'
];
+const insecureAuthOrigins = [
+ 'http://directory.example.com',
+ 'http://127.0.0.1:3000',
+ 'http://[::1]:3000',
+ 'http://localhost.example.com',
+ 'http://sub.localhost',
+ 'http://localhost.'
+];
const rejectedOrigins = [
'',
' ',
@@ -38,12 +45,6 @@ const rejectedOrigins = [
'javascript:alert(1)',
'https://',
'https://[broken',
- 'http://directory.example.com',
- 'http://127.0.0.1:3000',
- 'http://[::1]:3000',
- 'http://localhost.example.com',
- 'http://sub.localhost',
- 'http://localhost.',
'https://user:password@directory.example.com',
'https://@directory.example.com',
'https://directory.example.com/',
@@ -66,6 +67,8 @@ const rejectedOrigins = [
'https://directory.example.com:443',
'http://localhost:80',
'http://localhost:03000',
+ 'http://localhost:0',
+ 'https://directory.example.com:0',
'http://localhost:',
'http://localhost:65536',
'https://directory.example.com:008443',
@@ -81,17 +84,72 @@ const rejectedOrigins = [
];
// These fields share validators across strategies; exercise URL attack classes once.
-describe('canonical auth origins', () => {
+describe('canonical auth site URLs', () => {
it.each(acceptedOrigins)('accepts %j', (origin) => {
- expect(validateConfig({ links: {}, auth: { origin, credentials } }).auth?.origin).toBe(origin);
+ expect(
+ validateConfig({ links: {}, site: { url: origin }, auth: { credentials } }).site.url
+ ).toBe(origin);
});
- it.each([...rejectedOrigins, null, false, 3000, [], {}])(
+ it.each([...insecureAuthOrigins, ...rejectedOrigins, null, false, 3000, [], {}])(
'rejects rather than normalizing %j',
(origin) => {
- expect(() => validateConfig({ links: {}, auth: { origin, credentials } })).toThrow(
- ConfigError
- );
+ expect(() =>
+ validateConfig({ links: {}, site: { url: origin }, auth: { credentials } })
+ ).toThrow(ConfigError);
+ }
+ );
+});
+
+describe('canonical open site URLs', () => {
+ it.each([
+ ...acceptedOrigins,
+ ...insecureAuthOrigins,
+ 'http://example.com:8080',
+ 'http://[2001:db8::1]'
+ ])('accepts canonical HTTP(S) without authentication: %j', (url) => {
+ expect(validateConfig({ links: {}, site: { url } }, { env: {} }).site.url).toBe(url);
+ });
+
+ it.each([
+ ...rejectedOrigins,
+ 'http://example.com:80',
+ 'http://example.com/',
+ 'http://EXAMPLE.com',
+ null,
+ false,
+ 3000,
+ [],
+ {}
+ ])('rejects rather than normalizing %j', (url) => {
+ expect(() => validateConfig({ links: {}, site: { url } }, { env: {} })).toThrow(ConfigError);
+ });
+
+ it.each(strategies)('rejects old auth.origin for $name, even with site.url', ({ strategy }) => {
+ for (const site of [undefined, { url: origin }]) {
+ expect(() =>
+ validateConfig(
+ { links: {}, ...(site ? { site } : {}), auth: { origin, ...strategy } },
+ { env: {} }
+ )
+ ).toThrow(ConfigError);
+ }
+ });
+
+ it.each(strategies)(
+ 'reports HTTPS security violations at /site/url for $name',
+ ({ strategy }) => {
+ for (const url of insecureAuthOrigins) {
+ try {
+ validateConfig({ links: {}, site: { url }, auth: strategy }, { env: {} });
+ expect.fail('Expected HTTPS requirement');
+ } catch (error) {
+ expect(error).toBeInstanceOf(ConfigError);
+ expect((error as ConfigError).issues).toMatchObject([
+ { code: 'invalid_value', path: '/site/url' }
+ ]);
+ }
+ }
}
);
});
@@ -101,7 +159,8 @@ describe('optional auth secrets', () => {
'preserves a supplied secret verbatim',
(secret) => {
expect(
- validateConfig({ links: {}, auth: { origin, secret, credentials } }).auth?.secret
+ validateConfig({ links: {}, site: { url: origin }, auth: { secret, credentials } }).auth
+ ?.secret
).toBe(secret);
}
);
@@ -109,16 +168,17 @@ describe('optional auth secrets', () => {
it.each([null, false, 32, [], {}, '', 'x'.repeat(31), ' '.repeat(32)])(
'rejects invalid explicit secret %j',
(secret) => {
- expect(() => validateConfig({ links: {}, auth: { origin, secret, credentials } })).toThrow(
- ConfigError
- );
+ expect(() =>
+ validateConfig({ links: {}, site: { url: origin }, auth: { secret, credentials } })
+ ).toThrow(ConfigError);
}
);
});
describe('auth strategy boundary', () => {
- it('retains required origin and optional secret types', () => {
- expectTypeOf().toEqualTypeOf();
+ it('retains required site URL and originless auth with optional secret types', () => {
+ expectTypeOf().toEqualTypeOf();
+ expectTypeOf().not.toHaveProperty('origin');
expectTypeOf().toEqualTypeOf();
});
@@ -129,17 +189,20 @@ describe('auth strategy boundary', () => {
});
it.each(strategies)(
- 'requires an explicit origin for $name and never generates a secret',
+ 'defaults site URL for $name and never generates a secret',
({ strategy }) => {
const env = { ORIGIN: origin, AUTH_SECRET: secret };
- expect(() => validateConfig({ links: {}, auth: strategy }, { env })).toThrow(ConfigError);
- const raw = { links: {}, auth: { origin, ...strategy } };
+ expect(validateConfig({ links: {}, auth: strategy }, { env }).site.url).toBe(
+ 'http://localhost:3000'
+ );
+ const raw = { links: {}, site: { url: origin }, auth: { ...strategy } };
const before = structuredClone(raw);
expect(validateConfig(raw, { env }).auth).toEqual(raw.auth);
expect(validateConfig(raw, { env }).auth).not.toHaveProperty('secret');
expect(raw).toEqual(before);
- expect(validateConfig({ links: {}, auth: { origin, secret, ...strategy } }).auth).toEqual({
- origin,
+ expect(
+ validateConfig({ links: {}, site: { url: origin }, auth: { secret, ...strategy } }).auth
+ ).toEqual({
secret,
...strategy
});
@@ -148,10 +211,10 @@ describe('auth strategy boundary', () => {
it('applies the shared origin and secret constraints to OIDC too', () => {
expect(() =>
- validateConfig({ links: {}, auth: { origin: 'http://directory.example.com', oidc } })
+ validateConfig({ links: {}, site: { url: 'http://directory.example.com' }, auth: { oidc } })
).toThrow(ConfigError);
expect(() =>
- validateConfig({ links: {}, auth: { origin, secret: 'x'.repeat(31), oidc } })
+ validateConfig({ links: {}, site: { url: origin }, auth: { secret: 'x'.repeat(31), oidc } })
).toThrow(ConfigError);
});
});
@@ -160,23 +223,26 @@ describe('auth interpolation and safe errors', () => {
it('expands origin and secret before validation without changing authored input', () => {
const raw = {
links: {},
- auth: { origin: '${PUBLIC_ORIGIN:-http://localhost:3000}', secret: '${SECRET}', credentials }
+ site: { url: '${PUBLIC_ORIGIN:-http://localhost:3000}' },
+ auth: { secret: '${SECRET}', credentials }
};
const before = structuredClone(raw);
+ expect(validateConfig(raw, { env: { PUBLIC_ORIGIN: origin, SECRET: secret } }).site.url).toBe(
+ origin
+ );
+ expect(validateConfig(raw, { env: { SECRET: secret } }).site.url).toBe('http://localhost:3000');
expect(validateConfig(raw, { env: { PUBLIC_ORIGIN: origin, SECRET: secret } }).auth).toEqual({
- origin,
secret,
credentials
});
expect(validateConfig(raw, { env: { SECRET: secret } }).auth).toEqual({
- origin: 'http://localhost:3000',
secret,
credentials
});
expect(raw).toEqual(before);
});
- it.each(['origin', 'secret'] as const)(
+ it.each(['url', 'secret'] as const)(
'redacts invalid literal, expanded and missing %s',
(field) => {
const sentinel = 'SENTINEL-NEVER-LOG-THIS';
@@ -187,7 +253,11 @@ describe('auth interpolation and safe errors', () => {
]) {
try {
validateConfig(
- { links: {}, auth: { origin, secret, credentials, [field]: value } },
+ {
+ links: {},
+ site: { url: field === 'url' ? value : origin },
+ auth: { secret: field === 'secret' ? value : secret, credentials }
+ },
{ env }
);
expect.fail('Expected invalid auth');
@@ -206,7 +276,7 @@ describe('auth interpolation and safe errors', () => {
expect(error).not.toHaveProperty('cause');
if (value.startsWith('${') && !env.PRIVATE_VALUE) {
expect((error as ConfigError).issues).toMatchObject([
- { code: 'missing_environment', path: `/auth/${field}` }
+ { code: 'missing_environment', path: field === 'url' ? '/site/url' : '/auth/secret' }
]);
}
}
diff --git a/packages/config/src/config.schema.json b/packages/config/src/config.schema.json
index 6b0de59..38391a1 100644
--- a/packages/config/src/config.schema.json
+++ b/packages/config/src/config.schema.json
@@ -33,14 +33,14 @@
}
]
},
- "AuthOrigin": {
- "description": "The canonical public origin of Directory. HTTPS is required except for http://localhost[:port]. No credentials, path, trailing slash, query, fragment, or noncanonical URL spelling.",
+ "SiteUrl": {
+ "description": "The canonical public HTTP(S) origin of Directory. No credentials, path, trailing slash, query, fragment, or noncanonical URL spelling. Authentication requires HTTPS except for http://localhost[:port]. Omitted values use localhost with PORT, or 5173 in development and 3000 otherwise.",
"type": "string",
"anyOf": [
{
"type": "string",
"format": "uri",
- "pattern": "^(?:https://(?:[^\\s/\\\\?#@:\\[\\]A-Z%]+|\\[[0-9a-f:.]+\\])(?::(?!443(?![\\s\\S]))[0-9]+)?|http://localhost(?::(?!80(?![\\s\\S]))[0-9]+)?)(?![\\s\\S])"
+ "pattern": "^(?:https://(?:[^\\s/\\\\?#@:\\[\\]A-Z%]+|\\[[0-9a-f:.]+\\])(?::(?!443(?![\\s\\S]))[1-9][0-9]*)?|http://(?:[^\\s/\\\\?#@:\\[\\]A-Z%]+|\\[[0-9a-f:.]+\\])(?::(?!80(?![\\s\\S]))[1-9][0-9]*)?)(?![\\s\\S])"
},
{
"type": "string",
@@ -74,13 +74,13 @@
]
},
"SiteImagePath": {
- "description": "A mounted image path or the bundled /favicon.svg mark.",
+ "description": "A mounted image path or the bundled /favicon.png mark.",
"anyOf": [
{ "$ref": "#/$defs/LocalImagePath" },
{
"type": "string",
"anyOf": [
- { "type": "string", "const": "/favicon.svg" },
+ { "type": "string", "const": "/favicon.png" },
{
"type": "string",
"pattern": "(?:^|[^$])(?:\\$\\$)*\\$\\{[A-Z_][A-Z0-9_]*(?::-[^}]*)?\\}"
@@ -166,6 +166,7 @@
"additionalProperties": false,
"type": "object",
"properties": {
+ "url": { "default": "http://localhost:3000", "$ref": "#/$defs/SiteUrl" },
"title": {
"default": "Directory",
"type": "string",
@@ -178,8 +179,12 @@
]
},
"description": { "default": "", "type": "string" },
- "logo_path": { "default": "/favicon.svg", "$ref": "#/$defs/SiteImagePath" },
- "favicon_path": { "default": "/favicon.svg", "$ref": "#/$defs/SiteImagePath" },
+ "logo_path": { "default": "/favicon.png", "$ref": "#/$defs/SiteImagePath" },
+ "favicon_path": { "default": "/favicon.png", "$ref": "#/$defs/SiteImagePath" },
+ "og_image_path": {
+ "description": "Optional public Open Graph image, including when authentication is enabled. Use a /public/ image path, not an external URL; PNG or JPEG at 1200×630 is recommended. Omit or supply a missing image to generate a 1200×630 PNG from the site title, favicon and appearance only.",
+ "$ref": "#/$defs/LocalImagePath"
+ },
"footer": { "default": "", "type": "string" },
"open_links_in_new_tab": {
"default": true,
@@ -258,9 +263,8 @@
"additionalProperties": false,
"title": "OIDC",
"type": "object",
- "required": ["origin", "oidc"],
+ "required": ["oidc"],
"properties": {
- "origin": { "$ref": "#/$defs/AuthOrigin" },
"secret": { "$ref": "#/$defs/AuthSecret" },
"oidc": { "$ref": "#/$defs/OidcAuth" },
"credentials": { "not": {} }
@@ -270,9 +274,8 @@
"additionalProperties": false,
"title": "Shared username and password",
"type": "object",
- "required": ["origin", "credentials"],
+ "required": ["credentials"],
"properties": {
- "origin": { "$ref": "#/$defs/AuthOrigin" },
"secret": { "$ref": "#/$defs/AuthSecret" },
"credentials": { "$ref": "#/$defs/CredentialsAuth" },
"oidc": { "not": {} }
diff --git a/packages/config/src/editor-schema.test.ts b/packages/config/src/editor-schema.test.ts
index b03bb92..77d48b5 100644
--- a/packages/config/src/editor-schema.test.ts
+++ b/packages/config/src/editor-schema.test.ts
@@ -7,7 +7,7 @@ import {
configurationReferences,
HexColorSchema,
HttpUrlSchema,
- AuthOriginSchema,
+ SiteUrlSchema,
LocalImagePathSchema,
DirectoryConfigurationSchema
} from './schema.js';
@@ -62,23 +62,24 @@ describe('default-aware editor schema', () => {
'client_secret'
]);
const authBranches = definition(editor, 'Auth').anyOf as ObjectSchema[];
- expect(authBranches.map((branch) => branch.required)).toEqual([
- ['origin', 'oidc'],
- ['origin', 'credentials']
- ]);
+ expect(authBranches.map((branch) => branch.required)).toEqual([['oidc'], ['credentials']]);
expect(authBranches.every((branch) => branch.additionalProperties === false)).toBe(true);
expect(property(editor, 'links').additionalProperties).toBe(false);
expect(object((definition(editor, 'HttpUrl').anyOf as unknown[])[0]).format).toBe('uri');
});
- it('keeps auth origin required and secret optional, constrained and without defaults', () => {
+ it('defaults site.url and keeps auth secret optional, constrained and without defaults', () => {
const editor = createEditorSchema();
for (const branch of definition(editor, 'Auth').anyOf as ObjectSchema[]) {
- expect(property(branch, 'origin')).toEqual({ $ref: '#/$defs/AuthOrigin' });
+ expect(object(branch.properties)).not.toHaveProperty('origin');
expect(property(branch, 'secret')).toEqual({ $ref: '#/$defs/AuthSecret' });
expect(branch.required).not.toContain('secret');
}
- const origin = definition(editor, 'AuthOrigin');
+ const origin = definition(editor, 'SiteUrl');
+ expect(property(definition(editor, 'Site'), 'url')).toEqual({
+ $ref: '#/$defs/SiteUrl',
+ default: 'http://localhost:3000'
+ });
const secret = definition(editor, 'AuthSecret');
expect(secret).not.toHaveProperty('default');
expect((secret.anyOf as ObjectSchema[])[0]).toEqual({
@@ -95,7 +96,7 @@ describe('default-aware editor schema', () => {
for (const field of ['logo_path', 'favicon_path']) {
expect(property(definition(editor, 'Site'), field)).toEqual({
$ref: '#/$defs/SiteImagePath',
- default: '/favicon.svg'
+ default: '/favicon.png'
});
}
expect(property(definition(editor, 'Link'), 'logo_path')).toEqual({
@@ -106,11 +107,19 @@ describe('default-aware editor schema', () => {
expect(choices[0]).toEqual({ $ref: '#/$defs/LocalImagePath' });
expect((choices[1]!.anyOf as ObjectSchema[])[0]).toEqual({
type: 'string',
- const: '/favicon.svg'
+ const: '/favicon.png'
});
expect(interpolationPattern(choices[1]!).test('${SITE_IMAGE}')).toBe(true);
});
+ it('keeps the Open Graph image optional, local-only and without a default', () => {
+ const site = definition(createEditorSchema(), 'Site');
+ const image = property(site, 'og_image_path');
+ expect(image.$ref).toBe('#/$defs/LocalImagePath');
+ expect(image).not.toHaveProperty('default');
+ expect(site.required).toBeUndefined();
+ });
+
it('produces only resolvable local references, with no invented publication URL', () => {
const editor = createEditorSchema();
expect(editor.$id).toBeUndefined();
@@ -203,12 +212,7 @@ describe('default-aware editor schema', () => {
it('separates literal constraints from the environment-token branch', () => {
const editor = createEditorSchema();
- for (const canonical of [
- HttpUrlSchema,
- AuthOriginSchema,
- LocalImagePathSchema,
- HexColorSchema
- ]) {
+ for (const canonical of [HttpUrlSchema, SiteUrlSchema, LocalImagePathSchema, HexColorSchema]) {
const adapted = definition(editor, canonical.$id!);
const literal: ObjectSchema = { type: 'string', pattern: canonical.pattern };
if (canonical.format) literal.format = 'uri';
@@ -352,7 +356,7 @@ describe('default-aware editor schema', () => {
});
it('leaves canonical validation strict for placeholders and expanded values', () => {
- for (const schema of [HttpUrlSchema, AuthOriginSchema, LocalImagePathSchema, HexColorSchema]) {
+ for (const schema of [HttpUrlSchema, SiteUrlSchema, LocalImagePathSchema, HexColorSchema]) {
expect(Value.Check(schema, '${VALUE}')).toBe(false);
expect(Value.Check(schema, false)).toBe(false);
expect(Value.Check(schema, 1)).toBe(false);
diff --git a/packages/config/src/editor-schema.ts b/packages/config/src/editor-schema.ts
index 92e7a2a..cca164d 100644
--- a/packages/config/src/editor-schema.ts
+++ b/packages/config/src/editor-schema.ts
@@ -112,7 +112,7 @@ function adaptSchemaForEditor(
resolveReference(node.$ref, context);
node.$ref = context.referenceTargets.get(node.$ref) ?? node.$ref;
}
- if (node.format === 'directory-http-url' || node.format === 'directory-auth-origin') {
+ if (node.format === 'directory-http-url' || node.format === 'directory-site-url') {
node.format = 'uri';
}
removeDefaultedPropertiesFromRequired(node, context);
diff --git a/packages/config/src/errors.test.ts b/packages/config/src/errors.test.ts
index 76ceadc..92e2b31 100644
--- a/packages/config/src/errors.test.ts
+++ b/packages/config/src/errors.test.ts
@@ -23,9 +23,16 @@ describe('redacted configuration errors', () => {
{ code: 'invalid_value', path: '/properties' },
{ code: 'invalid_value', path: '/Site' },
{ code: 'invalid_value', path: '/Directory' },
- { code: 'invalid_value', path: '/site/order' }
+ { code: 'invalid_value', path: '/site/order' },
+ { code: 'invalid_value', path: '/auth/origin' }
+ ]);
+ expect(error.issues.map((issue) => issue.path)).toEqual([
+ '/*',
+ '/*',
+ '/*',
+ '/site/*',
+ '/auth/*'
]);
- expect(error.issues.map((issue) => issue.path)).toEqual(['/*', '/*', '/*', '/site/*']);
});
it('formats fixed messages with their redacted paths', () => {
diff --git a/packages/config/src/errors.ts b/packages/config/src/errors.ts
index d33fc64..93ef69c 100644
--- a/packages/config/src/errors.ts
+++ b/packages/config/src/errors.ts
@@ -16,7 +16,9 @@ export interface ConfigIssue {
readonly message: string;
}
-type IssueLocation = Pick;
+type IssueLocation = Pick & {
+ reason?: 'explicit_site_url_required';
+};
const schemaFieldNames = new Set(
[DirectoryConfigurationSchema, ...configurationReferences].flatMap(getSchemaFieldNames)
@@ -51,11 +53,11 @@ function getSchemaFieldNames(schema: TSchema): string[] {
function redactIssue(location: IssueLocation): ConfigIssue {
let code = location.code;
if (!Object.hasOwn(issueMessages, code)) code = 'invalid_value';
- return Object.freeze({
- code,
- path: redactIssuePath(location.path),
- message: issueMessages[code]
- });
+ let message: string = issueMessages[code];
+ if (code === 'invalid_value' && location.reason === 'explicit_site_url_required') {
+ message = 'Set site.url explicitly when using a random port, socket or socket activation.';
+ }
+ return Object.freeze({ code, path: redactIssuePath(location.path), message });
}
function redactIssuePath(path: string): string {
diff --git a/packages/config/src/load.test.ts b/packages/config/src/load.test.ts
index cafd268..b16cabb 100644
--- a/packages/config/src/load.test.ts
+++ b/packages/config/src/load.test.ts
@@ -3,7 +3,7 @@ import { tmpdir } from 'node:os';
import { join } from 'node:path';
import { fileURLToPath } from 'node:url';
import { inspect } from 'node:util';
-import { afterAll, beforeAll, describe, expect, it } from 'vitest';
+import { afterAll, beforeAll, describe, expect, it, vi } from 'vitest';
import { createEditorSchema } from './editor-schema.js';
import { ConfigError } from './errors.js';
import { configurationReferences, DirectoryConfigurationSchema } from './schema.js';
@@ -68,11 +68,12 @@ describe('default, interpolate, then validate', () => {
const config = validateConfig(raw, { env: {} });
expect(config.version).toBe(1);
expect(config.site).toEqual({
+ url: 'http://localhost:3000',
title: 'Directory',
description: '',
footer: '',
- logo_path: '/favicon.svg',
- favicon_path: '/favicon.svg',
+ logo_path: '/favicon.png',
+ favicon_path: '/favicon.png',
open_links_in_new_tab: true
});
expect(config.appearance).toEqual({
@@ -131,19 +132,20 @@ describe('default, interpolate, then validate', () => {
{ title: 'Home' },
{ logo_path: '/public/home.svg' },
{ favicon_path: '/public/site.png' },
- { logo_path: '/favicon.svg' },
- { favicon_path: '/favicon.svg' },
- { logo_path: '/favicon.svg', favicon_path: '/favicon.svg' }
+ { logo_path: '/favicon.png' },
+ { favicon_path: '/favicon.png' },
+ { logo_path: '/favicon.png', favicon_path: '/favicon.png' }
])('normalizes independent site image selections without mutating input: %j', (site) => {
const raw = { site, links: { photos: link } };
const before = structuredClone(raw);
const config = validateConfig(raw, { env: {} });
expect(config.site).toEqual({
+ url: 'http://localhost:3000',
title: 'Directory',
description: '',
footer: '',
- logo_path: '/favicon.svg',
- favicon_path: '/favicon.svg',
+ logo_path: '/favicon.png',
+ favicon_path: '/favicon.png',
open_links_in_new_tab: true,
...site
});
@@ -151,7 +153,7 @@ describe('default, interpolate, then validate', () => {
expect(config.links.photos).not.toHaveProperty('favicon_path');
config.site.logo_path = '/public/changed.svg';
expect(validateConfig(raw, { env: {} }).site.favicon_path).toBe(
- site.favicon_path ?? '/favicon.svg'
+ site.favicon_path ?? '/favicon.png'
);
expect(raw).toEqual(before);
});
@@ -199,11 +201,11 @@ describe('default, interpolate, then validate', () => {
it('interpolates site image selections before applying the strict image boundary', () => {
const raw = { site: { logo_path: '${LOGO}', favicon_path: '${ICON}' }, links: {} };
- const config = validateConfig(raw, { env: { LOGO: '/favicon.svg', ICON: '/public/icon.png' } });
- expect(config.site.logo_path).toBe('/favicon.svg');
+ const config = validateConfig(raw, { env: { LOGO: '/favicon.png', ICON: '/public/icon.png' } });
+ expect(config.site.logo_path).toBe('/favicon.png');
expect(config.site.favicon_path).toBe('/public/icon.png');
expect(() =>
- validateConfig(raw, { env: { LOGO: '/favicon.svg?x', ICON: '/public/icon.png' } })
+ validateConfig(raw, { env: { LOGO: '/favicon.png?x', ICON: '/public/icon.png' } })
).toThrow(ConfigError);
expect(() => validateConfig(raw, { env: {} })).toThrow(ConfigError);
});
@@ -275,25 +277,27 @@ describe('default, interpolate, then validate', () => {
it('loads either complete auth strategy and never fills missing credentials', () => {
const credentials = validateConfig(
- { links: {}, auth: { origin, credentials: { username: 'family', password: '${PASSWORD}' } } },
+ {
+ links: {},
+ site: { url: origin },
+ auth: { credentials: { username: 'family', password: '${PASSWORD}' } }
+ },
{ env: { PASSWORD: sentinel } }
);
expect(credentials.auth).toEqual({
- origin,
credentials: { username: 'family', password: sentinel }
});
const oidc = validateConfig(
{
links: {},
+ site: { url: origin },
auth: {
- origin,
oidc: { issuer: '${ISSUER}', client_id: 'directory', client_secret: '${SECRET}' }
}
},
{ env: { ISSUER: 'https://identity.example.com', SECRET: sentinel } }
);
expect(oidc.auth).toEqual({
- origin,
oidc: {
issuer: 'https://identity.example.com',
client_id: 'directory',
@@ -327,19 +331,20 @@ describe('default, interpolate, then validate', () => {
{ links: {}, site: { favicon_path: false } },
{ links: {}, auth: {} },
{ links: {}, auth: null },
- { links: {}, auth: { origin, credentials: {} } },
+ { links: {}, site: { url: origin }, auth: { credentials: {} } },
{
links: {},
- auth: { origin, oidc: { issuer: 'https://identity.example.com', client_id: 'directory' } }
+ site: { url: origin },
+ auth: { oidc: { issuer: 'https://identity.example.com', client_id: 'directory' } }
},
{
links: {},
- auth: { origin, credentials: { username: 'family', password: 'test' }, oidc: null }
+ site: { url: origin },
+ auth: { credentials: { username: 'family', password: 'test' }, oidc: null }
},
{
links: {},
auth: {
- origin,
credentials: { username: 'family', password: 'test' },
oidc: {
issuer: 'https://identity.example.com',
@@ -380,7 +385,11 @@ describe('default, interpolate, then validate', () => {
expect(invalid.issues[0]?.path).toBe('/links/*/url');
const badAuth = configurationError(() =>
validateConfig(
- { links: {}, auth: { origin, credentials: { username: sentinel, password: {} } } },
+ {
+ links: {},
+ site: { url: origin },
+ auth: { credentials: { username: sentinel, password: {} } }
+ },
{ env: {} }
)
);
@@ -394,6 +403,204 @@ describe('default, interpolate, then validate', () => {
});
});
+describe('runtime site URL defaults', () => {
+ it.each([
+ { env: {}, url: 'http://localhost:3000' },
+ { env: { NODE_ENV: 'production' }, url: 'http://localhost:3000' },
+ { env: { NODE_ENV: 'test' }, url: 'http://localhost:3000' },
+ { env: { NODE_ENV: 'development' }, url: 'http://localhost:5173' },
+ { env: { PORT: '8080' }, url: 'http://localhost:8080' },
+ { env: { PORT: '65535', NODE_ENV: 'development' }, url: 'http://localhost:65535' },
+ { env: { PORT: '1' }, url: 'http://localhost:1' },
+ { env: { PORT: '80' }, url: 'http://localhost' },
+ {
+ env: { HOST: 'public.example.com', LISTEN_FDS: '0', SOCKET_PATH: '' },
+ url: 'http://localhost:3000'
+ }
+ ])('resolves omissions using only the supplied environment: $env', ({ env, url }) => {
+ for (const site of [undefined, {}, { title: 'Home' }]) {
+ const raw = { links: {}, ...(site ? { site } : {}) };
+ const before = structuredClone(raw);
+ const environment = Object.freeze({ ...env });
+ expect(validateConfig(raw, { env: environment }).site.url).toBe(url);
+ expect(validateConfig(raw, { env: environment }).site.url).toBe(url);
+ expect(raw).toEqual(before);
+ expect(environment).toEqual(env);
+ }
+ });
+
+ it('uses process.env consistently, without leaking it into an injected environment', () => {
+ try {
+ vi.stubEnv('NODE_ENV', 'development');
+ vi.stubEnv('PORT', undefined);
+ vi.stubEnv('SOCKET_PATH', undefined);
+ vi.stubEnv('LISTEN_FDS', undefined);
+ expect(validateConfig({ links: {} }).site.url).toBe('http://localhost:5173');
+ expect(validateConfig({ links: {} }, { env: {} }).site.url).toBe('http://localhost:3000');
+ vi.stubEnv('PORT', '8080');
+ expect(validateConfig({ links: {} }).site.url).toBe('http://localhost:8080');
+ expect(validateConfig({ links: {} }, { env: process.env }).site.url).toBe(
+ 'http://localhost:8080'
+ );
+ expect(process.env.PORT).toBe('8080');
+ } finally {
+ vi.unstubAllEnvs();
+ }
+ });
+
+ it.each([
+ '',
+ ' ',
+ '-1',
+ '+3000',
+ '65536',
+ '1.5',
+ '1e3',
+ '0x10',
+ 'NaN',
+ 'Infinity',
+ '3000\n',
+ sentinel
+ ])('rejects invalid fallback PORT %j with a redacted site URL error', (PORT) => {
+ const error = configurationError(() => validateConfig({ links: {} }, { env: { PORT } }));
+ expect(error.issues).toMatchObject([{ code: 'invalid_value', path: '/site/url' }]);
+ expectRedacted(error);
+ });
+
+ it.each([
+ { PORT: '0' },
+ { PORT: '00' },
+ { SOCKET_PATH: '/private/socket' },
+ { LISTEN_FDS: '1' },
+ { LISTEN_FDS: '2', PORT: '3000' }
+ ])('requires an explicit URL for random ports or sockets: %j', (env) => {
+ const error = configurationError(() => validateConfig({ links: {} }, { env }));
+ expect(error.issues).toMatchObject([{ code: 'invalid_value', path: '/site/url' }]);
+ expect(error.message).toContain('Set site.url explicitly');
+ expect(error.message).not.toContain('/private/socket');
+ });
+
+ it.each([
+ { PORT: '0' },
+ { PORT: sentinel },
+ { SOCKET_PATH: '/private/socket' },
+ { LISTEN_FDS: '3', PORT: '0' },
+ { NODE_ENV: 'development', PORT: '8080' }
+ ])(
+ 'preserves explicit and interpolated URLs regardless of listener settings: %j',
+ async (env) => {
+ for (const url of [origin, '${PUBLIC_URL}']) {
+ const config = await loadYaml(`site:\n url: '${url}'\nlinks: {}\n`, {
+ ...env,
+ PUBLIC_URL: origin
+ });
+ expect(config.site.url).toBe(origin);
+ }
+ }
+ );
+
+ it.each([null, '', false, 8080, [], {}, 'not an origin'])(
+ 'does not treat an explicit invalid URL as omitted: %j',
+ (url) => {
+ const error = configurationError(() =>
+ validateConfig({ links: {}, site: { url } }, { env: { PORT: '0' } })
+ );
+ expect(error.issues.length).toBeGreaterThan(0);
+ expect(error.issues.every((issue) => issue.path === '/site/url')).toBe(true);
+ expect(error.message).not.toContain('Set site.url explicitly');
+ }
+ );
+
+ it('keeps defaults stable across repeated file loads and resolved configuration validation', async () => {
+ const env = Object.freeze({ NODE_ENV: 'development', PORT: '8080' });
+ const initial = await loadYaml('links: {}', env);
+ const reloaded = await loadYaml('links: {}', env);
+ expect(reloaded).toEqual(initial);
+ expect(validateConfig(initial, { env: { PORT: '0', SOCKET_PATH: '/private/socket' } })).toEqual(
+ initial
+ );
+ });
+});
+
+describe('optional Open Graph image', () => {
+ it.each([undefined, {}, { title: 'Home' }])(
+ 'leaves an omitted image absent after defaults: %j',
+ (site) => {
+ const config = validateConfig({ links: {}, ...(site ? { site } : {}) }, { env: {} });
+ expect(config.site).not.toHaveProperty('og_image_path');
+ }
+ );
+
+ it.each([
+ '/public/share.png',
+ '/public/cards/home.JPEG',
+ '/public/family photo.jpg',
+ '/public/图标/家.webp',
+ '/public/share.svg',
+ '/public/share.gif',
+ '/public/missing.png'
+ ])('preserves a local image without requiring the file to exist: %s', (og_image_path) => {
+ const raw = { site: { og_image_path }, links: {} };
+ const before = structuredClone(raw);
+ expect(validateConfig(raw, { env: {} }).site.og_image_path).toBe(og_image_path);
+ expect(raw).toEqual(before);
+ });
+
+ it.each(
+ [
+ null,
+ false,
+ 1,
+ [],
+ {},
+ '',
+ '/favicon.png',
+ 'https://example.com/share.png',
+ '//example.com/share.png',
+ 'data:image/png;base64,AAAA',
+ 'file:///public/share.png',
+ 'public/share.png',
+ '/share.png',
+ '/public/../share.png',
+ '/public/./share.png',
+ '/public//share.png',
+ '/public/%2e%2e/share.png',
+ '/public/a\\b.png',
+ '/public/share.png?size=large',
+ '/public/share.png#image',
+ '/public/share.html',
+ '/public/share.png\n',
+ '/public/share\u0000.png'
+ ].map((og_image_path) => ({ og_image_path }))
+ )('rejects invalid, remote and bundled image selections: $og_image_path', ({ og_image_path }) => {
+ const error = configurationError(() =>
+ validateConfig({ site: { og_image_path }, links: {} }, { env: {} })
+ );
+ expect(error.issues).toMatchObject([{ path: '/site/og_image_path' }]);
+ });
+
+ it('validates interpolated paths with the same local-only boundary', () => {
+ const raw = { site: { og_image_path: '${IMAGE}' }, links: {} };
+ expect(validateConfig(raw, { env: { IMAGE: '/public/share.png' } }).site.og_image_path).toBe(
+ '/public/share.png'
+ );
+ for (const env of [{}, { IMAGE: '/favicon.png' }, { IMAGE: 'https://example.com/share.png' }]) {
+ expect(() => validateConfig(raw, { env })).toThrow(ConfigError);
+ }
+ });
+
+ it('loads an optional image from YAML without changing other site defaults', async () => {
+ const config = await loadYaml('site:\n og_image_path: /public/share.png\nlinks: {}\n');
+ expect(config.site).toEqual({
+ ...validateConfig({ links: {} }, { env: {} }).site,
+ og_image_path: '/public/share.png'
+ });
+ await expect(loadYaml('site: {og_image_path: null}\nlinks: {}\n')).rejects.toBeInstanceOf(
+ ConfigError
+ );
+ });
+});
+
describe('YAML file loader', () => {
it.each([
{ site: '', expected: true },
@@ -419,11 +626,12 @@ describe('YAML file loader', () => {
expect(config.links).toEqual({});
expect(config).not.toHaveProperty('auth');
expect(config.site).toEqual({
+ url: 'http://localhost:3000',
title: 'Directory',
description: '',
footer: '',
- logo_path: '/favicon.svg',
- favicon_path: '/favicon.svg',
+ logo_path: '/favicon.png',
+ favicon_path: '/favicon.png',
open_links_in_new_tab: true
});
expect(config.appearance).toEqual({
@@ -444,8 +652,9 @@ describe('YAML file loader', () => {
const secret = 'test-only-secret-0123456789abcdef';
const config = await loadYaml(
`links: {}
+site:
+ url: '\${PUBLIC_ORIGIN}'
auth:
- origin: '\${PUBLIC_ORIGIN}'
secret: '\${SESSION_SECRET}'
credentials:
username: family
@@ -453,8 +662,8 @@ auth:
`,
{ PUBLIC_ORIGIN: origin, SESSION_SECRET: secret, PASSWORD: sentinel }
);
+ expect(config.site.url).toBe(origin);
expect(config.auth).toEqual({
- origin,
secret,
credentials: { username: 'family', password: sentinel }
});
diff --git a/packages/config/src/load.ts b/packages/config/src/load.ts
index 3ce7e20..fd225ba 100644
--- a/packages/config/src/load.ts
+++ b/packages/config/src/load.ts
@@ -6,7 +6,7 @@ import { assertSafeInput } from './input.js';
import { interpolate } from './interpolate.js';
import { resolveConfigPath } from './paths.js';
import { configurationReferences, DirectoryConfigurationSchema } from './schema.js';
-import type { ConfigLoadOptions, DirectoryConfiguration } from './types.js';
+import type { ConfigEnvironment, ConfigLoadOptions, DirectoryConfiguration } from './types.js';
export async function loadConfigFile(
path?: string,
@@ -29,14 +29,16 @@ export function validateConfig(
): DirectoryConfiguration {
assertSafeInput(raw);
try {
- const copy: unknown = structuredClone(raw);
+ const copy = structuredClone(raw) as Record;
+ const env = options.env ?? process.env;
+ defaultSiteUrl(copy, env);
const defaulted: unknown = Value.Default(
DirectoryConfigurationSchema,
[...configurationReferences],
copy
);
assertArrayShapesPreserved(raw, defaulted);
- const expanded = interpolate(defaulted, options.env ?? process.env);
+ const expanded = interpolate(defaulted, env);
return checkSchema(expanded);
} catch (error) {
if (error instanceof ConfigError) throw error;
@@ -44,6 +46,27 @@ export function validateConfig(
}
}
+// Resolve only omissions before TypeBox applies its static/editor defaults.
+function defaultSiteUrl(copy: Record, env: ConfigEnvironment): void {
+ if (!Object.hasOwn(copy, 'site')) copy.site = {};
+ const site = copy.site;
+ if (typeof site !== 'object' || site === null || Array.isArray(site)) return;
+ if (Object.hasOwn(site, 'url')) return;
+ const port = env.PORT ?? (env.NODE_ENV === 'development' ? '5173' : '3000');
+ const portNumber = Number(port);
+ const isDecimal = port.length > 0 && !/[^0-9]/.test(port);
+ if ((isDecimal && portNumber === 0) || env.SOCKET_PATH || Number(env.LISTEN_FDS) > 0) {
+ throw new ConfigError([
+ { code: 'invalid_value', path: '/site/url', reason: 'explicit_site_url_required' }
+ ]);
+ }
+ if (!isDecimal || !Number.isInteger(portNumber) || portNumber < 1 || portNumber > 65535) {
+ throw new ConfigError([{ code: 'invalid_value', path: '/site/url' }]);
+ }
+ (site as Record).url =
+ portNumber === 80 ? 'http://localhost' : `http://localhost:${portNumber}`;
+}
+
function assertArrayShapesPreserved(raw: unknown, defaulted: unknown, path = ''): void {
if (typeof raw !== 'object' || raw === null) return;
// TypeBox defaults can merge arrays into object defaults, or objects into array defaults.
@@ -98,5 +121,12 @@ function checkSchema(value: unknown): DirectoryConfiguration {
locations.push({ code: 'invalid_value', path: error.path });
}
if (locations.length > 0) throw new ConfigError(locations);
- return value as DirectoryConfiguration;
+ const config = value as DirectoryConfiguration;
+ if (config.auth) {
+ const url = new URL(config.site.url);
+ if (url.protocol !== 'https:' && url.hostname !== 'localhost') {
+ throw new ConfigError([{ code: 'invalid_value', path: '/site/url' }]);
+ }
+ }
+ return config;
}
diff --git a/packages/config/src/schema.test.ts b/packages/config/src/schema.test.ts
index 03ed5e4..fced67f 100644
--- a/packages/config/src/schema.test.ts
+++ b/packages/config/src/schema.test.ts
@@ -15,7 +15,6 @@ import {
import type { DirectoryConfiguration, DirectoryLink, DirectorySite } from './types.js';
const link = { title: 'Photos', url: 'https://photos.example.com' };
-const origin = 'https://directory.example.com';
const raw = { links: { photos: link } };
const linkDefaults = { tags: [], requires_auth: false, internal_only: false, admin_only: false };
@@ -37,11 +36,12 @@ describe('configuration defaults and inferred types', () => {
expect(value).toEqual({
version: 1,
site: {
+ url: 'http://localhost:3000',
title: 'Directory',
description: '',
footer: '',
- logo_path: '/favicon.svg',
- favicon_path: '/favicon.svg',
+ logo_path: '/favicon.png',
+ favicon_path: '/favicon.png',
open_links_in_new_tab: true
},
appearance: { primary_light_color: '#0f766e', primary_dark_color: '#5eead4' },
@@ -56,6 +56,7 @@ describe('configuration defaults and inferred types', () => {
const value = defaultFixture({ links: {} });
expect(accepts({ links: {} })).toBe(true);
expect(value).not.toHaveProperty('auth');
+ expect(value).not.toHaveProperty('site.og_image_path');
expect(defaultFixture(raw)).not.toHaveProperty('links.photos.group');
expect(accepts({})).toBe(false);
});
@@ -88,7 +89,10 @@ describe('configuration defaults and inferred types', () => {
expectTypeOf().toEqualTypeOf();
expectTypeOf().toEqualTypeOf();
expectTypeOf().toEqualTypeOf();
+ expectTypeOf().toEqualTypeOf();
+ expect(SiteSchema.required).toContain('url');
expectTypeOf().toEqualTypeOf();
+ expectTypeOf().toEqualTypeOf();
expectTypeOf().toEqualTypeOf();
expectTypeOf().toBeNullable();
expectTypeOf().toEqualTypeOf();
@@ -103,7 +107,6 @@ describe('configuration defaults and inferred types', () => {
const missingTitle: DirectoryLink = { url: link.url, ...linkDefaults };
// @ts-expect-error both auth strategies are forbidden statically too
const both: NonNullable = {
- origin,
credentials: { username: 'family', password: 'fixture' },
oidc: { issuer: 'https://id.example.com', client_id: 'directory', client_secret: 'fixture' }
};
@@ -168,7 +171,7 @@ describe('strict configuration boundary', () => {
},
{ unknown: {} }
].map((auth) => ({
- auth: auth && !Array.isArray(auth) && typeof auth === 'object' ? { origin, ...auth } : auth
+ auth
}))
)('rejects invalid or ambiguous auth: $auth', ({ auth }) => {
expect(accepts({ ...raw, auth })).toBe(false);
@@ -178,7 +181,7 @@ describe('strict configuration boundary', () => {
{ credentials: { username: 'family', password: 'fixture' } },
{ oidc: { issuer: 'https://id.example.com', client_id: 'directory', client_secret: 'fixture' } }
])('accepts exactly one complete auth strategy', (auth) => {
- expect(accepts({ ...raw, auth: { origin, ...auth } })).toBe(true);
+ expect(accepts({ ...raw, auth })).toBe(true);
});
it.each([
@@ -246,7 +249,7 @@ describe('strict configuration boundary', () => {
{ ...raw, appearance: { background_color: '#fff' } },
{
...raw,
- auth: { origin, credentials: { username: 'family', password: 'fixture', extra: true } }
+ auth: { credentials: { username: 'family', password: 'fixture', extra: true } }
}
])('rejects unknown structural fields and invalid explicit values', (value) => {
expect(accepts(value)).toBe(false);
@@ -349,15 +352,16 @@ describe('URL, image and color constraints', () => {
'https://example.com/logo.svg',
'//example.com/logo.svg',
'/favicon.svg',
- '/favicon.svg/',
- '/favicon.svg?x',
- '/favicon.svg#x',
- '/favicon%2esvg',
- '/Favicon.svg',
- '/favicon.svg\n',
+ '/favicon.png',
+ '/favicon.png/',
+ '/favicon.png?x',
+ '/favicon.png#x',
+ '/favicon%2epng',
+ '/Favicon.png',
+ '/favicon.png\n',
'data:image/svg+xml,test',
- 'file:///favicon.svg',
- 'favicon.svg',
+ 'file:///favicon.png',
+ 'favicon.png',
'/public/logo\u0000.svg',
'/public/logo\t.svg',
'/public/logo\u007f.svg',
@@ -374,7 +378,7 @@ describe('URL, image and color constraints', () => {
'/public/logo.svg\n'
])('rejects unsafe/non-image path %j', (path) => {
expect(Value.Check(LocalImagePathSchema, path)).toBe(false);
- if (path !== '/favicon.svg') {
+ if (path !== '/favicon.png') {
expect(Value.Check(SiteImagePathSchema, configurationReferences, path)).toBe(false);
for (const field of ['logo_path', 'favicon_path']) {
expect(accepts({ ...raw, site: { [field]: path } })).toBe(false);
@@ -383,9 +387,9 @@ describe('URL, image and color constraints', () => {
});
it('accepts the bundled mark only for site images, not bookmark logos', () => {
for (const field of ['logo_path', 'favicon_path']) {
- expect(accepts({ ...raw, site: { [field]: '/favicon.svg' } })).toBe(true);
+ expect(accepts({ ...raw, site: { [field]: '/favicon.png' } })).toBe(true);
}
- expect(accepts({ links: { photos: { ...link, logo_path: '/favicon.svg' } } })).toBe(false);
+ expect(accepts({ links: { photos: { ...link, logo_path: '/favicon.png' } } })).toBe(false);
});
it.each(['#fff', '#0f766e', '#ABCDEF'])('accepts hex color %s', (color) => {
expect(Value.Check(HexColorSchema, color)).toBe(true);
diff --git a/packages/config/src/schema.ts b/packages/config/src/schema.ts
index c895549..487c73a 100644
--- a/packages/config/src/schema.ts
+++ b/packages/config/src/schema.ts
@@ -22,11 +22,12 @@ FormatRegistry.Set('directory-http-url', (value) => {
}
});
-FormatRegistry.Set('directory-auth-origin', (value) => {
+FormatRegistry.Set('directory-site-url', (value) => {
try {
const url = new URL(value);
return (
- (url.protocol === 'https:' || (url.protocol === 'http:' && url.hostname === 'localhost')) &&
+ (url.protocol === 'https:' || url.protocol === 'http:') &&
+ url.port !== '0' &&
value === url.origin
);
} catch {
@@ -47,13 +48,13 @@ export const HttpUrlSchema = Type.String({
description: 'An absolute HTTP or HTTPS URL. Relative and executable URLs are not accepted.'
});
-export const AuthOriginSchema = Type.String({
- $id: 'AuthOrigin',
- format: 'directory-auth-origin',
+export const SiteUrlSchema = Type.String({
+ $id: 'SiteUrl',
+ format: 'directory-site-url',
// Editors cannot run the URL canonicalization check, but can enforce the origin shape.
- pattern: `^(?:https://(?:[^\\s/\\\\?#@:\\[\\]A-Z%]+|\\[[0-9a-f:.]+\\])(?::(?!443${end})[0-9]+)?|http://localhost(?::(?!80${end})[0-9]+)?)${end}`,
+ pattern: `^(?:https://(?:[^\\s/\\\\?#@:\\[\\]A-Z%]+|\\[[0-9a-f:.]+\\])(?::(?!443${end})[1-9][0-9]*)?|http://(?:[^\\s/\\\\?#@:\\[\\]A-Z%]+|\\[[0-9a-f:.]+\\])(?::(?!80${end})[1-9][0-9]*)?)${end}`,
description:
- 'The canonical public origin of Directory. HTTPS is required except for http://localhost[:port]. No credentials, path, trailing slash, query, fragment, or noncanonical URL spelling.'
+ 'The canonical public HTTP(S) origin of Directory. No credentials, path, trailing slash, query, fragment, or noncanonical URL spelling. Authentication requires HTTPS except for http://localhost[:port]. Omitted values use localhost with PORT, or 5173 in development and 3000 otherwise.'
});
export const AuthSecretSchema = Type.String({
@@ -72,8 +73,8 @@ export const LocalImagePathSchema = Type.String({
});
export const SiteImagePathSchema = Type.Union(
- [ref(LocalImagePathSchema), Type.Literal('/favicon.svg')],
- { $id: 'SiteImagePath', description: 'A mounted image path or the bundled /favicon.svg mark.' }
+ [ref(LocalImagePathSchema), Type.Literal('/favicon.png')],
+ { $id: 'SiteImagePath', description: 'A mounted image path or the bundled /favicon.png mark.' }
);
export const HexColorSchema = Type.String({
@@ -116,10 +117,17 @@ export const LinkSchema = Type.Object(
export const SiteSchema = Type.Object(
{
+ url: ref(SiteUrlSchema, { default: 'http://localhost:3000' }),
title: Type.String({ ...nonEmptyText, default: 'Directory' }),
description: Type.String({ default: '' }),
- logo_path: ref(SiteImagePathSchema, { default: '/favicon.svg' }),
- favicon_path: ref(SiteImagePathSchema, { default: '/favicon.svg' }),
+ logo_path: ref(SiteImagePathSchema, { default: '/favicon.png' }),
+ favicon_path: ref(SiteImagePathSchema, { default: '/favicon.png' }),
+ og_image_path: Type.Optional(
+ ref(LocalImagePathSchema, {
+ description:
+ 'Optional public Open Graph image, including when authentication is enabled. Use a /public/ image path, not an external URL; PNG or JPEG at 1200×630 is recommended. Omit or supply a missing image to generate a 1200×630 PNG from the site title, favicon and appearance only.'
+ })
+ ),
footer: Type.String({ default: '' }),
open_links_in_new_tab: Type.Boolean({
default: true,
@@ -158,7 +166,6 @@ export const AuthSchema = Type.Union(
[
Type.Object(
{
- origin: ref(AuthOriginSchema),
secret: Type.Optional(ref(AuthSecretSchema)),
oidc: ref(OidcAuthSchema),
credentials: Type.Optional(Type.Never())
@@ -167,7 +174,6 @@ export const AuthSchema = Type.Union(
),
Type.Object(
{
- origin: ref(AuthOriginSchema),
secret: Type.Optional(ref(AuthSecretSchema)),
credentials: ref(CredentialsAuthSchema),
oidc: Type.Optional(Type.Never())
@@ -194,7 +200,7 @@ export const DirectoryConfigurationSchema = Type.Object(
export const configurationReferences: TSchema[] = [
HttpUrlSchema,
- AuthOriginSchema,
+ SiteUrlSchema,
AuthSecretSchema,
LocalImagePathSchema,
SiteImagePathSchema,
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 9fafc88..042abdb 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -153,6 +153,12 @@ importers:
'@directory/config':
specifier: workspace:*
version: link:../../packages/config
+ '@takumi-rs/core':
+ specifier: 2.18.2
+ version: 2.18.2(preact@10.24.3)
+ '@takumi-rs/helpers':
+ specifier: 2.18.2
+ version: 2.18.2(preact@10.24.3)
bits-ui:
specifier: 'catalog:'
version: 2.18.1(@internationalized/date@3.12.4)(@sveltejs/kit@2.70.1(@sveltejs/vite-plugin-svelte@7.1.2(svelte@5.56.0(@typescript-eslint/types@8.60.0))(vite@8.0.16(@types/node@24.12.4)(esbuild@0.28.2)(yaml@2.9.1)))(svelte@5.56.0(@typescript-eslint/types@8.60.0))(typescript@6.0.3)(vite@8.0.16(@types/node@24.12.4)(esbuild@0.28.2)(yaml@2.9.1)))(svelte@5.56.0(@typescript-eslint/types@8.60.0))
@@ -982,6 +988,79 @@ packages:
'@swc/helpers@0.5.23':
resolution: {integrity: sha512-5lSsMOTXURePglDfvuAQUqkGek9Hg2kksOYay2m0+XR++b2NWYL/4sWyuvVBIs8oKnJaxkdi9whaL/sqN13afw==}
+ '@takumi-rs/core-darwin-arm64@2.18.2':
+ resolution: {integrity: sha512-7JjXUdT1ywBGghWAR8nim7emczQRsHV4TkLspITL3a853AahtNIwLTMMb/uK0KVAPwQR0plFEqzVU23iAzRBWQ==}
+ engines: {node: '>=18'}
+ cpu: [arm64]
+ os: [darwin]
+
+ '@takumi-rs/core-darwin-x64@2.18.2':
+ resolution: {integrity: sha512-YwExtQ81c91GLVKDnECruM5bM41a8flnXtQ/KTMSVovX74xzUZCe98XJjcyvTDdksF+bGMG9aqsmwX833HiMQw==}
+ engines: {node: '>=18'}
+ cpu: [x64]
+ os: [darwin]
+
+ '@takumi-rs/core-linux-arm64-gnu@2.18.2':
+ resolution: {integrity: sha512-NQcTa0mfIGAuGSLiTyJSTWn85uSj9Y7+adp+2yIaV89SZ1/thYg7HwGHMwpHQyYCZ2mTFWOwlh264nqYO1RvLw==}
+ engines: {node: '>=18'}
+ cpu: [arm64]
+ os: [linux]
+ libc: [glibc]
+
+ '@takumi-rs/core-linux-arm64-musl@2.18.2':
+ resolution: {integrity: sha512-5oaEkOZfyVolD6KxQ77aFeSHI1W7W8Oai4W0vBGzXyyXVLeONfWZkBFWPpXO0ojnPsKa2JVGL5mKFqRiwKAEQg==}
+ engines: {node: '>=18'}
+ cpu: [arm64]
+ os: [linux]
+ libc: [musl]
+
+ '@takumi-rs/core-linux-x64-gnu@2.18.2':
+ resolution: {integrity: sha512-UG95eda/4ySoJqV1QGl7ykH7AMKySvSkpafSVuIHefzu6fiQbyCOE9GRx/BWx0wKIE3ozQXteIP3ydnHQPJBJw==}
+ engines: {node: '>=18'}
+ cpu: [x64]
+ os: [linux]
+ libc: [glibc]
+
+ '@takumi-rs/core-linux-x64-musl@2.18.2':
+ resolution: {integrity: sha512-eTufsMdBMk8tvER1hBfh2RkE2Qv6ov05r9UEIXFDwZLVlXoHr1DbEp/k8Ze1a1DdLpZJizVQ9BKFKBUk8+SWnQ==}
+ engines: {node: '>=18'}
+ cpu: [x64]
+ os: [linux]
+ libc: [musl]
+
+ '@takumi-rs/core-win32-arm64-msvc@2.18.2':
+ resolution: {integrity: sha512-6C6ONbCg65smpkYRik9o3shON/8B8OP3VFpYXvSVHiW59boI+9SQKmOysTQBrZpSlUG5ZPAyoJHCfcFR5nawWA==}
+ engines: {node: '>=18'}
+ cpu: [arm64]
+ os: [win32]
+
+ '@takumi-rs/core-win32-x64-msvc@2.18.2':
+ resolution: {integrity: sha512-ui0aYjmhx9vsNlNc2ktLwZsk308132HwaQyp6OR3mQ40/svfnASJDxMyTdmh9O1Vv0ynph9idoj4eEh/0YQAjw==}
+ engines: {node: '>=18'}
+ cpu: [x64]
+ os: [win32]
+
+ '@takumi-rs/core@2.18.2':
+ resolution: {integrity: sha512-9g+oXNTAKLp6ZliXiQ0BkMXVPrXgaX34wjY7jO9osxbgFtBi3QLhnrDMyKFpSvXuOcbjdSCi1LkJ0YzN95bMQw==}
+ engines: {node: '>=18'}
+ peerDependencies:
+ csstype: '*'
+ peerDependenciesMeta:
+ csstype:
+ optional: true
+
+ '@takumi-rs/helpers@2.18.2':
+ resolution: {integrity: sha512-HHVdYmGxLos+Jn67mYU64gc+nW372zP8pF6zCnLzn3JMbGtcX5jV7a0N5uZseXkGrfGR07tsdWQbTkpO4Ms+WA==}
+ engines: {node: '>=18'}
+ peerDependencies:
+ preact: ^10.0.0 || ^11.0.0
+ react: ^18.0.0 || ^19.0.0
+ peerDependenciesMeta:
+ preact:
+ optional: true
+ react:
+ optional: true
+
'@tybys/wasm-util@0.10.4':
resolution: {integrity: sha512-W3c4gRigFS0T/Ma4qIYF3GDAc5AQdHb1yL5znJT1Zv1YaD9Kitx656wBjvr19qbiosmZT8lWDM5BEMynUqX65A==}
@@ -2683,6 +2762,50 @@ snapshots:
dependencies:
tslib: 2.8.1
+ '@takumi-rs/core-darwin-arm64@2.18.2':
+ optional: true
+
+ '@takumi-rs/core-darwin-x64@2.18.2':
+ optional: true
+
+ '@takumi-rs/core-linux-arm64-gnu@2.18.2':
+ optional: true
+
+ '@takumi-rs/core-linux-arm64-musl@2.18.2':
+ optional: true
+
+ '@takumi-rs/core-linux-x64-gnu@2.18.2':
+ optional: true
+
+ '@takumi-rs/core-linux-x64-musl@2.18.2':
+ optional: true
+
+ '@takumi-rs/core-win32-arm64-msvc@2.18.2':
+ optional: true
+
+ '@takumi-rs/core-win32-x64-msvc@2.18.2':
+ optional: true
+
+ '@takumi-rs/core@2.18.2(preact@10.24.3)':
+ dependencies:
+ '@takumi-rs/helpers': 2.18.2(preact@10.24.3)
+ optionalDependencies:
+ '@takumi-rs/core-darwin-arm64': 2.18.2
+ '@takumi-rs/core-darwin-x64': 2.18.2
+ '@takumi-rs/core-linux-arm64-gnu': 2.18.2
+ '@takumi-rs/core-linux-arm64-musl': 2.18.2
+ '@takumi-rs/core-linux-x64-gnu': 2.18.2
+ '@takumi-rs/core-linux-x64-musl': 2.18.2
+ '@takumi-rs/core-win32-arm64-msvc': 2.18.2
+ '@takumi-rs/core-win32-x64-msvc': 2.18.2
+ transitivePeerDependencies:
+ - preact
+ - react
+
+ '@takumi-rs/helpers@2.18.2(preact@10.24.3)':
+ optionalDependencies:
+ preact: 10.24.3
+
'@tybys/wasm-util@0.10.4':
dependencies:
tslib: 2.8.1
diff --git a/pnpm-workspace.yaml b/pnpm-workspace.yaml
index efa50c5..ff1bb71 100644
--- a/pnpm-workspace.yaml
+++ b/pnpm-workspace.yaml
@@ -31,3 +31,15 @@ catalog:
unplugin-icons: 23.0.1
vite: 8.0.16
vitest: 4.1.7
+
+minimumReleaseAgeExclude:
+ - '@takumi-rs/core-darwin-arm64@2.18.2'
+ - '@takumi-rs/core-darwin-x64@2.18.2'
+ - '@takumi-rs/core-linux-arm64-gnu@2.18.2'
+ - '@takumi-rs/core-linux-arm64-musl@2.18.2'
+ - '@takumi-rs/core-linux-x64-gnu@2.18.2'
+ - '@takumi-rs/core-linux-x64-musl@2.18.2'
+ - '@takumi-rs/core-win32-arm64-msvc@2.18.2'
+ - '@takumi-rs/core-win32-x64-msvc@2.18.2'
+ - '@takumi-rs/core@2.18.2'
+ - '@takumi-rs/helpers@2.18.2'
+