@exvio/os-backend-core 0.4.0

package/src/auth/login-policy.ts

@@ -0,0 +1,95 @@
+import { AuthError } from './errors.ts'
+import type {
+  LoginMode,
+  LoginPhase,
+  LoginPolicy,
+  LoginPolicyCheck,
+  LoginSurface,
+} from './types.ts'
+
+const LOGIN_MODES = new Set<LoginMode>(['hub_managed', 'standalone', 'hybrid'])
+const LOGIN_SURFACES = new Set<LoginSurface>(['email', 'google', 'microsoft', 'passkey', 'hub_ott'])
+const LOGIN_PHASES = new Set<LoginPhase>(['start', 'callback', 'finish'])
+
+const MODE_DEFAULTS = Object.freeze({
+  hub_managed: Object.freeze(['hub_ott'] as const),
+  standalone: Object.freeze(['email', 'google', 'microsoft', 'passkey'] as const),
+  hybrid: Object.freeze(['email', 'google', 'microsoft', 'passkey', 'hub_ott'] as const),
+}) satisfies Readonly<Record<LoginMode, readonly LoginSurface[]>>
+
+export interface CreateLoginPolicyOptions {
+  readonly mode: LoginMode
+  /** May only narrow a mode's defaults. Omitted surfaces use the mode default. */
+  readonly enabled?: Readonly<Partial<Record<LoginSurface, boolean>>>
+}
+
+function invalidInput(): never {
+  throw new AuthError({ code: 'invalid_input', status: 400 })
+}
+
+function snapshotEnabled(value: unknown): Readonly<Partial<Record<LoginSurface, boolean>>> {
+  if (value === undefined) return Object.freeze({})
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) invalidInput()
+
+  let prototype: object | null
+  let descriptors: Record<string, PropertyDescriptor>
+  try {
+    prototype = Object.getPrototypeOf(value)
+    descriptors = Object.getOwnPropertyDescriptors(value)
+  } catch {
+    return invalidInput()
+  }
+  if (prototype !== Object.prototype && prototype !== null) invalidInput()
+
+  const snapshot: Partial<Record<LoginSurface, boolean>> = {}
+  for (const [key, descriptor] of Object.entries(descriptors)) {
+    if (!LOGIN_SURFACES.has(key as LoginSurface) || !('value' in descriptor)) invalidInput()
+    if (typeof descriptor.value !== 'boolean') invalidInput()
+    snapshot[key as LoginSurface] = descriptor.value
+  }
+  return Object.freeze(snapshot)
+}
+
+export function createLoginPolicy(options: CreateLoginPolicyOptions): LoginPolicy {
+  if (!options || typeof options !== 'object') invalidInput()
+
+  let mode: LoginMode
+  let configuredSurfaces: Readonly<Partial<Record<LoginSurface, boolean>>>
+  try {
+    mode = options.mode
+    configuredSurfaces = snapshotEnabled(options.enabled)
+  } catch (error) {
+    if (error instanceof AuthError) throw error
+    return invalidInput()
+  }
+  if (!LOGIN_MODES.has(mode)) invalidInput()
+
+  const defaults = new Set<LoginSurface>(MODE_DEFAULTS[mode])
+  const enabled = new Set<LoginSurface>()
+  for (const surface of LOGIN_SURFACES) {
+    const configured = configuredSurfaces[surface]
+    // Configuration can fail closed by disabling a default. It cannot enable
+    // a credential surface forbidden by the selected mode.
+    if (defaults.has(surface) && configured !== false) enabled.add(surface)
+  }
+
+  const enabledSurfaces = Object.freeze([...enabled])
+  const allows = (check: LoginPolicyCheck): boolean => (
+    check !== null
+    && typeof check === 'object'
+    && LOGIN_SURFACES.has(check.surface)
+    && LOGIN_PHASES.has(check.phase)
+    && enabled.has(check.surface)
+  )
+
+  return Object.freeze({
+    mode,
+    enabledSurfaces,
+    allows,
+    assertAllowed(check: LoginPolicyCheck): void {
+      if (!allows(check)) {
+        throw new AuthError({ code: 'login_not_allowed', status: 403 })
+      }
+    },
+  })
+}

package/src/auth/oauth-state.ts

