@crombolo/auth 0.0.0-stage → 0.9.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kineco
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/NOTICE

@@ -0,0 +1,69 @@
+crombolo
+Copyright (c) 2026 Kineco
+
+This product includes third-party software. crombolo is an independent project.
+It is not affiliated with, endorsed by, or sponsored by Umbraco A/S, which owns
+the Umbraco trademark.
+
+There are three places third-party material is redistributed, rather than merely
+depended on:
+
+  @crombolo/backoffice-dist   the built Umbraco backoffice and the browser
+                              packages bundled into it, produced by
+                              `bun run vendor:backoffice`
+  @crombolo/backoffice-dist   three CSS files copied unmodified from the Umbraco
+                              client source tree
+  @crombolo/contracts         the Umbraco Management API OpenAPI document,
+                              copied unmodified
+
+No Umbraco trademark is redistributed. The Umbraco wordmark, the "U" roundel
+favicon and the installer illustration are deliberately not carried in this
+repository: MIT grants copyright permission and says nothing about trademarks, so
+crombolo's own marks are served at those paths instead. See `BRANDED_ASSETS` in
+`@crombolo/backoffice-host`.
+
+The Umbraco backoffice
+----------------------
+@umbraco-cms/backoffice 18.2.0 — MIT — https://github.com/umbraco/Umbraco-CMS
+@umbraco-ui/uui 2.0.2 — MIT — https://github.com/umbraco/Umbraco.UI
+
+Static files from the Umbraco client source tree
+------------------------------------------------
+css/umb-css.css, css/rte-content.css, css/umbraco-blockgridlayout.css
+  — copied unmodified from Umbraco-CMS release-18.2.0 — MIT
+  — https://github.com/umbraco/Umbraco-CMS
+Shipped in @crombolo/backoffice-dist under `upstream-static/`.
+
+`rte-content.css` itself carries Tiptap's default editor styles, copied from
+tiptap v2.11.7 (MIT); the file records this in its own header.
+
+The Umbraco Management API contract
+-----------------------------------
+OpenApi.json — copied unmodified from Umbraco-CMS release-18.2.0
+  (src/Umbraco.Cms.Api.Management/OpenApi.json) — MIT
+  — https://github.com/umbraco/Umbraco-CMS
+Shipped in @crombolo/contracts, which also ships the TypeScript types generated
+from it.
+
+Browser runtime dependencies bundled into the backoffice build
+--------------------------------------------------------------
+@heximal/expressions 0.1.5 — BSD-3-Clause
+@microsoft/signalr 10.0.11 — MIT
+@tiptap/* 3.31.3 — MIT
+diff 9.0.0 — BSD-3-Clause
+dompurify 3.4.16 — Apache-2.0, elected from "MPL-2.0 OR Apache-2.0"
+element-internals-polyfill 3.0.2 — MIT
+lit 3.3.3 — BSD-3-Clause
+luxon 3.7.2 — MIT
+marked 18.0.14 — MIT
+monaco-editor 0.57.0 — MIT
+rxjs 7.8.2 — Apache-2.0
+uuid 14.0.2 — MIT
+
+dompurify is offered under either licence; Apache-2.0 is elected here, so no
+MPL-2.0 obligation attaches to the copy bundled into the backoffice build. Of the
+Apache-2.0 packages above, none ships a NOTICE file of its own, so Apache-2.0
+section 4(d) adds nothing to this file.
+
+Each package's own licence text ships inside its npm distribution and applies
+unchanged to the copies bundled here.

package/package.json

@@ -1,6 +1,34 @@
 {
   "name": "@crombolo/auth",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.9.1",
+  "description": "OAuth2 authorization server, password hashing, cookies and member tickets for crombolo.",
+  "license": "MIT",
+  "author": "Crombolo",
+  "homepage": "https://github.com/kineco-au/crombolo-cms#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kineco-au/crombolo-cms.git",
+    "directory": "packages/auth"
+  },
+  "bugs": {
+    "url": "https://github.com/kineco-au/crombolo-cms/issues"
+  },
+  "engines": {
+    "bun": ">=1.3.0"
+  },
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "files": [
+    "src",
+    "NOTICE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@crombolo/core": "0.9.1",
+    "@crombolo/data": "0.9.1"
+  }
+}

package/src/admin.ts

@@ -0,0 +1,48 @@
+/**
+ * Administrator account maintenance.
+ *
+ * A seeded password is printed once, on the run that creates the account, and
+ * seeding is idempotent — so without this there is no way back into a database
+ * whose generated password has scrolled away.
+ */
+import { hashPassword, passwordConfigJson, verifyPassword } from './password.ts'
+import { generateToken } from './pkce.ts'
+import type { AuthStore } from './store.ts'
+
+export interface EnsuredAdmin {
+  login: string
+  password: string
+  /** False when the account already existed and only its password was replaced. */
+  created: boolean
+  /** Sessions invalidated by the password change. */
+  sessionsEnded: number
+}
+
+/** A readable but high-entropy password for local development. */
+export function generatePassword(): string {
+  return generateToken(12).replaceAll('-', '').replaceAll('_', '').slice(0, 16)
+}
+
+/**
+ * Guarantees that `login` can sign in with the returned password, clearing any
+ * lockout on the way. A changed password ends existing sessions, because a change
+ * that leaves old tokens working is not a change; an unchanged one keeps them, so
+ * restarting with a configured password does not sign editors out.
+ */
+export async function resetAdminPassword(
+  store: AuthStore,
+  login: string,
+  password = generatePassword(),
+): Promise<EnsuredAdmin | undefined> {
+  const user = await store.findUserByLogin(login)
+  if (!user) return undefined
+
+  await store.enable(user.id)
+  if (await verifyPassword(password, user.passwordHash))
+    return { login: user.login, password, created: false, sessionsEnded: 0 }
+
+  await store.setPassword(user.id, await hashPassword(password), passwordConfigJson())
+  const sessionsEnded = await store.endAllSessionsForUser(user.id)
+
+  return { login: user.login, password, created: false, sessionsEnded }
+}

