@atproto/bsky 0.0.198 → 0.0.199

package/src/api/age-assurance/redirects/kws-age-verified.ts

@@ -0,0 +1,107 @@
+import express, { RequestHandler } from 'express'
+import { ageAssuranceLogger as logger } from '../../../logger'
+import { getClientUa, validateSignature } from '../../kws/util'
+import { AGE_ASSURANCE_CONFIG } from '../const'
+import { parseKWSAgeVerifiedStatus } from '../kws/age-verified'
+import {
+  type KWSExternalPayloadV2,
+  parseKWSExternalPayloadV2,
+} from '../kws/external-payload'
+import { createEvent } from '../stash'
+import { AppContextWithAA } from '../types'
+import { computeAgeAssuranceAccessOrThrow } from '../util'
+
+function parseQueryParams(
+  ctx: AppContextWithAA,
+  req: express.Request,
+): {
+  status: string
+  externalPayload: string
+} {
+  try {
+    const status = String(req.query.status)
+    const externalPayload = String(req.query.externalPayload)
+    const signature = String(req.query.signature)
+
+    validateSignature(
+      ctx.cfg.kws.ageVerifiedRedirectSecret,
+      `${status}:${externalPayload}`,
+      signature,
+    )
+
+    return {
+      status,
+      externalPayload,
+    }
+  } catch (err) {
+    throw new Error('Invalid KWS API request', { cause: err })
+  }
+}
+
+export const handler =
+  (ctx: AppContextWithAA): RequestHandler =>
+  async (req: express.Request, res: express.Response) => {
+    let externalPayload: KWSExternalPayloadV2 | undefined
+
+    try {
+      const query = parseQueryParams(ctx, req)
+      const { verified, verifiedMinimumAge } = parseKWSAgeVerifiedStatus(
+        query.status,
+      )
+      externalPayload = parseKWSExternalPayloadV2(query.externalPayload)
+      const { actorDid, attemptId, countryCode, regionCode } = externalPayload
+
+      /*
+       * KWS does not send unverified webhooks for age verification, so we
+       * expect all webhooks to be verified. This is just a sanity check.
+       */
+      if (!verified) {
+        const message =
+          'Expected KWS verification redirect to have verified status'
+        logger.error({}, message)
+        throw new Error(message)
+      }
+
+      const { access } = computeAgeAssuranceAccessOrThrow(
+        AGE_ASSURANCE_CONFIG,
+        {
+          countryCode,
+          regionCode,
+          verifiedMinimumAge,
+        },
+      )
+
+      await createEvent(ctx, actorDid, {
+        attemptId,
+        // Assumes `app.set('trust proxy', ...)` configured with `true` or specific values.
+        completeIp: req.ip,
+        completeUa: getClientUa(req),
+        countryCode,
+        regionCode,
+        status: 'assured',
+        access,
+      })
+
+      const q = new URLSearchParams({ actorDid, result: 'success' })
+
+      return res
+        .status(302)
+        .setHeader('Location', `${ctx.cfg.kws.redirectUrl}?${q}`)
+        .end()
+    } catch (err) {
+      logger.error(
+        { err, ...externalPayload },
+        'Failed to handle KWS verification redirect',
+      )
+
+      const q = new URLSearchParams({
+        ...(externalPayload ? { actorDid: externalPayload.actorDid } : {}),
+        result: 'unknown',
+      })
+
+      return res
+        .status(302)
+        .setHeader('Location', `${ctx.cfg.kws.redirectUrl}?${q}`)
+        .end()
+    }
+  }

package/src/api/age-assurance/stash.ts

