@meith/settings 0.16.0

package/src/fields.ts

@@ -0,0 +1,58 @@
+import type { SettingDefinition } from './definitions'
+
+export interface SettingOption {
+  readonly value: string
+  readonly label: string
+}
+
+export type SettingField =
+  | { readonly kind: 'text' }
+  | { readonly kind: 'textarea' }
+  | { readonly kind: 'boolean' }
+  | { readonly kind: 'number'; readonly min?: number; readonly max?: number }
+  | { readonly kind: 'select'; readonly options: readonly SettingOption[] }
+  | { readonly kind: 'secret' }
+
+export function settingField(definition: SettingDefinition): SettingField {
+  if (definition.secret === true) return { kind: 'secret' }
+
+  const ui = definition.ui
+  if (ui?.options !== undefined) return { kind: 'select', options: ui.options }
+
+  switch (typeof definition.default) {
+    case 'boolean':
+      return { kind: 'boolean' }
+    case 'number':
+      return {
+        kind: 'number',
+        ...(ui?.min === undefined ? {} : { min: ui.min }),
+        ...(ui?.max === undefined ? {} : { max: ui.max }),
+      }
+    default:
+      return ui?.multiline === true ? { kind: 'textarea' } : { kind: 'text' }
+  }
+}
+
+export function secretClearField(key: string): string {
+  return `${key}__clear`
+}
+
+export function coerceFormValue(
+  definition: SettingDefinition,
+  raw: string | undefined,
+  options: { readonly clear?: boolean } = {},
+): unknown {
+  if (typeof definition.default === 'boolean') return raw !== undefined && raw !== ''
+  if (definition.secret === true) {
+    if (options.clear === true) return definition.default
+    if (raw === undefined || raw === '') return undefined
+  }
+  if (raw === undefined) return undefined
+
+  if (typeof definition.default === 'number') {
+    const value = Number(raw)
+    return raw.trim() === '' || Number.isNaN(value) ? raw : value
+  }
+
+  return raw
+}

package/src/index.ts

@@ -0,0 +1,69 @@
+export {
+  type BoardUrlEnvironment,
+  type BoardUrlResolution,
+  type BoardUrlSource,
+  isUsableOrigin,
+  normaliseOrigin,
+  resolveBoardUrl,
+} from './board-url'
+export {
+  isLogoKey,
+  isLogoScheme,
+  LOGO_SCHEMES,
+  type LogoScheme,
+  logoFormat,
+  logoPath,
+} from './branding'
+export {
+  SETTING_DEFINITION_BY_KEY,
+  SETTING_DEFINITIONS,
+  type SettingDefinition,
+  type SettingGroup,
+  type SettingKey,
+  type SettingValue,
+} from './definitions'
+export {
+  coerceFormValue,
+  type SettingField,
+  type SettingOption,
+  secretClearField,
+  settingField,
+} from './fields'
+export { DEFAULT_PRIVACY_POLICY, DEFAULT_TERMS_OF_SERVICE } from './legal'
+export {
+  canSendMail,
+  defaultPort,
+  describeMailConfig,
+  type HttpMailConfig,
+  type LogMailConfig,
+  MAIL_PRESET_BY_ID,
+  MAIL_PRESETS,
+  type MailConfig,
+  type MailEnvironment,
+  type MailPreset,
+  type MailResolution,
+  type MailSecurity,
+  type MailSource,
+  type MailTransport,
+  mailConfigFromEnvironment,
+  mailConfigFromSettings,
+  mailConfigProblems,
+  NO_MAIL,
+  resolveMailConfig,
+  type SmtpMailConfig,
+} from './mail'
+export { isUsableFeedUrl, isUsableIssuer } from './origin'
+export {
+  type PushConfig,
+  type PushProblem,
+  type PushResolution,
+  pushContact,
+  resolvePushConfig,
+} from './push'
+export {
+  type SaveResult,
+  type SettingsRepository,
+  SettingsSnapshot,
+  type SettingsSnapshotOptions,
+  saveSettings,
+} from './store'

package/src/legal.ts

