@exvio/os-backend-core 0.4.0

package/src/auth/redaction.ts

@@ -0,0 +1,142 @@
+const REDACTED = '[REDACTED]'
+const SENSITIVE_KEY = /^(?:authorization|proxy[_-]?authorization|authorization[_-]?code|cookie|set[_-]?cookie|password(?:[_-]?hash)?|(?:current|new|confirm|old)[_-]?password|passcode|secret|token|state|ticket|ott|api[_-]?key|credential|verifier|(?:password|token|secret|credential|api[_-]?key)[_-]?hash|(?:x[_-]?)?visitor[_-]?id|session[_-]?id|client[_-]?secret|code[_-]?verifier|oauth[_-]?state|(?:access|refresh|id|reset|challenge|backup|recovery|csrf|oauth|one[_-]?time|exchange)[_-]?(?:token|secret|code|verifier|ticket)|raw|cause)$/iu
+const BEARER_VALUE = /\b(Bearer|Basic)\s+[^\s,;]+/giu
+const QUERY_SECRET = /([?&#](?:t|access[_-]?token|refresh[_-]?token|id[_-]?token|reset[_-]?token|challenge[_-]?token|visitor[_-]?id|code[_-]?verifier|token|code|state|secret|api[_-]?key)=)[^&#\s]*/giu
+/* Generic auth namespaces only. An application's own credential-bearing
+   prefixes are passed to redactAuthStorageKey(); the package does not publish
+   any product's storage layout. */
+const AUTH_STORAGE_KEY_PREFIXES = Object.freeze([
+  'session:',
+  'oauth:pkce:',
+  'oauth:state:',
+  'auth:oauth-state:',
+  'auth:oauth-browser-exchange:',
+  'passkey:auth:',
+  'passkey:reg:',
+  'webauthn:challenge:',
+  '2fa:challenge:',
+  'password:reset:',
+  'password_reset:',
+] as const)
+
+function redactText(text: string, secrets: readonly string[]): string {
+  let redacted = text
+    .replace(BEARER_VALUE, '$1 [REDACTED]')
+    .replace(QUERY_SECRET, '$1[REDACTED]')
+  for (const secret of secrets) {
+    if (secret.length > 0) redacted = redacted.replaceAll(secret, REDACTED)
+  }
+  return redacted
+}
+
+/**
+ * Redact the credential-bearing suffix of a Redis/storage key while retaining
+ * enough namespace information for operational diagnostics.
+ *
+ * `prefixes` adds the application's own credential-bearing namespaces to the
+ * built-in generic set. Application key namespaces are supported, so both
+ * `session:<secret>` and `APP:session:<secret>` become safe to log. A key that
+ * matches no prefix is returned unchanged.
+ */
+export function redactAuthStorageKey(key: string, prefixes: readonly string[] = []): string {
+  if (typeof key !== 'string' || key.length === 0) return REDACTED
+
+  const normalized = key.toLowerCase()
+  let redactionAt = Number.POSITIVE_INFINITY
+  for (const prefix of [...AUTH_STORAGE_KEY_PREFIXES, ...normalizePrefixes(prefixes)]) {
+    let index = normalized.indexOf(prefix)
+    while (index >= 0) {
+      const isSegmentBoundary = index === 0 || normalized[index - 1] === ':'
+      if (isSegmentBoundary) {
+        redactionAt = Math.min(redactionAt, index + prefix.length)
+        break
+      }
+      index = normalized.indexOf(prefix, index + 1)
+    }
+  }
+
+  return Number.isFinite(redactionAt)
+    ? `${key.slice(0, redactionAt)}${REDACTED}`
+    : key
+}
+
+function normalizePrefixes(prefixes: readonly string[]): readonly string[] {
+  return prefixes
+    .filter(prefix => typeof prefix === 'string' && prefix.trim().length > 0)
+    .map((prefix) => {
+      const lower = prefix.trim().toLowerCase()
+      return lower.endsWith(':') ? lower : `${lower}:`
+    })
+}
+
+/**
+ * Return a detached, JSON-safe value suitable for auth diagnostics. Sensitive
+ * fields, raw causes, known secret values, and credentials in URLs/headers are
+ * removed. The original object is never mutated.
+ */
+export function redactAuthSecrets(
+  value: unknown,
+  secrets: readonly string[] = [],
+): unknown {
+  const secretSnapshot = Object.freeze([...secrets].filter(secret => typeof secret === 'string'))
+  const seen = new WeakSet<object>()
+
+  const visit = (current: unknown, depth: number): unknown => {
+    if (depth > 12) return '[MAX_DEPTH]'
+    if (current === null || current === undefined || typeof current === 'boolean') return current
+    if (typeof current === 'string') return redactText(current, secretSnapshot)
+    if (typeof current === 'number') return Number.isFinite(current) ? current : String(current)
+    if (typeof current === 'bigint') return current.toString()
+    if (typeof current === 'symbol' || typeof current === 'function') return REDACTED
+    if (current instanceof Date) {
+      return Number.isNaN(current.valueOf()) ? REDACTED : current.toISOString()
+    }
+    if (current instanceof Error) {
+      let name = 'Error'
+      try {
+        if (/^[A-Za-z][A-Za-z0-9]{0,63}Error$/u.test(current.name)) name = current.name
+      } catch {
+        // Even Error.name can be replaced with an accessor. Do not invoke it again.
+      }
+      return {
+        name,
+        // An arbitrary Error message has no safe schema. It can include a
+        // database URL, provider response, reset token, or other unknown secret.
+        message: REDACTED,
+      }
+    }
+    if (typeof current !== 'object') return REDACTED
+    if (seen.has(current)) return '[CIRCULAR]'
+    seen.add(current)
+
+    let descriptors: Record<string, PropertyDescriptor>
+    try {
+      descriptors = Object.getOwnPropertyDescriptors(current)
+    } catch {
+      return REDACTED
+    }
+
+    if (Array.isArray(current)) {
+      const length = Math.min(current.length, 1_000)
+      const output: unknown[] = []
+      for (let index = 0; index < length; index += 1) {
+        const descriptor = descriptors[String(index)]
+        output.push(descriptor && 'value' in descriptor
+          ? visit(descriptor.value, depth + 1)
+          : REDACTED)
+      }
+      if (current.length > length) output.push('[TRUNCATED]')
+      return output
+    }
+
+    const output: Record<string, unknown> = Object.create(null) as Record<string, unknown>
+    for (const [key, descriptor] of Object.entries(descriptors)) {
+      output[key] = SENSITIVE_KEY.test(key) || !('value' in descriptor)
+        ? REDACTED
+        : visit(descriptor.value, depth + 1)
+    }
+    return output
+  }
+
+  return visit(value, 0)
+}

package/src/auth/session.ts

@@ -0,0 +1,106 @@
+import { AuthError } from './errors.ts'
+import type { SessionTtlInput } from './types.ts'
+
+const SESSION_BEARER_TOKEN_PATTERN = /^sat_v1_[A-Za-z0-9_-]{43}$/
+// Compatibility is deliberately limited to the UUIDv7 values issued by the
+// pre-Core session runtime. Broad base64url input would also accept other auth
+// artefacts (OAuth state, management handles, one-time tickets) as bearers.
+const LEGACY_SESSION_BEARER_TOKEN_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/iu
+const SESSION_HANDLE_PATTERN = /^smh_v1_[A-Za-z0-9_-]{43}$/
+
+function base64Url(bytes: Uint8Array): string {
+  let binary = ''
+  for (const byte of bytes) binary += String.fromCharCode(byte)
+  return btoa(binary).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/u, '')
+}
+
+function assertSessionToken(token: string): void {
+  if (!isSessionBearerToken(token)) {
+    throw new AuthError({ code: 'invalid_session_token', status: 400 })
+  }
+}
+
+export function createSecureAuthToken(byteLength = 32): string {
+  if (!Number.isSafeInteger(byteLength) || byteLength < 24 || byteLength > 128) {
+    throw new AuthError({ code: 'invalid_input', status: 400 })
+  }
+  return base64Url(crypto.getRandomValues(new Uint8Array(byteLength)))
+}
+
+/** Issue a bearer in a namespace that cannot be confused with other auth tokens. */
+export function createSessionBearerToken(): string {
+  return `sat_v1_${createSecureAuthToken()}`
+}
+
+/**
+ * Return whether `token` is a session bearer issued by this runtime.
+ *
+ * UUIDv7 is accepted only as a temporary compatibility format for sessions
+ * created before the `sat_v1_` namespace was introduced.
+ */
+export function isSessionBearerToken(token: unknown): token is string {
+  return typeof token === 'string'
+    && (SESSION_BEARER_TOKEN_PATTERN.test(token)
+      || LEGACY_SESSION_BEARER_TOKEN_PATTERN.test(token))
+}
+
+export async function createSessionManagementHandle(token: string): Promise<string> {
+  assertSessionToken(token)
+  const digest = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(token))
+  return `smh_v1_${base64Url(new Uint8Array(digest))}`
+}
+
+function constantTimeEqual(left: string, right: string): boolean {
+  if (left.length !== right.length) return false
+  let difference = 0
+  for (let index = 0; index < left.length; index += 1) {
+    difference |= left.charCodeAt(index) ^ right.charCodeAt(index)
+  }
+  return difference === 0
+}
+
+export async function matchesSessionManagementHandle(
+  token: string,
+  handle: string,
+): Promise<boolean> {
+  assertSessionToken(token)
+  if (typeof handle !== 'string' || !SESSION_HANDLE_PATTERN.test(handle)) {
+    throw new AuthError({ code: 'invalid_session_handle', status: 400 })
+  }
+  return constantTimeEqual(await createSessionManagementHandle(token), handle)
+}
+
+export function remainingSessionTtl(input: SessionTtlInput): number {
+  if (!input || typeof input !== 'object') {
+    throw new AuthError({ code: 'invalid_input', status: 400 })
+  }
+  const nowMs = input.nowMs ?? Date.now()
+  const values = [
+    input.createdAtMs,
+    input.lastActiveAtMs,
+    input.absoluteTtlSeconds,
+    input.inactivityTtlSeconds,
+    nowMs,
+  ]
+  if (values.some(value => !Number.isSafeInteger(value) || value < 0)) {
+    throw new AuthError({ code: 'invalid_input', status: 400 })
+  }
+  if (
+    input.createdAtMs < 0
+    || input.lastActiveAtMs < input.createdAtMs
+    || !Number.isSafeInteger(input.absoluteTtlSeconds)
+    || input.absoluteTtlSeconds <= 0
+    || !Number.isSafeInteger(input.inactivityTtlSeconds)
+    || input.inactivityTtlSeconds <= 0
+  ) {
+    throw new AuthError({ code: 'invalid_input', status: 400 })
+  }
+
+  const absoluteExpiry = input.createdAtMs + (input.absoluteTtlSeconds * 1_000)
+  const inactivityExpiry = input.lastActiveAtMs + (input.inactivityTtlSeconds * 1_000)
+  if (!Number.isSafeInteger(absoluteExpiry) || !Number.isSafeInteger(inactivityExpiry)) {
+    throw new AuthError({ code: 'invalid_input', status: 400 })
+  }
+  const remainingMs = Math.min(absoluteExpiry, inactivityExpiry) - nowMs
+  return remainingMs <= 0 ? 0 : Math.ceil(remainingMs / 1_000)
+}