@@ -0,0 +1,22 @@
+import { TID } from '@atproto/common'
+import { AppContext } from '../../context'
+import { Event as AgeAssuranceEvent } from '../../lexicon/types/app/bsky/ageassurance/defs'
+import { Namespaces } from '../../stash'
+
+export async function createEvent(
+  ctx: AppContext,
+  actorDid: string,
+  event: Omit<AgeAssuranceEvent, 'createdAt'>,
+) {
+  const payload: AgeAssuranceEvent = {
+    createdAt: new Date().toISOString(),
+    ...event,
+  }
+  await ctx.stashClient.create({
+    actorDid: actorDid,
+    namespace: Namespaces.AppBskyAgeassuranceDefsEvent,
+    key: TID.nextStr(),
+    payload,
+  })
+  return payload
+}

package/src/api/age-assurance/types.ts

@@ -0,0 +1,10 @@
+import { KwsConfig, ServerConfig } from '../../config'
+import { AppContext } from '../../context'
+import { KwsClient } from '../../kws'
+
+export type AppContextWithAA = AppContext & {
+  kwsClient: KwsClient
+  cfg: ServerConfig & {
+    kws: KwsConfig
+  }
+}

package/src/api/age-assurance/util.ts

@@ -0,0 +1,66 @@
+import {
+  type AppBskyAgeassuranceDefs,
+  computeAgeAssuranceRegionAccess,
+  getAgeAssuranceRegionConfig,
+} from '@atproto/api'
+
+/**
+ * Compute age assurance access based on verified minimum age. Thrown errors
+ * are internal errors, so handle them accordingly.
+ */
+export function computeAgeAssuranceAccessOrThrow(
+  config: AppBskyAgeassuranceDefs.Config,
+  {
+    countryCode,
+    regionCode,
+    verifiedMinimumAge,
+  }: {
+    countryCode: string
+    regionCode?: string
+    verifiedMinimumAge: number
+  },
+) {
+  const region = getAgeAssuranceRegionConfig(config, {
+    countryCode,
+    regionCode,
+  })
+
+  if (region) {
+    const result = computeAgeAssuranceRegionAccess(region, {
+      assuredAge: verifiedMinimumAge,
+      /*
+       * We don't care about this here, this is a client-only rule. If we have
+       * verified data, we can use that, and the account creation date is
+       * irrelevant.
+       */
+      accountCreatedAt: undefined,
+    })
+
+    if (result) {
+      return result
+    } else {
+      /*
+       * If we don't get a result, it's because none of the rules matched,
+       * which is a configuration error: there should always be a default
+       * rule.
+       */
+      throw new Error('Cound not compute age assurance region access')
+    }
+  } else {
+    /**
+     * If we had geolocation data, but we don't have a region config for this
+     * geolocation, then it means a user outside of our configured regions
+     * has completed age verification. In this case, we can't determine their
+     * access level, so we throw an error.
+     *
+     * This case is also guarded in `app.bsky.ageassurance.begin`.
+     */
+    throw new Error('Could not get config for region')
+  }
+}
+
+export function createLocationString(countryCode: string, regionCode?: string) {
+  return regionCode
+    ? `${countryCode.toUpperCase()}-${regionCode.toUpperCase()}`
+    : countryCode.toUpperCase()
+}

package/src/api/age-assurance/webhooks/kws-age-verified.ts