@@ -0,0 +1,117 @@
+export const DEFAULT_TERMS_OF_SERVICE = `## The short version
+
+This community is run by its administrators. These terms are the agreement
+between them and you. By creating an account, and by posting, you accept them.
+
+## Your account
+
+- Give a working e-mail address. It is how the board reaches you about your own
+  account, and how you get back in when you forget your password.
+- Keep your password to yourself. Anything posted from your account is treated
+  as posted by you.
+- One account per person, unless an administrator has agreed otherwise.
+- Do not register on behalf of someone else, or claim to be someone you are not.
+
+## What you post
+
+You keep the rights to what you write. By posting it here you allow this
+community to store it and to show it to whoever can read the forum it is in,
+for as long as the community keeps running.
+
+Do not post anything that is unlawful where this board operates, that harasses
+or threatens another person, that infringes someone else's copyright, that
+exists to advertise, or that deliberately disrupts other people's discussions.
+
+## Moderation
+
+Moderators may edit, move, hide or delete any post, lock any thread, and warn,
+suspend or remove any account. They do not have to ask first, and a decision may
+be made about the effect of a post rather than its intent.
+
+If you think a decision was wrong, say so to the staff rather than in the
+thread — that is the route that can actually change it.
+
+## Ending your membership
+
+You may stop using the board at any time and may ask the administrators to close
+your account. Closing an account does not automatically delete what you have
+already posted: the discussions other members took part in stay readable. If you
+need something specific removed, ask, and the administrators will decide.
+
+## Availability
+
+The board is provided as it is. There is no guarantee that it stays up, that
+nothing is lost, or that it will keep running indefinitely. Keep your own copy
+of anything you cannot afford to lose.
+
+## Changes
+
+These terms can change. Continuing to use the board after a change means you
+accept the version in force at the time you use it.
+
+## Contact
+
+Questions about these terms go to the board's administrators.`
+
+export const DEFAULT_PRIVACY_POLICY = `## What this covers
+
+How this community handles information about the people who use it. The
+administrators of this board decide what happens to that information.
+
+## What is collected
+
+- **What you give us.** Your username, e-mail address, password (stored only as
+  a hash, never as text anyone can read), and anything you choose to put in your
+  profile or your posts.
+- **What using the board records.** The IP address a request came from, the time
+  of it, and the browser it announced itself as — kept so that abuse can be
+  traced and spam refused.
+- **Cookies.** One for your session, so the board knows you are signed in, and
+  ones remembering your preferences. Signing out clears the session cookie.
+
+## What it is used for
+
+Running the board: showing your posts to other members, sending the mail you
+asked for, keeping accounts secure, and dealing with spam and abuse. Nothing
+here is sold, and nothing is handed to advertisers.
+
+## What other people can see
+
+Your username, your profile, your posts, and when you were last active are
+visible to anyone who can read the forum in question — which, on a public forum,
+means anyone at all, including search engines. Your e-mail address and your IP
+address are not shown to other members; administrators and moderators can see
+them as part of moderating.
+
+## Who else is involved
+
+The board runs on servers rented from a hosting provider, and it may send mail
+through a mail provider. Those providers handle the data needed to do their job,
+and nothing further.
+
+If this board offers a "sign in with…" button, choosing it tells that provider
+you have an account here and hands this board the address and display name they
+hold for you. Nothing else passes in either direction, and no member has to use
+one: a password works the same as it always did. A passkey involves nobody but
+you and this board — the key never leaves your device.
+
+## How long it is kept
+
+Your account and your posts are kept while your account exists. Technical logs,
+including IP addresses, are kept only as long as they are useful for security
+and moderation, and then discarded.
+
+## What you can ask for
+
+You can ask the administrators for a copy of what is held about you, for a
+correction to it, or for your account to be closed. Closing an account does not
+by itself delete posts other members replied to; ask if you need something
+specific removed, and it will be considered.
+
+## Changes
+
+This policy can change. The version on this page is the one in force.
+
+## Contact
+
+Questions about your data go to the board's administrators.`

package/src/mail.ts