package/src/cookies.ts

@@ -0,0 +1,91 @@
+/**
+ * Cookie handling for reference tokens.
+ *
+ * Umbraco v17+ never returns real token values to the browser: the token
+ * endpoint's JSON body carries `[redacted]`, and the real values live in
+ * `__Host-`-prefixed httpOnly cookies. The client sends `credentials: include`
+ * and `refresh_token=[redacted]`, and the server substitutes the real value.
+ *
+ * The `__Host-` prefix requires Secure and `Path=/` with no Domain. Browsers
+ * treat http://localhost as a secure context, so it works in local development,
+ * but a site served over plain http on another hostname must drop the prefix —
+ * hence `securePrefix`.
+ */
+export const REDACTED = '[redacted]'
+
+export interface CookieNames {
+  accessToken: string
+  refreshToken: string
+  session: string
+}
+
+export interface CookieOptions {
+  /** Distinguishes cookies when several sites share a host. */
+  siteName: string
+  /** False drops the `__Host-` prefix and the Secure flag, for plain-http dev. */
+  securePrefix: boolean
+}
+
+export function cookieNames(options: CookieOptions): CookieNames {
+  const prefix = options.securePrefix ? '__Host-' : ''
+  return {
+    accessToken: `${prefix}umbAccessToken${options.siteName}`,
+    refreshToken: `${prefix}umbRefreshToken${options.siteName}`,
+    session: `${prefix}umbSession${options.siteName}`,
+  }
+}
+
+export function parseCookies(header: string | null): Map<string, string> {
+  const out = new Map<string, string>()
+  if (!header) return out
+  for (const part of header.split(';')) {
+    const index = part.indexOf('=')
+    if (index < 1) continue
+    const name = part.slice(0, index).trim()
+    const value = part.slice(index + 1).trim()
+    if (name) out.set(name, decodeURIComponent(value))
+  }
+  return out
+}
+
+export function readCookie(request: Request, name: string): string | undefined {
+  return parseCookies(request.headers.get('cookie')).get(name)
+}
+
+export interface SetCookieInit {
+  name: string
+  value: string
+  maxAgeSeconds?: number
+  secure: boolean
+  /** Session cookies are scoped to the backoffice; tokens must be Path=/ for `__Host-`. */
+  path?: string
+}
+
+export function serializeCookie(init: SetCookieInit): string {
+  const parts = [
+    `${init.name}=${encodeURIComponent(init.value)}`,
+    `Path=${init.path ?? '/'}`,
+    'HttpOnly',
+    'SameSite=Lax',
+  ]
+  if (init.secure) parts.push('Secure')
+  if (init.maxAgeSeconds !== undefined) parts.push(`Max-Age=${Math.max(0, init.maxAgeSeconds)}`)
+  return parts.join('; ')
+}
+
+export function expireCookie(name: string, secure: boolean, path = '/'): string {
+  return serializeCookie({ name, value: '', maxAgeSeconds: 0, secure, path })
+}
+
+/**
+ * Replaces a token value the client sent as `[redacted]` with the real one from
+ * the cookie. A value that is not the redaction placeholder is returned as-is, so
+ * a non-browser client can still present a real token.
+ */
+export function resolveRedacted(
+  submitted: string | null | undefined,
+  cookieValue: string | undefined,
+): string | undefined {
+  if (submitted && submitted !== REDACTED) return submitted
+  return cookieValue
+}

