wirejs-resources 0.1.1-alpha

package/lib/adapters/context.js

@@ -0,0 +1,98 @@
+import { CookieJar } from "./cookie-jar.js";
+
+const contextWrappers = new Set();
+
+/**
+ * @typedef {(...args: any) => any} ApiMethod
+ */
+
+/**
+ * @typedef {{
+ * 	[K in string]: ApiMethod | ApiNamespace
+ * }} ApiNamespace
+ */
+
+/**
+ * @template T
+ * @typedef {T extends ((...args: infer ARGS) => infer RT)
+ * 	? ((
+ * 		context: Context | boolean,
+ * 		...args: ARGS
+ * 	) => RT extends Promise<any> ? RT : Promise<RT>) : never
+ * } ContextfulApiMethod
+ */
+
+/**
+ * @template T
+ * @typedef {{
+ * 	[K in keyof T]: T[K] extends ApiMethod
+ * 	? ContextfulApiMethod<T[K]>
+ * 	: ContextfulApiNamespace<T[K]>
+ * }} ContextfulApiNamespace
+ */
+
+/**
+ * @template {ApiNamespace | ApiMethod} T
+ * @typedef {T extends ApiMethod
+ * 	? ContextfulApiMethod<T>
+ * 	: ContextfulApiNamespace<T>
+ * } ContextWrapped
+ */
+
+/**
+ * @template {ApiMethod | ApiNamespace} T
+ * @param {(context: Context) => T} contextWrapper
+ * @param {string[]} [path]
+ * @returns {ContextWrapped<T>}
+ */
+export function withContext(contextWrapper, path = []) {
+	// first param needs to be a function, which enables `Proxy` to implement `apply()`.
+	const fnOrNs = new Proxy(function() {}, {
+		apply(_target, _thisArg, args) {
+			const [context, ...remainingArgs] = args;
+			let functionOrNamespaceObject = contextWrapper(context);
+			console.log({context, args, functionOrNamespaceObject, path});
+			for (const k of path) {
+				functionOrNamespaceObject = functionOrNamespaceObject[k];
+			}
+			return functionOrNamespaceObject(...remainingArgs);
+		},
+		get(_target, prop) {
+			return withContext(contextWrapper, [...path, prop])
+		}
+	});
+	contextWrappers.add(fnOrNs);
+	return fnOrNs;
+}
+
+/**
+ * 
+ * @param {Object} fnOrNS
+ * @returns {fnOrNS is (context: Context) => T}
+ */
+export function requiresContext(fnOrNS) {
+	return contextWrappers.has(fnOrNS);
+}
+
+export class Context {
+	/**
+	 * @type {CookieJar} cookies
+	 */
+	cookies;
+
+	/**
+	 * @type {URL} location
+	 */
+	location;
+
+	/**
+	 * @param {{
+	 * 	cookies: CookieJar;
+	 * 	location: URL;
+	 * }}
+	 */
+	constructor({ cookies, location }) {
+		this.cookies = cookies;
+		this.location = location;
+	}
+}

package/lib/adapters/cookie-jar.js

