@crombolo/auth 0.0.0-stage → 0.10.0

package/src/routes.ts

@@ -0,0 +1,338 @@
+/**
+ * HTTP surface for back-office security.
+ *
+ * These endpoints live on Umbraco's BackOfficeController, which is excluded from
+ * the OpenAPI document, so they are matched by path rather than through the
+ * contract-first router.
+ */
+import { MANAGEMENT_API_PATH, problemDetails, problemResponse } from '@crombolo/core'
+import {
+  type CookieOptions,
+  cookieNames,
+  expireCookie,
+  REDACTED,
+  readCookie,
+  resolveRedacted,
+  serializeCookie,
+} from './cookies.ts'
+import type { AuthService } from './service.ts'
+import { BACKOFFICE_CLIENT_ID, DEFAULT_SCOPE } from './service.ts'
+
+export const SECURITY_PREFIX = `${MANAGEMENT_API_PATH}/security/back-office`
+
+export interface AuthRouteOptions {
+  backOfficePath: string
+  service: AuthService
+  cookies: CookieOptions
+}
+
+export interface AuthRoutes {
+  /** Handles a security endpoint, or returns undefined when the path is not one. */
+  handle(request: Request, pathname: string): Promise<Response | undefined>
+}
+
+/**
+ * An OAuth error response. A 400 or 401 carrying a JSON `error` member is
+ * definitive: the client stops retrying. Any other shape is treated as transient
+ * and retried, which leaves the editor hanging.
+ */
+function oauthError(error: string, description: string, status = 400): Response {
+  return Response.json({ error, error_description: description }, { status })
+}
+
+export function createAuthRoutes(options: AuthRouteOptions): AuthRoutes {
+  // The contract's path, not the backoffice's: these are Management API
+  // operations and the client calls them there wherever the editor is mounted.
+  const prefix = SECURITY_PREFIX
+  const names = cookieNames(options.cookies)
+  const secure = options.cookies.securePrefix
+  const { service } = options
+
+  const expectedRedirectUri = (origin: string) =>
+    `${origin}${options.backOfficePath}/oauth_complete`
+
+  function sessionCookie(sessionId: string, maxAgeSeconds: number): string {
+    return serializeCookie({ name: names.session, value: sessionId, secure, maxAgeSeconds })
+  }
+
+  /** Real token values only ever leave the server inside these cookies. */
+  function tokenCookies(
+    accessToken: string,
+    refreshToken: string,
+    accessTtl: number,
+    refreshTtl: number,
+  ): string[] {
+    return [
+      serializeCookie({
+        name: names.accessToken,
+        value: accessToken,
+        secure,
+        maxAgeSeconds: accessTtl,
+      }),
+      serializeCookie({
+        name: names.refreshToken,
+        value: refreshToken,
+        secure,
+        maxAgeSeconds: refreshTtl,
+      }),
+    ]
+  }
+
+  function clearedCookies(): string[] {
+    return [
+      expireCookie(names.accessToken, secure),
+      expireCookie(names.refreshToken, secure),
+      expireCookie(names.session, secure),
+    ]
+  }
+
+  async function handleAuthorize(request: Request, url: URL): Promise<Response> {
+    const params = url.searchParams
+    const clientId = params.get('client_id') ?? ''
+    const redirectUri = params.get('redirect_uri') ?? ''
+    const responseType = params.get('response_type') ?? ''
+    const codeChallenge = params.get('code_challenge') ?? ''
+    const method = (params.get('code_challenge_method') ?? 'S256') as 'S256' | 'plain'
+    const state = params.get('state') ?? undefined
+
+    if (clientId !== BACKOFFICE_CLIENT_ID) {
+      return oauthError('invalid_client', `Unknown client '${clientId}'.`)
+    }
+    if (responseType !== 'code') {
+      return oauthError(
+        'unsupported_response_type',
+        'Only the authorization code flow is supported.',
+      )
+    }
+    // PKCE is mandatory: the client is public and cannot hold a secret.
+    if (!codeChallenge) {
+      return oauthError('invalid_request', 'code_challenge is required.')
+    }
+    if (redirectUri !== expectedRedirectUri(url.origin)) {
+      return oauthError('invalid_request', 'redirect_uri is not registered for this client.')
+    }
+
+    const sessionId = readCookie(request, names.session)
+    const session = sessionId ? await service.resolveSession(sessionId) : undefined
+    if (!sessionId || !session) {
+      // No session yet: send the browser to the login page, which returns here.
+      const loginUrl = new URL(`${options.backOfficePath}/login`, url.origin)
+      loginUrl.searchParams.set('returnUrl', url.pathname + url.search)
+      return Response.redirect(loginUrl.href, 302)
+    }
+
+    const code = await service.authorize(sessionId, session.userId, {
+      clientId,
+      redirectUri,
+      scope: params.get('scope') ?? DEFAULT_SCOPE,
+      state,
+      codeChallenge,
+      codeChallengeMethod: method,
+    })
+
+    const target = new URL(redirectUri)
+    target.searchParams.set('code', code)
+    if (state) target.searchParams.set('state', state)
+    return Response.redirect(target.href, 302)
+  }
+
+  async function handleToken(request: Request, url: URL): Promise<Response> {
+    const form = new URLSearchParams(await request.text())
+    const grantType = form.get('grant_type') ?? ''
+    const clientId = form.get('client_id') ?? ''
+
+    // API users: a machine client presents its own id and secret and gets a bearer token back
+    if (grantType === 'client_credentials') {
+      const issued = await service.clientCredentials(clientId, form.get('client_secret') ?? '')
+      if (!issued.ok) return oauthError(issued.error, issued.description, 401)
+      return Response.json({
+        access_token: issued.accessToken,
+        token_type: 'Bearer',
+        expires_in: issued.expiresIn,
+        issued_at: issued.issuedAt,
+        scope: DEFAULT_SCOPE,
+      })
+    }
+
+    if (clientId !== BACKOFFICE_CLIENT_ID) {
+      return oauthError('invalid_client', `Unknown client '${clientId}'.`)
+    }
+
+    const result =
+      grantType === 'authorization_code'
+        ? await (async () => {
+            const code = form.get('code')
+            const verifier = form.get('code_verifier')
+            if (!code || !verifier) {
+              return {
+                ok: false as const,
+                error: 'invalid_request' as const,
+                description: 'code and code_verifier are required.',
+              }
+            }
+            return service.exchangeCode(
+              code,
+              verifier,
+              clientId,
+              form.get('redirect_uri') ?? expectedRedirectUri(url.origin),
+            )
+          })()
+        : grantType === 'refresh_token'
+          ? await (async () => {
+              // The client sends `[redacted]`; the real token is in the cookie.
+              const refreshToken = resolveRedacted(
+                form.get('refresh_token'),
+                readCookie(request, names.refreshToken),
+              )
+              if (!refreshToken) {
+                return {
+                  ok: false as const,
+                  error: 'invalid_grant' as const,
+                  description: 'No refresh token was presented.',
+                }
+              }
+              return service.refresh(refreshToken, clientId)
+            })()
+          : {
+              ok: false as const,
+              error: 'unsupported_grant_type' as const,
+              description: `Unsupported grant_type '${grantType}'.`,
+            }
+
+    if (!result.ok) {
+      const status = result.error === 'invalid_client' ? 401 : 400
+      const response = oauthError(result.error, result.description, status)
+      // A definitive rejection must not leave stale cookies behind.
+      for (const cookie of clearedCookies()) response.headers.append('set-cookie', cookie)
+      return response
+    }
+
+    const { grant } = result
+    const headers = new Headers({ 'content-type': 'application/json; charset=utf-8' })
+    for (const cookie of tokenCookies(
+      grant.accessToken,
+      grant.refreshToken,
+      service.settings.accessTokenSeconds,
+      service.settings.refreshTokenSeconds,
+    )) {
+      headers.append('set-cookie', cookie)
+    }
+    headers.append(
+      'set-cookie',
+      sessionCookie(grant.sessionId, service.settings.refreshTokenSeconds),
+    )
+
+    return new Response(
+      JSON.stringify({
+        access_token: REDACTED,
+        refresh_token: REDACTED,
+        token_type: 'Bearer',
+        expires_in: grant.expiresIn,
+        issued_at: grant.issuedAt,
+        scope: DEFAULT_SCOPE,
+      }),
+      { status: 200, headers },
+    )
+  }
+
+  async function handleLogin(request: Request): Promise<Response> {
+    let body: { username?: unknown; password?: unknown }
+    try {
+      body = (await request.json()) as typeof body
+    } catch {
+      return problemResponse(
+        problemDetails({ title: 'Invalid request', status: 400, detail: 'Expected a JSON body.' }),
+      )
+    }
+    const username = typeof body.username === 'string' ? body.username : ''
+    const password = typeof body.password === 'string' ? body.password : ''
+    if (!username || !password) {
+      return problemResponse(
+        problemDetails({
+          title: 'Invalid request',
+          status: 400,
+          detail: 'username and password are required.',
+        }),
+      )
+    }
+
+    const result = await service.login(
+      username,
+      password,
+      request.headers.get('x-forwarded-for') ?? undefined,
+    )
+
+    // Status codes the login UI branches on: 401 invalid, 402 needs 2FA,
+    // 403 locked or not approved.
+    if (result.status === 'invalid') {
+      return problemResponse(
+        problemDetails({
+          title: 'Invalid credentials',
+          status: 401,
+          operationStatus: 'InvalidCredentials',
+        }),
+      )
+    }
+    if (result.status === 'notAllowed') {
+      return problemResponse(
+        problemDetails({ title: 'Login not allowed', status: 403, operationStatus: result.reason }),
+      )
+    }
+    if (result.status === 'twoFactorRequired') {
+      return Response.json(
+        { twoFactorLoginView: null, enabledTwoFactorProviderNames: result.providers },
+        { status: 402 },
+      )
+    }
+
+    return new Response(null, {
+      status: 200,
+      headers: {
+        'set-cookie': sessionCookie(result.sessionId, service.settings.refreshTokenSeconds),
+      },
+    })
+  }
+
+  async function handleRevoke(request: Request): Promise<Response> {
+    const form = new URLSearchParams(await request.text())
+    const token = resolveRedacted(form.get('token'), readCookie(request, names.accessToken))
+    if (token) await service.revokeAccessToken(token)
+    const response = new Response(null, { status: 200 })
+    for (const cookie of clearedCookies()) response.headers.append('set-cookie', cookie)
+    return response
+  }
+
+  async function handleSignOut(request: Request, url: URL): Promise<Response> {
+    const sessionId = readCookie(request, names.session)
+    if (sessionId) await service.signOut(sessionId)
+
+    const requested = url.searchParams.get('post_logout_redirect_uri')
+    const allowed = `${url.origin}${options.backOfficePath}/logout`
+    const location = requested === allowed ? allowed : `${url.origin}${options.backOfficePath}`
+    const response = new Response(null, { status: 302, headers: { location } })
+    for (const cookie of clearedCookies()) response.headers.append('set-cookie', cookie)
+    return response
+  }
+
+  return {
+    async handle(request, pathname) {
+      if (!pathname.startsWith(`${prefix}/`)) return undefined
+      const action = pathname.slice(prefix.length + 1)
+      const url = new URL(request.url)
+
+      if (action === 'authorize' && request.method === 'GET') return handleAuthorize(request, url)
+      if (action === 'token' && request.method === 'POST') return handleToken(request, url)
+      if (action === 'login' && request.method === 'POST') return handleLogin(request)
+      if (action === 'revoke' && request.method === 'POST') return handleRevoke(request)
+      if (action === 'signout') return handleSignOut(request, url)
+      if (action === 'verify-2fa' && request.method === 'POST') {
+        return oauthError(
+          'unsupported_grant_type',
+          'Two-factor authentication is not implemented.',
+          400,
+        )
+      }
+      return undefined
+    },
+  }
+}