@@ -0,0 +1,281 @@
+import type { SettingsSnapshot } from './store'
+
+export type MailSecurity = 'tls' | 'starttls' | 'none'
+
+export type MailTransport = 'log' | 'http' | 'smtp'
+
+export interface LogMailConfig {
+  readonly transport: 'log'
+}
+
+export interface HttpMailConfig {
+  readonly transport: 'http'
+  readonly from: string
+  readonly endpoint: string
+  readonly token: string
+}
+
+export interface SmtpMailConfig {
+  readonly transport: 'smtp'
+  readonly from: string
+  readonly host: string
+  readonly port: number
+  readonly security: MailSecurity
+  readonly username: string
+  readonly password: string
+}
+
+export type MailConfig = LogMailConfig | HttpMailConfig | SmtpMailConfig
+
+export const NO_MAIL: LogMailConfig = { transport: 'log' }
+
+export interface MailEnvironment {
+  readonly MAIL_DRIVER?: MailTransport | undefined
+  readonly MAIL_FROM?: string | undefined
+  readonly MAIL_HTTP_ENDPOINT?: string | undefined
+  readonly MAIL_HTTP_TOKEN?: string | undefined
+  readonly MAIL_SMTP_HOST?: string | undefined
+  readonly MAIL_SMTP_PORT?: number | undefined
+  readonly MAIL_SMTP_SECURITY?: MailSecurity | undefined
+  readonly MAIL_SMTP_USERNAME?: string | undefined
+  readonly MAIL_SMTP_PASSWORD?: string | undefined
+}
+
+export type MailSource = 'environment' | 'board'
+
+export interface MailResolution {
+  readonly config: MailConfig
+  readonly source: MailSource
+  readonly problems: readonly string[]
+}
+
+function text(value: string | undefined): string {
+  return (value ?? '').trim()
+}
+
+export function mailConfigFromEnvironment(source: MailEnvironment): MailConfig | null {
+  switch (source.MAIL_DRIVER) {
+    case 'http':
+      return {
+        transport: 'http',
+        from: text(source.MAIL_FROM),
+        endpoint: text(source.MAIL_HTTP_ENDPOINT),
+        token: text(source.MAIL_HTTP_TOKEN),
+      }
+    case 'smtp':
+      return {
+        transport: 'smtp',
+        from: text(source.MAIL_FROM),
+        host: text(source.MAIL_SMTP_HOST),
+        port: source.MAIL_SMTP_PORT ?? defaultPort(source.MAIL_SMTP_SECURITY ?? 'starttls'),
+        security: source.MAIL_SMTP_SECURITY ?? 'starttls',
+        username: text(source.MAIL_SMTP_USERNAME),
+        password: text(source.MAIL_SMTP_PASSWORD),
+      }
+    default:
+      return null
+  }
+}
+
+export function mailConfigFromSettings(settings: SettingsSnapshot): MailConfig {
+  switch (settings.get('mail.transport')) {
+    case 'http':
+      return {
+        transport: 'http',
+        from: text(settings.get('mail.from')),
+        endpoint: text(settings.get('mail.http_endpoint')),
+        token: text(settings.get('mail.http_token')),
+      }
+    case 'smtp':
+      return {
+        transport: 'smtp',
+        from: text(settings.get('mail.from')),
+        host: text(settings.get('mail.smtp_host')),
+        port: settings.get('mail.smtp_port'),
+        security: settings.get('mail.smtp_security') as MailSecurity,
+        username: text(settings.get('mail.smtp_username')),
+        password: text(settings.get('mail.smtp_password')),
+      }
+    default:
+      return NO_MAIL
+  }
+}
+
+export function defaultPort(security: MailSecurity): number {
+  return security === 'tls' ? 465 : 587
+}
+
+export function resolveMailConfig(input: {
+  readonly environment: MailEnvironment
+  readonly settings: SettingsSnapshot
+}): MailResolution {
+  const fromEnvironment = mailConfigFromEnvironment(input.environment)
+  const config = fromEnvironment ?? mailConfigFromSettings(input.settings)
+
+  return {
+    config,
+    source: fromEnvironment === null ? 'board' : 'environment',
+    problems: mailConfigProblems(config),
+  }
+}
+
+export function mailConfigProblems(config: MailConfig): readonly string[] {
+  const problems: string[] = []
+
+  if (config.transport === 'log') return problems
+
+  if (config.from === '') {
+    problems.push('No sender address. Mail needs an address to come from.')
+  }
+
+  if (config.transport === 'http') {
+    if (config.endpoint === '') problems.push('No API endpoint.')
+    if (config.token === '') problems.push('No API key.')
+  }
+
+  if (config.transport === 'smtp') {
+    if (config.host === '') problems.push('No SMTP host.')
+    if (!Number.isInteger(config.port) || config.port < 1 || config.port > 65535) {
+      problems.push('The SMTP port must be between 1 and 65535.')
+    }
+    if (config.username !== '' && config.password === '') {
+      problems.push('An SMTP username was given with no password.')
+    }
+    if (config.username === '' && config.password !== '') {
+      problems.push('An SMTP password was given with no username.')
+    }
+  }
+
+  return problems
+}
+
+export function canSendMail(config: MailConfig): boolean {
+  return config.transport !== 'log' && mailConfigProblems(config).length === 0
+}
+
+export function describeMailConfig(config: MailConfig): string {
+  switch (config.transport) {
+    case 'log':
+      return 'Not sending — messages are written to the server log'
+    case 'http':
+      return `HTTP API at ${hostOf(config.endpoint)}, from ${config.from || '(no address)'}`
+    case 'smtp':
+      return (
+        `SMTP to ${config.host || '(no host)'}:${config.port} (${config.security}), ` +
+        `from ${config.from || '(no address)'}`
+      )
+  }
+}
+
+function hostOf(endpoint: string): string {
+  try {
+    return new URL(endpoint).host
+  } catch {
+    return endpoint === '' ? '(no endpoint)' : endpoint
+  }
+}
+
+export interface MailPreset {
+  readonly id: string
+  readonly label: string
+  readonly transport: 'http' | 'smtp'
+  readonly note: string
+  readonly endpoint?: string
+  readonly host?: string
+  readonly port?: number
+  readonly security?: MailSecurity
+  readonly username?: string
+}
+
+export const MAIL_PRESETS: readonly MailPreset[] = [
+  {
+    id: 'mailbox',
+    label: 'A mailbox I already have (SMTP)',
+    transport: 'smtp',
+    note:
+      'The least work by a distance, if you already receive mail on this domain: ' +
+      'SPF and DKIM are set up already, so there are no DNS records to add. Use ' +
+      'your provider’s SMTP host and an app password — never your login password.',
+    port: 465,
+    security: 'tls',
+  },
+  {
+    id: 'resend-http',
+    label: 'Resend (API)',
+    transport: 'http',
+    endpoint: 'https://api.resend.com/emails',
+    note:
+      'Free for 3,000 messages a month. You must verify your sending domain with ' +
+      'Resend first — until you do, a new account can only mail the address you ' +
+      'signed up with, and every other message is rejected.',
+  },
+  {
+    id: 'resend-smtp',
+    label: 'Resend (SMTP)',
+    transport: 'smtp',
+    host: 'smtp.resend.com',
+    port: 465,
+    security: 'tls',
+    username: 'resend',
+    note:
+      'The same service as the row above, over SMTP. The username is the literal ' +
+      'word “resend” and the password is your API key. Verify your domain first.',
+  },
+  {
+    id: 'brevo',
+    label: 'Brevo (SMTP)',
+    transport: 'smtp',
+    host: 'smtp-relay.brevo.com',
+    port: 587,
+    security: 'starttls',
+    note:
+      'The most generous free tier — around 300 messages a day. Independent ' +
+      'deliverability testing puts it below Postmark and Resend, which matters ' +
+      'most for password resets. Verify your domain first.',
+  },
+  {
+    id: 'postmark',
+    label: 'Postmark (SMTP)',
+    transport: 'smtp',
+    host: 'smtp.postmarkapp.com',
+    port: 587,
+    security: 'starttls',
+    note:
+      'The best-delivering of these and the stingiest — 100 messages a month free, ' +
+      'and an approval step before you can send at all. Username and password are ' +
+      'both the server API token. Verify your domain first.',
+  },
+  {
+    id: 'ses',
+    label: 'Amazon SES (SMTP)',
+    transport: 'smtp',
+    port: 587,
+    security: 'starttls',
+    note:
+      'The cheapest at volume and the most work to start: a new account is in a ' +
+      'sandbox that can only mail verified addresses, and leaving it needs a ' +
+      'support request. The host is email-smtp.<your-region>.amazonaws.com, and ' +
+      'the credentials are SMTP credentials — not your AWS access keys.',
+  },
+  {
+    id: 'smtp',
+    label: 'Any other SMTP server',
+    transport: 'smtp',
+    port: 587,
+    security: 'starttls',
+    note: 'Anything that speaks SMTP, including a relay you run yourself.',
+  },
+  {
+    id: 'http',
+    label: 'Any other JSON API',
+    transport: 'http',
+    note:
+      'Only works for a provider whose API takes Resend’s exact field names — ' +
+      'from, to, subject, text, html, reply_to — with a Bearer token. Postmark and ' +
+      'Mailgun do not; use their SMTP hosts instead.',
+  },
+]
+
+export const MAIL_PRESET_BY_ID: ReadonlyMap<string, MailPreset> = new Map(
+  MAIL_PRESETS.map((preset) => [preset.id, preset]),
+)

