@atproto/bsky 0.0.198 → 0.0.199

package/src/api/kws/index.ts

@@ -9,7 +9,13 @@ export const createRouter = (ctx: AppContext): Router => {
 
   const router = Router()
   router.use(raw({ type: 'application/json' }))
-  router.post('/age-assurance-webhook', webhookAuth(ctx), webhookHandler(ctx))
+  router.post(
+    '/age-assurance-webhook',
+    webhookAuth({
+      secret: ctx.cfg.kws.webhookSecret,
+    }),
+    webhookHandler(ctx),
+  )
   router.get('/age-assurance-verification', verificationHandler(ctx))
   return router
 }

package/src/api/kws/webhook.ts

@@ -1,19 +1,21 @@
 import express, { RequestHandler } from 'express'
 import { httpLogger as log } from '../../logger'
+import { AGE_ASSURANCE_CONFIG } from '../age-assurance/const'
+import {
+  KWSExternalPayloadVersion,
+  parseKWSExternalPayloadV1WithV2Compat,
+} from '../age-assurance/kws/external-payload'
+import { createEvent } from '../age-assurance/stash'
+import { computeAgeAssuranceAccessOrThrow } from '../age-assurance/util'
 import {
   AppContextWithKwsClient,
   KwsWebhookBody,
   webhookBodyIntermediateSchema,
 } from './types'
-import {
-  createStashEvent,
-  kwsWwwAuthenticate,
-  parseExternalPayload,
-  validateSignature,
-} from './util'
+import { createStashEvent, kwsWwwAuthenticate, validateSignature } from './util'
 
 export const webhookAuth =
-  (ctx: AppContextWithKwsClient): RequestHandler =>
+  ({ secret }: { secret: string }): RequestHandler =>
   (req: express.Request, res: express.Response, next: express.NextFunction) => {
     const body: Buffer = req.body
     const sigHeader = req.headers['x-kws-signature']
@@ -34,7 +36,7 @@ export const webhookAuth =
       }
 
       const data = `${timestamp}.${body}`
-      validateSignature(ctx.cfg.kws.webhookSecret, data, signature)
+      validateSignature(secret, data, signature)
       next()
     } catch (err) {
       log.error({ err }, 'Invalid KWS webhook signature')
@@ -51,21 +53,10 @@ type AgeAssuranceWebhookIntermediateBody = {
   }
 }
 