package/src/auth/types.ts

@@ -0,0 +1,72 @@
+export type LoginMode = 'hub_managed' | 'standalone' | 'hybrid'
+
+export type LoginSurface =
+  | 'email'
+  | 'google'
+  | 'microsoft'
+  | 'passkey'
+  | 'hub_ott'
+
+export type LoginPhase = 'start' | 'callback' | 'finish'
+
+export interface LoginPolicyCheck {
+  readonly surface: LoginSurface
+  readonly phase: LoginPhase
+}
+
+export interface LoginPolicy {
+  readonly mode: LoginMode
+  readonly enabledSurfaces: readonly LoginSurface[]
+  allows(check: LoginPolicyCheck): boolean
+  assertAllowed(check: LoginPolicyCheck): void
+}
+
+/**
+ * The backing implementation MUST make `take` an atomic read-and-delete.
+ * A GET followed by DEL does not satisfy this contract.
+ */
+export interface OneTimeAuthStore {
+  put(key: string, value: string, ttlSeconds: number): Promise<void>
+  take(key: string): Promise<string | null>
+}
+
+export interface OAuthStateIssueInput {
+  readonly tenantId: number
+  readonly provider: string
+  readonly redirectUri: string
+  readonly verifier: string
+  readonly initiatingSessionId?: string
+  readonly returnTo?: string
+}
+
+export interface OAuthStateConsumeInput {
+  readonly state: string
+  readonly tenantId: number
+  readonly provider: string
+  readonly redirectUri: string
+  readonly initiatingSessionId?: string
+}
+
+export interface OAuthStatePayload {
+  readonly tenantId: number
+  readonly provider: string
+  readonly redirectUri: string
+  readonly verifier: string
+  readonly initiatingSessionId?: string
+  readonly returnTo?: string
+  readonly issuedAt: number
+  readonly expiresAt: number
+}
+
+export interface OAuthStateManager {
+  issue(input: OAuthStateIssueInput): Promise<string>
+  consume(input: OAuthStateConsumeInput): Promise<OAuthStatePayload>
+}
+
+export interface SessionTtlInput {
+  readonly createdAtMs: number
+  readonly lastActiveAtMs: number
+  readonly absoluteTtlSeconds: number
+  readonly inactivityTtlSeconds: number
+  readonly nowMs?: number
+}