@@ -0,0 +1,94 @@
+/**
+ * @typedef {Object} Cookie
+ * @property {string} name
+ * @property {string} value
+ * @property {number} [maxAge] - The maximum age (TTL) in seconds
+ * @property {boolean} [httpOnly] - Whether the cookie is only accessible to the client (not JS)
+ * @property {boolean} [secure] - Whether the cookie should only be sent over HTTPS (or localhost)
+ */
+
+export class CookieJar {
+	/**
+	 * @type {Record<string, Cookie>}
+	 */
+	#cookies = {};
+
+	/**
+	 * The list of cookies that have been set with `set()` which need to be
+	 * sent to the client.
+	 * 
+	 * @type {Set<string>}
+	 */
+	#setCookies = new Set();
+
+	/**
+	 * Initialize
+	 * 
+	 * @param {string | undefined} cookie
+	 */
+	constructor(cookie) {
+		this.#cookies = Object.fromEntries(
+			(cookie || '')
+				.split(/;/g)
+				.map(c => {
+					const [k, v] = c.split('=').map(p => decodeURIComponent(p.trim()));
+					return [k, {
+						name: k,
+						value: v
+					}];
+				})
+		);
+	}
+
+	/**
+	 * @param {Cookie} cookie 
+	 */
+	set(cookie) {
+		this.#cookies[cookie.name] = {...cookie};
+		this.#setCookies.add(cookie.name);
+	}
+	
+	/**
+	 * 
+	 * @param {string} name 
+	 * @returns {Cookie | undefined}
+	 */
+	get(name) {
+		return this.#cookies[name] ? { ...this.#cookies[name] } : undefined;
+	}
+
+	/**
+	 * 
+	 * @param {string} name 
+	 */
+	delete(name) {
+		if (this.#cookies[name]) {
+			this.#cookies[name].value = '-- deleted --';
+			this.#cookies[name].maxAge = 0;
+			this.#setCookies.add(name);
+		}
+	}
+
+	/**
+	 * Gets a copy of all cookies.
+	 * 
+	 * Changes made to this copy are not reflected
+	 * 
+	 * @returns {Record<string, string>}
+	 */
+	getAll() {
+		const all = {};
+		for (const cookie of Object.values(this.#cookies)) {
+			all[cookie.name] = cookie.value;
+		}
+		return all;
+	}
+
+	getSetCookies() {
+		const all = [];
+		for (const name of this.#setCookies) {
+			all.push({...this.#cookies[name]});
+		}
+		return all;
+	}
+}

package/lib/index.js

@@ -0,0 +1,4 @@
+export { FileService } from './services/file.js';
+export { AuthenticationService } from './services/authentication.js';
+export { CookieJar } from './adapters/cookie-jar.js';
+export { withContext, requiresContext, Context } from './adapters/context.js';

package/lib/resources/secret.js

@@ -0,0 +1,48 @@
+import process from 'process';
+import fs from 'fs';
+import path from 'path';
+import crypto from 'crypto';
+
+const CWD = process.cwd();
+
+/**
+ * @type {Map<string, Secret>}
+ */
+const secrets = new Map();
+
+export class Secret {
+	#id;
+
+	/**
+	 * @param {string} id 
+	 * @param {string} [value]
+	 */
+	constructor(id, value) {
+		this.#id = id;
+		secrets.set(id, this);
+		if (!fs.existsSync(this.#filename())) {
+			fs.mkdirSync(path.dirname(this.#filename()), { recursive: true });
+			fs.writeFileSync(
+				this.#filename(),
+				value ?? crypto.randomBytes(64).toString('base64url')
+			);
+		}
+	}
+
+	#filename() {
+		const sanitizedId = this.id.replace('~', '-').replace(/\.+/g, '.');
+		return path.join(CWD, 'temp', 'wirejs-services', 'secrets', sanitizedId);
+	}
+
+	get id() {
+		return this.#id;
+	}
+
+	async read() {
+		return fs.promises.readFile(this.#filename(), 'utf8');
+	}
+
+	async write(value) {
+		fs.promises.writeFile(this.#filename(), value);
+	}
+}

package/lib/services/authentication.js

@@ -0,0 +1,424 @@
+import process from 'process';
+import fs from 'fs';
+import path from 'path';
+
+import * as jose from 'jose';
+import bcrypt from 'bcrypt';
+
+import { Secret } from '../resources/secret.js';
+import { CookieJar } from '../adapters/cookie-jar.js';
+import { withContext } from '../adapters/context.js';
+
+const CWD = process.cwd();
+const SALT_ROUNDS = 10;
+
+const signingSecret = new Secret('wirejs-services/auth-jwt-signing-secret');
+
+/**
+ * @typedef {{
+ * 	id: string;
+ * 	password: string;
+ * }} User
+ */
+
+/**
+ * @typedef {{
+ * 	label: string;
+ * 	type: 'string' | 'password' | 'number' | 'boolean';
+ * 	isRequired?: boolean;
+ * }} AuthenticationInput
+ */
+
+/**
+ * @typedef {{
+ * 	name: string;
+ * 	title?: string;
+ * 	description?: string;
+ * 	message?: string;
+ * 	inputs?: Record<string, AuthenticationInput>;
+ * 	buttons?: string[];
+ * }} Action
+ */
+
+/**
+ * @typedef {{
+ * 	state: 'authenticated' | 'unauthenticated';
+ * 	user: string | undefined;
+ * }} AuthenticationBaseState
+ */
+
+/**
+ * @typedef {{
+ * 	state: AuthenticationBaseState;
+ * 	message?: string;
+ * 	actions: Record<string, Action>;
+ * }} AuthenticationState
+ */
+
+/**
+ * @typedef {{
+ * 	key: string;
+ * 	inputs: Record<string, string | number | boolean>;
+ * 	verb: string;
+ * }} PerformActionParameter
+ */
+
+/**
+ * @typedef {{
+ * 	message: string;
+ * 	field?: string;
+ * }} AuthenticationError
+ */
+
+/**
+ * @typedef {Object} AuthenticationServiceOptions
+ * @property {number} [duration] - The number of seconds the authentication session stays alive.
+ * @property {boolean} [keepalive] - Whether to automatically extend (keep alive) an authentication session when used.
+ * @property {string} [cookie] - The name of the cookie to use to store the authentication state JWT.
+ */
+
+/**
+ * @type {Map<string, AuthService>}
+ */
+const services = new Map();
+
+const ONE_WEEK = 7 * 24 * 60 * 60; // days * hours/day * minutes/hour * seconds/minute
+
+export class AuthenticationService {
+	id;
+	#duration;
+	#keepalive;
+	#cookieName;
+	#signingSecret;
+
+	#users;
+
+	/**
+	 * 
+	 * @param {string} id 
+	 * @param {AuthenticationServiceOptions} [options]
+	 */
+	constructor(id, { duration, keepalive, cookie } = {}) {
+		this.id = id;
+		this.#duration = duration || ONE_WEEK;
+		this.#keepalive = !!keepalive;
+		this.#cookieName = cookie ?? 'identity';
+
+		this.#users = {
+			id,
+			
+			/**
+			 * 
+			 * @param {string} username
+			 */
+			async get(username) {
+				try {
+					const data = await fs.promises.readFile(this.filenameFor(username));
+					return JSON.parse(data);
+				} catch {
+					return undefined;
+				}
+			},
+
+			/**
+			 * @param {string} username
+			 * @param {User} user
+			 */
+			async set(username, details) {
+				await fs.promises.mkdir(
+					path.dirname(this.filenameFor(username)),
+					{ recursive: true }
+				);
+				await fs.promises.writeFile(
+					this.filenameFor(username),
+					JSON.stringify(details)
+				);
+			},
+
+			/**
+			 * @param {string} username
+			 */
+			async has(username) {
+				const user = await this.get(username);
+				return !!user;
+			},
+
+			/**
+			 * @param {string} username
+			 * @returns 
+			 */
+			filenameFor(username) {
+				const sanitizedId = this.id.replace('~', '-').replace(/\.+/g, '.');
+				const sanitizedName = username.replace('~', '-').replace(/\.+/g, '.');
+				return path.join(CWD,
+					'temp',
+					'wirejs-services',
+					'authentication',
+					sanitizedId,
+					`${sanitizedName}.json`
+				);
+			}
+		}
+				
+		if (services.has(id)) {
+			services.set(id, this);
+		}
+	}
+
+	async getSigningSecret() {
+		const secretAsString = await signingSecret.read();
+		return new TextEncoder().encode(secretAsString);
+	}
+
+	/**
+	 * @type {Promise<Uint8Array<ArrayBufferLike>>}
+	 */
+	get signingSecret() {
+		if (!this.#signingSecret) {
+			this.#signingSecret = this.getSigningSecret();
+		}
+		return this.#signingSecret;
+	}
+
+	/**
+	 * @param {CookieJar} cookies
+	 * @returns {Promise<AuthenticationBaseState>}
+	 */
+	async getBaseState(cookies) {
+		let idCookie, idPayload, user;
+
+		try {
+			idCookie = cookies.get(this.#cookieName)?.value;
+			idPayload = idCookie ? (
+				await jose.jwtVerify(idCookie, await this.signingSecret)
+			) : undefined;
+			user = idPayload ? idPayload.payload.sub : undefined;
+		} catch (err) {
+			// jose doesn't like our cookie.
+			console.error(err);
+		}
+
+		if (user) {
+			return {
+				state: 'authenticated',
+				user
+			}
+		} else {
+			return {
+				state: 'unauthenticated',
+				user: undefined,
+			}
+		}
+	}
+
+	/**
+	 * @param {CookieJar} cookies
+	 * @returns {Promise<AuthenticationState>}
+	 */
+	async getState(cookies) {
+		const state = await this.getBaseState(cookies);
+		if (state.state === 'authenticated') {
+			if (this.#keepalive) this.setBaseState(state);
+			return {
+				state,
+				actions: {
+					changepassword: {
+						name: "Change Password",
+						inputs: {
+							existingPassword: {
+								label: 'Old Password',
+								type: 'password',
+							},
+							newPassword: {
+								label: 'New Password',
+								type: 'password',
+							}
+						},
+						buttons: ['Change Password']
+					},
+					signout: {
+						name: "Sign out"
+					},
+				}
+			}
+		} else {
+			return {
+				state,
+				actions: {
+					signin: {
+						name: "Sign In",
+						inputs: {
+							username: {
+								label: 'Username',
+								type: 'text',
+							},
+							password: {
+								label: 'Password',
+								type: 'password',
+							},
+						},
+						buttons: ['Sign In']
+					},
+					signup: {
+						name: "Sign Up",
+						inputs: {
+							username: {
+								label: 'Username',
+								type: 'text',
+							},
+							password: {
+								label: 'Password',
+								type: 'password',
+							},
+						},
+						buttons: ['Sign Up']
+					},
+				}
+			}
+		}
+	}
+
+	/**
+	 * 
+	 * @param {CookieJar} cookies 
+	 * @param {string | undefined} [user]
+	 */
+	async setBaseState(cookies, user) {
+		if (!user) {
+			cookies.delete(this.#cookieName);
+		} else {
+			const jwt = await new jose.SignJWT({})
+				.setProtectedHeader({ alg: 'HS256' })
+				.setIssuedAt()
+				.setSubject(user)
+				.setExpirationTime(`${this.#duration}s`)
+				.sign(await this.signingSecret);
+
+			cookies.set({
+				name: this.#cookieName,
+				value: jwt,
+				httpOnly: true,
+				secure: true,
+				maxAge: this.#duration
+			});
+		}	
+	}
+
+	/**
+	 * 
+	 * @param {Record<string, string>} input 
+	 * @param {string[]} fields 
+	 * @returns {AuthenticationError[] | undefined}
+	 */
+	missingFieldErrors(input, fields) {
+		/**
+		 * @type {AuthenticationError[]}
+		 */
+		const errors = [];
+		for (const field of fields) {
+			if (!input[field]) errors.push({
+				field,
+				message: "Field is required."
+			});
+		}
+		return errors.length > 0 ? errors : undefined;
+	}
+
+	/**
+	 * @param {CookieJar} cookies
+	 * @param {PerformActionParameter} params
+	 * @returns {Promise<AuthenticationState | { errors: AuthenticationError[] }>}
+	 */
+	async setState(cookies, { key, inputs, verb: _verb }) {
+		if (key === 'signout') {
+			await this.setBaseState(cookies, undefined);
+			return this.getState(cookies);
+		} else if (key === 'signup') {
+			const errors = this.missingFieldErrors(inputs, ['username', 'password']);
+			if (errors) {
+				return { errors };
+			} else if (await this.#users.has(inputs.username)) {
+				return { errors: 
+						[{
+						field: 'username',
+						message: 'User already exists.'
+					}]
+				};
+			} else {
+				await this.#users.set(inputs.username, {
+					id: inputs.username,
+					password: await bcrypt.hash(inputs.password, SALT_ROUNDS)
+				});
+				await this.setBaseState(cookies, inputs.username);
+				return this.getState(cookies);
+			}
+		} else if (key === 'signin') {
+			const user = await this.#users.get(inputs.username);
+			if (!user) {
+				return { errors:
+					[{
+						field: 'username',
+						message: `User doesn't exist.`
+					}]
+				};
+			} else if (await bcrypt.compare(inputs.password, user.password)) {
+				// a real authentication service will use password hashing.
+				// this is an in-memory just-for-testing user pool.
+				await this.setBaseState(cookies, inputs.username);
+				return this.getState(cookies);
+			} else {
+				return { errors:
+					[{
+						field: 'password',
+						message: "Incorrect password."
+					}]
+				};
+			}
+		} else if (key === 'changepassword') {
+			const state = await this.getBaseState(cookies);
+			const user = await this.#users.get(state.user);
+			if (!user) {
+				return { errors:
+					[{
+						field: 'username',
+						message: `You're not signed in as a recognized user.`
+					}]
+				};
+			} else if (await bcrypt.compare(inputs.existingPassword, user.password)) {
+				await this.#users.set(user.id, {
+					...user,
+					password: await bcrypt.hash(inputs.newPassword, SALT_ROUNDS)
+				});
+				return {
+					message: "Password updated.",
+					...await this.getState(cookies)
+				};
+			} else {
+				return { errors: [{
+						field: 'existingPassword',
+						message: "The provided existing password is incorrect."
+					}]
+				};
+			}
+		} else {
+			return { errors: 
+				[{
+					message: 'Unrecognized authentication action.'
+				}]
+			};
+		}
+	}
+
+	buildApi() {
+		return withContext(context => ({
+			getState: () => this.getState(context.cookies),
+
+			/**
+			 * 
+			 * @param {Parameters<typeof this['setState']>[1]} options 
+			 * @returns 
+			 */
+			setState: (options) => this.setState(context.cookies, options),
+		}));
+	}
+}

package/lib/services/file.js

@@ -0,0 +1,78 @@
+import process from 'process';
+import fs from 'fs';
+import path from 'path';
+
+const CWD = process.cwd();
+
+/**
+ * @type {Map<string, FileService>}
+ */
+const services = new Map();
+
+export class FileService {
+	id;
+
+	/**
+	 * 
+	 * @param {{
+	 * 	id: string
+	 * }} options
+	 */
+	constructor(id) {
+		this.id = id;
+		if (!services.has(id)) {
+			services.set(id, this);
+		}
+	}
+
+	/**
+	 * @param {string} filename 
+	 * @returns 
+	 */
+	#fullNameFor(filename) {
+		const sanitizedId = this.id.replace('~', '-').replace(/\.+/g, '.');
+		const sanitizedName = filename.replace('~', '-').replace(/\.+/g, '.');
+		return path.join(CWD, 'temp', 'wirejs-services', 'files', sanitizedId, sanitizedName);
+	}
+
+	/**
+	 * @param {string} filename
+	 * @param {BufferEncoding} [encoding]
+	 * @return {Promise<string>} file data as a string
+	 */
+	async read(filename, encoding = 'utf8') {
+		return fs.promises.readFile(this.#fullNameFor(filename), { encoding });
+	}
+
+	/**
+	 * 
+	 * @param {string} filename 
+	 * @param {string} data 
+	 */
+	async write(filename, data) {
+		const fullname = this.#fullNameFor(filename);
+		await fs.promises.mkdir(path.dirname(fullname), { recursive: true });
+		return fs.promises.writeFile(fullname, data);
+	}
+
+	/**
+	 * 
+	 * @param {string} filename 
+	 */
+	async delete(filename) {
+		return fs.promises.unlink(this.#fullNameFor(filename));
+	}
+
+	/**
+	 * 
+	 * @param {{
+	 * 	prefix?: string
+	 * }} [options]
+	 */
+	async * list({ prefix = '' } = {}) {
+		const all = await fs.promises.readdir(CWD, { recursive: true });
+		for (const name of all) {
+			if (prefix === undefined || name.startsWith(prefix)) yield name;
+		}
+	}
+}

package/lib/services/sendmail.js

@@ -0,0 +1,12 @@
+/**
+ * @type {Map<string, SendmailService>}
+ */
+const services = new Map();
+
+class SendmailService {
+	id;
+
+	constructor({ id }) {
+
+	}
+}

package/lib/types.ts

@@ -0,0 +1,11 @@
+import type {
+	AuthenticationService as AuthenticationServiceBase,
+	withContext as withContextBase,
+	FileService as FileServiceBase,
+	Context as ContextBase
+} from './index.js';
+
+export declare class Context extends ContextBase {};
+export declare class AuthenticationService extends AuthenticationServiceBase {};
+export declare class FileService extends FileServiceBase {};
+export declare function withContext(): typeof withContextBase;

package/package.json

@@ -0,0 +1,29 @@
+{
+	"name": "wirejs-resources",
+	"version": "0.1.1-alpha",
+	"description": "Basic services and server-side resources for wirejs apps",
+	"type": "module",
+	"main": "./lib/index.js",
+	"types": "./lib/types.ts",
+	"exports": {
+		".": {
+			"types": "./lib/types.ts",
+			"default": "./lib/index.js"
+		}
+	},
+	"scripts": {},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/svidgen/create-wirejs-app.git"
+	},
+	"author": "Jon Wire",
+	"license": "AGPL-3.0-only",
+	"bugs": {
+		"url": "https://github.com/svidgen/create-wirejs-app/issues"
+	},
+	"homepage": "https://github.com/svidgen/create-wirejs-app#readme",
+	"dependencies": {
+		"bcrypt": "^5.1.1",
+		"jose": "^5.9.6"
+	}
+}