@atproto/bsky 0.0.170 → 0.0.172

package/src/api/app/bsky/notification/unregisterPush.ts

@@ -0,0 +1,38 @@
+import {
+  InvalidRequestError,
+  MethodNotImplementedError,
+} from '@atproto/xrpc-server'
+import { AppContext } from '../../../../context'
+import { Server } from '../../../../lexicon'
+import { assertLexPlatform, lexPlatformToProtoPlatform } from './util'
+
+export default function (server: Server, ctx: AppContext) {
+  server.app.bsky.notification.unregisterPush({
+    auth: ctx.authVerifier.standard,
+    handler: async ({ auth, input }) => {
+      if (!ctx.courierClient) {
+        throw new MethodNotImplementedError(
+          'This service is not configured to support push token registration.',
+        )
+      }
+      const { token, platform, serviceDid, appId } = input.body
+      const did = auth.credentials.iss
+      if (serviceDid !== auth.credentials.aud) {
+        throw new InvalidRequestError('Invalid serviceDid.')
+      }
+      try {
+        assertLexPlatform(platform)
+      } catch (err) {
+        throw new InvalidRequestError(
+          'Unsupported platform: must be "ios", "android", or "web".',
+        )
+      }
+      await ctx.courierClient.unregisterDeviceToken({
+        did,
+        token,
+        platform: lexPlatformToProtoPlatform(platform),
+        appId,
+      })
+    },
+  })
+}

package/src/api/app/bsky/notification/util.ts

@@ -13,6 +13,7 @@ import {
   NotificationPreference,
   NotificationPreferences,
 } from '../../../../proto/bsky_pb'
+import { AppPlatform } from '../../../../proto/courier_pb'
 
 type DeepPartial<T> = T extends object
   ? {
@@ -122,3 +123,20 @@ export const protobufToLex = (
     verified: protobufPreferenceToLex(res.verified),
   })
 }
+
+type LexPlatform = 'ios' | 'android' | 'web'
+
+export function assertLexPlatform(
+  platform: string,
+): asserts platform is LexPlatform {
+  if (platform !== 'ios' && platform !== 'android' && platform !== 'web') {
+    throw new Error('Unsupported platform: must be "ios", "android", or "web".')
+  }
+}
+
+export const lexPlatformToProtoPlatform = (platform: string): AppPlatform =>
+  platform === 'ios'
+    ? AppPlatform.IOS
+    : platform === 'android'
+      ? AppPlatform.ANDROID
+      : AppPlatform.WEB

package/src/api/app/bsky/unspecced/getAgeAssuranceState.ts

@@ -0,0 +1,46 @@
+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.unspecced.getAgeAssuranceState({
+    auth: ctx.authVerifier.standard,
+    handler: async ({ auth }) => {
+      const viewer = auth.credentials.iss
+      const actorInfo = await getAgeVerificationState(ctx, viewer)
+
+      return {
+        encoding: 'application/json',
+        body: {
+          lastInitiatedAt:
+            actorInfo.ageAssuranceStatus?.lastInitiatedAt
+              ?.toDate()
+              .toISOString() ?? undefined,
+          status: actorInfo.ageAssuranceStatus?.status ?? 'unknown',
+        },
+      }
+    },
+  })
+}
+
+const getAgeVerificationState = 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/app/bsky/unspecced/initAgeAssurance.ts

