@atproto/bsky 0.0.198 → 0.0.200

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

@@ -0,0 +1,75 @@
+import { z } from 'zod'
+
+/**
+ * Schema for KWS the `status` object on `age-verified` payloads.
+ */
+export const KWSAgeVerifiedStatusSchema = z.object({
+  verified: z.boolean(),
+  verifiedMinimumAge: z.number(),
+  transactionId: z.string().optional(),
+})
+
+/**
+ * The KWS `status` object on `age-verified` payloads.
+ */
+export type KWSAgeVerifiedStatus = z.infer<typeof KWSAgeVerifiedStatusSchema>
+
+export function serializeKWSAgeVerifiedStatus(
+  status: KWSAgeVerifiedStatus,
+): string {
+  return JSON.stringify(KWSAgeVerifiedStatusSchema.parse(status))
+}
+
+/**
+ * Parse KWS `age-verified` status object.
+ */
+export const parseKWSAgeVerifiedStatus = (
+  raw: string,
+): KWSAgeVerifiedStatus => {
+  try {
+    const value = JSON.parse(raw)
+    return KWSAgeVerifiedStatusSchema.parse(value)
+  } catch (err) {
+    throw new Error(`Invalid KWS age-verified status: ${raw}`, {
+      cause: err,
+    })
+  }
+}
+
+/**
+ * Schema for KWS `age-verified` webhooks.
+ *
+ * Note: we don't use `.strict()` here so that we avoid breaking if KWS adds
+ * fields, and some fields below are not strictly typed since we're not using
+ * them.
+ */
+export const KWSAgeVerifiedWebhookSchema = z.object({
+  name: z.string(),
+  time: z.string(), // ISO8601 timestamp, but don't validate here
+  orgId: z.string().uuid().optional(),
+  productId: z.string().uuid().optional(),
+  payload: z.object({
+    email: z.string(), // no need to validate here
+    externalPayload: z.string(),
+    status: KWSAgeVerifiedStatusSchema,
+  }),
+})
+
+/**
+ * The raw KWS `age-verified` webhook body
+ */
+export type KWSWebhookAgeVerified = z.infer<typeof KWSAgeVerifiedWebhookSchema>
+
+/**
+ * Parse KWS `age-verified` webhook body and its external payload.
+ */
+export const parseKWSAgeVerifiedWebhook = (
+  raw: string,
+): KWSWebhookAgeVerified => {
+  try {
+    const value: unknown = JSON.parse(raw)
+    return KWSAgeVerifiedWebhookSchema.parse(value)
+  } catch (err) {
+    throw new Error(`Invalid webhook body: ${raw}`, { cause: err })
+  }
+}

package/src/api/age-assurance/kws/const.ts

@@ -0,0 +1,33 @@
+/**
+ * Supported languages for KWS Adult Verification. This list comes from KWS's
+ * Age Verification Developer Guide PDF doc.
+ */
+export const KWS_SUPPORTED_LANGUAGES = new Set([
+  'en',
+  'ar',
+  'zh-Hans',
+  'nl',
+  'tl',
+  'fr',
+  'de',
+  'id',
+  'it',
+  'ja',
+  'ko',
+  'pl',
+  'pt-BR',
+  'pt',
+  'ru',
+  'es',
+  'th',
+  'tr',
+  'vi',
+])
+
+/**
+ * Regions where our "version 2" using the `age-verified` KWS flow is
+ * available. In these regions, we'll use a different KWS flow from the
+ * existing `adult-verified` flow, pass along a different external payload, and
+ * handle webhooks/redirects differently in the appview.
+ */
+export const KWS_V2_COUNTRIES = new Set(['AU'])

package/src/api/age-assurance/kws/external-payload.test.ts

@@ -0,0 +1,72 @@
+import { describe, expect, it } from '@jest/globals'
+import {
+  KWSExternalPayloadVersion,
+  parseKWSExternalPayloadV1WithV2Compat,
+  parseKWSExternalPayloadV2,
+  parseKWSExternalPayloadVersion,
+  serializeKWSExternalPayloadV1,
+  serializeKWSExternalPayloadV2,
+} from './external-payload'
+
+describe('parseKWSExternalPayloadVersion', () => {
+  it('should return V2 for "2"', () => {
+    const result = parseKWSExternalPayloadVersion('2')
+    expect(result).toBe('2')
+  })
+  it('should return V1 for unknown versions', () => {
+    const result = parseKWSExternalPayloadVersion('unknown')
+    expect(result).toBe('1')
+  })
+})
+
+describe('parseKWSExternalPayloadV1WithV2Compat', () => {
+  it('should parse V1 payload correctly', () => {
+    const payload = {
+      attemptId: '123',
+      actorDid: 'did:plc:123',
+    }
+    const serialized = serializeKWSExternalPayloadV1(payload)
+    const result = parseKWSExternalPayloadV1WithV2Compat(serialized)
+    expect(result).toEqual({
+      version: KWSExternalPayloadVersion.V1,
+      ...payload,
+    })
+  })
+  it('should parse V2 payload correctly', () => {
+    const payload = {
+      version: KWSExternalPayloadVersion.V2 as const,
+      attemptId: '123',
+      actorDid: 'did:plc:123',
+      countryCode: 'US',
+    }
+    const serialized = serializeKWSExternalPayloadV2(payload)
+    const result = parseKWSExternalPayloadV1WithV2Compat(serialized)
+    expect(result).toEqual(payload)
+  })
+})
+
+describe('serializeKWSExternalPayloadV2 & parseKWSExternalPayloadV2', () => {
+  const payload = {
+    version: KWSExternalPayloadVersion.V2 as const,
+    attemptId: '123',
+    actorDid: 'did:plc:123',
+    countryCode: 'US',
+    regionCode: 'CA',
+  }
+  it('compresses when serializing', () => {
+    const serialized = serializeKWSExternalPayloadV2(payload)
+    const comparison = JSON.stringify({
+      v: KWSExternalPayloadVersion.V2,
+      id: payload.attemptId,
+      did: payload.actorDid,
+      gc: payload.countryCode,
+      gr: payload.regionCode,
+    })
+    expect(serialized).toEqual(comparison)
+  })
+  it('decompresses when parsing', () => {
+    const serialized = serializeKWSExternalPayloadV2(payload)
+    const deserialized = parseKWSExternalPayloadV2(serialized)
+    expect(deserialized).toEqual(payload)
+  })
+})

