@axium/server 0.9.0 → 0.11.0

package/dist/io.js

@@ -2,29 +2,32 @@ import { Logger } from 'logzen';
 import { exec } from 'node:child_process';
 import * as fs from 'node:fs';
 import { homedir } from 'node:os';
-import { join } from 'node:path/posix';
+import { dirname, join, resolve } from 'node:path/posix';
 import { styleText } from 'node:util';
-import config from './config.js';
-/**
- * Find the Axium directory.
- * This directory includes things like config files, secrets, etc.
- */
-export function findDir(global) {
-    if (process.env.AXIUM_DIR)
-        return process.env.AXIUM_DIR;
-    if (global && process.getuid?.() === 0)
-        return '/etc/axium';
-    if (global)
-        return join(homedir(), '.axium');
-    return '.axium';
-}
-if (process.getuid?.() === 0)
-    fs.mkdirSync('/etc/axium', { recursive: true });
-fs.mkdirSync(findDir(false), { recursive: true });
+import { _unique } from './state.js';
+export const systemDir = '/etc/axium';
+export const userDir = join(homedir(), '.axium');
+export const dirs = _unique('dirs', [systemDir, userDir]);
+for (let dir = resolve(process.cwd()); dir !== '/'; dir = dirname(dir)) {
+    if (fs.existsSync(join(dir, '.axium')))
+        dirs.push(join(dir, '.axium'));
+}
+if (process.env.AXIUM_DIR)
+    dirs.push(process.env.AXIUM_DIR);
+try {
+    fs.mkdirSync(systemDir, { recursive: true });
+}
+catch {
+    // Missing permissions
+}
+fs.mkdirSync(userDir, { recursive: true });
 export const logger = new Logger({
     hideWarningStack: true,
     noGlobalConsole: true,
 });