@@ -0,0 +1,71 @@
+import crypto from 'node:crypto'
+import { isEmailValid } from '@hapi/address'
+import { isDisposableEmail } from 'disposable-email-domains-js'
+import {
+  ForbiddenError,
+  InvalidRequestError,
+  MethodNotImplementedError,
+} from '@atproto/xrpc-server'
+import { AppContext } from '../../../../context'
+import { GateID } from '../../../../feature-gates'
+import { Server } from '../../../../lexicon'
+import { KwsExternalPayload } from '../../../kws/types'
+import { createStashEvent, getClientUa } from '../../../kws/util'
+
+export default function (server: Server, ctx: AppContext) {
+  server.app.bsky.unspecced.initAgeAssurance({
+    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 enabled =
+        ctx.cfg.debugMode ||
+        ctx.featureGates.check({ userID: actorDid }, GateID.AgeAssurance)
+      if (!enabled) {
+        throw new ForbiddenError()
+      }
+
+      const { email, language, countryCode } = input.body
+      if (!isEmailValid(email) || isDisposableEmail(email)) {
+        throw new InvalidRequestError(
+          'This email address is not supported, please use a different email.',
+        )
+      }
+
+      const attemptId = crypto.randomUUID()
+      // Assumes `app.set('trust proxy', ...)` configured with `true` or specific values.
+      const initIp = req.ip
+      const initUa = getClientUa(req)
+      const externalPayload: KwsExternalPayload = { actorDid, attemptId }
+
+      await ctx.kwsClient.sendEmail({
+        countryCode: countryCode.toUpperCase(),
+        email,
+        externalPayload,
+        language,
+      })
+
+      const event = await createStashEvent(ctx, {
+        actorDid,
+        attemptId,
+        email,
+        initIp,
+        initUa,
+        status: 'pending',
+      })
+
+      return {
+        encoding: 'application/json',
+        body: {
+          status: event.status,
+          lastInitiatedAt: event.createdAt,
+        },
+      }
+    },
+  })
+}

package/src/api/external.ts

@@ -0,0 +1,13 @@
+import { Router } from 'express'
+import { AppContext } from '../context'
+import * as kwsApi from './kws'
+
+export const createRouter = (ctx: AppContext): Router => {
+  const router = Router()
+
+  if (ctx.kwsClient) {
+    router.use('/kws', kwsApi.createRouter(ctx))
+  }
+
+  return router
+}

package/src/api/index.ts

@@ -51,6 +51,7 @@ import putPreferences from './app/bsky/notification/putPreferences'
 import putPreferencesV2 from './app/bsky/notification/putPreferencesV2'
 import registerPush from './app/bsky/notification/registerPush'
 import updateSeen from './app/bsky/notification/updateSeen'
+import getAgeAssuranceState from './app/bsky/unspecced/getAgeAssuranceState'
 import getConfig from './app/bsky/unspecced/getConfig'
 import getPopularFeedGenerators from './app/bsky/unspecced/getPopularFeedGenerators'
 import getPostThreadOtherV2 from './app/bsky/unspecced/getPostThreadOtherV2'
@@ -61,6 +62,7 @@ import getSuggestedUsers from './app/bsky/unspecced/getSuggestedUsers'
 import getTaggedSuggestions from './app/bsky/unspecced/getTaggedSuggestions'
 import getTrendingTopics from './app/bsky/unspecced/getTrendingTopics'
 import getTrends from './app/bsky/unspecced/getTrends'
+import initAgeAssurance from './app/bsky/unspecced/initAgeAssurance'
 import getAccountInfos from './com/atproto/admin/getAccountInfos'
 import getSubjectStatus from './com/atproto/admin/getSubjectStatus'
 import updateSubjectStatus from './com/atproto/admin/updateSubjectStatus'
@@ -75,6 +77,8 @@ export * as wellKnown from './well-known'
 
 export * as blobResolver from './blob-resolver'
 