@@ -0,0 +1,75 @@
+import express, { RequestHandler } from 'express'
+import { ageAssuranceLogger as logger } from '../../../logger'
+import { AGE_ASSURANCE_CONFIG } from '../const'
+import {
+  type KWSWebhookAgeVerified,
+  parseKWSAgeVerifiedWebhook,
+} from '../kws/age-verified'
+import { parseKWSExternalPayloadV2 } from '../kws/external-payload'
+import { createEvent } from '../stash'
+import { type AppContextWithAA } from '../types'
+import { computeAgeAssuranceAccessOrThrow } from '../util'
+
+export const handler =
+  (ctx: AppContextWithAA): RequestHandler =>
+  async (req: express.Request, res: express.Response) => {
+    let body: KWSWebhookAgeVerified
+    try {
+      body = parseKWSAgeVerifiedWebhook(req.body)
+    } catch (err) {
+      const message = 'Failed to parse KWS webhook body'
+      logger.error({ err }, message)
+      return res.status(400).json({ error: message })
+    }
+
+    const { status, externalPayload } = body.payload
+    const { verified, verifiedMinimumAge } = status
+    const { actorDid, countryCode, regionCode, attemptId } =
+      parseKWSExternalPayloadV2(externalPayload)
+
+    /*
+     * KWS does not send unverified webhooks for age verification, so we
+     * expect all webhooks to be verified. This is just a sanity check.
+     */
+    if (!verified) {
+      const message = 'Expected KWS webhook to have verified status'
+      logger.error({}, message)
+      return res.status(400).json({ error: message })
+    }
+
+    let result: ReturnType<typeof computeAgeAssuranceAccessOrThrow> | undefined
+    try {
+      result = computeAgeAssuranceAccessOrThrow(AGE_ASSURANCE_CONFIG, {
+        countryCode,
+        regionCode,
+        verifiedMinimumAge,
+      })
+    } catch (err) {
+      // internal errors
+      logger.error(
+        { err, attemptId, actorDid, countryCode, regionCode },
+        'Failed to compute age assurance access',
+      )
+    }
+
+    try {
+      if (result) {
+        await createEvent(ctx, actorDid, {
+          attemptId,
+          countryCode,
+          regionCode,
+          status: 'assured',
+          access: result.access,
+        })
+      }
+
+      return res.status(200).end()
+    } catch (err) {
+      const message = 'Failed to handle KWS webhook'
+      logger.error(
+        { err, attemptId, actorDid, countryCode, regionCode },
+        message,
+      )
+      return res.status(500).json({ error: message })
+    }
+  }

package/src/api/app/bsky/ageassurance/begin.ts