package/src/service.ts

@@ -0,0 +1,354 @@
+/**
+ * The OAuth 2.0 authorization server, shaped to what the Umbraco backoffice
+ * actually sends. See docs/backoffice-hosting.md for the wire contract.
+ */
+import { type ExtensionSectionAlias, type SectionAlias, toSectionAliases } from '@crombolo/core'
+import { hashPassword, passwordConfigJson, verifyPassword } from './password.ts'
+import { type CodeChallengeMethod, generateToken, verifyChallenge } from './pkce.ts'
+import type { AuthStore, UserRow } from './store.ts'
+
+/**
+ * The `client_id` the vendored backoffice sends, which `routes.ts` checks an
+ * incoming request against. Not a name we pick: `umb-auth-client.js` takes it as
+ * a constructor default and `auth.context.js` constructs that client without
+ * passing one, so the browser puts this exact string on every authorize and
+ * token call. There is no attribute and no setting to change it.
+ *
+ * Renaming the value therefore does not rebrand anything — it makes the server
+ * reject the only client that calls it, and every sign-in fails with
+ * `invalid_client`. The API-user prefix in `adapters/users.ts` is the one that
+ * was genuinely ours, and it moved to crombolo in migration 020.
+ */
+export const BACKOFFICE_CLIENT_ID = 'umbraco-back-office'
+export const DEFAULT_SCOPE = 'offline_access'
+
+export interface AuthSettings {
+  /** Access token lifetime. Umbraco uses a quarter of the session timeout. */
+  accessTokenSeconds: number
+  refreshTokenSeconds: number
+  authorizationCodeSeconds: number
+  /** Failed attempts before the account is locked. 0 disables lockout. */
+  maxFailedLoginAttempts: number
+}
+
+export const DEFAULT_AUTH_SETTINGS: AuthSettings = {
+  accessTokenSeconds: 20 * 60,
+  refreshTokenSeconds: 80 * 60,
+  authorizationCodeSeconds: 5 * 60,
+  maxFailedLoginAttempts: 10,
+}
+
+export type LoginResult =
+  | { status: 'success'; user: UserRow; sessionId: string }
+  | { status: 'invalid' }
+  | { status: 'twoFactorRequired'; providers: string[] }
+  | { status: 'notAllowed'; reason: 'disabled' | 'lockedOut' | 'notApproved' }
+
+export interface AuthorizationRequest {
+  clientId: string
+  redirectUri: string
+  scope: string
+  state: string | undefined
+  codeChallenge: string
+  codeChallengeMethod: CodeChallengeMethod
+}
+
+export interface TokenGrant {
+  accessToken: string
+  refreshToken: string
+  expiresIn: number
+  issuedAt: number
+  sessionId: string
+  userId: number
+}
+
+export type TokenError =
+  | 'invalid_grant'
+  | 'invalid_request'
+  | 'invalid_client'
+  | 'unauthorized_client'
+
+export type TokenResult =
+  | { ok: true; grant: TokenGrant }
+  | { ok: false; error: TokenError; description: string }
+
+export interface ResolvedIdentity {
+  user: UserRow
+  sessionId: string
+  allowedSections: Array<SectionAlias | ExtensionSectionAlias>
+  groupKeys: string[]
+  isAdmin: boolean
+  hasAccessToAllLanguages: boolean
+  permissions: string[]
+}
+
+/**
+ * Normalises login timing so a valid username with a wrong password takes the
+ * same time as an unknown username. Without this, response time reveals which
+ * accounts exist.
+ */
+async function withMinimumDuration<T>(minimumMs: number, work: () => Promise<T>): Promise<T> {
+  const started = Bun.nanoseconds()
+  const result = await work()
+  const elapsedMs = (Bun.nanoseconds() - started) / 1_000_000
+  if (elapsedMs < minimumMs) await Bun.sleep(minimumMs - elapsedMs)
+  return result
+}
+
+const DUMMY_HASH_PROMISE = hashPassword(crypto.randomUUID())
+
+export class AuthService {
+  #store: AuthStore
+  #settings: AuthSettings
+
+  constructor(store: AuthStore, settings: AuthSettings = DEFAULT_AUTH_SETTINGS) {
+    this.#store = store
+    this.#settings = settings
+  }
+
+  get settings(): AuthSettings {
+    return this.#settings
+  }
+
+  async login(login: string, password: string, ipAddress?: string): Promise<LoginResult> {
+    return withMinimumDuration(120, async () => {
+      const user = await this.#store.findUserByLogin(login)
+      if (!user) {
+        // Verify against a throwaway hash so an unknown user costs the same.
+        await verifyPassword(password, await DUMMY_HASH_PROMISE)
+        return { status: 'invalid' } as const
+      }
+      // Before the password, as ASP.NET Identity's PreSignInCheck does it. After
+      // it, the two answers differ by whether the password was right — so once an
+      // attacker has tripped the lockout themselves, guessing on is free and the
+      // status code tells them when they have found it. The throwaway verify keeps
+      // this path costing what the others cost.
+      if (user.isLockedOut) {
+        await verifyPassword(password, await DUMMY_HASH_PROMISE)
+        return { status: 'notAllowed', reason: 'lockedOut' } as const
+      }
+      if (!(await verifyPassword(password, user.passwordHash))) {
+        const attempts = await this.#store.recordLoginFailure(user.id)
+        if (
+          this.#settings.maxFailedLoginAttempts > 0 &&
+          attempts >= this.#settings.maxFailedLoginAttempts
+        ) {
+          await this.#store.lockOut(user.id)
+        }
+        return { status: 'invalid' } as const
+      }
+      // `isApproved` stays behind the password on purpose: it is not a state an
+      // attacker can induce, so answering it only to whoever knows the password
+      // discloses strictly less than checking it up front.
+      if (!user.isApproved) return { status: 'notAllowed', reason: 'notApproved' } as const
+
+      const sessionId = crypto.randomUUID()
+      await this.#store.recordLoginSuccess(user.id, sessionId, ipAddress)
+      return { status: 'success', user, sessionId } as const
+    })
+  }
+
+  /** Issues a single-use authorization code for an already-authenticated session. */
+  async authorize(
+    sessionId: string,
+    userId: number,
+    request: AuthorizationRequest,
+  ): Promise<string> {
+    const code = generateToken()
+    await this.#store.createAuthorizationCode({
+      code,
+      userId,
+      sessionId,
+      clientId: request.clientId,
+      redirectUri: request.redirectUri,
+      codeChallenge: request.codeChallenge,
+      codeChallengeMethod: request.codeChallengeMethod,
+      scope: request.scope,
+      expiresAt: new Date(Date.now() + this.#settings.authorizationCodeSeconds * 1000),
+    })
+    return code
+  }
+
+  async exchangeCode(
+    code: string,
+    codeVerifier: string,
+    clientId: string,
+    redirectUri: string,
+  ): Promise<TokenResult> {
+    const record = await this.#store.consumeAuthorizationCode(code)
+    if (!record)
+      return { ok: false, error: 'invalid_grant', description: 'Unknown authorization code.' }
+    if (record.consumedAt) {
+      // Replay: the code was already exchanged, so kill the whole session.
+      await this.#store.endSession(record.sessionId)
+      return { ok: false, error: 'invalid_grant', description: 'Authorization code already used.' }
+    }
+    if (record.expiresAt.getTime() < Date.now()) {
+      return { ok: false, error: 'invalid_grant', description: 'Authorization code has expired.' }
+    }
+    if (record.clientId !== clientId) {
+      return { ok: false, error: 'invalid_client', description: 'Client mismatch.' }
+    }
+    if (record.redirectUri !== redirectUri) {
+      return { ok: false, error: 'invalid_grant', description: 'Redirect URI mismatch.' }
+    }
+    if (
+      !verifyChallenge(
+        codeVerifier,
+        record.codeChallenge,
+        record.codeChallengeMethod as CodeChallengeMethod,
+      )
+    ) {
+      return { ok: false, error: 'invalid_grant', description: 'PKCE verification failed.' }
+    }
+
+    return {
+      ok: true,
+      grant: await this.#issue(record.userId, record.sessionId, clientId, record.scope),
+    }
+  }
+
+  async refresh(refreshToken: string, clientId: string): Promise<TokenResult> {
+    const existing = await this.#store.findToken(refreshToken, 'refresh')
+    if (!existing)
+      return { ok: false, error: 'invalid_grant', description: 'Unknown refresh token.' }
+    if (existing.revokedAt) {
+      // Reuse of a rotated token means the chain is compromised.
+      await this.#store.endSession(existing.sessionId)
+      return { ok: false, error: 'invalid_grant', description: 'Refresh token has been revoked.' }
+    }
+    if (existing.expiresAt.getTime() < Date.now()) {
+      return { ok: false, error: 'invalid_grant', description: 'Refresh token has expired.' }
+    }
+    if (existing.clientId !== clientId) {
+      return { ok: false, error: 'invalid_client', description: 'Client mismatch.' }
+    }
+    const session = await this.#store.findSession(existing.sessionId)
+    if (!session) return { ok: false, error: 'invalid_grant', description: 'Session has ended.' }
+
+    await this.#store.revokeToken(existing.id)
+    return {
+      ok: true,
+      grant: await this.#issue(
+        existing.userId,
+        existing.sessionId,
+        clientId,
+        existing.scope,
+        existing.id,
+      ),
+    }
+  }
+
+  /**
+   * The client-credentials grant for API users: a secret checked against the
+   * user's credential yields an access token and no refresh token.
+   */
+  async clientCredentials(
+    clientId: string,
+    secret: string,
+  ): Promise<
+    | { ok: true; accessToken: string; expiresIn: number; issuedAt: number }
+    | { ok: false; error: TokenError; description: string }
+  > {
+    const credential = await this.#store.findClientCredential(clientId)
+    const valid = credential ? await verifyPassword(secret, credential.secretHash) : false
+    const user = credential && valid ? await this.#store.findUserById(credential.userId) : undefined
+    if (user?.kind !== 'Api' || user.isLockedOut || !user.isApproved)
+      return { ok: false, error: 'invalid_client', description: 'Invalid client credentials.' }
+    const sessionId = crypto.randomUUID()
+    await this.#store.recordLoginSuccess(user.id, sessionId)
+    const accessToken = generateToken()
+    const now = Date.now()
+    await this.#store.createToken({
+      token: accessToken,
+      type: 'access',
+      userId: user.id,
+      sessionId,
+      clientId,
+      scope: DEFAULT_SCOPE,
+      expiresAt: new Date(now + this.#settings.accessTokenSeconds * 1000),
+    })
+    return {
+      ok: true,
+      accessToken,
+      expiresIn: this.#settings.accessTokenSeconds,
+      issuedAt: Math.floor(now / 1000),
+    }
+  }
+
+  /** Resolves a reference access token to an identity, or undefined. */
+  async resolveAccessToken(accessToken: string): Promise<ResolvedIdentity | undefined> {
+    const token = await this.#store.findToken(accessToken, 'access')
+    if (!token || token.revokedAt || token.expiresAt.getTime() < Date.now()) return undefined
+    const session = await this.#store.findSession(token.sessionId)
+    if (!session) return undefined
+    const user = await this.#store.findUserById(token.userId)
+    if (!user || user.isLockedOut || !user.isApproved) return undefined
+
+    const authorization = await this.#store.loadAuthorization(user.id)
+    return {
+      user,
+      sessionId: token.sessionId,
+      allowedSections: toSectionAliases(authorization.appAliases),
+      groupKeys: authorization.groupKeys,
+      isAdmin: authorization.isAdmin,
+      hasAccessToAllLanguages: authorization.hasAccessToAllLanguages,
+      permissions: authorization.permissions,
+    }
+  }
+
+  async resolveSession(sessionId: string): Promise<{ userId: number } | undefined> {
+    return this.#store.findSession(sessionId)
+  }
+
+  async signOut(sessionId: string): Promise<void> {
+    await this.#store.endSession(sessionId)
+  }
+
+  async revokeAccessToken(accessToken: string): Promise<void> {
+    const token = await this.#store.findToken(accessToken, 'access')
+    if (token) await this.#store.endSession(token.sessionId)
+  }
+
+  async #issue(
+    userId: number,
+    sessionId: string,
+    clientId: string,
+    scope: string,
+    parentId?: number,
+  ): Promise<TokenGrant> {
+    const accessToken = generateToken()
+    const refreshToken = generateToken()
+    const now = Date.now()
+    await this.#store.createToken({
+      token: accessToken,
+      type: 'access',
+      userId,
+      sessionId,
+      clientId,
+      scope,
+      expiresAt: new Date(now + this.#settings.accessTokenSeconds * 1000),
+      parentId,
+    })
+    await this.#store.createToken({
+      token: refreshToken,
+      type: 'refresh',
+      userId,
+      sessionId,
+      clientId,
+      scope,
+      expiresAt: new Date(now + this.#settings.refreshTokenSeconds * 1000),
+      parentId,
+    })
+    return {
+      accessToken,
+      refreshToken,
+      expiresIn: this.#settings.accessTokenSeconds,
+      issuedAt: Math.floor(now / 1000),
+      sessionId,
+      userId,
+    }
+  }
+}
+
+export { passwordConfigJson }