+export * as external from './external'
+
 export default function (server: Server, ctx: AppContext) {
   // app.bsky
   getTimeline(server, ctx)
@@ -138,6 +142,8 @@ export default function (server: Server, ctx: AppContext) {
   getConfig(server, ctx)
   getPopularFeedGenerators(server, ctx)
   getTaggedSuggestions(server, ctx)
+  getAgeAssuranceState(server, ctx)
+  initAgeAssurance(server, ctx)
   // com.atproto
   getSubjectStatus(server, ctx)
   updateSubjectStatus(server, ctx)

package/src/api/kws/api.ts

@@ -0,0 +1,92 @@
+import express, { RequestHandler } from 'express'
+import { httpLogger as log } from '../../logger'
+import {
+  AppContextWithKwsClient,
+  KwsVerificationIntermediateQuery,
+  KwsVerificationQuery,
+  verificationIntermediateQuerySchema,
+} from './types'
+import {
+  createStashEvent,
+  getClientUa,
+  parseExternalPayload,
+  parseStatus,
+  validateSignature,
+} from './util'
+
+const validateRequest = (
+  ctx: AppContextWithKwsClient,
+  req: express.Request,
+): KwsVerificationQuery => {
+  try {
+    const intermediate: KwsVerificationIntermediateQuery =
+      verificationIntermediateQuerySchema.parse({
+        externalPayload: req.query.externalPayload,
+        signature: req.query.signature,
+        status: req.query.status,
+      })
+
+    const data = `${intermediate.status}:${intermediate.externalPayload}`
+    validateSignature(
+      ctx.cfg.kws.verificationSecret,
+      data,
+      intermediate.signature,
+    )
+
+    return {
+      ...intermediate,
+      externalPayload: parseExternalPayload(intermediate.externalPayload),
+      status: parseStatus(intermediate.status),
+    }
+  } catch (err) {
+    throw new Error('Invalid KWS API request', { cause: err })
+  }
+}
+
+export const verificationHandler =
+  (ctx: AppContextWithKwsClient): RequestHandler =>
+  async (req: express.Request, res: express.Response) => {
+    let actorDid: string | undefined
+    try {
+      const query = validateRequest(ctx, req)
+      const {
+        externalPayload,
+        status: { verified },
+      } = query
+      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',
+      })
+      return res
+        .status(302)
+        .setHeader(
+          'Location',
+          `${ctx.cfg.kws.redirectUrl}?${new URLSearchParams({ actorDid, result: 'success' })}`,
+        )
+        .end()
+    } catch (err) {
+      log.error({ err }, 'Failed to handle KWS verification response')
+
+      return res
+        .status(302)
+        .setHeader(
+          'Location',
+          `${ctx.cfg.kws.redirectUrl}?${new URLSearchParams({ ...(actorDid ? { actorDid } : {}), result: 'unknown' })}`,
+        )
+        .end()
+    }
+  }

package/src/api/kws/index.ts

@@ -0,0 +1,23 @@
+import { Router, raw } from 'express'
+import { AppContext } from '../../context'
+import { verificationHandler } from './api'
+import { AppContextWithKwsClient } from './types'
+import { webhookAuth, webhookHandler } from './webhook'
+
+export const createRouter = (ctx: AppContext): Router => {
+  assertAppContextWithAgeAssuranceClient(ctx)
+
+  const router = Router()
+  router.use(raw({ type: 'application/json' }))
+  router.post('/age-assurance-webhook', webhookAuth(ctx), webhookHandler(ctx))
+  router.get('/age-assurance-verification', verificationHandler(ctx))
+  return router
+}
+
+const assertAppContextWithAgeAssuranceClient: (
+  ctx: AppContext,
+) => asserts ctx is AppContextWithKwsClient = (ctx: AppContext) => {
+  if (!ctx.kwsClient) {
+    throw new Error('Tried to set up KWS router without kwsClient configured.')
+  }
+}

package/src/api/kws/types.ts