@@ -0,0 +1,167 @@
+import crypto from 'node:crypto'
+import { isEmailValid } from '@hapi/address'
+import { isDisposableEmail } from 'disposable-email-domains-js'
+import { getAgeAssuranceRegionConfig } from '@atproto/api'
+import {
+  InvalidRequestError,
+  MethodNotImplementedError,
+} from '@atproto/xrpc-server'
+import { AppContext } from '../../../../context'
+import { Server } from '../../../../lexicon'
+import { InputSchema } from '../../../../lexicon/types/app/bsky/ageassurance/begin'
+import { httpLogger as log } from '../../../../logger'
+import { ActorInfo } from '../../../../proto/bsky_pb'
+import { AGE_ASSURANCE_CONFIG } from '../../../age-assurance/const'
+import {
+  KWS_SUPPORTED_LANGUAGES,
+  KWS_V2_COUNTRIES,
+} from '../../../age-assurance/kws/const'
+import {
+  KWSExternalPayloadTooLargeError,
+  KWSExternalPayloadVersion,
+  serializeKWSExternalPayloadV2,
+} from '../../../age-assurance/kws/external-payload'
+import { createEvent } from '../../../age-assurance/stash'
+import { createLocationString } from '../../../age-assurance/util'
+import { getClientUa } from '../../../kws/util'
+
+export default function (server: Server, ctx: AppContext) {
+  server.app.bsky.ageassurance.begin({
+    auth: ctx.authVerifier.standard,
+    handler: async ({ auth, input, req }) => {
+      if (!ctx.kwsClient) {
+        throw new MethodNotImplementedError(
+          'This service is not configured to support age assurance.',
+        )
+      }
+
+      const actorDid = auth.credentials.iss
+      const actorInfo = await getAgeVerificationState(ctx, actorDid)
+
+      if (actorInfo?.ageAssuranceStatus) {
+        if (
+          actorInfo.ageAssuranceStatus.status !== 'unknown' &&
+          actorInfo.ageAssuranceStatus.status !== 'pending'
+        ) {
+          throw new InvalidRequestError(
+            `Cannot initiate age assurance flow from current state: ${actorInfo.ageAssuranceStatus.status}`,
+            'InvalidInitiation',
+          )
+        }
+      }
+
+      const attemptId = crypto.randomUUID()
+      const { email, language, countryCode, regionCode } = validateInput(
+        input.body,
+      )
+
+      let externalPayload: string
+      try {
+        externalPayload = serializeKWSExternalPayloadV2({
+          version: KWSExternalPayloadVersion.V2,
+          actorDid,
+          attemptId,
+          countryCode,
+          regionCode,
+        })
+      } catch (err) {
+        if (err instanceof KWSExternalPayloadTooLargeError) {
+          log.error({ err, actorDid }, err.message)
+          throw new InvalidRequestError(
+            'Age Assurance flow failed because DID is too long',
+            'DidTooLong',
+          )
+        }
+        throw err
+      }
+
+      /*
+       * Determine if age assurance config exists for this region. The calling
+       * application should already have checked for this, so this is just a
+       * safeguard.
+       */
+      const region = getAgeAssuranceRegionConfig(AGE_ASSURANCE_CONFIG, {
+        countryCode,
+        regionCode,
+      })
+      if (!region) {
+        const message = 'Age Assurance is not required in this region'
+        log.error({ actorDid, countryCode, regionCode }, message)
+        throw new InvalidRequestError(message, 'RegionNotSupported')
+      }
+
+      const location = createLocationString(countryCode, regionCode)
+
+      if (KWS_V2_COUNTRIES.has(region.countryCode)) {
+        // `age-verified` flow
+        await ctx.kwsClient.sendAgeVerifiedFlowEmail({
+          location,
+          email,
+          externalPayload,
+          language,
+        })
+      } else {
+        // `adult-verified` flow is what we've been using prior to `age-verified`
+        await ctx.kwsClient.sendAdultVerifiedFlowEmail({
+          location,
+          email,
+          externalPayload,
+          language,
+        })
+      }
+
+      const event = await createEvent(ctx, actorDid, {
+        attemptId,
+        email,
+        // Assumes `app.set('trust proxy', ...)` configured with `true` or specific values.
+        initIp: req.ip,
+        initUa: getClientUa(req),
+        status: 'pending',
+        access: 'unknown',
+        countryCode,
+        regionCode,
+      })
+
+      return {
+        encoding: 'application/json',
+        body: {
+          lastInitiatedAt: event.createdAt,
+          status: 'pending',
+          access: 'unknown',
+        },
+      }
+    },
+  })
+}
+
+function validateInput({ email, language, ...rest }: InputSchema): InputSchema {
+  if (!isEmailValid(email) || isDisposableEmail(email)) {
+    throw new InvalidRequestError(
+      'This email address is not supported, please use a different email.',
+      'InvalidEmail',
+    )
+  }
+
+  return {
+    email,
+    language: KWS_SUPPORTED_LANGUAGES.has(language) ? language : 'en',
+    ...rest,
+  }
+}
+
+async function getAgeVerificationState(
+  ctx: AppContext,
+  actorDid: string,
+): Promise<ActorInfo | undefined> {
+  try {
+    const res = await ctx.dataplane.getActors({
+      dids: [actorDid],
+      returnAgeAssuranceForDids: [actorDid],
+      skipCacheForDids: [actorDid],
+    })
+
+    return res.actors[0]
+  } catch (err) {
+    return undefined
+  }
+}

package/src/api/app/bsky/ageassurance/getConfig.ts

@@ -0,0 +1,15 @@
+import { AGE_ASSURANCE_CONFIG } from '../../../../api/age-assurance/const'
+import { AppContext } from '../../../../context'
+import { Server } from '../../../../lexicon'
+
+export default function (server: Server, ctx: AppContext) {
+  server.app.bsky.ageassurance.getConfig({
+    auth: ctx.authVerifier.standardOptional,
+    handler: async () => {
+      return {
+        encoding: 'application/json',
+        body: AGE_ASSURANCE_CONFIG,
+      }
+    },
+  })
+}