package/src/index.ts

@@ -0,0 +1,8 @@
+export * from './admin.ts'
+export * from './cookies.ts'
+export * from './member-session.ts'
+export * from './password.ts'
+export * from './pkce.ts'
+export * from './routes.ts'
+export * from './service.ts'
+export * from './store.ts'

package/src/member-session.ts

@@ -0,0 +1,94 @@
+/**
+ * The cookie a signed-in member carries on the front end.
+ *
+ * Umbraco authenticates members with ASP.NET Identity's application cookie, and
+ * revokes one by rotating the member's security stamp. This is the same design
+ * without the framework: a signed ticket naming the member, its expiry and the
+ * stamp it was issued against. Nothing is stored server side, so a load-balanced
+ * set needs only the shared signing key — and because the stamp is checked on
+ * every request, changing a password or locking an account ends every session it
+ * had, immediately.
+ *
+ * The ticket is signed, not encrypted: it carries no secret, and a member reading
+ * their own key learns nothing. Tampering is what matters, and HMAC-SHA256 over
+ * the payload is what stops it.
+ */
+const ENCODER = new TextEncoder()
+
+export interface MemberTicket {
+  /** The member's key. */
+  id: string
+  /** The security stamp the ticket was issued against. */
+  stamp: string
+  /** Seconds since the epoch. */
+  expires: number
+}
+
+const base64url = (bytes: Uint8Array): string =>
+  btoa(String.fromCharCode(...bytes))
+    .replaceAll('+', '-')
+    .replaceAll('/', '_')
+    .replace(/=+$/, '')
+
+const fromBase64url = (value: string): Uint8Array => {
+  const padded = value.replaceAll('-', '+').replaceAll('_', '/')
+  const binary = atob(padded + '='.repeat((4 - (padded.length % 4)) % 4))
+  return Uint8Array.from(binary, (c) => c.charCodeAt(0))
+}
+
+async function key(secret: string): Promise<CryptoKey> {
+  return crypto.subtle.importKey(
+    'raw',
+    ENCODER.encode(secret),
+    { name: 'HMAC', hash: 'SHA-256' },
+    false,
+    ['sign', 'verify'],
+  )
+}
+
+/** A signed ticket: `<payload>.<signature>`, both base64url. */
+export async function signMemberTicket(secret: string, ticket: MemberTicket): Promise<string> {
+  const payload = base64url(ENCODER.encode(JSON.stringify(ticket)))
+  const signature = await crypto.subtle.sign('HMAC', await key(secret), ENCODER.encode(payload))
+  return `${payload}.${base64url(new Uint8Array(signature))}`
+}
+
+/**
+ * Reads a ticket, or undefined when it is malformed, unsigned by us, or expired.
+ * Whether the stamp still matches is the caller's business — only it can look
+ * the member up.
+ */
+export async function readMemberTicket(
+  secret: string,
+  value: string | undefined,
+  now: Date = new Date(),
+): Promise<MemberTicket | undefined> {
+  if (!value) return undefined
+  const [payload, signature] = value.split('.')
+  if (!payload || !signature) return undefined
+  let valid = false
+  try {
+    valid = await crypto.subtle.verify(
+      'HMAC',
+      await key(secret),
+      fromBase64url(signature) as unknown as ArrayBuffer,
+      ENCODER.encode(payload),
+    )
+  } catch {
+    return undefined
+  }
+  if (!valid) return undefined
+  try {
+    const parsed = JSON.parse(new TextDecoder().decode(fromBase64url(payload))) as MemberTicket
+    if (typeof parsed?.id !== 'string' || typeof parsed?.expires !== 'number') return undefined
+    if (parsed.expires * 1000 <= now.getTime()) return undefined
+    return parsed
+  } catch {
+    return undefined
+  }
+}
+
+/** The cookie name, alongside the backoffice's own so the two never collide. */
+export function memberCookieName(options: { siteName: string; securePrefix: boolean }): string {
+  return `${options.securePrefix ? '__Host-' : ''}umbMember${options.siteName}`
+}

