@owlmeans/server-auth 0.1.18-rc.8 → 0.1.18

package/src/re-captcha/token.ts

@@ -0,0 +1,89 @@
+import { AuthenticationType, AuthRole, AuthUnavailable, GUEST_ID } from '@owlmeans/auth'
+import type { AuthCredentials } from '@owlmeans/auth'
+import { extractAuthToken, trust } from '@owlmeans/auth-common/utils'
+import { EnvelopeKind, makeEnvelopeModel } from '@owlmeans/basic-envelope'
+import type { EnvelopeModel } from '@owlmeans/basic-envelope'
+import { TRUSTED } from '@owlmeans/config'
+import { memoHelper } from '@owlmeans/context'
+import { logger } from '@owlmeans/log'
+import { RecordExists } from '@owlmeans/resource'
+import type { Resource } from '@owlmeans/resource'
+import { AUTH_CACHE, AUTH_SRV_KEY, AUTHEN_TIMEFRAME } from '../consts.js'
+import type { AuthSpent } from '../types.js'
+import type { Config, Context } from '../types.local.js'
+import type { ReCaptchaCarrier, ReCaptchaGuest, ReCaptchaTokenHelper } from './types.js'
+
+const log = logger('server-auth:re-captcha')
+
+export const makeReCaptchaTokenHelper = (context: Context): ReCaptchaTokenHelper => {
+  const refuse = (reason: string): null => {
+    log.debug('reCAPTCHA token refused', { reason }, { event: 'auth.refused' })
+    return null
+  }
+
+  const verify = async (token: string): Promise<ReCaptchaGuest | null> => {
+    let envelope: EnvelopeModel<AuthCredentials>
+    try {
+      envelope = makeEnvelopeModel<AuthCredentials>(token, EnvelopeKind.Token)
+    } catch {
+      return refuse('token')
+    }
+    if (envelope.type() !== AuthenticationType.ReCaptcha) {
+      return refuse('type')
+    }
+    // A guest token lives no longer than its spend record does, so it can never be spent twice.
+    const ttl = envelope.envelope.ttl
+    if (ttl == null || ttl > AUTHEN_TIMEFRAME) {
+      return refuse('ttl')
+    }
+
+    const signer = await trust<Config, Context>(context, TRUSTED, AUTH_SRV_KEY)
+    // Signature and expiry: an envelope past `dt + ttl` does not verify.
+    if (!await envelope.verify(signer.key)) {
+      return refuse('signature')
+    }
+
+    const credential = envelope.message<AuthCredentials>()
+    if (credential == null || typeof credential !== 'object') {
+      return refuse('token')
+    }
+    if (credential.credential !== signer.user.id) {
+      return refuse('issuer')
+    }
+    if (credential.type !== AuthenticationType.ReCaptcha || credential.role !== AuthRole.Guest
+      || credential.userId !== GUEST_ID) {
+      return refuse('guest')
+    }
+    if (typeof credential.challenge !== 'string' || credential.challenge === '') {
+      return refuse('challenge')
+    }
+
+    return { credential, challenge: credential.challenge, expiresAt: new Date(envelope.envelope.dt + ttl) }
+  }
+
+  const inspect = async (req: ReCaptchaCarrier): Promise<ReCaptchaGuest | null> => {
+    const token = extractAuthToken(req, AuthenticationType.ReCaptcha)
+
+    return token == null || token === '' ? null : await verify(token)
+  }
+
+  const spend = async (guest: ReCaptchaGuest): Promise<boolean> => {
+    try {
+      await context.resource<Resource<AuthSpent>>(AUTH_CACHE)
+        .create({ id: guest.challenge }, { ttl: AUTHEN_TIMEFRAME / 1000 })
+    } catch (error) {
+      if (error instanceof RecordExists || (error as { type?: string } | null)?.type === RecordExists.typeName) {
+        log.debug('reCAPTCHA token refused', { reason: 'spent' }, { event: 'auth.refused' })
+        return false
+      }
+      throw new AuthUnavailable('auth-cache')
+    }
+
+    return true
+  }
+
+  return { inspect, verify, spend }
+}
+
+/** The reCAPTCHA token checks of a context — built once per context. */
+export const reCaptchaTokenOf = memoHelper.oncePer(makeReCaptchaTokenHelper)

package/src/re-captcha/types.ts