package/src/api/app/bsky/ageassurance/getState.ts

@@ -0,0 +1,53 @@
+import { UpstreamFailureError } from '@atproto/xrpc-server'
+import { AppContext } from '../../../../context'
+import { Server } from '../../../../lexicon'
+import { ActorInfo } from '../../../../proto/bsky_pb'
+
+export default function (server: Server, ctx: AppContext) {
+  server.app.bsky.ageassurance.getState({
+    auth: ctx.authVerifier.standard,
+    handler: async ({ auth }) => {
+      const viewer = auth.credentials.iss
+      const actor = await getActorInfo(ctx, viewer)
+
+      return {
+        encoding: 'application/json',
+        body: {
+          state: {
+            lastInitiatedAt:
+              actor.ageAssuranceStatus?.lastInitiatedAt
+                ?.toDate()
+                .toISOString() || undefined,
+            status: actor.ageAssuranceStatus?.status || 'unknown',
+            access: actor.ageAssuranceStatus?.access || 'unknown',
+          },
+          metadata: {
+            accountCreatedAt:
+              actor.createdAt?.toDate().toISOString() || undefined,
+          },
+        },
+      }
+    },
+  })
+}
+
+const getActorInfo = async (
+  ctx: AppContext,
+  actorDid: string,
+): Promise<ActorInfo> => {
+  try {
+    const res = await ctx.dataplane.getActors({
+      dids: [actorDid],
+      returnAgeAssuranceForDids: [actorDid],
+      skipCacheForDids: [actorDid],
+    })
+
+    return res.actors[0]
+  } catch (err) {
+    throw new UpstreamFailureError(
+      'Cannot get current age assurance state',
+      'GetAgeAssuranceStateFailed',
+      { cause: err },
+    )
+  }
+}

package/src/api/external.ts

@@ -1,5 +1,6 @@
 import { Router } from 'express'
 import { AppContext } from '../context'