package/src/origin.ts

@@ -0,0 +1,52 @@
+export function normaliseOrigin(value: string): string {
+  return value.trim().replace(/\/+$/, '')
+}
+
+export function isUsableIssuer(value: string): boolean {
+  let parsed: URL
+  try {
+    parsed = new URL(normaliseOrigin(value))
+  } catch {
+    return false
+  }
+
+  if (parsed.protocol !== 'https:' && parsed.hostname !== 'localhost') return false
+  if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') return false
+  return parsed.hostname !== '' && parsed.search === '' && parsed.hash === ''
+}
+
+/**
+ * https, or plain http to a loopback address — the same allowance
+ * `allowedRedirectHosts` gives a plugin route, for the same reason: a test
+ * double never gets real TLS, and self-hosting a marketplace mirror should
+ * not have to fake a certificate to be pointed at from a dev or e2e board.
+ */
+export function isUsableFeedUrl(value: string): boolean {
+  let parsed: URL
+  try {
+    parsed = new URL(value)
+  } catch {
+    return false
+  }
+
+  const hostname = parsed.hostname.toLowerCase()
+  const loopback = hostname === '127.0.0.1' || hostname === 'localhost' || hostname === '[::1]'
+  return parsed.protocol === 'https:' || (parsed.protocol === 'http:' && loopback)
+}
+
+export function isUsableOrigin(value: string): boolean {
+  let parsed: URL
+  try {
+    parsed = new URL(normaliseOrigin(value))
+  } catch {
+    return false
+  }
+
+  if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') return false
+  if (parsed.hostname === '') return false
+  return (
+    (parsed.pathname === '' || parsed.pathname === '/') &&
+    parsed.search === '' &&
+    parsed.hash === ''
+  )
+}