@@ -0,0 +1,67 @@
+import { z } from 'zod'
+import { KwsConfig, ServerConfig } from '../../config'
+import { AppContext } from '../../context'
+import { KwsClient } from '../../kws'
+
+export type AppContextWithKwsClient = AppContext & {
+  kwsClient: KwsClient
+  cfg: ServerConfig & {
+    kws: KwsConfig
+  }
+}
+
+export type KwsExternalPayload = {
+  actorDid: string
+  attemptId: string
+}
+
+// `.strict()` because we control the payload structure.
+export const externalPayloadSchema = z
+  .object({
+    actorDid: z.string(),
+    attemptId: z.string(),
+  })
+  .strict()
+
+export type KwsStatus = {
+  verified: boolean
+}
+
+export type KwsVerificationIntermediateQuery = {
+  externalPayload: string
+  status: string
+  signature: string
+}
+
+// Not `.strict()` to avoid breaking if KWS adds fields.
+export const verificationIntermediateQuerySchema = z.object({
+  externalPayload: z.string(),
+  signature: z.string(),
+  status: z.string(),
+})
+
+export type KwsVerificationQuery = {
+  externalPayload: KwsExternalPayload
+  signature: string
+  status: KwsStatus
+}
+
+export type KwsWebhookBody = {
+  payload: {
+    externalPayload: KwsExternalPayload
+    status: KwsStatus
+  }
+}
+
+// Not `.strict()` to avoid breaking if KWS adds fields.
+export const statusSchema = z.object({
+  verified: z.boolean(),
+})
+
+// Not `.strict()` to avoid breaking if KWS adds fields.
+export const webhookBodyIntermediateSchema = z.object({
+  payload: z.object({
+    externalPayload: z.string(),
+    status: statusSchema,
+  }),
+})

package/src/api/kws/util.ts

@@ -0,0 +1,111 @@
+import crypto from 'node:crypto'
+import express from 'express'
+import { TID } from '@atproto/common'
+import { AppContext } from '../../context'
+import {
+  AgeAssuranceEvent,
+  AgeAssuranceState,
+} from '../../lexicon/types/app/bsky/unspecced/defs'
+import { Namespaces } from '../../stash'
+import {
+  KwsExternalPayload,
+  KwsStatus,
+  externalPayloadSchema,
+  statusSchema,
+} from './types'
+
+export const createStashEvent = async (
+  ctx: AppContext,
+  {
+    actorDid,
+    attemptId,
+    email,
+    initIp,
+    initUa,
+    completeIp,
+    completeUa,
+    status,
+  }: {
+    actorDid: string
+    attemptId: string
+    email?: string
+    initIp?: string
+    initUa?: string
+    completeIp?: string
+    completeUa?: string
+    status: AgeAssuranceState['status']
+  },
+) => {
+  const stashPayload: AgeAssuranceEvent = {
+    createdAt: new Date().toISOString(),
+    email,
+    status,
+    attemptId,
+    initIp,
+    initUa,
+    completeIp,
+    completeUa,
+  }
+
+  await ctx.stashClient.create({
+    actorDid,
+    namespace: Namespaces.AppBskyUnspeccedDefsAgeAssuranceEvent,
+    key: TID.nextStr(),
+    payload: stashPayload,
+  })
+  return stashPayload
+}
+
+export const validateSignature = (
+  key: string,
+  data: string,
+  signature: string,
+) => {
+  const expectedSignature = crypto
+    .createHmac('sha256', key)
+    .update(data)
+    .digest('hex')
+
+  const expectedSignatureBuf = Buffer.from(expectedSignature, 'hex')
+  const actualSignatureBuf = Buffer.from(signature, 'hex')
+
+  if (expectedSignatureBuf.length !== actualSignatureBuf.length) {
+    throw new Error(`Signature mismatch`)
+  }
+
+  if (!crypto.timingSafeEqual(expectedSignatureBuf, actualSignatureBuf)) {
+    throw new Error(`Signature mismatch`)
+  }
+}
+
+export const serializeExternalPayload = (value: KwsExternalPayload): string => {
+  return JSON.stringify(value)
+}
+
+export const parseExternalPayload = (
+  serialized: string,
+): KwsExternalPayload => {
+  try {
+    const value: unknown = JSON.parse(serialized)
+    return externalPayloadSchema.parse(value)
+  } catch (err) {
+    throw new Error(`Invalid external payload: ${serialized}`, { cause: err })
+  }
+}
+
+export const parseStatus = (serialized: string): KwsStatus => {
+  try {
+    const value: unknown = JSON.parse(serialized)
+    return statusSchema.parse(value)
+  } catch (err) {
+    throw new Error(`Invalid status: ${serialized}`, { cause: err })
+  }
+}
+
+export const kwsWwwAuthenticate = (): Record<string, string> => ({
+  'www-authenticate': `Signature realm="kws"`,
+})
+
+export const getClientUa = (req: express.Request): string | undefined => {
+  return req.headers['user-agent']
+}