+import * as aaApi from './age-assurance'
 import * as kwsApi from './kws'
 
 export const createRouter = (ctx: AppContext): Router => {
@@ -7,6 +8,7 @@ export const createRouter = (ctx: AppContext): Router => {
 
   if (ctx.kwsClient) {
     router.use('/kws', kwsApi.createRouter(ctx))
+    router.use(aaApi.createRouter(ctx))
   }
 
   return router

package/src/api/index.ts

@@ -5,6 +5,9 @@ import getProfiles from './app/bsky/actor/getProfiles'
 import getSuggestions from './app/bsky/actor/getSuggestions'
 import searchActors from './app/bsky/actor/searchActors'
 import searchActorsTypeahead from './app/bsky/actor/searchActorsTypeahead'
+import aaBegin from './app/bsky/ageassurance/begin'
+import aaGetConfig from './app/bsky/ageassurance/getConfig'
+import aaGetState from './app/bsky/ageassurance/getState'
 import createBookmark from './app/bsky/bookmark/createBookmark'
 import deleteBookmark from './app/bsky/bookmark/deleteBookmark'
 import getBookmarks from './app/bsky/bookmark/getBookmarks'
@@ -156,6 +159,9 @@ export default function (server: Server, ctx: AppContext) {
   getTaggedSuggestions(server, ctx)
   getAgeAssuranceState(server, ctx)
   initAgeAssurance(server, ctx)
+  aaGetConfig(server, ctx)
+  aaGetState(server, ctx)
+  aaBegin(server, ctx)
   // com.atproto
   getSubjectStatus(server, ctx)
   updateSubjectStatus(server, ctx)

package/src/api/kws/api.ts

@@ -1,42 +1,41 @@
 import express, { RequestHandler } from 'express'
 import { httpLogger as log } from '../../logger'
+import { AGE_ASSURANCE_CONFIG } from '../age-assurance/const'
 import {
-  AppContextWithKwsClient,
-  KwsVerificationIntermediateQuery,
-  KwsVerificationQuery,
-  verificationIntermediateQuerySchema,
-} from './types'
+  KWSExternalPayloadVersion,
+  parseKWSExternalPayloadV1WithV2Compat,
+} from '../age-assurance/kws/external-payload'
+import { createEvent } from '../age-assurance/stash'
+import { computeAgeAssuranceAccessOrThrow } from '../age-assurance/util'
+import { AppContextWithKwsClient } from './types'
 import {
   createStashEvent,
   getClientUa,
-  parseExternalPayload,
   parseStatus,
   validateSignature,
 } from './util'
 
-const validateRequest = (
+function parseQueryParams(
   ctx: AppContextWithKwsClient,
   req: express.Request,
-): KwsVerificationQuery => {
+): {
+  status: string
+  externalPayload: string
+} {
   try {
-    const intermediate: KwsVerificationIntermediateQuery =
-      verificationIntermediateQuerySchema.parse({
-        externalPayload: req.query.externalPayload,
-        signature: req.query.signature,
-        status: req.query.status,
-      })
+    const status = String(req.query.status)
+    const externalPayload = String(req.query.externalPayload)
+    const signature = String(req.query.signature)
 
-    const data = `${intermediate.status}:${intermediate.externalPayload}`
     validateSignature(
       ctx.cfg.kws.verificationSecret,
-      data,
-      intermediate.signature,
+      `${status}:${externalPayload}`,
+      signature,
     )
 
     return {
-      ...intermediate,
-      externalPayload: parseExternalPayload(intermediate.externalPayload),
-      status: parseStatus(intermediate.status),
+      status,
+      externalPayload,
     }
   } catch (err) {
     throw new Error('Invalid KWS API request', { cause: err })
@@ -48,29 +47,51 @@ export const verificationHandler =
   async (req: express.Request, res: express.Response) => {
     let actorDid: string | undefined
     try {
-      const query = validateRequest(ctx, req)
-      const {
-        externalPayload,
-        status: { verified },
-      } = query
+      const query = parseQueryParams(ctx, req)
+      const { verified } = parseStatus(query.status)
       if (!verified) {
         throw new Error(
           'Unexpected KWS verification response call with unverified status',
         )
       }
 
-      const { actorDid: externalPayloadActorDid, attemptId } = externalPayload
-      actorDid = externalPayloadActorDid
       // Assumes `app.set('trust proxy', ...)` configured with `true` or specific values.
       const completeIp = req.ip
       const completeUa = getClientUa(req)
-      await createStashEvent(ctx, {
-        actorDid,
-        attemptId,
-        completeIp,
-        completeUa,
-        status: 'assured',
-      })
+      const externalPayload = parseKWSExternalPayloadV1WithV2Compat(
+        query.externalPayload,
+      )
+      actorDid = externalPayload.actorDid
+
+      if (externalPayload.version === KWSExternalPayloadVersion.V2) {
+        const { countryCode, regionCode, attemptId } = externalPayload
+        const { access } = computeAgeAssuranceAccessOrThrow(
+          AGE_ASSURANCE_CONFIG,
+          {
+            countryCode: countryCode,
+            regionCode: regionCode,
+            verifiedMinimumAge: 18, // `adult-verified` is 18+ only
+          },
+        )
+        await createEvent(ctx, actorDid, {
+          attemptId,
+          status: 'assured',
+          access,
+          countryCode,
+          regionCode,
+          completeIp,
+          completeUa,
+        })
+      } else {
+        await createStashEvent(ctx, {
+          actorDid,
+          attemptId: externalPayload.attemptId,
+          status: 'assured',
+          completeIp,
+          completeUa,
+        })
+      }
+
       return res
         .status(302)
         .setHeader(