-const parseBody = (serialized: string): KwsWebhookBody => {
+const parseBody = (serialized: string): AgeAssuranceWebhookIntermediateBody => {
   try {
     const value: unknown = JSON.parse(serialized)
-    const intermediate: AgeAssuranceWebhookIntermediateBody =
-      webhookBodyIntermediateSchema.parse(value)
-
-    return {
-      ...intermediate,
-      payload: {
-        ...intermediate.payload,
-        externalPayload: parseExternalPayload(
-          intermediate.payload.externalPayload,
-        ),
-      },
-    }
+    return webhookBodyIntermediateSchema.parse(value)
   } catch (err) {
     throw new Error(`Invalid webhook body: ${serialized}`, { cause: err })
   }
@@ -74,7 +65,7 @@ const parseBody = (serialized: string): KwsWebhookBody => {
 export const webhookHandler =
   (ctx: AppContextWithKwsClient): RequestHandler =>
   async (req: express.Request, res: express.Response) => {
-    let body: KwsWebhookBody
+    let body: AgeAssuranceWebhookIntermediateBody
     try {
       body = parseBody(req.body)
     } catch (err) {
@@ -82,23 +73,55 @@ export const webhookHandler =
       return res.status(400).json(err)
     }
 
-    const {
-      payload: {
-        status: { verified },
-        externalPayload,
-      },
-    } = body
-    const { actorDid, attemptId } = externalPayload
+    const { verified } = body.payload.status
     if (!verified) {
       throw new Error('Unexpected KWS webhook call with unverified status')
     }
 
+    const externalPayload = parseKWSExternalPayloadV1WithV2Compat(
+      body.payload.externalPayload,
+    )
+    const isV2 = externalPayload.version === KWSExternalPayloadVersion.V2
+
+    let result: ReturnType<typeof computeAgeAssuranceAccessOrThrow> | undefined
+    if (isV2) {
+      const { attemptId, actorDid, countryCode, regionCode } = externalPayload
+      try {
+        result = computeAgeAssuranceAccessOrThrow(AGE_ASSURANCE_CONFIG, {
+          countryCode: countryCode,
+          regionCode: regionCode,
+          verifiedMinimumAge: 18, // `adult-verified` is 18+ only
+        })
+      } catch (err) {
+        // internal errors
+        log.error(
+          { err, attemptId, actorDid, countryCode, regionCode },
+          'Failed to compute age assurance access',
+        )
+      }
+    }
+
     try {
-      await createStashEvent(ctx, {
-        actorDid,
-        attemptId,
-        status: 'assured',
-      })
+      if (isV2) {
+        if (result) {
+          const { attemptId, actorDid, countryCode, regionCode } =
+            externalPayload
+          await createEvent(ctx, actorDid, {
+            attemptId,
+            status: 'assured',
+            access: result.access,
+            countryCode,
+            regionCode,
+          })
+        } // else do nothing
+      } else {
+        const { attemptId, actorDid } = externalPayload
+        await createStashEvent(ctx, {
+          attemptId: attemptId,
+          actorDid: actorDid,
+          status: 'assured',
+        })
+      }
       return res.status(200).end()
     } catch (err) {
       log.error({ err }, 'Failed to handle KWS webhook')

package/src/config.ts

@@ -13,8 +13,22 @@ export interface KwsConfig {
   clientId: string
   redirectUrl: string
   userAgent: string
+  /**
+   * V1 secret used to validate `adult-verifieid` redirects
+   */
   verificationSecret: string
+  /**
+   * V1 secret used to validate `adult-verified` webhooks
+   */
   webhookSecret: string
+  /**
+   * V2 secret used to validate `age-verified` webhooks
+   */
+  ageVerifiedWebhookSecret: string
+  /**
+   * V2 secret used to validate `age-verified` redirects
+   */
+  ageVerifiedRedirectSecret: string
 }
 
 export interface ServerConfigValues {
@@ -251,6 +265,10 @@ export class ServerConfig {
     const kwsUserAgent = process.env.BSKY_KWS_USER_AGENT
     const kwsVerificationSecret = process.env.BSKY_KWS_VERIFICATION_SECRET
     const kwsWebhookSecret = process.env.BSKY_KWS_WEBHOOK_SECRET
+    const kwsAgeVerifiedWebhookSecret =
+      process.env.BSKY_KWS_AGE_VERIFIED_WEBHOOK_SECRET
+    const kwsAgeVerifiedRedirectSecret =
+      process.env.BSKY_KWS_AGE_VERIFIED_REDIRECT_SECRET
     if (
       kwsApiKey ||
       kwsApiOrigin ||
@@ -259,7 +277,9 @@ export class ServerConfig {
       kwsRedirectUrl ||
       kwsUserAgent ||
       kwsVerificationSecret ||
-      kwsWebhookSecret
+      kwsWebhookSecret ||
+      kwsAgeVerifiedWebhookSecret ||
+      kwsAgeVerifiedRedirectSecret
     ) {
       assert(
         kwsApiOrigin &&
@@ -269,7 +289,9 @@ export class ServerConfig {
           kwsUserAgent &&
           kwsVerificationSecret &&
           kwsWebhookSecret &&
-          kwsApiKey,
+          kwsApiKey &&
+          kwsAgeVerifiedWebhookSecret &&
+          kwsAgeVerifiedRedirectSecret,
         'all KWS environment variables must be set if any are set',
       )
       kws = {
@@ -281,6 +303,8 @@ export class ServerConfig {
         userAgent: kwsUserAgent,
         verificationSecret: kwsVerificationSecret,
         webhookSecret: kwsWebhookSecret,
+        ageVerifiedWebhookSecret: kwsAgeVerifiedWebhookSecret,
+        ageVerifiedRedirectSecret: kwsAgeVerifiedRedirectSecret,
       }
     }
 

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

@@ -8,6 +8,7 @@ import { TID } from '@atproto/common'
 import { jsonStringToLex } from '@atproto/lexicon'
 import { AtUri } from '@atproto/syntax'
 import { ids } from '../../lexicon/lexicons'
+import { Event as AgeAssuranceV2Event } from '../../lexicon/types/app/bsky/ageassurance/defs'
 import { Bookmark } from '../../lexicon/types/app/bsky/bookmark/defs'
 import { SubjectActivitySubscription } from '../../lexicon/types/app/bsky/notification/defs'
 import { AgeAssuranceEvent } from '../../lexicon/types/app/bsky/unspecced/defs'
@@ -175,6 +176,8 @@ const createRoutes = (db: Database) => (router: ConnectRouter) =>
           namespace === Namespaces.AppBskyUnspeccedDefsAgeAssuranceEvent
         ) {
           await handleAgeAssuranceEventOperation(db, req, now)
+        } else if (namespace === Namespaces.AppBskyAgeassuranceDefsEvent) {
+          await handleAgeAssuranceV2EventOperation(db, req, now)
         } else if (namespace === Namespaces.AppBskyBookmarkDefsBookmark) {
           await handleBookmarkOperation(db, req, now)
         }
@@ -314,6 +317,34 @@ const handleAgeAssuranceEventOperation = async (
     .execute()
 }
 
+const handleAgeAssuranceV2EventOperation = async (
+  db: Database,
+  req: PutOperationRequest,
+  _now: string,
+) => {
+  const { actorDid, method, payload } = req
+  if (method !== Method.CREATE) return
+
+  const parsed = jsonStringToLex(
+    Buffer.from(payload).toString('utf8'),
+  ) as AgeAssuranceV2Event
+  const { status, createdAt, access, countryCode, regionCode } = parsed
+
+  const update = {
+    ageAssuranceStatus: status,
+    ageAssuranceLastInitiatedAt: status === 'pending' ? createdAt : undefined,
+    ageAssuranceAccess: access,
+    ageAssuranceCountryCode: countryCode,
+    ageAssuranceRegionCode: regionCode,
+  }
+
+  return db.db
+    .updateTable('actor')
+    .set(update)
+    .where('did', '=', actorDid)
+    .execute()
+}
+
 const handleBookmarkOperation = async (
   db: Database,
   req: PutOperationRequest,

package/src/data-plane/server/db/migrations/20251120T004738098Z-update-actor-age-assurance-v2.ts

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

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

@@ -55,3 +55,4 @@ export * as _20250611T140649895Z from './20250611T140649895Z-add-activity-subscr
 export * as _20250627T025331240Z from './20250627T025331240Z-add-actor-age-assurance-columns'
 export * as _20250812T183735692Z from './20250812T183735692Z-add-bookmarks'
 export * as _20250813T174955711Z from './20250813T174955711Z-add-post-agg-bookmarks'
+export * as _20251120T004738098Z from './20251120T004738098Z-update-actor-age-assurance-v2'

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

@@ -9,6 +9,9 @@ export interface Actor {
   trustedVerifier: Generated<boolean>
   ageAssuranceStatus: string | null
   ageAssuranceLastInitiatedAt: string | null
+  ageAssuranceAccess: string | null
+  ageAssuranceCountryCode: string | null
+  ageAssuranceRegionCode: string | null
 }
 
 export const tableName = 'actor'

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

@@ -134,11 +134,22 @@ export default (db: Database): Partial<ServiceImpl<typeof Service>> => ({
           return undefined
         }
 
+        const status = row?.ageAssuranceStatus ?? 'unknown'
+        let access = row?.ageAssuranceAccess
+        if (status === 'assured') {
+          access = 'full'
+        } else if (status === 'blocked') {
+          access = 'none'
+        } else {
+          access = 'unknown'
+        }
+
         return {
-          status: row?.ageAssuranceStatus ?? 'unknown',
           lastInitiatedAt: row?.ageAssuranceLastInitiatedAt
             ? Timestamp.fromDate(new Date(row?.ageAssuranceLastInitiatedAt))
             : undefined,
+          status,
+          access,
         }
       }
 

package/src/hydration/hydrator.ts

@@ -1327,7 +1327,7 @@ export class Hydrator {
     const uri = new AtUri(uriStr)
     const [did] = await this.actor.getDids([uri.host])
     if (!did) return uriStr
-    uri.host = did
+    uri.hostname = did
     return uri.toString()
   }
 }

package/src/kws.ts

@@ -15,8 +15,30 @@ const authResponseSchema = z.object({
 })
 
 const EXTERNAL_PAYLOAD_CHAR_LIMIT = 200
+/**
+ * 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 KwsExternalPayloadError extends Error {}
 
+export type KWSSendEmailRequestCommon = {
+  email: string
+  location: string
+  language: string
+  externalPayload: string
+}
+
+export type KWSSendEmailRequest =
+  | (KWSSendEmailRequestCommon & {
+      userContext: 'adult'
+    })
+  | (KWSSendEmailRequestCommon & {
+      userContext: 'age'
+      minimumAge: number
+    })
+
 export class KwsClient {
   constructor(public cfg: KwsConfig) {}
 
@@ -68,6 +90,9 @@ export class KwsClient {
     })
   }
 
+  /**
+   * @deprecated Use `sendAdultVerifiedFlowEmail` or `sendAgeVerifiedFlowEmail` instead.
+   */
   async sendEmail({
     countryCode,
     email,
@@ -113,4 +138,60 @@ export class KwsClient {
 
     return res.json()
   }
+
+  /**
+   * Sends a KWS verification email with the given properties.
+   */
+  async email(props: KWSSendEmailRequest) {
+    const res = await this.fetchWithAuth(
+      `${this.cfg.apiOrigin}/v1/verifications/send-email`,
+      {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          'User-Agent': this.cfg.userAgent,
+        },
+        body: JSON.stringify(props),
+      },
+    )
+
+    if (!res.ok) {
+      const errorText = await res.text()
+      log.error(
+        {
+          status: res.status,
+          statusText: res.statusText,
+          errorText,
+          flow: props.userContext,
+        },
+        'Failed to send KWS email',
+      )
+      throw new Error('Failed to send KWS email')
+    }
+
+    return res.json()
+  }
+
+  /**
+   * Sends an email to the user initiating an `adult` verification flow, which
+   * results in `adult-verified` events/webhooks.
+   */
+  async sendAdultVerifiedFlowEmail(props: KWSSendEmailRequestCommon) {
+    return this.email({
+      ...props,
+      userContext: 'adult',
+    })
+  }
+
+  /**
+   * Sends an email to the user initiating an `age` verification flow, which
+   * results in `age-verified` events/webhooks.
+   */
+  async sendAgeVerifiedFlowEmail(props: KWSSendEmailRequestCommon) {
+    return this.email({
+      ...props,
+      userContext: 'age',
+      minimumAge: 16, // KWS required value
+    })
+  }
 }

package/src/logger.ts

@@ -17,6 +17,8 @@ export const featureGatesLogger: ReturnType<typeof subsystemLogger> =
   subsystemLogger('bsky:featuregates')
 export const dataplaneLogger: ReturnType<typeof subsystemLogger> =
   subsystemLogger('bsky:dp')
+export const ageAssuranceLogger: ReturnType<typeof subsystemLogger> =
+  subsystemLogger('bsky:aa')
 export const httpLogger: ReturnType<typeof subsystemLogger> =
   subsystemLogger('bsky')
 

package/src/proto/bsky_pb.ts

@@ -3856,6 +3856,16 @@ export class AgeAssuranceStatus extends Message<AgeAssuranceStatus> {
    */
   overrideApplied = false;
 
+  /**
+   * @generated from field: string access = 4;
+   */
+  access = "";
+
+  /**
+   * @generated from field: string access_reason = 5;
+   */
+  accessReason = "";
+
   constructor(data?: PartialMessage<AgeAssuranceStatus>) {
     super();
     proto3.util.initPartial(data, this);
@@ -3867,6 +3877,8 @@ export class AgeAssuranceStatus extends Message<AgeAssuranceStatus> {
     { no: 1, name: "status", kind: "scalar", T: 9 /* ScalarType.STRING */ },
     { no: 2, name: "last_initiated_at", kind: "message", T: Timestamp },
     { no: 3, name: "override_applied", kind: "scalar", T: 8 /* ScalarType.BOOL */ },
+    { no: 4, name: "access", kind: "scalar", T: 9 /* ScalarType.STRING */ },
+    { no: 5, name: "access_reason", kind: "scalar", T: 9 /* ScalarType.STRING */ },
   ]);
 
   static fromBinary(bytes: Uint8Array, options?: Partial<BinaryReadOptions>): AgeAssuranceStatus {

package/src/stash.ts

@@ -3,6 +3,7 @@
 import { LexValue, stringifyLex } from '@atproto/lexicon'
 import { BsyncClient } from './bsync'
 import { lexicons } from './lexicon/lexicons'
+import { Event as AgeAssuranceEventV2 } from './lexicon/types/app/bsky/ageassurance/defs'
 import { Bookmark } from './lexicon/types/app/bsky/bookmark/defs'
 import {
   Preferences,
@@ -22,6 +23,8 @@ export const Namespaces = {
     'app.bsky.notification.defs#subjectActivitySubscription' satisfies PickNSID<SubjectActivitySubscription>,
   AppBskyUnspeccedDefsAgeAssuranceEvent:
     'app.bsky.unspecced.defs#ageAssuranceEvent' satisfies PickNSID<AgeAssuranceEvent>,
+  AppBskyAgeassuranceDefsEvent:
+    'app.bsky.ageassurance.defs#event' satisfies PickNSID<AgeAssuranceEventV2>,
 }
 
 export type Namespace = (typeof Namespaces)[keyof typeof Namespaces]