package/src/changelog/catalogue.ts

@@ -0,0 +1,140 @@
+import { createAcceptLanguageResolver } from './locale.ts'
+import { ChangelogError } from './types.ts'
+import type {
+  ChangelogCatalogue,
+  ChangelogCatalogueOptions,
+  ChangelogEntry,
+  LocalizedChangelogEntry,
+} from './types.ts'
+
+const VERSION_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._:-]*$/
+
+export function createChangelogCatalogue<Locale extends string>(
+  options: ChangelogCatalogueOptions<Locale>,
+): ChangelogCatalogue<Locale> {
+  validateOptions(options)
+  const locales = Object.freeze([...options.locales])
+  const localeSet = new Set<string>(locales)
+  const entries = Object.freeze(options.entries.map(entry => snapshotEntry(entry, locales, options)))
+  if (new Set(entries.map(entry => entry.version)).size !== entries.length) {
+    invalidCatalogue('Changelog versions must be unique')
+  }
+  const latest = entries[0]!
+  const knownVersions = new Set(entries.map(entry => entry.version))
+  const resolveLocale = createAcceptLanguageResolver({
+    locales,
+    defaultLocale: options.defaultLocale,
+    ...(options.languageTags ? { languageTags: options.languageTags } : {}),
+  })
+
+  const isLocale = (value: unknown): value is Locale => (
+    typeof value === 'string' && localeSet.has(value)
+  )
+
+  const bodyFor = (
+    entry: ChangelogEntry<Locale>,
+    locale: Locale,
+  ): { body: string; locale: Locale } => {
+    if (!isLocale(locale)) invalidCatalogue('Changelog locale is not supported')
+    const requested = entry.body[locale]
+    if (nonEmpty(requested)) return { body: requested, locale }
+    const fallback = entry.body[options.defaultLocale]
+    if (nonEmpty(fallback)) return { body: fallback, locale: options.defaultLocale }
+    for (const candidate of locales) {
+      const body = entry.body[candidate]
+      if (nonEmpty(body)) return { body, locale: candidate }
+    }
+    invalidCatalogue('Changelog entry has no localized body')
+  }
+
+  const localize = (locale: Locale): readonly LocalizedChangelogEntry<Locale>[] => {
+    if (!isLocale(locale)) invalidCatalogue('Changelog locale is not supported')
+    return Object.freeze(entries.map((entry) => {
+      const localized = bodyFor(entry, locale)
+      return Object.freeze({
+        version: entry.version,
+        date: entry.date,
+        title: entry.title,
+        body: localized.body,
+        locale: localized.locale,
+      })
+    }))
+  }
+
+  return Object.freeze({
+    entries,
+    latest,
+    locales,
+    defaultLocale: options.defaultLocale,
+    maxVersionLength: options.maxVersionLength,
+    resolveLocale,
+    isLocale,
+    isKnownVersion: (version: string) => knownVersions.has(version),
+    bodyFor,
+    localize,
+  })
+}
+
+function validateOptions<Locale extends string>(options: ChangelogCatalogueOptions<Locale>): void {
+  if (
+    !options
+    || !Array.isArray(options.entries)
+    || options.entries.length === 0
+    || !Array.isArray(options.locales)
+    || options.locales.length === 0
+    || new Set(options.locales).size !== options.locales.length
+    || !options.locales.includes(options.defaultLocale)
+    || !Number.isSafeInteger(options.maxVersionLength)
+    || options.maxVersionLength <= 0
+    || options.maxVersionLength > 256
+  ) invalidCatalogue('Changelog catalogue configuration is invalid')
+}
+
+function snapshotEntry<Locale extends string>(
+  entry: ChangelogEntry<Locale>,
+  locales: readonly Locale[],
+  options: ChangelogCatalogueOptions<Locale>,
+): ChangelogEntry<Locale> {
+  if (
+    !entry
+    || typeof entry.version !== 'string'
+    || entry.version.length > options.maxVersionLength
+    || !VERSION_PATTERN.test(entry.version)
+    || typeof entry.date !== 'string'
+    || entry.date.trim().length === 0
+    || entry.date.length > 256
+    || typeof entry.title !== 'string'
+    || entry.title.trim().length === 0
+    || entry.title.length > 512
+    || !entry.body
+    || typeof entry.body !== 'object'
+    || Array.isArray(entry.body)
+  ) invalidCatalogue('Changelog entry is invalid')
+
+  const body: Partial<Record<Locale, string>> = Object.create(null) as Partial<Record<Locale, string>>
+  for (const locale of locales) {
+    const value = entry.body[locale]
+    if (value !== undefined) {
+      if (!nonEmpty(value)) invalidCatalogue('Changelog body is invalid')
+      body[locale] = value
+    }
+  }
+  if (!nonEmpty(body[options.defaultLocale])) {
+    invalidCatalogue('Changelog entry is missing its default-locale body')
+  }
+
+  return Object.freeze({
+    version: entry.version,
+    date: entry.date,
+    title: entry.title,
+    body: Object.freeze(body),
+  })
+}
+
+function nonEmpty(value: unknown): value is string {
+  return typeof value === 'string' && value.trim().length > 0
+}
+
+function invalidCatalogue(message: string): never {
+  throw new ChangelogError({ code: 'invalid_catalogue', message })
+}