package/src/api/kws/webhook.ts

@@ -0,0 +1,107 @@
+import express, { RequestHandler } from 'express'
+import { httpLogger as log } from '../../logger'
+import {
+  AppContextWithKwsClient,
+  KwsWebhookBody,
+  webhookBodyIntermediateSchema,
+} from './types'
+import {
+  createStashEvent,
+  kwsWwwAuthenticate,
+  parseExternalPayload,
+  validateSignature,
+} from './util'
+
+export const webhookAuth =
+  (ctx: AppContextWithKwsClient): RequestHandler =>
+  (req: express.Request, res: express.Response, next: express.NextFunction) => {
+    const body: Buffer = req.body
+    const sigHeader = req.headers['x-kws-signature']
+    if (!sigHeader || typeof sigHeader !== 'string') {
+      return res.status(401).header(kwsWwwAuthenticate()).json({
+        success: false,
+        error:
+          'Invalid authentication for KWS webhook: missing signature header',
+      })
+    }
+
+    try {
+      const parts = sigHeader.split(',')
+      const timestamp = parts.find((p) => p.startsWith('t='))?.split('=')[1]
+      const signature = parts.find((p) => p.startsWith('v1='))?.split('=')[1]
+      if (typeof timestamp !== 'string' || typeof signature !== 'string') {
+        throw new Error('Invalid webhook signature format')
+      }
+
+      const data = `${timestamp}.${body}`
+      validateSignature(ctx.cfg.kws.webhookSecret, data, signature)
+      next()
+    } catch (err) {
+      log.error({ err }, 'Invalid KWS webhook signature')
+      return res.status(401).header(kwsWwwAuthenticate()).json({
+        success: false,
+        error: 'Invalid authentication for KWS webhook: signature mismatch',
+      })
+    }
+  }
+
+type AgeAssuranceWebhookIntermediateBody = {
+  payload: Omit<KwsWebhookBody['payload'], 'externalPayload'> & {
+    externalPayload: string
+  }
+}
+
+const parseBody = (serialized: string): KwsWebhookBody => {
+  try {
+    const value: unknown = JSON.parse(serialized)
+    const intermediate: AgeAssuranceWebhookIntermediateBody =
+      webhookBodyIntermediateSchema.parse(value)
+
+    return {
+      ...intermediate,
+      payload: {
+        ...intermediate.payload,
+        externalPayload: parseExternalPayload(
+          intermediate.payload.externalPayload,
+        ),
+      },
+    }
+  } catch (err) {
+    throw new Error(`Invalid webhook body: ${serialized}`, { cause: err })
+  }
+}
+
+export const webhookHandler =
+  (ctx: AppContextWithKwsClient): RequestHandler =>
+  async (req: express.Request, res: express.Response) => {
+    let body: KwsWebhookBody
+    try {
+      body = parseBody(req.body)
+    } catch (err) {
+      log.error({ err }, 'Invalid KWS webhook body')
+      return res.status(400).json(err)
+    }
+
+    const {
+      payload: {
+        status: { verified },
+        externalPayload,
+      },
+    } = body
+    const { actorDid, attemptId } = externalPayload
+    if (!verified) {
+      throw new Error('Unexpected KWS webhook call with unverified status')
+    }
+
+    try {
+      await createStashEvent(ctx, {
+        actorDid,
+        attemptId,
+        status: 'assured',
+      })
+      return res.status(200).end()
+    } catch (err) {
+      log.error({ err }, 'Failed to handle KWS webhook')
+      return res.status(500).json(err)
+    }
+  }