+/**
+ * @internal
+ */
 export const output = {
     constructor: { name: 'Console' },
     error(message) {
@@ -40,20 +43,24 @@ export const output = {
         console.log(message);
     },
     debug(message) {
-        console.debug(message.startsWith('\x1b') ? message : styleText('gray', message));
+        _debugOutput && console.debug(message.startsWith('\x1b') ? message : styleText('gray', message));
     },
 };
 logger.attach(output);
+let timeout = 1000;
+export function setCommandTimeout(value) {
+    timeout = value;
+}
 /**
  * Run a system command with the fancy "Example... done."
  * @internal
  */
-export async function run(opts, message, command) {
+export async function run(message, command) {
     let stderr;
     try {
-        opts.output('start', message);
+        start(message);
         const { promise, resolve, reject } = Promise.withResolvers();
-        exec(command, opts, (err, stdout, _stderr) => {
+        exec(command, { timeout }, (err, stdout, _stderr) => {
             stderr = _stderr.startsWith('ERROR:') ? _stderr.slice(6).trim() : _stderr;
             if (err)
                 reject('[command]');
@@ -61,7 +68,7 @@ export async function run(opts, message, command) {
                 resolve(stdout);
         });
         const value = await promise;
-        opts.output('done');
+        done();
         return value;
     }
     catch (error) {
@@ -85,10 +92,17 @@ export function handleError(e) {
     else
         exit(e);
 }
-export function defaultOutput(tag, message = '') {
+let _debugOutput = false;
+/**
+ * Enable or disable debug output.
+ */
+export function _setDebugOutput(enabled) {
+    _debugOutput = enabled;
+}
+function defaultOutput(tag, message = '') {
     switch (tag) {
         case 'debug':
-            config.debug && output.debug(message);
+            _debugOutput && output.debug(message);
             break;
         case 'info':
             console.log(message);
@@ -109,15 +123,31 @@ export function defaultOutput(tag, message = '') {
             console.log(styleText('whiteBright', 'Running plugin: ' + message));
     }
 }
-/**
- * TS can't tell when we do this inline
- * @internal
- */
-export function _fixOutput(opt) {
-    if (opt.output === false)
-        opt.output = () => { };
-    else
-        opt.output ??= defaultOutput;
+let _taggedOutput = defaultOutput;
+export function useTaggedOutput(output) {
+    _taggedOutput = output;
+}
+// Shortcuts for tagged output
+export function done() {
+    _taggedOutput?.('done');
+}
+export function start(message) {
+    _taggedOutput?.('start', message);
+}
+export function plugin(name) {
+    _taggedOutput?.('plugin', name);
+}
+export function debug(message) {
+    _taggedOutput?.('debug', message);
+}
+export function info(message) {
+    _taggedOutput?.('info', message);
+}
+export function warn(message) {
+    _taggedOutput?.('warn', message);
+}
+export function error(message) {
+    _taggedOutput?.('error', message);
 }
 /** @internal */
 export const _portMethods = ['node-cap'];
@@ -129,46 +159,45 @@ export const _portActions = ['enable', 'disable'];
  * If the origin has a port, passkeys do not work correctly with some password managers.
  */
 export async function restrictedPorts(opt) {
-    _fixOutput(opt);
-    opt.output('start', 'Checking for root privileges');
+    start('Checking for root privileges');
     if (process.getuid?.() != 0)
         throw 'root privileges are needed to change restricted ports.';
-    opt.output('done');
-    opt.output('start', 'Checking ports method');
+    done();
+    start('Checking ports method');
     if (!_portMethods.includes(opt.method))
         throw 'invalid';
-    opt.output('done');
-    opt.output('start', 'Checking ports action');
+    done();
+    start('Checking ports action');
     if (!_portActions.includes(opt.action))
         throw 'invalid';
-    opt.output('done');
+    done();
     switch (opt.method) {
         case 'node-cap': {
-            const setcap = await run(opt, 'Finding setcap', 'command -v setcap')
+            const setcap = await run('Finding setcap', 'command -v setcap')
                 .then(e => e.trim())
                 .catch(() => {
-                opt.output('warn', 'not in path.');
-                opt.output('start', 'Checking for /usr/sbin/setcap');
+                warn('not in path.');
+                start('Checking for /usr/sbin/setcap');
                 fs.accessSync('/usr/sbin/setcap', fs.constants.X_OK);
-                opt.output('done');
+                done();
                 return '/usr/sbin/setcap';
             });
-            opt.output('debug', 'Using setcap at ' + setcap);
+            debug('Using setcap at ' + setcap);
             let { node } = opt;
-            node ||= await run(opt, 'Finding node', 'command -v node')
+            node ||= await run('Finding node', 'command -v node')
                 .then(e => e.trim())
                 .catch(() => {
-                opt.output('warn', 'not in path.');
-                opt.output('start', 'Checking for /usr/bin/node');
+                warn('not in path.');
+                start('Checking for /usr/bin/node');
                 fs.accessSync('/usr/bin/node', fs.constants.X_OK);
-                opt.output('done');
+                done();
                 return '/usr/bin/node';
             });
-            opt.output('start', 'Resolving real path for node');
+            start('Resolving real path for node');
             node = fs.realpathSync(node);
-            opt.output('done');
-            opt.output('debug', 'Using node at ' + node);
-            await run(opt, 'Setting ports capability', `${setcap} cap_net_bind_service=${opt.action == 'enable' ? '+' : '-'}ep ${node}`);
+            done();
+            debug('Using node at ' + node);
+            await run('Setting ports capability', `${setcap} cap_net_bind_service=${opt.action == 'enable' ? '+' : '-'}ep ${node}`);
             break;
         }
     }
@@ -178,13 +207,13 @@ export async function restrictedPorts(opt) {
  * The handler will allow the parent scope to continue if a relation already exists,
  * rather than fatally exiting.
  */
-export function someWarnings(output, ...allowList) {
+export function someWarnings(...allowList) {
     return (error) => {
         error = typeof error == 'object' && 'message' in error ? error.message : error;
         for (const [pattern, message = error] of allowList) {
             if (!pattern.test(error))
                 continue;
-            output('warn', message);
+            warn(message);
             return;
         }
         throw error;

package/dist/linking.d.ts

@@ -0,0 +1,10 @@
+export declare function listRouteLinks(): Generator<{
+    id: string;
+    from: string;
+    to: string;
+}>;
+/**
+ * Symlinks .svelte page routes for plugins and the server into a project's routes directory.
+ */
+export declare function linkRoutes(): void;
+export declare function unlinkRoutes(): void;

package/dist/linking.js

@@ -0,0 +1,76 @@
+import { existsSync, symlinkSync, unlinkSync } from 'node:fs';
+import { join, resolve } from 'node:path/posix';
+import config from './config.js';
+import * as io from './io.js';
+import { getSpecifier, plugins } from './plugins.js';
+const textFor = {
+    builtin: 'built-in routes',
+};
+function info(id) {
+    const text = id.startsWith('#') ? textFor[id.slice(1)] : `routes for plugin: ${id}`;
+    const link = join(config.web.routes, `(${id.startsWith('#') ? id.slice(1) : id.replaceAll('/', '__')}`);
+    return [text, link];
+}
+export function* listRouteLinks() {
+    const [, link] = info('#builtin');
+    yield { id: '#builtin', from: resolve(import.meta.dirname, '../routes'), to: link };
+    for (const plugin of plugins) {
+        if (!plugin.routes)
+            continue;
+        const [, link] = info(plugin.name);
+        yield { id: plugin.name, from: join(import.meta.resolve(getSpecifier(plugin)), plugin.routes), to: link };
+    }
+}
+function createLink(id, routes) {
+    const [text, link] = info(id);
+    if (existsSync(link)) {
+        io.warn('already exists.');
+        io.start('Unlinking ' + text);
+        try {
+            unlinkSync(link);
+        }
+        catch (e) {
+            io.exit(e && e instanceof Error ? e.message : e.toString());
+        }
+        io.done();
+        io.start('Re-linking ' + text);
+    }
+    try {
+        symlinkSync(routes, link, 'dir');
+    }
+    catch (e) {
+        io.exit(e && e instanceof Error ? e.message : e.toString());
+    }
+}
+/**
+ * Symlinks .svelte page routes for plugins and the server into a project's routes directory.
+ */
+export function linkRoutes() {
+    io.start('Linking built-in routes');
+    createLink('#builtin', resolve(import.meta.dirname, '../routes'));
+    for (const plugin of plugins) {
+        if (!plugin.routes)
+            continue;
+        io.start(`Linking routes for plugin: ${plugin.name}`);
+        createLink(plugin.name, join(import.meta.resolve(getSpecifier(plugin)), plugin.routes));
+    }
+}
+function removeLink(id) {
+    const [text, link] = info(id);
+    if (!existsSync(link))
+        return;
+    io.start('Unlinking ' + text);
+    try {
+        unlinkSync(link);
+    }
+    catch (e) {
+        io.exit(e && e instanceof Error ? e.message : e.toString());
+    }
+    io.done();
+}
+export function unlinkRoutes() {
+    removeLink('#builtin');
+    for (const plugin of plugins) {
+        removeLink(plugin.name);
+    }
+}

package/dist/plugins.d.ts

@@ -1,21 +1,37 @@
 import z from 'zod/v4';
-export declare const fn: z.ZodCustom<(...args: unknown[]) => any, (...args: unknown[]) => any>;
+import type { Database, InitOptions, OpOptions } from './database.js';
+export declare const PluginMetadata: z.ZodObject<{
+    name: z.ZodString;
+    version: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    routes: z.ZodOptional<z.ZodString>;
+}, z.core.$loose>;
 export declare const Plugin: z.ZodObject<{
-    id: z.ZodString;
     name: z.ZodString;
     version: z.ZodString;
     description: z.ZodOptional<z.ZodString>;
+    routes: z.ZodOptional<z.ZodString>;
     statusText: z.ZodCustom<z.core.$InferInnerFunctionTypeAsync<z.core.$ZodTuple<[], null>, z.ZodString>, z.core.$InferInnerFunctionTypeAsync<z.core.$ZodTuple<[], null>, z.ZodString>>;
-    db_init: z.ZodOptional<z.ZodCustom<(...args: unknown[]) => any, (...args: unknown[]) => any>>;
-    db_remove: z.ZodOptional<z.ZodCustom<(...args: unknown[]) => any, (...args: unknown[]) => any>>;
-    db_wipe: z.ZodOptional<z.ZodCustom<(...args: unknown[]) => any, (...args: unknown[]) => any>>;
-    db_clean: z.ZodOptional<z.ZodCustom<(...args: unknown[]) => any, (...args: unknown[]) => any>>;
-}, z.core.$strip>;
-export interface Plugin extends z.infer<typeof Plugin> {
+    hooks: z.ZodOptional<z.ZodRecord<z.ZodUnion<[z.ZodLiteral<"remove" | "db_init" | "db_wipe" | "clean">, z.ZodNever]>, z.ZodCustom<(...args: any[]) => any, (...args: any[]) => any>>>;
+}, z.core.$loose>;
+declare const kSpecifier: unique symbol;
+export type Plugin = z.infer<typeof Plugin>;
+interface PluginInternal extends Plugin {
+    [kSpecifier]: string;
+    hooks: Hooks;
+}
+export interface Hooks {
+    db_init?: (opt: InitOptions, db: Database) => void | Promise<void>;
+    remove?: (opt: {
+        force?: boolean;
+    }, db: Database) => void | Promise<void>;
+    db_wipe?: (opt: OpOptions, db: Database) => void | Promise<void>;
+    clean?: (opt: Partial<OpOptions>, db: Database) => void | Promise<void>;
 }
-export declare const plugins: Set<Plugin>;
-export declare function resolvePlugin(search: string): Plugin | undefined;
-export declare function pluginText(plugin: Plugin): string;
+export declare const plugins: Set<PluginInternal>;
+export declare function resolvePlugin(search: string): PluginInternal | undefined;
+export declare function pluginText(plugin: PluginInternal): string;
 export declare function loadPlugin(specifier: string): Promise<void>;
+export declare function getSpecifier(plugin: PluginInternal): string;
 export declare function loadPlugins(dir: string): Promise<void>;
-export declare function loadDefaultPlugins(): Promise<void>;
+export {};

package/dist/plugins.js

@@ -1,52 +1,60 @@
+import { zAsyncFunction } from '@axium/core/schemas';
 import * as fs from 'node:fs';
-import { join, resolve } from 'node:path/posix';
+import { resolve } from 'node:path/posix';
 import { styleText } from 'node:util';
 import z from 'zod/v4';
-import { findDir, output } from './io.js';
-import { zAsyncFunction } from '@axium/core/schemas';
-export const fn = z.custom(data => typeof data === 'function');
-export const Plugin = z.object({
-    id: z.string(),
+import { output } from './io.js';
+import { _unique } from './state.js';
+export const PluginMetadata = z.looseObject({
     name: z.string(),
     version: z.string(),
     description: z.string().optional(),
+    routes: z.string().optional(),
+});
+const hookNames = ['db_init', 'remove', 'db_wipe', 'clean'];
+const fn = z.custom(data => typeof data === 'function');
+export const Plugin = PluginMetadata.extend({
     statusText: zAsyncFunction(z.function({ input: [], output: z.string() })),
-    db_init: fn.optional(),
-    db_remove: fn.optional(),
-    db_wipe: fn.optional(),
-    db_clean: fn.optional(),
+    hooks: z.partialRecord(z.literal(hookNames), fn).optional(),
 });
-export const plugins = new Set();
+const kSpecifier = Symbol('specifier');
+export const plugins = _unique('plugins', new Set());
 export function resolvePlugin(search) {
     for (const plugin of plugins) {
-        if (plugin.name.startsWith(search) || plugin.id.startsWith(search))
+        if (plugin.name === search)
             return plugin;
     }
 }
 export function pluginText(plugin) {
     return [
         styleText('whiteBright', plugin.name),
-        plugin.id,
         `Version: ${plugin.version}`,
         `Description: ${plugin.description ?? styleText('dim', '(none)')}`,
-        `Database integration: ${[plugin.db_init, plugin.db_remove, plugin.db_wipe]
-            .filter(Boolean)
-            .map(fn => fn?.name.slice(3))
-            .join(', ') || styleText('dim', '(none)')}`,
+        `Hooks: ${Object.keys(plugin.hooks).join(', ') || styleText('dim', '(none)')}`,
+        // @todo list the routes when debug output is enabled
+        `Routes: ${plugin.routes || styleText('dim', '(none)')}`,
     ].join('\n');
 }
 export async function loadPlugin(specifier) {
     try {
-        const plugin = await Plugin.parseAsync(await import(/* @vite-ignore */ specifier)).catch(e => {
+        const imported = await import(/* @vite-ignore */ specifier);
+        const maybePlugin = 'default' in imported ? imported.default : imported;
+        const plugin = Object.assign({ hooks: {}, [kSpecifier]: specifier }, await Plugin.parseAsync(maybePlugin).catch(e => {
             throw z.prettifyError(e);
-        });
+        }));
+        if (plugin.name.startsWith('#') || plugin.name.includes(' ')) {
+            throw 'Invalid plugin name. Plugin names can not start with a hash or contain spaces.';
+        }
         plugins.add(plugin);
-        output.debug(`Loaded plugin: "${plugin.name}" (${plugin.id}) ${plugin.version}`);
+        output.debug(`Loaded plugin: ${plugin.name} ${plugin.version}`);
     }
     catch (e) {
-        output.debug(`Failed to load plugin from ${specifier}: ${e.message || e}`);
+        output.debug(`Failed to load plugin from ${specifier}: ${e ? (e instanceof Error ? e.message : e.toString()) : e}`);
     }
 }
+export function getSpecifier(plugin) {
+    return plugin[kSpecifier];
+}
 export async function loadPlugins(dir) {
     fs.mkdirSync(dir, { recursive: true });
     const files = fs.readdirSync(dir);
@@ -58,7 +66,3 @@ export async function loadPlugins(dir) {
         await loadPlugin(path);
     }
 }
-export async function loadDefaultPlugins() {
-    await loadPlugins(join(findDir(true), 'plugins'));
-    await loadPlugins(join(findDir(false), 'plugins'));
-}

package/dist/requests.d.ts

@@ -0,0 +1,14 @@
+import { type User } from '@axium/core/user';
+import { type HttpError, type RequestEvent } from '@sveltejs/kit';
+import z from 'zod/v4';
+import { type SessionAndUser, type UserInternal } from './auth.js';
+export declare function parseBody<const Schema extends z.ZodType, const Result extends z.infer<Schema> = z.infer<Schema>>(event: RequestEvent, schema: Schema): Promise<Result>;
+export declare function getToken(event: RequestEvent, sensitive?: boolean): string | undefined;
+export interface AuthResult extends SessionAndUser {
+    /** The user authenticating the request. */
+    accessor: UserInternal;
+}
+export declare function checkAuth(event: RequestEvent, userId: string, sensitive?: boolean): Promise<AuthResult>;
+export declare function createSessionData(userId: string, elevated?: boolean): Promise<Response>;
+export declare function stripUser(user: UserInternal, includeProtected?: boolean): User;
+export declare function withError(text: string, code?: number): (e: Error | HttpError) => never;

package/dist/requests.js

@@ -0,0 +1,67 @@
+import { userProtectedFields, userPublicFields } from '@axium/core/user';
+import { error, json } from '@sveltejs/kit';
+import { serialize as serializeCookie } from 'cookie';
+import { pick } from 'utilium';
+import z from 'zod/v4';
+import { createSession, getSessionAndUser, getUser } from './auth.js';
+import { config } from './config.js';
+export async function parseBody(event, schema) {
+    const contentType = event.request.headers.get('content-type');
+    if (!contentType || !contentType.includes('application/json'))
+        error(415, { message: 'Invalid content type' });
+    const body = await event.request.json().catch(() => error(415, { message: 'Invalid JSON' }));
+    try {
+        return schema.parse(body);
+    }
+    catch (e) {
+        error(400, { message: z.prettifyError(e) });
+    }
+}
+export function getToken(event, sensitive = false) {
+    const header_token = event.request.headers.get('Authorization')?.replace('Bearer ', '');
+    if (header_token)
+        return header_token;
+    if (config.debug || config.api.cookie_auth) {
+        return event.cookies.get(sensitive ? 'elevated_token' : 'session_token');
+    }
+}
+export async function checkAuth(event, userId, sensitive = false) {
+    const token = getToken(event, sensitive);
+    if (!token)
+        throw error(401, { message: 'Missing token' });
+    const session = await getSessionAndUser(token).catch(() => error(401, { message: 'Invalid or expired session' }));
+    if (session.userId !== userId) {
+        if (!session.user?.isAdmin)
+            error(403, { message: 'User ID mismatch' });
+        // Admins are allowed to manage other users.
+        const accessor = session.user;
+        session.user = await getUser(userId).catch(() => error(404, { message: 'Target user not found' }));
+        return Object.assign(session, { accessor });
+    }
+    if (!session.elevated && sensitive)
+        error(403, 'This token can not be used for sensitive actions');
+    return Object.assign(session, { accessor: session.user });
+}
+export async function createSessionData(userId, elevated = false) {
+    const { token, expires } = await createSession(userId, elevated);
+    const response = json({ userId, token: elevated ? '[[redacted:elevated]]' : token }, { status: 201 });
+    const cookies = serializeCookie(elevated ? 'elevated_token' : 'session_token', token, {
+        httpOnly: true,
+        path: '/',
+        expires,
+        secure: config.auth.secure_cookies,
+        sameSite: 'lax',
+    });
+    response.headers.set('Set-Cookie', cookies);
+    return response;
+}
+export function stripUser(user, includeProtected = false) {
+    return pick(user, ...userPublicFields, ...(includeProtected ? userProtectedFields : []));
+}
+export function withError(text, code = 500) {
+    return function (e) {
+        if ('body' in e)
+            throw e;
+        error(code, { message: text + (config.debug && e.message ? `: ${e.message}` : '') });
+    };
+}

package/dist/routes.d.ts

@@ -1,9 +1,10 @@
 import type { RequestMethod } from '@axium/core/requests';
-import type { LoadEvent, RequestEvent } from '@sveltejs/kit';
+import type { RequestEvent } from '@sveltejs/kit';
 import type { Component } from 'svelte';
 import type z from 'zod/v4';
 type _Params = Partial<Record<string, string>>;
-export type EndpointHandlers<Params extends _Params = _Params> = Partial<Record<RequestMethod, (event: RequestEvent<Params>) => object | Promise<object>>>;
+type MaybePromise<T> = T | Promise<T>;
+export type EndpointHandlers<Params extends _Params = _Params> = Partial<Record<RequestMethod, (event: RequestEvent<Params>) => MaybePromise<object | Response>>>;
 export type RouteParamOptions = z.ZodType;
 export interface CommonRouteOptions<Params extends _Params = _Params> {
     path: string;
@@ -15,6 +16,7 @@ export interface CommonRouteOptions<Params extends _Params = _Params> {
  * A route with server-side handlers for different HTTP methods.
  */
 export interface ServerRouteOptions<Params extends _Params = _Params> extends CommonRouteOptions<Params>, EndpointHandlers<Params> {
+    api?: boolean;
 }
 export interface WebRouteOptions extends CommonRouteOptions {
     load?(event: RequestEvent): object | Promise<object>;
@@ -25,31 +27,28 @@ export type RouteOptions = ServerRouteOptions | WebRouteOptions;
 export interface RouteCommon {
     path: string;
     params?: Record<string, RouteParamOptions>;
-    [kBuiltin]: boolean;
 }
 export interface ServerRoute extends RouteCommon, EndpointHandlers {
+    api: boolean;
     server: true;
 }
 export interface WebRoute extends RouteCommon {
     server: false;
-    load?(event: LoadEvent): object | Promise<object>;
-    page?: Component;
+    load?(event: RequestEvent): object | Promise<object>;
+    page: Component;
 }
 export type Route = ServerRoute | WebRoute;
 /**
  * @internal
  */
 export declare const routes: Map<string, Route>;
-declare const kBuiltin: unique symbol;
-export declare function addRoute(opt: RouteOptions, _routeMap?: Map<string, Route>): void;
+export declare function addRoute(opt: RouteOptions): void;
 /**
  * Resolve a request URL into a route.
  * This handles parsing of parameters in the URL.
  */
-export declare function resolveRoute<T extends Route>(event: RequestEvent | LoadEvent, _routeMap?: Map<string, T>): T | undefined;
-/**
- * This function marks all existing routes as built-in.
- * @internal
- */
-export declare function _markDefaults(): void;
+export declare function resolveRoute(event: {
+    url: URL;
+    params?: object;
+}): Route | undefined;
 export {};