package/src/changelog/index.ts

@@ -0,0 +1,5 @@
+export { createChangelogCatalogue } from './catalogue.ts'
+export { createAcceptLanguageResolver } from './locale.ts'
+export { createChangelogService } from './service.ts'
+export type * from './types.ts'
+export { ChangelogError } from './types.ts'

package/src/changelog/locale.ts

@@ -0,0 +1,122 @@
+import { ChangelogError } from './types.ts'
+import type {
+  AcceptLanguageResolver,
+  AcceptLanguageResolverOptions,
+} from './types.ts'
+
+interface LanguagePreference {
+  readonly tag: string
+  readonly quality: number
+  readonly order: number
+}
+
+/** RFC-style weighted negotiation mapped onto application-owned locale keys. */
+export function createAcceptLanguageResolver<Locale extends string>(
+  options: AcceptLanguageResolverOptions<Locale>,
+): AcceptLanguageResolver<Locale> {
+  const locales = validateLocales(options.locales, options.defaultLocale)
+  const supported = new Set<string>(locales)
+  const aliases = new Map<string, Locale>()
+
+  for (const locale of locales) aliases.set(locale.toLowerCase(), locale)
+  for (const [rawTag, locale] of Object.entries(options.languageTags ?? {})) {
+    const tag = normalizeLanguageTag(rawTag)
+    if (!tag || !supported.has(locale)) invalidLocale()
+    const existing = aliases.get(tag)
+    if (existing !== undefined && existing !== locale) invalidLocale()
+    aliases.set(tag, locale)
+  }
+
+  return (acceptLanguage?: string | null): Locale => {
+    if (typeof acceptLanguage !== 'string' || !acceptLanguage || acceptLanguage.length > 4_096) {
+      return options.defaultLocale
+    }
+    const preferences = parseAcceptLanguage(acceptLanguage)
+    const explicitQuality = new Map<Locale, number>()
+    for (const preference of preferences) {
+      if (preference.tag === '*') continue
+      const locale = resolveTag(preference.tag, aliases)
+      if (locale !== undefined) {
+        explicitQuality.set(locale, Math.max(explicitQuality.get(locale) ?? 0, preference.quality))
+      }
+    }
+    for (const preference of preferences) {
+      if (preference.quality === 0) continue
+      if (preference.tag === '*') {
+        const wildcard = locales.find(locale => !explicitQuality.has(locale))
+        if (wildcard !== undefined) return wildcard
+        continue
+      }
+      const matched = resolveTag(preference.tag, aliases)
+      if (matched !== undefined && explicitQuality.get(matched) !== 0) return matched
+    }
+    if (explicitQuality.get(options.defaultLocale) === 0) {
+      return locales.find(locale => explicitQuality.get(locale) !== 0) ?? options.defaultLocale
+    }
+    return options.defaultLocale
+  }
+}
+
+function resolveTag<Locale extends string>(
+  tag: string,
+  aliases: ReadonlyMap<string, Locale>,
+): Locale | undefined {
+  let candidate = tag
+  while (candidate) {
+    const matched = aliases.get(candidate)
+    if (matched !== undefined) return matched
+    const separator = candidate.lastIndexOf('-')
+    if (separator < 0) break
+    candidate = candidate.slice(0, separator)
+  }
+  return undefined
+}
+
+function validateLocales<Locale extends string>(
+  values: readonly Locale[],
+  defaultLocale: Locale,
+): readonly Locale[] {
+  if (
+    !Array.isArray(values)
+    || values.length === 0
+    || values.some(value => typeof value !== 'string' || value.trim() !== value || value.length === 0)
+    || new Set(values).size !== values.length
+    || new Set(values.map(value => value.toLowerCase())).size !== values.length
+    || !values.includes(defaultLocale)
+  ) invalidLocale()
+  return [...values]
+}
+
+function parseAcceptLanguage(header: string): LanguagePreference[] {
+  const preferences: LanguagePreference[] = []
+  for (const [order, rawPart] of header.split(',').entries()) {
+    const segments = rawPart.trim().split(';')
+    const tag = normalizeLanguageTag(segments.shift() ?? '')
+    if (!tag) continue
+    let quality = 1
+    let valid = true
+    for (const parameter of segments) {
+      const match = /^q\s*=\s*(0(?:\.\d{0,3})?|1(?:\.0{0,3})?)$/i.exec(parameter.trim())
+      if (!match) {
+        valid = false
+        break
+      }
+      quality = Number(match[1])
+    }
+    if (valid) preferences.push({ tag, quality, order })
+  }
+  return preferences.sort((left, right) => right.quality - left.quality || left.order - right.order)
+}
+
+function normalizeLanguageTag(value: string): string | null {
+  const normalized = value.trim().toLowerCase()
+  if (normalized === '*') return normalized
+  return /^[a-z]{1,8}(?:-[a-z0-9]{1,8})*$/.test(normalized) ? normalized : null
+}
+
+function invalidLocale(): never {
+  throw new ChangelogError({
+    code: 'invalid_locale',
+    message: 'Changelog locale configuration is invalid',
+  })
+}