package/src/push.ts

@@ -0,0 +1,44 @@
+import { type BoardUrlEnvironment, resolveBoardUrl } from './board-url'
+import type { SettingsSnapshot } from './store'
+
+export interface PushConfig {
+  readonly publicKey: string
+  readonly privateKey: string
+  readonly subject: string
+}
+
+export type PushProblem = 'disabled' | 'no-keys' | 'no-subject'
+
+export type PushResolution =
+  | { readonly config: PushConfig; readonly problem: null }
+  | { readonly config: null; readonly problem: PushProblem }
+
+export function pushContact(input: {
+  readonly environment: BoardUrlEnvironment
+  readonly settings: SettingsSnapshot
+}): string {
+  const stated = input.settings.get('push.contact').trim()
+  if (stated !== '') return stated
+
+  const from = input.settings.get('mail.from').trim()
+  if (from !== '') return `mailto:${from}`
+
+  const { url } = resolveBoardUrl(input)
+  return url.startsWith('https://') ? url : ''
+}
+
+export function resolvePushConfig(input: {
+  readonly environment: BoardUrlEnvironment
+  readonly settings: SettingsSnapshot
+}): PushResolution {
+  if (!input.settings.get('push.enabled')) return { config: null, problem: 'disabled' }
+
+  const publicKey = input.settings.get('push.vapid_public_key').trim()
+  const privateKey = input.settings.get('push.vapid_private_key').trim()
+  if (publicKey === '' || privateKey === '') return { config: null, problem: 'no-keys' }
+
+  const subject = pushContact(input)
+  if (subject === '') return { config: null, problem: 'no-subject' }
+
+  return { config: { publicKey, privateKey, subject }, problem: null }
+}