package/src/api/age-assurance/kws/external-payload.ts

@@ -0,0 +1,149 @@
+import { z } from 'zod'
+
+export const KWS_EXTERNAL_PAYLOAD_CHAR_LIMIT = 250
+
+/**
+ * Thrown when the provided external payload exceeds KWS's character limit.
+ *
+ * This is most commonly caused by DIDs that are too long, such as for
+ * `did:web` DIDs. But it's very rare, and the client has special handling for
+ * this case.
+ */
+export class KWSExternalPayloadTooLargeError extends Error {}
+
+export enum KWSExternalPayloadVersion {
+  V1 = '1',
+  V2 = '2',
+}
+
+export function parseKWSExternalPayloadVersion(raw: string) {
+  switch (raw) {
+    case KWSExternalPayloadVersion.V2:
+      return KWSExternalPayloadVersion.V2
+    default:
+      return KWSExternalPayloadVersion.V1
+  }
+}
+
+export type KWSExternalPayloadV1 = {
+  actorDid: string
+  attemptId: string
+}
+
+export const KWSExternalPayloadV1Schema = z.object({
+  actorDid: z.string(),
+  attemptId: z.string(),
+})
+
+export function parseKWSExternalPayloadV1(raw: string): KWSExternalPayloadV1 {
+  try {
+    const value: unknown = JSON.parse(raw)
+    return KWSExternalPayloadV1Schema.parse(value)
+  } catch (err) {
+    throw new Error(`Failed to parse KWSExternalPayloadV1`, {
+      cause: err,
+    })
+  }
+}
+
+export function serializeKWSExternalPayloadV1(
+  payload: KWSExternalPayloadV1,
+): string {
+  try {
+    return JSON.stringify(KWSExternalPayloadV1Schema.parse(payload))
+  } catch (err) {
+    throw new Error('Failed to serialize KWSExternalPayloadV1', { cause: err })
+  }
+}
+
+/**
+ * During our migration from v1 to v2 of the KWS external payload, we'll be
+ * sending v2 payloads on the v1 flow (the `adult-verified` email flow). We use
+ * this utility to parse either v1 or v2 payloads in that flow.
+ *
+ * Check for the `version` field on the output of this method to discriminate
+ * between the two types and handle them differently.
+ */
+export function parseKWSExternalPayloadV1WithV2Compat(
+  raw: string,
+):
+  | (KWSExternalPayloadV1 & { version: KWSExternalPayloadVersion.V1 })
+  | KWSExternalPayloadV2 {
+  const deserialized = JSON.parse(raw)
+  const v2 = deserialized.v === KWSExternalPayloadVersion.V2
+
+  if (v2) {
+    return parseKWSExternalPayloadV2(raw)
+  } else {
+    return {
+      ...parseKWSExternalPayloadV1(raw),
+      version: KWSExternalPayloadVersion.V1,
+    }
+  }
+}
+
+/***************************
+ * KWS External Payload V2 *
+ ***************************/
+
+export type KWSExternalPayloadV2 = {
+  version: KWSExternalPayloadVersion.V2
+  attemptId: string
+  actorDid: string
+  countryCode: string
+  regionCode?: string
+}
+
+export const KWSExternalPayloadV2Schema = z.object({
+  v: z.string(),
+  id: z.string(),
+  did: z.string(),
+  gc: z.string().length(2),
+  gr: z.string().optional(),
+})
+
+export function serializeKWSExternalPayloadV2(
+  payload: KWSExternalPayloadV2,
+): string {
+  let compressed: z.infer<typeof KWSExternalPayloadV2Schema>
+  try {
+    compressed = KWSExternalPayloadV2Schema.parse({
+      v: KWSExternalPayloadVersion.V2, // version
+      id: payload.attemptId,
+      did: payload.actorDid,
+      gc: payload.countryCode, // geolocation country
+      gr: payload.regionCode, // geolocation region
+    })
+  } catch (err) {
+    throw new Error('Failed to serialize KWSExternalPayloadV2', { cause: err })
+  }
+
+  const serialized = JSON.stringify(compressed)
+
+  if (serialized.length > KWS_EXTERNAL_PAYLOAD_CHAR_LIMIT) {
+    throw new KWSExternalPayloadTooLargeError(
+      `Serialized external payload size ${serialized.length} exceeds limit of ${KWS_EXTERNAL_PAYLOAD_CHAR_LIMIT}`,
+    )
+  }
+
+  return serialized
+}
+
+export function parseKWSExternalPayloadV2(raw: string): KWSExternalPayloadV2 {
+  try {
+    const deserialized = JSON.parse(raw)
+    const parsed = KWSExternalPayloadV2Schema.parse(deserialized)
+
+    return {
+      version: KWSExternalPayloadVersion.V2,
+      attemptId: parsed.id,
+      actorDid: parsed.did,
+      countryCode: parsed.gc,
+      regionCode: parsed.gr,
+    }
+  } catch (err) {
+    throw new Error(`Failed to parse KWSExternalPayloadV2`, {
+      cause: err,
+    })
+  }
+}

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 })
+    }
+  }