@byline/core 6.7.2 → 6.8.0

package/dist/@types/site-config.d.ts

@@ -5,7 +5,7 @@
  *
  * Copyright (c) Infonomic Company Limited
  */
-import type { PasswordSignInProtection, SessionProvider } from '@byline/auth';
+import type { PasskeyRequestProtection, PasswordSignInProtection, SessionProvider } from '@byline/auth';
 import type { RecurringTaskDefinition } from '../scheduler/types.js';
 import type { SlugifierFn } from '../utils/slugify.js';
 import type { FilenameSlugifierFn } from '../utils/slugify-filename.js';
@@ -351,6 +351,10 @@ export interface ServerConfig<TAdminStore = unknown> extends BaseConfig {
      * ```
      */
     sessionProvider?: SessionProvider;
+    /** Explicit WebAuthn trust configuration; never inferred from request headers. */
+    passkeys?: PasskeyConfig;
+    /** Shared WebAuthn network admission and independent process capacity; required when enabled. */
+    passkeyRequests?: PasskeyRequestProtection;
     /** Required by the host password sign-in endpoint; shared limiter and trusted IP resolver. */
     passwordSignIn?: PasswordSignInProtection;
     /**
@@ -476,3 +480,13 @@ export interface ServerConfig<TAdminStore = unknown> extends BaseConfig {
 export type ResolvedServerConfig<TAdminStore = unknown> = Omit<ServerConfig<TAdminStore>, 'routes'> & {
     routes: RoutesConfig;
 };
+/** Server-owned WebAuthn trust configuration. No related-origin expansion is supported. */
+export interface PasskeyConfig {
+    /** Canonical lowercase DNS name, without scheme, port or path. */
+    rpId: string;
+    rpName: string;
+    /** Exact canonical origins, including a non-default port when needed. */
+    origins: readonly string[];
+    /** Explicit local-development exception, restricted to http://localhost origins. */
+    allowInsecureLocalhost?: boolean;
+}

package/dist/config/config.js

@@ -2,6 +2,7 @@ import { commitHookAttachment, prepareHookAttachment, } from './attach-hooks.js'
 import { resolveRoutes } from './routes.js';
 import { validateAdminConfigs, validateBlockAdminConfigs } from './validate-admin-configs.js';
 import { validateCollections } from './validate-collections.js';
+import { resolvePasskeyConfig } from './validate-passkey-config.js';
 // ---------------------------------------------------------------------------
 // Global config storage
 // ---------------------------------------------------------------------------
@@ -79,7 +80,13 @@ export function defineServerConfig(config) {
 /** Resolve and validate server config without replacing the registered singleton. */
 export function resolveServerConfig(config) {
     validateCollections(config.collections);
-    const resolved = { ...config, routes: resolveRoutes(config.routes) };
+    const passkeys = resolvePasskeyConfig(config.passkeys, config.sessionProvider);
+    if (passkeys &&
+        (typeof config.passkeyRequests?.resolveClientIp !== 'function' ||
+            typeof config.passkeyRequests.limiter?.acquire !== 'function' ||
+            typeof config.passkeyRequests.limiter?.consume !== 'function'))
+        throw new Error('Passkeys require passkeyRequests with trusted client IP resolution and admission');
+    const resolved = { ...config, passkeys, routes: resolveRoutes(config.routes) };
     preparedHookAttachments.set(resolved, prepareHookAttachment(resolved));
     return resolved;
 }

package/dist/config/validate-passkey-config.d.ts

@@ -0,0 +1,4 @@
+import type { SessionProvider } from '@byline/auth';
+import type { PasskeyConfig } from '../@types/site-config.js';
+/** Pure boot-time validation; deliberately contains no Node or cryptographic imports. */
+export declare function resolvePasskeyConfig(config: PasskeyConfig | undefined, provider: Pick<SessionProvider, 'capabilities' | 'passkeys'> | undefined): PasskeyConfig | undefined;

package/dist/config/validate-passkey-config.js

@@ -0,0 +1,89 @@
+const methods = [
+    'signInOptions',
+    'verifySignIn',
+    'passwordProof',
+    'proofOptions',
+    'verifyProof',
+    'enrollmentOptions',
+    'verifyEnrollment',
+    'listCredentials',
+    'renameCredential',
+    'removeCredential',
+];
+function invalid(reason) {
+    throw new Error(`Invalid passkey configuration: ${reason}`);
+}
+/** Pure boot-time validation; deliberately contains no Node or cryptographic imports. */
+export function resolvePasskeyConfig(config, provider) {
+    const supported = provider?.capabilities.passkeys;
+    if (supported !== undefined && typeof supported !== 'boolean') {
+        invalid('provider capability must be a boolean');
+    }
+    if (config === undefined) {
+        if (supported === true || provider?.passkeys !== undefined) {
+            invalid('an enabled provider requires explicit relying-party configuration');
+        }
+        return undefined;
+    }
+    if (!config || typeof config !== 'object' || Array.isArray(config))
+        invalid('expected an object');
+    if (supported !== true || !provider?.passkeys)
+        invalid('provider does not support passkeys');
+    for (const method of methods) {
+        if (typeof provider.passkeys[method] !== 'function')
+            invalid(`provider is missing ${method}`);
+    }
+    const allowed = new Set(['rpId', 'rpName', 'origins', 'allowInsecureLocalhost']);
+    if (Object.keys(config).some((key) => !allowed.has(key)))
+        invalid('unknown configuration option');
+    if (typeof config.rpId !== 'string' ||
+        config.rpId.length > 253 ||
+        !/^(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)*[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/.test(config.rpId) ||
+        (config.rpId !== 'localhost' && !config.rpId.includes('.')) ||
+        /^[\d.]+$/.test(config.rpId)) {
+        invalid('rpId must be a canonical DNS name or localhost');
+    }
+    if (typeof config.rpName !== 'string' || !config.rpName.trim() || config.rpName.length > 200) {
+        invalid('rpName must contain 1–200 characters');
+    }
+    if (config.allowInsecureLocalhost !== undefined &&
+        typeof config.allowInsecureLocalhost !== 'boolean') {
+        invalid('allowInsecureLocalhost must be a boolean');
+    }
+    if (!Array.isArray(config.origins) || config.origins.length === 0)
+        invalid('origins are required');
+    const origins = [];
+    for (const origin of config.origins) {
+        if (typeof origin !== 'string')
+            invalid('origins must be strings');
+        let url;
+        try {
+            url = new URL(origin);
+        }
+        catch {
+            invalid('origin is not a URL');
+        }
+        if (url.origin !== origin || url.username || url.password)
+            invalid('origins must be exact origins');
+        const local = config.allowInsecureLocalhost === true &&
+            config.rpId === 'localhost' &&
+            url.hostname === 'localhost' &&
+            url.protocol === 'http:';
+        if (url.protocol !== 'https:' && !local)
+            invalid('origins require HTTPS outside explicit localhost development');
+        if (url.hostname !== config.rpId && !url.hostname.endsWith(`.${config.rpId}`)) {
+            invalid('origin must belong to the configured relying party');
+        }
+        if (origins.includes(origin))
+            invalid('origins must be unique');
+        origins.push(origin);
+    }
+    return Object.freeze({
+        rpId: config.rpId,
+        rpName: config.rpName,
+        origins: Object.freeze(origins),
+        ...(config.allowInsecureLocalhost === undefined
+            ? {}
+            : { allowInsecureLocalhost: config.allowInsecureLocalhost }),
+    });
+}

package/dist/config/validate-passkey-config.test.node.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/config/validate-passkey-config.test.node.js

@@ -0,0 +1,152 @@
+import { describe, expect, it } from 'vitest';
+import { testAdapter } from '../storage/db-adapter.test-helper.js';
+import { resolveServerConfig } from './config.js';
+import { resolvePasskeyConfig } from './validate-passkey-config.js';
+const unused = async () => {
+    throw new Error('Configuration validation must not execute provider operations');
+};
+const passwordOnly = {
+    capabilities: { passwordChange: true, magicLink: false, sso: false },
+    signInWithPassword: unused,
+    verifyAccessToken: unused,
+    refreshSession: unused,
+    revokeSession: unused,
+    resolveActor: unused,
+};
+const ceremonies = {
+    signInOptions: unused,
+    verifySignIn: unused,
+    passwordProof: unused,
+    proofOptions: unused,
+    verifyProof: unused,
+    enrollmentOptions: unused,
+    verifyEnrollment: unused,
+    listCredentials: unused,
+    renameCredential: unused,
+    removeCredential: unused,
+};
+const enabled = {
+    ...passwordOnly,
+    capabilities: { ...passwordOnly.capabilities, passkeys: true },
+    passkeys: ceremonies,
+};
+const config = {
+    rpId: 'example.com',
+    rpName: 'Byline',
+    origins: ['https://example.com', 'https://edit.example.com:8443'],
+};
+describe('optional passkey configuration', () => {
+    it('keeps existing password-only and absent providers working', () => {
+        expect(resolvePasskeyConfig(undefined, passwordOnly)).toBeUndefined();
+        expect(resolvePasskeyConfig(undefined, undefined)).toBeUndefined();
+        expect(resolvePasskeyConfig(undefined, {
+            ...passwordOnly,
+            capabilities: { ...passwordOnly.capabilities, passkeys: false },
+        })).toBeUndefined();
+    });
+    it('validates and snapshots explicitly configured trust without invoking a ceremony', () => {
+        const origins = [...config.origins];
+        const resolved = resolvePasskeyConfig({ ...config, origins }, enabled);
+        origins.push('https://evil.example.com');
+        expect(resolved.origins).toEqual(config.origins);
+        expect(Object.isFrozen(resolved)).toBe(true);
+        expect(Object.isFrozen(resolved.origins)).toBe(true);
+    });
+    it('runs validation through server configuration resolution', () => {
+        expect(() => resolveServerConfig({
+            collections: [],
+            db: testAdapter({}),
+            i18n: {
+                admin: { defaultLocale: 'en', locales: [] },
+                content: { defaultLocale: 'en', locales: [] },
+            },
+            sessionProvider: passwordOnly,
+            passkeys: config,
+        })).toThrow('provider does not support passkeys');
+    });
+    it('requires configuration and capability to agree', () => {
+        expect(() => resolvePasskeyConfig(undefined, enabled)).toThrow('explicit relying-party');
+        expect(() => resolvePasskeyConfig(config, passwordOnly)).toThrow('does not support');
+        expect(() => resolvePasskeyConfig(config, undefined)).toThrow('does not support');
+        expect(() => resolvePasskeyConfig(config, { ...enabled, passkeys: undefined })).toThrow('does not support');
+        expect(() => resolvePasskeyConfig(undefined, { ...passwordOnly, passkeys: ceremonies })).toThrow('explicit relying-party');
+    });
+    it.each(Object.keys(ceremonies))('rejects a provider missing %s', (method) => {
+        const partial = { ...ceremonies, [method]: undefined };
+        expect(() => resolvePasskeyConfig(config, { ...enabled, passkeys: partial })).toThrow(`missing ${method}`);
+    });
+    it.each([
+        '',
+        'example.com:443',
+        'https://example.com',
+        '*.example.com',
+        'EXAMPLE.COM',
+        'example.com.',
+        '127.0.0.1',
+        '[::1]',
+        'com',
+    ])('rejects invalid RP ID %s', (rpId) => {
+        expect(() => resolvePasskeyConfig({ ...config, rpId }, enabled)).toThrow('rpId');
+    });
+    it.each([
+        'http://example.com',
+        'https://example.com/',
+        'https://example.com/path',
+        'https://example.com?x=1',
+        'https://example.com#fragment',
+        'https://user@example.com',
+        'https://EXAMPLE.COM',
+        'https://example.com:443',
+        'https://evil-example.com',
+        'https://example.com.evil.com',
+        'https://other.com',
+        'null',
+        '*',
+    ])('rejects an unsafe or noncanonical origin %s', (origin) => {
+        expect(() => resolvePasskeyConfig({ ...config, origins: [origin] }, enabled)).toThrow('Invalid passkey');
+    });
+    it('permits HTTP only for explicitly enabled localhost development', () => {
+        const local = { rpId: 'localhost', rpName: 'Local', origins: ['http://localhost:5173'] };
+        expect(() => resolvePasskeyConfig(local, enabled)).toThrow('HTTPS');
+        expect(resolvePasskeyConfig({ ...local, allowInsecureLocalhost: true }, enabled)?.origins).toEqual(local.origins);
+        expect(() => resolvePasskeyConfig({ ...config, origins: ['http://example.com'], allowInsecureLocalhost: true }, enabled)).toThrow('HTTPS');
+        expect(() => resolvePasskeyConfig({ ...local, origins: ['http://foo.localhost'], allowInsecureLocalhost: true }, enabled)).toThrow('HTTPS');
+    });
+    it.each([
+        { rpName: '' },
+        { rpName: '   ' },
+        { rpName: 'x'.repeat(201) },
+        { origins: [] },
+        { origins: ['https://example.com', 'https://example.com'] },
+        { origins: [42] },
+        { allowInsecureLocalhost: 'true' },
+        { relatedOrigins: true },
+    ])('rejects malformed or unsupported configuration %j', (invalid) => {
+        expect(() => resolvePasskeyConfig({ ...config, ...invalid }, enabled)).toThrow('Invalid passkey');
+    });
+});
+describe('passkey host protection configuration', () => {
+    const server = {
+        collections: [],
+        db: testAdapter({}),
+        i18n: {
+            admin: { defaultLocale: 'en', locales: [] },
+            content: { defaultLocale: 'en', locales: [] },
+        },
+        sessionProvider: enabled,
+        passkeys: config,
+    };
+    it('fails closed at boot without trusted IP and admission methods', () => {
+        expect(() => resolveServerConfig(server)).toThrow('passkeyRequests');
+        expect(() => resolveServerConfig({
+            ...server,
+            passkeyRequests: { resolveClientIp: () => null, limiter: {} },
+        })).toThrow('passkeyRequests');
+    });
+    it('accepts explicit protection without invoking it', () => {
+        expect(resolveServerConfig({
+            ...server,
+            passkeyRequests: { resolveClientIp: unused, limiter: { acquire: unused, consume: unused } },
+        }).passkeys).toEqual(config);
+    });
+});

package/dist/core.js

@@ -87,6 +87,7 @@ export const initBylineCore = async (config, pinoLogger) => {
         tasks: configuredTasks,
         adapter: composed.db,
         passwordSignIn: resolvedConfig.passwordSignIn,
+        passkeyRequests: resolvedConfig.passkeyRequests,
     });
     // Freeze a snapshot of the validated task set: a new array of new, frozen
     // objects, then freeze the array itself. Without this, `core.recurringTasks`

package/dist/index.d.ts

@@ -5,6 +5,7 @@ export { type CollectionGroupBucket, groupCollectionsForAdmin, } from './config/
 export { resolveRoutes } from './config/routes.js';
 export { validateAdminConfigs, validateBlockAdminConfigs, validateCollectionGroups, } from './config/validate-admin-configs.js';
 export { RESERVED_FIELD_NAMES } from './config/validate-collections.js';
+export { resolvePasskeyConfig } from './config/validate-passkey-config.js';
 export { type BylineCore, getBylineCore, initBylineCore } from './core.js';
 export * from './defaults/default-values.js';
 export { getHostRequestBridge, type HostCookieSetOptions, type HostRequestBridge, registerHostRequestBridge, tryGetHostRequestBridge, } from './host/host-request-bridge.js';

package/dist/index.js

@@ -17,6 +17,7 @@ export { groupCollectionsForAdmin, } from './config/group-collections.js';
 export { resolveRoutes } from './config/routes.js';
 export { validateAdminConfigs, validateBlockAdminConfigs, validateCollectionGroups, } from './config/validate-admin-configs.js';
 export { RESERVED_FIELD_NAMES } from './config/validate-collections.js';
+export { resolvePasskeyConfig } from './config/validate-passkey-config.js';
 export { getBylineCore, initBylineCore } from './core.js';
 export * from './defaults/default-values.js';
 export { getHostRequestBridge, registerHostRequestBridge, tryGetHostRequestBridge, } from './host/host-request-bridge.js';

package/dist/scheduler/validate-scheduler-config.d.ts

@@ -5,7 +5,7 @@
  *
  * Copyright (c) Infonomic Company Limited
  */
-import type { PasswordSignInProtection } from '@byline/auth';
+import type { PasskeyRequestProtection, PasswordSignInProtection } from '@byline/auth';
 import type { ISchedulerStore, RecurringTaskDefinition } from './types.js';
 /**
  * Boot-time gate. Recurring tasks registered against an adapter that does not
@@ -14,6 +14,7 @@ import type { ISchedulerStore, RecurringTaskDefinition } from './types.js';
  */
 export declare function validateSchedulerConfig(params: {
     passwordSignIn?: PasswordSignInProtection;
+    passkeyRequests?: PasskeyRequestProtection;
     tasks?: readonly RecurringTaskDefinition[];
     adapter: {
         scheduler?: ISchedulerStore;

package/dist/scheduler/validate-scheduler-config.js

@@ -13,10 +13,15 @@ import { validateRecurringTasks } from './validate-tasks.js';
  */
 export function validateSchedulerConfig(params) {
     const tasks = params.tasks ?? [];
-    const cleanup = params.passwordSignIn?.limiter.requiredCleanupTask;
-    if (cleanup && !tasks.some((task) => task.name === cleanup)) {
-        throw new Error(`Password sign-in requires recurring task "${cleanup}". Register the limiter's cleanupTask ` +
-            'in recurringTasks and start the host scheduler (or invoke runDueTasks externally).');
+    for (const [name, protection] of [
+        ['Password sign-in', params.passwordSignIn],
+        ['Passkeys', params.passkeyRequests],
+    ]) {
+        const cleanup = protection?.limiter.requiredCleanupTask;
+        if (cleanup && !tasks.some((task) => task.name === cleanup)) {
+            throw new Error(`${name} requires recurring task "${cleanup}". Register the limiter's cleanupTask ` +
+                'in recurringTasks and start the host scheduler (or invoke runDueTasks externally).');
+        }
     }
     if (tasks.length === 0)
         return;