@@ -0,0 +1,45 @@
+import type { AuthCredentials } from '@owlmeans/auth'
+import type { AbstractRequest } from '@owlmeans/entrypoint'
+
+/** A reCAPTCHA guest token that passed every check but the spend. */
+export interface ReCaptchaGuest {
+  /**
+   * The credential the auth manager signed: `GUEST_ID`, role Guest, type ReCaptcha, stamped with
+   * the auth service record's id. It names nobody.
+   */
+  credential: AuthCredentials
+  /** The server-issued challenge the token carries — the key it is spent under in `AUTH_CACHE`. */
+  challenge: string
+  /** When the token stops being accepted. */
+  expiresAt: Date
+}
+
+/** Anything that carries request headers: an entrypoint request, or a raw Fastify request. */
+export interface ReCaptchaCarrier extends Partial<Pick<AbstractRequest, 'headers'>> {}
+
+/**
+ * The checks of a reCAPTCHA guest token (`Authorization: RE-CAPTCHA <token>`), bound to the context
+ * whose `TRUSTED` record `AUTH_SRV_KEY` signed it and whose `AUTH_CACHE` spends it.
+ */
+export interface ReCaptchaTokenHelper {
+  /**
+   * The guest a request carries, checked WITHOUT spending: envelope type, signature by the auth
+   * service key, TTL (at most `AUTHEN_TIMEFRAME`), the auth record's stamp, type ReCaptcha, role
+   * Guest, `GUEST_ID`, a server-issued challenge. Made for a pre-parse check (before a body is read);
+   * the route itself still needs the guard, which spends.
+   *
+   * @returns `null` for a request without such a header or with a token that fails a check.
+   * @throws {SyntaxError} when the context has no `AUTH_SRV_KEY` trusted record (a configuration fault).
+   */
+  inspect: (req: ReCaptchaCarrier) => Promise<ReCaptchaGuest | null>
+  /** {@link inspect} for a bare token (the value after `RE-CAPTCHA `). */
+  verify: (token: string) => Promise<ReCaptchaGuest | null>
+  /**
+   * Spend the token: an atomic create-once of its challenge in `AUTH_CACHE` (Redis `SET NX` in a
+   * backend context), under the same key a bearer exchange and the IAM finalizer claim.
+   *
+   * @returns `false` when the token was spent before.
+   * @throws {AuthUnavailable} when the cache cannot answer.
+   */
+  spend: (guest: ReCaptchaGuest) => Promise<boolean>
+}

package/src/service.ts

@@ -1,25 +1,85 @@
-import type { ServerContext, ServerConfig } from '@owlmeans/server-context'
+import type { ServerContext } from '@owlmeans/server-context'
 import { TRUSTED } from '@owlmeans/config'
 import { AUTH_CACHE, AUTH_SRV_KEY, AUTHEN_TIMEFRAME, DEFAULT_ALIAS } from './consts.js'
 import type { AuthServiceAppend, AuthService, AuthSpent } from './types.js'
 import { assertContext, createService } from '@owlmeans/context'
 import { EnvelopeKind, makeEnvelopeModel } from '@owlmeans/basic-envelope'
-import type { Auth, AuthCredentials } from '@owlmeans/auth'
-import { AuthenFailed, AuthorizationError, AuthroizationType } from '@owlmeans/auth'
+import { type Auth, type AuthCredentials, AuthenFailed, AuthenticationType, AuthorizationError, AuthroizationType, AuthUnavailable } from '@owlmeans/auth'
 import type { AbstractRequest, AbstractResponse } from '@owlmeans/entrypoint'
 import type { Resource } from '@owlmeans/resource'
 import { createStaticResource } from '@owlmeans/static-resource'
 import { trust, extractAuthToken } from '@owlmeans/auth-common/utils'
+import { ENTITY_RESOLVER, type EntityResolverService, TOKEN_UPDATE } from '@owlmeans/auth-common'
+import { AUTH_IDENTITY_PROFILE, type IdentityProfile, type IdentityProfileResource } from '@owlmeans/server-auth-identity'
+import { appendMemoryAuthSessionManager, AUTH_SESSION_MANAGER, AUTH_SESSION_TTL, type AuthSessionManager } from '@owlmeans/server-auth-session'
+import { idHelper } from '@owlmeans/basic-ids'
+import { logger } from '@owlmeans/log'
+import type { Config, Context } from './types.local.js'
 