package/src/password.ts

@@ -0,0 +1,33 @@
+/**
+ * Password hashing.
+ *
+ * Umbraco stores ASP.NET Core Identity v3 hashes (PBKDF2-HMAC-SHA512). We are not
+ * reading existing Umbraco databases, so we use argon2id instead, and keep the
+ * `password_config` marker column so the algorithm is recorded per row and can be
+ * rotated later exactly as Umbraco rotates its legacy formats.
+ */
+export const PASSWORD_ALGORITHM = 'ARGON2ID'
+
+export interface PasswordConfig {
+  hashAlgorithm: string
+}
+
+export const passwordConfigJson = (algorithm = PASSWORD_ALGORITHM): string =>
+  JSON.stringify({ hashAlgorithm: algorithm } satisfies PasswordConfig)
+
+export async function hashPassword(password: string): Promise<string> {
+  return Bun.password.hash(password, { algorithm: 'argon2id' })
+}
+
+/**
+ * Verifies a password. Returns false rather than throwing for a malformed or
+ * absent hash, so a user row with no password simply cannot sign in.
+ */
+export async function verifyPassword(password: string, hash: string | null): Promise<boolean> {
+  if (!hash) return false
+  try {
+    return await Bun.password.verify(password, hash)
+  } catch {
+    return false
+  }
+}

package/src/pkce.ts

@@ -0,0 +1,49 @@
+/**
+ * PKCE (RFC 7636). The client generates a 128-character verifier and sends us
+ * the S256 challenge; we verify the verifier against it at token exchange.
+ */
+import { createHash } from 'node:crypto'
+
+export type CodeChallengeMethod = 'S256' | 'plain'
+
+export function base64UrlEncode(bytes: Uint8Array | Buffer): string {
+  return Buffer.from(bytes).toString('base64url')
+}
+
+export function deriveChallenge(verifier: string): string {
+  return base64UrlEncode(createHash('sha256').update(verifier).digest())
+}
+
+/**
+ * `plain` is accepted only because the spec defines it; the backoffice always
+ * sends S256, so a plain challenge in practice means something is wrong.
+ */
+export function verifyChallenge(
+  verifier: string,
+  challenge: string,
+  method: CodeChallengeMethod,
+): boolean {
+  const expected = method === 'S256' ? deriveChallenge(verifier) : verifier
+  return timingSafeEqual(expected, challenge)
+}
+
+export function timingSafeEqual(a: string, b: string): boolean {
+  if (a.length !== b.length) return false
+  let mismatch = 0
+  for (let i = 0; i < a.length; i++) mismatch |= a.charCodeAt(i) ^ b.charCodeAt(i)
+  return mismatch === 0
+}
+
+/** Opaque, high-entropy credential: authorization codes and reference tokens. */
+export function generateToken(bytes = 48): string {
+  return base64UrlEncode(crypto.getRandomValues(new Uint8Array(bytes)))
+}
+
+/**
+ * Credentials are stored hashed so a database read cannot yield a usable token.
+ * SHA-256 is right here, not argon2: these are high-entropy random values, not
+ * guessable secrets, and validation happens on every request.
+ */
+export function hashToken(token: string): string {
+  return createHash('sha256').update(token).digest('base64url')
+}