package/dist/scheduler/validate-scheduler-config.test.node.js

@@ -52,3 +52,20 @@ describe('validateSchedulerConfig', () => {
         })).toThrow(/interval/i);
     });
 });
+it('requires passkey counter cleanup and accepts one shared task for both limiters', () => {
+    const protection = {
+        resolveClientIp: () => '192.0.2.1',
+        limiter: {
+            requiredCleanupTask: task.name,
+            acquire: async () => () => { },
+            consume: async () => ({ allowed: true, retryAfterSeconds: 0 }),
+        },
+    };
+    expect(() => validateSchedulerConfig({ passkeyRequests: protection, adapter: { scheduler: store } })).toThrow('Passkeys requires recurring task');
+    expect(() => validateSchedulerConfig({
+        passwordSignIn: protection,
+        passkeyRequests: protection,
+        tasks: [task],
+        adapter: { scheduler: store },
+    })).not.toThrow();
+});

package/package.json

@@ -2,9 +2,9 @@
   "name": "@byline/core",
   "private": false,
   "license": "MPL-2.0",
-  "version": "6.7.2",
+  "version": "6.8.0",
   "engines": {
-    "node": ">=20.9.0"
+    "node": ">=22.22.2"
   },
   "description": "Byline CMS core package",
   "keywords": [
@@ -82,7 +82,7 @@
     "dist"
   ],
   "dependencies": {
-    "@byline/auth": "6.7.2",
+    "@byline/auth": "6.8.0",
     "dotenv": "^18.0.8",
     "pino": "^10.4.0",
     "sharp": "^0.35.5",