@atproto/bsky 0.0.169 → 0.0.171

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

package/src/config.ts

@@ -6,6 +6,17 @@ type LiveNowConfig = {
   domains: string[]
 }[]
 
+export interface KwsConfig {
+  apiKey: string
+  apiOrigin: string
+  authOrigin: string
+  clientId: string
+  redirectUrl: string
+  userAgent: string
+  verificationSecret: string
+  webhookSecret: string
+}
+
 export interface ServerConfigValues {
   // service
   version?: string
@@ -72,6 +83,7 @@ export interface ServerConfigValues {
   proxyMaxResponseSize?: number
   proxyMaxRetries?: number
   proxyPreferCompressed?: boolean
+  kws?: KwsConfig
 }
 
 export class ServerConfig {
@@ -222,6 +234,48 @@ export class ServerConfig {
     const proxyPreferCompressed =
       process.env.BSKY_PROXY_PREFER_COMPRESSED === 'true'
 
+    let kws: KwsConfig | undefined
+    const kwsApiKey = process.env.BSKY_KWS_API_KEY
+    const kwsApiOrigin = process.env.BSKY_KWS_API_ORIGIN
+    const kwsAuthOrigin = process.env.BSKY_KWS_AUTH_ORIGIN
+    const kwsClientId = process.env.BSKY_KWS_CLIENT_ID
+    const kwsRedirectUrl = process.env.BSKY_KWS_REDIRECT_URL
+    const kwsUserAgent = process.env.BSKY_KWS_USER_AGENT
+    const kwsVerificationSecret = process.env.BSKY_KWS_VERIFICATION_SECRET
+    const kwsWebhookSecret = process.env.BSKY_KWS_WEBHOOK_SIGNING_KEY
+    if (
+      kwsApiKey ||
+      kwsApiOrigin ||
+      kwsAuthOrigin ||
+      kwsClientId ||
+      kwsRedirectUrl ||
+      kwsUserAgent ||
+      kwsVerificationSecret ||
+      kwsWebhookSecret
+    ) {
+      assert(
+        kwsApiOrigin &&
+          kwsAuthOrigin &&
+          kwsClientId &&
+          kwsRedirectUrl &&
+          kwsUserAgent &&
+          kwsVerificationSecret &&
+          kwsWebhookSecret &&
+          kwsApiKey,
+        'all KWS environment variables must be set if any are set',
+      )
+      kws = {
+        apiKey: kwsApiKey,
+        apiOrigin: kwsApiOrigin,
+        authOrigin: kwsAuthOrigin,
+        clientId: kwsClientId,
+        redirectUrl: kwsRedirectUrl,
+        userAgent: kwsUserAgent,
+        verificationSecret: kwsVerificationSecret,
+        webhookSecret: kwsWebhookSecret,
+      }
+    }
+
     return new ServerConfig({
       version,
       debugMode,
@@ -279,6 +333,7 @@ export class ServerConfig {
       proxyMaxResponseSize,
       proxyMaxRetries,
       proxyPreferCompressed,
+      kws,
       ...stripUndefineds(overrides ?? {}),
     })
   }
@@ -513,6 +568,10 @@ export class ServerConfig {
   get proxyPreferCompressed(): boolean {
     return this.cfg.proxyPreferCompressed ?? true
   }
+
+  get kws() {
+    return this.cfg.kws
+  }
 }
 
 function stripUndefineds(

package/src/context.ts

@@ -12,6 +12,7 @@ import { CourierClient } from './courier'
 import { DataPlaneClient, HostList } from './data-plane/client'
 import { FeatureGates } from './feature-gates'
 import { Hydrator } from './hydration/hydrator'
+import { KwsClient } from './kws'
 import { httpLogger as log } from './logger'
 import { StashClient } from './stash'
 import {
@@ -41,6 +42,7 @@ export class AppContext {
       authVerifier: AuthVerifier
       featureGates: FeatureGates
       blobDispatcher: Dispatcher
+      kwsClient: KwsClient | undefined
     },
   ) {}
 
@@ -116,6 +118,10 @@ export class AppContext {
     return this.opts.blobDispatcher
   }
 
+  get kwsClient(): KwsClient | undefined {
+    return this.opts.kwsClient
+  }
+
   reqLabelers(req: express.Request): ParsedLabelers {
     const val = req.header('atproto-accept-labelers')
     let parsed: ParsedLabelers | null

package/src/data-plane/bsync/index.ts

@@ -9,6 +9,7 @@ import { jsonStringToLex } from '@atproto/lexicon'
 import { AtUri } from '@atproto/syntax'
 import { ids } from '../../lexicon/lexicons'
 import { SubjectActivitySubscription } from '../../lexicon/types/app/bsky/notification/defs'
+import { AgeAssuranceEvent } from '../../lexicon/types/app/bsky/unspecced/defs'
 import { httpLogger } from '../../logger'
 import { Service } from '../../proto/bsync_connect'
 import {
@@ -159,10 +160,10 @@ const createRoutes = (db: Database) => (router: ConnectRouter) =>
 
       const now = new Date().toISOString()
 
-      // index all items into private_data
+      // Index all items into private_data.
       await handleGenericOperation(db, req, now)
 
-      // maintain bespoke indexes for certain namespaces
+      // Maintain bespoke indexes for certain namespaces.
       if (
         namespace ===
         Namespaces.AppBskyNotificationDefsSubjectActivitySubscription
@@ -174,6 +175,16 @@ const createRoutes = (db: Database) => (router: ConnectRouter) =>
               'mock bsync put operation failed',
             ),
         )
+      } else if (
+        namespace === Namespaces.AppBskyUnspeccedDefsAgeAssuranceEvent
+      ) {
+        await handleAgeAssuranceEventOperation(db, req, now).catch(
+          (err: unknown) =>
+            httpLogger.warn(
+              { err, namespace },
+              'mock bsync put operation failed',
+            ),
+        )
       }
 
       return {
@@ -197,6 +208,43 @@ const createRoutes = (db: Database) => (router: ConnectRouter) =>
     },
   })
 
+// upsert into or remove from private_data
+const handleGenericOperation = async (
+  db: Database,
+  req: PutOperationRequest,
+  now: string,
+) => {
+  const { actorDid, namespace, key, method, payload } = req
+  if (method === Method.CREATE || method === Method.UPDATE) {
+    await db.db
+      .insertInto('private_data')
+      .values({
+        actorDid,
+        namespace,
+        key,
+        payload: Buffer.from(payload).toString('utf8'),
+        indexedAt: now,
+        updatedAt: now,
+      })
+      .onConflict((oc) =>
+        oc.columns(['actorDid', 'namespace', 'key']).doUpdateSet({
+          payload: excluded(db.db, 'payload'),
+          updatedAt: excluded(db.db, 'updatedAt'),
+        }),
+      )
+      .execute()
+  } else if (method === Method.DELETE) {
+    await db.db
+      .deleteFrom('private_data')
+      .where('actorDid', '=', actorDid)
+      .where('namespace', '=', namespace)
+      .where('key', '=', key)
+      .execute()
+  } else {
+    assert.fail(`unexpected method ${method}`)
+  }
+}
+
 const handleSubjectActivitySubscriptionOperation = async (
   db: Database,
   req: PutOperationRequest,
@@ -246,39 +294,27 @@ const handleSubjectActivitySubscriptionOperation = async (
     .execute()
 }
 
-// upsert into or remove from private_data
-const handleGenericOperation = async (
+const handleAgeAssuranceEventOperation = async (
   db: Database,
   req: PutOperationRequest,
-  now: string,
+  _now: string,
 ) => {
-  const { actorDid, namespace, key, method, payload } = req
-  if (method === Method.CREATE || method === Method.UPDATE) {
-    await db.db
-      .insertInto('private_data')
-      .values({
-        actorDid,
-        namespace,
-        key,
-        payload: Buffer.from(payload).toString('utf8'),
-        indexedAt: now,
-        updatedAt: now,
-      })
-      .onConflict((oc) =>
-        oc.columns(['actorDid', 'namespace', 'key']).doUpdateSet({
-          payload: excluded(db.db, 'payload'),
-          updatedAt: excluded(db.db, 'updatedAt'),
-        }),
-      )
-      .execute()
-  } else if (method === Method.DELETE) {
-    await db.db
-      .deleteFrom('private_data')
-      .where('actorDid', '=', actorDid)
-      .where('namespace', '=', namespace)
-      .where('key', '=', key)
-      .execute()
-  } else {
-    assert.fail(`unexpected method ${method}`)
+  const { actorDid, method, payload } = req
+  if (method !== Method.CREATE) return
+
+  const parsed = jsonStringToLex(
+    Buffer.from(payload).toString('utf8'),
+  ) as AgeAssuranceEvent
+  const { status, createdAt } = parsed
+
+  const update = {
+    ageAssuranceStatus: status,
+    ageAssuranceLastInitiatedAt: status === 'pending' ? createdAt : undefined,
   }
+
+  return db.db
+    .updateTable('actor')
+    .set(update)
+    .where('did', '=', actorDid)
+    .execute()
 }

package/src/data-plane/server/db/migrations/20250627T025331240Z-add-actor-age-assurance-columns.ts

@@ -0,0 +1,22 @@
+import { Kysely } from 'kysely'
+
+export async function up(db: Kysely<unknown>): Promise<void> {
+  await db.schema
+    .alterTable('actor')
+    .addColumn('ageAssuranceStatus', 'text')
+    .execute()
+
+  await db.schema
+    .alterTable('actor')
+    .addColumn('ageAssuranceLastInitiatedAt', 'varchar')
+    .execute()
+}
+
+export async function down(db: Kysely<unknown>): Promise<void> {
+  await db.schema.alterTable('actor').dropColumn('ageAssuranceStatus').execute()
+
+  await db.schema
+    .alterTable('actor')
+    .dropColumn('ageAssuranceLastInitiatedAt')
+    .execute()
+}

package/src/data-plane/server/db/migrations/index.ts

@@ -52,3 +52,4 @@ export * as _20250526T023712742Z from './20250526T023712742Z-like-repost-via'
 export * as _20250528T221913281Z from './20250528T221913281Z-add-record-tags'
 export * as _20250602T190357447Z from './20250602T190357447Z-add-private-data'
 export * as _20250611T140649895Z from './20250611T140649895Z-add-activity-subscription'
+export * as _20250627T025331240Z from './20250627T025331240Z-add-actor-age-assurance-columns'

package/src/data-plane/server/db/tables/actor.ts

@@ -7,6 +7,8 @@ export interface Actor {
   takedownRef: string | null
   upstreamStatus: string | null
   trustedVerifier: Generated<boolean>
+  ageAssuranceStatus: string | null
+  ageAssuranceLastInitiatedAt: string | null
 }
 
 export const tableName = 'actor'

package/src/data-plane/server/routes/profile.ts

@@ -22,7 +22,7 @@ type VerifiedBy = {
 
 export default (db: Database): Partial<ServiceImpl<typeof Service>> => ({
   async getActors(req) {
-    const { dids } = req
+    const { dids, returnAgeAssuranceForDids } = req
     if (dids.length === 0) {
       return { actors: [] }
     }
@@ -105,6 +105,7 @@ export default (db: Database): Partial<ServiceImpl<typeof Service>> => ({
         }
         return acc
       }, {} as VerifiedBy)
+      const ageAssuranceForDids = new Set(returnAgeAssuranceForDids)
 
       const activitySubscription = () => {
         const record = parseRecordBytes<AppBskyNotificationDeclaration.Record>(
@@ -128,6 +129,19 @@ export default (db: Database): Partial<ServiceImpl<typeof Service>> => ({
         }
       }
 
+      const ageAssuranceStatus = () => {
+        if (!ageAssuranceForDids.has(did)) {
+          return undefined
+        }
+
+        return {
+          status: row?.ageAssuranceStatus ?? 'unknown',
+          lastInitiatedAt: row?.ageAssuranceLastInitiatedAt
+            ? Timestamp.fromDate(new Date(row?.ageAssuranceLastInitiatedAt))
+            : undefined,
+        }
+      }
+
       return {
         exists: !!row,
         handle: row?.handle ?? undefined,
@@ -149,6 +163,7 @@ export default (db: Database): Partial<ServiceImpl<typeof Service>> => ({
         tags: [],
         profileTags: [],
         allowActivitySubscriptionsFrom: activitySubscription(),
+        ageAssuranceStatus: ageAssuranceStatus(),
       }
     })
     return { actors }

package/src/feature-gates.ts

@@ -13,6 +13,7 @@ export enum GateID {
    * appease TS
    */
   _ = '',
+  AgeAssurance = 'age_assurance',
 }
 
 /**

package/src/index.ts

@@ -10,7 +10,7 @@ import { AtpAgent } from '@atproto/api'
 import { DAY, SECOND } from '@atproto/common'
 import { Keypair } from '@atproto/crypto'
 import { IdResolver } from '@atproto/identity'
-import API, { blobResolver, health, wellKnown } from './api'
+import API, { blobResolver, external, health, wellKnown } from './api'
 import { createBlobDispatcher } from './api/blob-dispatcher'
 import { AuthVerifier, createPublicKeyObject } from './auth-verifier'
 import { authWithApiKey as bsyncAuth, createBsyncClient } from './bsync'
@@ -27,6 +27,7 @@ import { FeatureGates } from './feature-gates'
 import { Hydrator } from './hydration/hydrator'
 import * as imageServer from './image/server'
 import { ImageUriBuilder } from './image/uri'
+import { createKwsClient } from './kws'
 import { createServer } from './lexicon'
 import { loggerMiddleware } from './logger'
 import { createStashClient } from './stash'
@@ -58,6 +59,7 @@ export class BskyAppView {
   }): BskyAppView {
     const { config, signingKey } = opts
     const app = express()
+    app.set('trust proxy', true)
     app.use(cors({ maxAge: DAY / SECOND }))
     app.use(loggerMiddleware)
     app.use(compression())
@@ -150,6 +152,8 @@ export class BskyAppView {
         })
       : undefined
 
+    const kwsClient = config.kws ? createKwsClient(config.kws) : undefined
+
     const entrywayJwtPublicKey = config.entrywayJwtPublicKeyHex
       ? createPublicKeyObject(config.entrywayJwtPublicKeyHex)
       : undefined
@@ -186,6 +190,7 @@ export class BskyAppView {
       authVerifier,
       featureGates,
       blobDispatcher,
+      kwsClient,
     })
 
     let server = createServer({
@@ -205,6 +210,7 @@ export class BskyAppView {
     app.use(imageServer.createMiddleware(ctx, { prefix: '/img/' }))
     app.use(server.xrpc.router)
     app.use(error.handler)
+    app.use('/external', external.createRouter(ctx))
 
     return new BskyAppView({ ctx, app })
   }