-type Config = ServerConfig
-type Context = ServerContext<Config>
+
+const log = logger('server-auth')
 
 export const makeAuthService = (alias: string = DEFAULT_ALIAS): AuthService => {
+  /**
+   * A refused token exchange — the manager's token presented to open a session. Logged with the
+   * reason and the account id only; returns the error for the caller to throw.
+   */
+  const refuse = (reason: string, error: AuthenFailed, userId?: string): AuthenFailed => {
+    const accountId = userId == null ? undefined
+      : userId.includes('@') ? `*@${userId.slice(userId.lastIndexOf('@') + 1)}` : userId
+    log.warn('Session exchange refused', { reason, ...(accountId != null ? { accountId } : {}) }, { event: 'auth.refused' })
+    return error
+  }
+
   const location = `server-auth:${alias}`
 
   const cache = (context: Context): Resource<AuthSpent> =>
     context.resource<Resource<AuthSpent>>(AUTH_CACHE)
 
+  const sessions = (context: Context): AuthSessionManager | null =>
+    context.hasService(AUTH_SESSION_MANAGER)
+      ? context.service<AuthSessionManager>(AUTH_SESSION_MANAGER)
+      : null
+
+  const entityIdFor = async (context: Context, entitySlug: string | undefined): Promise<string | null> => {
+    if (entitySlug == null || entitySlug === '') return null
+    if (!context.hasService(ENTITY_RESOLVER)) return entitySlug
+    const entity = await context.service<EntityResolverService>(ENTITY_RESOLVER).resolve(entitySlug)
+    return entity?.id ?? null
+  }
+
+  const refresh = async (context: Context, auth: Auth, version: number): Promise<Auth | null> => {
+    const entityId = await entityIdFor(context, auth.entitySlug)
+    if (entityId == null || auth.profileId == null || !context.hasResource(AUTH_IDENTITY_PROFILE)) return null
+    const profiles = context.resource<IdentityProfileResource>(AUTH_IDENTITY_PROFILE)
+    let profile: IdentityProfile | null = null
+    try {
+      profile = await profiles.load({ entityId, profileId: auth.profileId })
+    } catch {
+      // A missing profile is a definitive authentication refusal; a failed profile store is an
+      // availability dependency and must not look like a revoked browser session.
+      throw new AuthUnavailable('identity-profile')
+    }
+    if (profile == null || (profile.expiresAt != null && new Date(profile.expiresAt).getTime() <= Date.now())) return null
+    return {
+      ...auth,
+      userId: profile.userId ?? auth.userId,
+      role: profile.role,
+      scopes: profile.scopes ?? [],
+      ...(profile.permissions != null ? { permissions: profile.permissions } : {}),
+      authorizationVersion: version,
+      createdAt: new Date()
+    }
+  }
+
+  const sign = async (context: Context, auth: Auth): Promise<string> => {
+    const trusted = await trust<Config, Context>(context, TRUSTED, context.cfg.alias ?? context.cfg.service)
+    const ttl = auth.expiresAt == null ? AUTH_SESSION_TTL : Math.max(0, new Date(auth.expiresAt).getTime() - Date.now())
+    const authorization = await makeEnvelopeModel<Auth>(AuthroizationType.Ed25519BasicToken)
+      .send(auth, ttl).sign(trusted.key, EnvelopeKind.Token)
+    return `${AuthroizationType.Ed25519BasicToken.toUpperCase()} ${authorization}`
+  }
+
   const service: AuthService = createService<AuthService>(alias, {
     match: async req => extractAuthToken(req, AuthroizationType.Ed25519BasicToken) != null,
 
@@ -37,7 +97,29 @@ export const makeAuthService = (alias: string = DEFAULT_ALIAS): AuthService => {
         return false as T
       }
 
-      res.resolve(envelope.message())
+      let auth = envelope.message()
+      const manager = sessions(context)
+      if (manager != null) {
+        if (auth.sessionId == null) return false as T
+        let decision
+        try {
+          decision = await manager.inspect(auth.sessionId)
+        } catch {
+          // Registry availability is a security dependency. A guard cannot authenticate through it.
+          throw new AuthUnavailable('session-registry')
+        }
+        if (decision.state !== 'active' && decision.state !== 'refresh') return false as T
+        if (decision.state === 'refresh') {
+          const refreshed = await refresh(context, auth, decision.version)
+          if (refreshed == null) return false as T
+          auth = refreshed
+          const replacement = await sign(context, auth)
+          res.responseProvider?.header(TOKEN_UPDATE, replacement)
+          req.headers = { ...req.headers, authorization: replacement }
+        }
+      }
+
+      res.resolve(auth)
 
       return true as T
     },
@@ -51,8 +133,19 @@ export const makeAuthService = (alias: string = DEFAULT_ALIAS): AuthService => {
       if (!await envelope.verify(trusted.key)) {
         throw new AuthorizationError('unpack')
       }
-
-      return envelope.message()
+      const auth = envelope.message()
+      const manager = sessions(context)
+      if (manager != null) {
+        if (auth.sessionId == null) throw new AuthorizationError('session')
+        let decision
+        try {
+          decision = await manager.inspect(auth.sessionId)
+        } catch {
+          throw new AuthUnavailable('session-registry')
+        }
+        if (decision.state !== 'active') throw new AuthorizationError('session')
+      }
+      return auth
     },
 
     authenticated: async () => {
@@ -65,25 +158,32 @@ export const makeAuthService = (alias: string = DEFAULT_ALIAS): AuthService => {
 
       const authService = await trust<Config, Context>(context, TRUSTED, AUTH_SRV_KEY)
       if (!await envelope.verify(authService.key)) {
-        throw new AuthenFailed()
+        throw refuse('signature', new AuthenFailed())
       }
 
       const credentials = envelope.message()
       const msg = credentials.challenge
 
-      // @TODO This operation is not atomic in case of redis store usage and scling
+      // A reCAPTCHA token proves a solved challenge, never a person: it is spent by
+      // `makeReCaptchaGuard` on the one route that takes it and never becomes a session. Refused
+      // before the spend, so a token presented here stays usable where it belongs.
+      if (envelope.type() === AuthenticationType.ReCaptcha || credentials.type === AuthenticationType.ReCaptcha) {
+        throw refuse('guest', new AuthenFailed('guest'), credentials.userId)
+      }
 
       try {
         await cache(context).create({ id: msg }, { ttl: AUTHEN_TIMEFRAME / 1000 })
       } catch {
-        throw new AuthenFailed()
+        throw refuse('replay', new AuthenFailed(), credentials.userId)
       }
 
       if (credentials.credential !== authService.user.id) {
-        throw new AuthenFailed()
+        throw refuse('issuer', new AuthenFailed(), credentials.userId)
       }
 
       // @TODO Move to a plugin
+      const issuedAt = Date.now()
+      const expiresAt = new Date(issuedAt + AUTH_SESSION_TTL)
       const auth: Auth = {
         token: credentials.challenge,
         userId: credentials.userId,
@@ -92,16 +192,26 @@ export const makeAuthService = (alias: string = DEFAULT_ALIAS): AuthService => {
         type: AuthroizationType.Ed25519BasicToken,
         source: context.cfg.service,
         profileId: credentials.profileId,
-        entityId: credentials.entityId,
+        entitySlug: credentials.entitySlug,
         isUser: true,
-        createdAt: new Date()
+        createdAt: new Date(issuedAt),
+        expiresAt,
+        sessionId: idHelper.uuid(),
+        authorizationVersion: 1
+      }
+      const manager = sessions(context)
+      if (manager != null) {
+        const entityId = await entityIdFor(context, auth.entitySlug)
+        if (entityId == null || auth.profileId == null) throw refuse('session', new AuthenFailed('session'), auth.userId)
+        const decision = await manager.register({
+          id: auth.sessionId!, kind: 'bearer', entityId, profileId: auth.profileId,
+          issuedAt, expiresAt: expiresAt.getTime()
+        })
+        if (decision.state !== 'active') throw refuse('session', new AuthenFailed('session'), auth.userId)
+        auth.authorizationVersion = decision.version
       }
 
-      const trusted = await trust<Config, Context>(context, TRUSTED, context.cfg.alias ?? context.cfg.service)
-      const authorization = await makeEnvelopeModel<Auth>(AuthroizationType.Ed25519BasicToken)
-        .send(auth, null).sign(trusted.key, EnvelopeKind.Token)
-
-      return { token: `${AuthroizationType.Ed25519BasicToken.toUpperCase()} ${authorization}` }
+      return { token: await sign(context, auth) }
     }
   })
 
@@ -116,6 +226,10 @@ export const appendAuthService = <C extends Config, T extends ServerContext<C>>(
     ctx.registerResource(createStaticResource(AUTH_CACHE))
   }
 
+  // Every standalone server gets an expiring process-local registry. Scaled deployments replace
+  // it with appendRedisAuthSessionManager before calling this helper.
+  appendMemoryAuthSessionManager(ctx)
+
   const service = makeAuthService(alias)
   const context = ctx as T & AuthServiceAppend
 

package/src/types.local.ts

@@ -0,0 +1,5 @@
+import type { ServerContext, ServerConfig } from '@owlmeans/server-context'
+
+export type Config = ServerConfig
+
+export type Context = ServerContext<Config>

package/tests/context.ts

@@ -1,4 +1,4 @@
-import { AppType, Layer, makeBasicContext } from '@owlmeans/context'
+import { AppType, makeBasicContext } from '@owlmeans/context'
 import type { BasicConfig, BasicContext } from '@owlmeans/context'
 import { createStaticResource } from '@owlmeans/static-resource'
 import { makeMemoryTrustedResource, makeFixtureKeyPair } from '@owlmeans/test-auth'
@@ -25,6 +25,8 @@ export const makeTestContext = () => {
     id: authServiceKP.exportAddress(),
     name: AUTH_SRV_KEY,
     credential: authServiceKP.exportPublic(),
+    // Local, deterministic test-only key: the manager signs its synthetic exchange envelope.
+    secret: authServiceKP.export(),
     scopes: ['*'],
   }
 
@@ -39,7 +41,6 @@ export const makeTestContext = () => {
   const cfg: BasicConfig = {
     ready: false,
     service: SERVICE_NAME,
-    layer: Layer.Service,
     type: AppType.Backend,
     services: {},
   }