@@ -0,0 +1,332 @@
+import { AuthError } from './errors.ts'
+import { createSecureAuthToken } from './session.ts'
+import type {
+  OAuthStateConsumeInput,
+  OAuthStateIssueInput,
+  OAuthStateManager,
+  OAuthStatePayload,
+  OneTimeAuthStore,
+} from './types.ts'
+
+const OAUTH_STATE_PATTERN = /^oas_v1_[A-Za-z0-9_-]{43}$/
+const PROVIDER_PATTERN = /^[a-z][a-z0-9_-]{0,63}$/
+const PKCE_VERIFIER_PATTERN = /^[A-Za-z0-9._~-]{43,128}$/
+const SESSION_ID_PATTERN = /^[A-Za-z0-9._~-]{16,256}$/
+const KEY_PREFIX_PATTERN = /^[A-Za-z0-9:_-]{1,64}$/
+const encoder = new TextEncoder()
+
+interface StoredOAuthState extends OAuthStatePayload {
+  readonly v: 1
+}
+
+export interface CreateOAuthStateManagerOptions {
+  readonly store: OneTimeAuthStore
+  readonly ttlSeconds?: number
+  readonly maxSerializedBytes?: number
+  readonly keyPrefix?: string
+  /** Millisecond clock, primarily for deterministic contract tests. */
+  readonly now?: () => number
+  /** Must return 32 bytes or more of unguessable base64url entropy in production. */
+  readonly generateState?: () => string
+}
+
+function invalidInput(): never {
+  throw new AuthError({ code: 'invalid_input', status: 400 })
+}
+
+function assertTenantId(tenantId: number): void {
+  if (!Number.isSafeInteger(tenantId) || tenantId <= 0) invalidInput()
+}
+
+function assertProvider(provider: string): void {
+  if (typeof provider !== 'string' || !PROVIDER_PATTERN.test(provider)) invalidInput()
+}
+
+function assertRedirectUri(redirectUri: string): void {
+  if (typeof redirectUri !== 'string' || redirectUri.length > 2_048) invalidInput()
+  let parsed: URL
+  try {
+    parsed = new URL(redirectUri)
+  } catch {
+    invalidInput()
+  }
+  if (
+    (parsed.protocol !== 'https:' && parsed.protocol !== 'http:')
+    || parsed.username !== ''
+    || parsed.password !== ''
+    || parsed.hash !== ''
+  ) invalidInput()
+}
+
+function assertVerifier(verifier: string): void {
+  if (typeof verifier !== 'string' || !PKCE_VERIFIER_PATTERN.test(verifier)) invalidInput()
+}
+
+function assertInitiatingSessionId(sessionId: string | undefined): void {
+  if (sessionId !== undefined && (
+    typeof sessionId !== 'string' || !SESSION_ID_PATTERN.test(sessionId)
+  )) invalidInput()
+}
+
+function assertReturnTo(returnTo: string | undefined): void {
+  if (returnTo === undefined) return
+  if (
+    typeof returnTo !== 'string'
+    || returnTo.length === 0
+    || returnTo.length > 2_048
+    || !returnTo.startsWith('/')
+    || returnTo.startsWith('//')
+    || returnTo.includes('\\')
+    || /[\u0000-\u001F\u007F]/u.test(returnTo)
+  ) invalidInput()
+}
+
+function assertIssueInput(input: OAuthStateIssueInput): void {
+  if (input === null || typeof input !== 'object' || Array.isArray(input)) invalidInput()
+  assertTenantId(input.tenantId)
+  assertProvider(input.provider)
+  assertRedirectUri(input.redirectUri)
+  assertVerifier(input.verifier)
+  assertInitiatingSessionId(input.initiatingSessionId)
+  assertReturnTo(input.returnTo)
+}
+
+function assertConsumeInput(input: OAuthStateConsumeInput): void {
+  if (input === null || typeof input !== 'object' || Array.isArray(input)) {
+    throw new AuthError({ code: 'invalid_oauth_state', status: 400 })
+  }
+  assertTenantId(input.tenantId)
+  assertProvider(input.provider)
+  assertRedirectUri(input.redirectUri)
+  assertInitiatingSessionId(input.initiatingSessionId)
+  if (typeof input.state !== 'string' || !OAUTH_STATE_PATTERN.test(input.state)) {
+    throw new AuthError({ code: 'invalid_oauth_state', status: 400 })
+  }
+}
+
+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, '')
+}
+
+async function hashState(state: string): Promise<string> {
+  const digest = await crypto.subtle.digest('SHA-256', encoder.encode(state))
+  return base64Url(new Uint8Array(digest))
+}
+
+function parseStoredPayload(serialized: string, maxSerializedBytes: number): StoredOAuthState {
+  if (encoder.encode(serialized).byteLength > maxSerializedBytes) {
+    throw new AuthError({ code: 'invalid_oauth_state', status: 400 })
+  }
+
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(serialized)
+  } catch {
+    throw new AuthError({ code: 'invalid_oauth_state', status: 400 })
+  }
+  if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    throw new AuthError({ code: 'invalid_oauth_state', status: 400 })
+  }
+
+  const value = parsed as Record<string, unknown>
+  const allowedKeys = new Set([
+    'v',
+    'tenantId',
+    'provider',
+    'redirectUri',
+    'verifier',
+    'initiatingSessionId',
+    'returnTo',
+    'issuedAt',
+    'expiresAt',
+  ])
+  if (Object.keys(value).some(key => !allowedKeys.has(key))) {
+    throw new AuthError({ code: 'invalid_oauth_state', status: 400 })
+  }
+
+  try {
+    if (value.v !== 1) invalidInput()
+    assertTenantId(value.tenantId as number)
+    assertProvider(value.provider as string)
+    assertRedirectUri(value.redirectUri as string)
+    assertVerifier(value.verifier as string)
+    assertInitiatingSessionId(value.initiatingSessionId as string | undefined)
+    assertReturnTo(value.returnTo as string | undefined)
+    if (
+      typeof value.issuedAt !== 'number'
+      || !Number.isSafeInteger(value.issuedAt)
+      || value.issuedAt < 0
+      || typeof value.expiresAt !== 'number'
+      || !Number.isSafeInteger(value.expiresAt)
+      || value.expiresAt <= value.issuedAt
+      || value.expiresAt - value.issuedAt > 3_600_000
+    ) invalidInput()
+  } catch {
+    throw new AuthError({ code: 'invalid_oauth_state', status: 400 })
+  }
+
+  return value as unknown as StoredOAuthState
+}
+
+/**
+ * Issue and atomically consume a tenant-bound OAuth transaction.
+ * The backing key contains only SHA-256(state), so Redis/profiler key logs do
+ * not disclose a replayable raw state token.
+ */
+export function createOAuthStateManager(
+  options: CreateOAuthStateManagerOptions,
+): OAuthStateManager {
+  if (
+    !options
+    || typeof options !== 'object'
+    || !options.store
+    || typeof options.store.put !== 'function'
+    || typeof options.store.take !== 'function'
+  ) {
+    invalidInput()
+  }
+  const ttlSeconds = options.ttlSeconds ?? 600
+  const maxSerializedBytes = options.maxSerializedBytes ?? 4_096
+  const keyPrefix = options.keyPrefix ?? 'auth:oauth-state:v1:'
+  const now = options.now ?? Date.now
+  const generateState = options.generateState ?? (() => `oas_v1_${createSecureAuthToken()}`)
+
+  if (!Number.isSafeInteger(ttlSeconds) || ttlSeconds < 30 || ttlSeconds > 3_600) invalidInput()
+  if (
+    !Number.isSafeInteger(maxSerializedBytes)
+    || maxSerializedBytes < 512
+    || maxSerializedBytes > 16_384
+    || !KEY_PREFIX_PATTERN.test(keyPrefix)
+    || typeof now !== 'function'
+    || typeof generateState !== 'function'
+  ) invalidInput()
+
+  // Capture and bind the adapter methods themselves. Reassigning `store.put`
+  // or `store.take` after construction cannot downgrade atomic semantics.
+  const put = options.store.put.bind(options.store)
+  const take = options.store.take.bind(options.store)
+
+  // Copy every option once. Mutating the caller-owned options object cannot
+  // relax policy or change transaction semantics after construction.
+  const snapshot = Object.freeze({
+    put,
+    take,
+    ttlSeconds,
+    maxSerializedBytes,
+    keyPrefix,
+    now,
+    generateState,
+  })
+
+  const storageKey = async (state: string): Promise<string> => (
+    `${snapshot.keyPrefix}${await hashState(state)}`
+  )
+
+  return Object.freeze({
+    async issue(input: OAuthStateIssueInput): Promise<string> {
+      assertIssueInput(input)
+      let state: string
+      let issuedAt: number
+      try {
+        state = snapshot.generateState()
+        issuedAt = snapshot.now()
+      } catch (error) {
+        throw new AuthError({ code: 'invalid_oauth_state', status: 500, cause: error })
+      }
+      if (typeof state !== 'string' || !OAUTH_STATE_PATTERN.test(state)) {
+        throw new AuthError({ code: 'invalid_oauth_state', status: 500 })
+      }
+      if (!Number.isSafeInteger(issuedAt) || issuedAt < 0) invalidInput()
+      const expiresAt = issuedAt + (snapshot.ttlSeconds * 1_000)
+      if (!Number.isSafeInteger(expiresAt)) invalidInput()
+
+      const payload: StoredOAuthState = {
+        v: 1,
+        tenantId: input.tenantId,
+        provider: input.provider,
+        redirectUri: input.redirectUri,
+        verifier: input.verifier,
+        ...(input.initiatingSessionId === undefined
+          ? {}
+          : { initiatingSessionId: input.initiatingSessionId }),
+        ...(input.returnTo === undefined ? {} : { returnTo: input.returnTo }),
+        issuedAt,
+        expiresAt,
+      }
+      const serialized = JSON.stringify(payload)
+      if (encoder.encode(serialized).byteLength > snapshot.maxSerializedBytes) invalidInput()
+
+      try {
+        await snapshot.put(
+          await storageKey(state),
+          serialized,
+          snapshot.ttlSeconds,
+        )
+      } catch (error) {
+        throw new AuthError({
+          code: 'auth_store_unavailable',
+          status: 503,
+          retryable: true,
+          cause: error,
+        })
+      }
+      return state
+    },
+
+    async consume(input: OAuthStateConsumeInput): Promise<OAuthStatePayload> {
+      assertConsumeInput(input)
+      let serialized: string | null
+      try {
+        serialized = await snapshot.take(await storageKey(input.state))
+      } catch (error) {
+        throw new AuthError({
+          code: 'auth_store_unavailable',
+          status: 503,
+          retryable: true,
+          cause: error,
+        })
+      }
+      if (serialized === null) {
+        throw new AuthError({ code: 'invalid_oauth_state', status: 400 })
+      }
+
+      const payload = parseStoredPayload(serialized, snapshot.maxSerializedBytes)
+      let currentTime: number
+      try {
+        currentTime = snapshot.now()
+      } catch (error) {
+        throw new AuthError({ code: 'invalid_oauth_state', status: 500, cause: error })
+      }
+      if (!Number.isSafeInteger(currentTime) || currentTime < 0) invalidInput()
+      if (payload.issuedAt > currentTime) {
+        throw new AuthError({ code: 'invalid_oauth_state', status: 400 })
+      }
+      if (payload.expiresAt <= currentTime) {
+        throw new AuthError({ code: 'oauth_state_expired', status: 400 })
+      }
+      if (
+        payload.tenantId !== input.tenantId
+        || payload.provider !== input.provider
+        || payload.redirectUri !== input.redirectUri
+        || payload.initiatingSessionId !== input.initiatingSessionId
+      ) {
+        throw new AuthError({ code: 'oauth_state_mismatch', status: 400 })
+      }
+
+      return Object.freeze({
+        tenantId: payload.tenantId,
+        provider: payload.provider,
+        redirectUri: payload.redirectUri,
+        verifier: payload.verifier,
+        ...(payload.initiatingSessionId === undefined
+          ? {}
+          : { initiatingSessionId: payload.initiatingSessionId }),
+        ...(payload.returnTo === undefined ? {} : { returnTo: payload.returnTo }),
+        issuedAt: payload.issuedAt,
+        expiresAt: payload.expiresAt,
+      })
+    },
+  })
+}