@oxy.so/core 1.12.0 → 1.13.0

package/dist/types/index.d.ts

@@ -29,6 +29,8 @@ export type { ServiceTokenResponse, OAuthUserInfoResponse, OAuthTokenExchangeRes
 export type { CommonsSignInHandle, CommonsSignInStatus, CommonsSignInPurpose, CommonsOAuthContext, CommonsApprovalInfo, CommonsApprovalSubjectAccount, CommonsSignInActionResult, CommonsOAuthFinalizeResult, CommonsDeliveryResult, } from './mixins/OxyServices.auth';
 export type { PushTokenPlatform, RegisterPushTokenInput, } from './mixins/OxyServices.notifications';
 export type { ServiceApp, ServiceActingAsVerification, OxyAuthRefusal } from './mixins/OxyServices.utility';
+export type { OxyAccountEvent, OxyAccountEventFeedItem, OxyAccountEventFeedPage, VerifyAccountEventOptions, } from './mixins/OxyServices.utility';
+export { OxyAccountEventError, OXY_ACCOUNT_DELETED_EVENT_URI } from './mixins/OxyServices.utility';
 export type { ContactDiscoveryMatch, ContactDiscoveryResponse, } from './mixins/OxyServices.contacts';
 export type { BulkFollowEntry, BulkFollowResult, BulkUnfollowEntry, BulkUnfollowResult, FollowMutationResult, ViewerGraph, } from './mixins/OxyServices.user';
 export { OxyAppDataIdentifierError } from './mixins/OxyServices.appData';

package/dist/types/mixins/OxyServices.user.d.ts

@@ -97,6 +97,13 @@ export declare function OxyServicesUserMixin<T extends typeof OxyServicesBase>(B
          */
         _serviceApiKey: string | null;
         _serviceApiSecret: string | null;
+        /**
+         * Whether this process can mint a service token by attesting what it is
+         * (ADR 0026), defined on the auth mixin. A host with no key pair that CAN
+         * attest is a first-party backend exactly like one with a key pair, and
+         * `getUsersByIds` must treat it as one.
+         */
+        _canUseWorkloadIdentity: () => Promise<boolean>;
         /**
          * Get profile by username.
          *
@@ -229,8 +236,10 @@ export declare function OxyServicesUserMixin<T extends typeof OxyServicesBase>(B
          * caller, and returns the SAME public `{ data: PublicUserProfile[] }`
          * payload (canonical `name.displayName` + `_count`) in every case — no
          * viewer-specific fields. This method picks the path automatically:
-         * - **Service-configured host (backend):** when `configureServiceAuth(apiKey,
-         *   apiSecret)` has been called, the chunk is fetched via `makeServiceRequest`
+         * - **Service host (backend):** when `configureServiceAuth(apiKey,
+         *   apiSecret)` has been called, OR the process can attest its workload
+         *   identity (ADR 0026 — an ECS task with no key pair), the chunk is fetched
+         *   via `makeServiceRequest`
          *   (attaches `Authorization: Bearer <serviceToken>`). This is the
          *   server-to-server feed/notification hydration path (e.g. Mention's
          *   `PostHydrationService`) and is unchanged.

package/dist/types/mixins/OxyServices.utility.d.ts

@@ -25,6 +25,64 @@ export interface ServiceActingAsVerification {
     authorized: boolean;
     scopes: string[];
 }
+/** The SET `events` member Oxy uses for an account deletion. */
+export declare const OXY_ACCOUNT_DELETED_EVENT_URI = "https://oxy.so/events/account.deleted";
+/**
+ * A verified account event from Oxy (OxyHQ/Mention#1169): a person deleted
+ * their Oxy account and every relying application must erase what it holds
+ * for them. Returned by `verifyAccountEvent` only after the signature, `typ`,
+ * issuer and audience all check out.
+ */
+export interface OxyAccountEvent {
+    /** The event id (`jti`). Stable across webhook retries and the pull feed: dedupe on it. */
+    eventId: string;
+    type: 'account.deleted';
+    /** The deleted Oxy account. */
+    userId: string;
+    /**
+     * The account's handle at deletion time, for relying parties that address
+     * the person by handle (an ActivityPub actor URI). `null` when the account had
+     * none, or when the token predates the field.
+     */
+    username: string | null;
+    /** ISO-8601 time the deletion committed. */
+    occurredAt: string;
+    /** `true` when Oxy archived the row to keep financial records. Erase either way. */
+    retained: boolean;
+    /** The application the event was addressed to (`aud`). */
+    applicationId: string;
+    /** Seconds since the epoch the token was issued at (`iat`). */
+    issuedAt: number;
+}
+/** One entry of the account-event pull feed (`GET /account-events`). */
+export interface OxyAccountEventFeedItem {
+    eventId: string;
+    type: 'account.deleted';
+    userId: string;
+    username: string | null;
+    occurredAt: string;
+    retained: boolean;
+    /** The same signed token the webhook carries. Verify it with `verifyAccountEvent`. */
+    token: string;
+}
+export interface OxyAccountEventFeedPage {
+    events: OxyAccountEventFeedItem[];
+    /** Pass back as `after` to continue; unchanged when the page is empty. */
+    nextCursor: string | null;
+}
+export interface VerifyAccountEventOptions {
+    /**
+     * The application id the token must be addressed to. Defaults to the `appId`
+     * of this client's configured service credential.
+     */
+    audience?: string;
+    /** Defaults to `/.well-known/jwks.json` on this client's API origin. */
+    jwksUrl?: string;
+}
+/** Why an account event token was refused. `message` never contains the token. */
+export declare class OxyAccountEventError extends Error {
+    constructor(message: string);
+}
 /**
  * Service app metadata attached to requests authenticated with service tokens.
  *
@@ -177,6 +235,31 @@ export declare function OxyServicesUtilityMixin<T extends typeof OxyServicesBase
          * @internal Used by the auth() middleware — not part of the public API
          */
         verifyServiceActingAs(appId: string, userId: string): Promise<ServiceActingAsVerification | null>;
+        /**
+         * Verify an account event token from Oxy — the body of an account-event
+         * webhook, or an entry's `token` from `listAccountEvents` — and return the
+         * event. Throws {@link OxyAccountEventError} unless the token is an
+         * EdDSA-signed `secevent+jwt` from Oxy's published key set, issued by
+         * `oxy-auth`, addressed to this application, carrying exactly one known
+         * event. A service token (`typ: JWT`) is refused here, as this token is
+         * refused as a service token.
+         *
+         * Node only (it needs `node:crypto`). The caller must still be idempotent on
+         * `eventId`: Oxy delivers at least once, by push and by pull.
+         */
+        verifyAccountEvent(token: string, options?: VerifyAccountEventOptions): Promise<OxyAccountEvent>;
+        /**
+         * One page of account events addressed to this application, oldest first,
+         * from Oxy's pull feed — the reconciliation path behind the webhook. Needs
+         * the service credential (`configureServiceAuth`). Verify each entry's
+         * `token` with {@link verifyAccountEvent} before acting on it.
+         */
+        listAccountEvents(options?: {
+            after?: string;
+            limit?: number;
+        }): Promise<OxyAccountEventFeedPage>;
+        /** @internal The `appId` claim of this client's own service token. */
+        _configuredServiceAppId(): Promise<string>;
         /**
          * Express.js authentication middleware
          *
@@ -380,7 +463,7 @@ export declare function OxyServicesUtilityMixin<T extends typeof OxyServicesBase
         withAuthRetry<T_1>(operation: () => Promise<T_1>, operationName: string, options?: {
             maxRetries?: number;
             retryDelay?: number;
-            authTimeoutMs?: number;
+            authTimeoutMs? /** @internal Per-client public-key cache; never contains private material. */: number;
         }): Promise<T_1>;
         validate(): Promise<boolean>;
         handleError(error: unknown): Error;

package/dist/types/server/requesterAssertion.d.ts

@@ -40,8 +40,8 @@ export declare const oxyRequesterAssertionClaimsSchema: z.ZodObject<{
     sub: string;
     aud: string;
     iss: string;
-    iat: number;
     jti: string;
+    iat: number;
     azp: string;
     cid: string;
     agentId: string;
@@ -50,8 +50,8 @@ export declare const oxyRequesterAssertionClaimsSchema: z.ZodObject<{
     sub: string;
     aud: string;
     iss: string;
-    iat: number;
     jti: string;
+    iat: number;
     azp: string;
     cid: string;
     agentId: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oxy.so/core",
-  "version": "1.12.0",
+  "version": "1.13.0",
   "description": "OxyHQ SDK Foundation — API client, authentication, cryptographic identity, and shared utilities",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",

package/src/i18n/locales/en-US.json

@@ -1934,7 +1934,17 @@
     "warning": "This action cannot be undone. Your account and all associated data will be permanently deleted.",
     "confirmLabel": "Type \"{{username}}\" to confirm",
     "confirm": "Delete Forever",
-    "error": "Failed to delete account"
+    "error": "Failed to delete account",
+    "handoff": {
+      "commonsTitle": "Delete your account in Oxy Commons",
+      "commonsMessage": "Your identity key is kept by Oxy Commons on this device, and deleting your account needs it. Commons will open on Settings > Delete account to finish.",
+      "openCommons": "Open Oxy Commons",
+      "commonsOpenFailed": "Couldn't open Oxy Commons. Open it yourself and go to Settings > Delete account.",
+      "elsewhereTitle": "Delete your account where your identity is",
+      "elsewhereMessage": "Deleting your account needs your identity key, and it isn't on this device. Open Oxy Commons on the device that holds your identity and go to Settings > Delete account, or open {{site}} in a browser that holds it.",
+      "gotIt": "Got it",
+      "identityUnreadable": "Couldn't read this device's identity storage. Unlock your device and try again."
+    }
   },
   "manageAccount": {
     "title": "Manage your Oxy Account",

package/src/i18n/locales/es-ES.json

@@ -1934,7 +1934,17 @@
     "warning": "Esta acción no se puede deshacer. Tu cuenta y todos los datos asociados se eliminarán de forma permanente.",
     "confirmLabel": "Escribe \"{{username}}\" para confirmar",
     "confirm": "Eliminar para siempre",
-    "error": "No se pudo eliminar la cuenta"
+    "error": "No se pudo eliminar la cuenta",
+    "handoff": {
+      "commonsTitle": "Elimina tu cuenta en Oxy Commons",
+      "commonsMessage": "Tu clave de identidad la guarda Oxy Commons en este dispositivo, y eliminar tu cuenta la necesita. Commons se abrirá en Ajustes > Eliminar cuenta para terminar.",
+      "openCommons": "Abrir Oxy Commons",
+      "commonsOpenFailed": "No se pudo abrir Oxy Commons. Ábrelo tú y ve a Ajustes > Eliminar cuenta.",
+      "elsewhereTitle": "Elimina tu cuenta donde está tu identidad",
+      "elsewhereMessage": "Eliminar tu cuenta necesita tu clave de identidad, y no está en este dispositivo. Abre Oxy Commons en el dispositivo que guarda tu identidad y ve a Ajustes > Eliminar cuenta, o abre {{site}} en un navegador que la guarde.",
+      "gotIt": "Entendido",
+      "identityUnreadable": "No se pudo leer el almacén de identidad de este dispositivo. Desbloquea el dispositivo e inténtalo de nuevo."
+    }
   },
   "manageAccount": {
     "title": "Gestiona tu cuenta de Oxy",

package/src/index.ts

@@ -85,6 +85,13 @@ export type {
     RegisterPushTokenInput,
 } from './mixins/OxyServices.notifications';
 export type { ServiceApp, ServiceActingAsVerification, OxyAuthRefusal } from './mixins/OxyServices.utility';
+export type {
+  OxyAccountEvent,
+  OxyAccountEventFeedItem,
+  OxyAccountEventFeedPage,
+  VerifyAccountEventOptions,
+} from './mixins/OxyServices.utility';
+export { OxyAccountEventError, OXY_ACCOUNT_DELETED_EVENT_URI } from './mixins/OxyServices.utility';
 export type {
     ContactDiscoveryMatch,
     ContactDiscoveryResponse,

package/src/mixins/OxyServices.user.ts

@@ -155,6 +155,14 @@ export function OxyServicesUserMixin<T extends typeof OxyServicesBase>(Base: T)
     declare _serviceApiKey: string | null;
     declare _serviceApiSecret: string | null;
 
+    /**
+     * Whether this process can mint a service token by attesting what it is
+     * (ADR 0026), defined on the auth mixin. A host with no key pair that CAN
+     * attest is a first-party backend exactly like one with a key pair, and
+     * `getUsersByIds` must treat it as one.
+     */
+    declare _canUseWorkloadIdentity: () => Promise<boolean>;
+
     /**
      * Get profile by username.
      *
@@ -464,8 +472,10 @@ export function OxyServicesUserMixin<T extends typeof OxyServicesBase>(Base: T)
      * caller, and returns the SAME public `{ data: PublicUserProfile[] }`
      * payload (canonical `name.displayName` + `_count`) in every case — no
      * viewer-specific fields. This method picks the path automatically:
-     * - **Service-configured host (backend):** when `configureServiceAuth(apiKey,
-     *   apiSecret)` has been called, the chunk is fetched via `makeServiceRequest`
+     * - **Service host (backend):** when `configureServiceAuth(apiKey,
+     *   apiSecret)` has been called, OR the process can attest its workload
+     *   identity (ADR 0026 — an ECS task with no key pair), the chunk is fetched
+     *   via `makeServiceRequest`
      *   (attaches `Authorization: Bearer <serviceToken>`). This is the
      *   server-to-server feed/notification hydration path (e.g. Mention's
      *   `PostHydrationService`) and is unchanged.
@@ -500,10 +510,17 @@ export function OxyServicesUserMixin<T extends typeof OxyServicesBase>(Base: T)
         chunks.push(uniqueIds.slice(i, i + USERS_BY_IDS_CHUNK_SIZE));
       }
 
-      // A backend that called configureServiceAuth() uses the bearer-service
-      // path; any other caller (browser / RN with a user session) uses the
-      // user-bearer path.
-      const useServiceAuth = Boolean(this._serviceApiKey && this._serviceApiSecret);
+      // A backend uses the bearer-service path; any other caller (browser / RN
+      // with a user session) uses the user-bearer path. "A backend" means one
+      // that can get a service token at all — a key pair, OR a task role it can
+      // attest. Asking only about the key pair sent every attested backend down
+      // the user path with no bearer: an anonymous request, charged to the
+      // shared NAT address's per-IP budget and slowed by its 500ms penalty.
+      // Measured from Mention's task (2026-09-25): 520ms per anonymous chunk
+      // against 20ms with the service token, enough to put its 1.5s hydration
+      // deadline out of reach on every cache miss.
+      const useServiceAuth = Boolean(this._serviceApiKey && this._serviceApiSecret)
+        || await this._canUseWorkloadIdentity();
 
       // Run chunks concurrently; a single chunk failure must not sink the rest.
       const settled = await Promise.all(

package/src/mixins/OxyServices.utility.ts

@@ -57,6 +57,73 @@ export interface ServiceActingAsVerification {
   scopes: string[];
 }
 
+/** The SET `events` member Oxy uses for an account deletion. */
+export const OXY_ACCOUNT_DELETED_EVENT_URI = 'https://oxy.so/events/account.deleted';
+
+/**
+ * A verified account event from Oxy (OxyHQ/Mention#1169): a person deleted
+ * their Oxy account and every relying application must erase what it holds
+ * for them. Returned by `verifyAccountEvent` only after the signature, `typ`,
+ * issuer and audience all check out.
+ */
+export interface OxyAccountEvent {
+  /** The event id (`jti`). Stable across webhook retries and the pull feed: dedupe on it. */
+  eventId: string;
+  type: 'account.deleted';
+  /** The deleted Oxy account. */
+  userId: string;
+  /**
+   * The account's handle at deletion time, for relying parties that address
+   * the person by handle (an ActivityPub actor URI). `null` when the account had
+   * none, or when the token predates the field.
+   */
+  username: string | null;
+  /** ISO-8601 time the deletion committed. */
+  occurredAt: string;
+  /** `true` when Oxy archived the row to keep financial records. Erase either way. */
+  retained: boolean;
+  /** The application the event was addressed to (`aud`). */
+  applicationId: string;
+  /** Seconds since the epoch the token was issued at (`iat`). */
+  issuedAt: number;
+}
+
+/** One entry of the account-event pull feed (`GET /account-events`). */
+export interface OxyAccountEventFeedItem {
+  eventId: string;
+  type: 'account.deleted';
+  userId: string;
+  username: string | null;
+  occurredAt: string;
+  retained: boolean;
+  /** The same signed token the webhook carries. Verify it with `verifyAccountEvent`. */
+  token: string;
+}
+
+export interface OxyAccountEventFeedPage {
+  events: OxyAccountEventFeedItem[];
+  /** Pass back as `after` to continue; unchanged when the page is empty. */
+  nextCursor: string | null;
+}
+
+export interface VerifyAccountEventOptions {
+  /**
+   * The application id the token must be addressed to. Defaults to the `appId`
+   * of this client's configured service credential.
+   */
+  audience?: string;
+  /** Defaults to `/.well-known/jwks.json` on this client's API origin. */
+  jwksUrl?: string;
+}
+
+/** Why an account event token was refused. `message` never contains the token. */
+export class OxyAccountEventError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'OxyAccountEventError';
+  }
+}
+
 /**
  * Service app metadata attached to requests authenticated with service tokens.
  *
@@ -334,6 +401,147 @@ export function OxyServicesUtilityMixin<T extends typeof OxyServicesBase>(Base:
       }
     }
 
+    /**
+     * Verify an account event token from Oxy — the body of an account-event
+     * webhook, or an entry's `token` from `listAccountEvents` — and return the
+     * event. Throws {@link OxyAccountEventError} unless the token is an
+     * EdDSA-signed `secevent+jwt` from Oxy's published key set, issued by
+     * `oxy-auth`, addressed to this application, carrying exactly one known
+     * event. A service token (`typ: JWT`) is refused here, as this token is
+     * refused as a service token.
+     *
+     * Node only (it needs `node:crypto`). The caller must still be idempotent on
+     * `eventId`: Oxy delivers at least once, by push and by pull.
+     */
+    async verifyAccountEvent(
+      token: string,
+      options: VerifyAccountEventOptions = {},
+    ): Promise<OxyAccountEvent> {
+      if (typeof token !== 'string' || token.length === 0 || token.length > 16 * 1024) {
+        throw new OxyAccountEventError('Account event token is missing or oversized');
+      }
+      const parts = token.split('.');
+      if (parts.length !== 3 || parts.some((part) => part.length === 0)) {
+        throw new OxyAccountEventError('Account event token is not a compact JWS');
+      }
+      const [headerB64, payloadB64, signatureB64] = parts as [string, string, string];
+      let header: Record<string, unknown>;
+      let payload: Record<string, unknown>;
+      try {
+        header = parseJsonSegment(headerB64);
+        payload = parseJsonSegment(payloadB64);
+      } catch {
+        throw new OxyAccountEventError('Account event token is malformed');
+      }
+      if (
+        Object.keys(header).length !== 3
+        || header.alg !== 'EdDSA'
+        || header.typ !== 'secevent+jwt'
+        || typeof header.kid !== 'string'
+        || !/^[A-Za-z0-9._-]{1,128}$/.test(header.kid)
+      ) {
+        throw new OxyAccountEventError('Account event token header is not supported');
+      }
+
+      const nodeCrypto = await loadNodeCrypto();
+      let jwk: ServiceTokenPublicJwk;
+      try {
+        jwk = await resolveServiceTokenPublicKey(
+          header.kid,
+          options.jwksUrl ?? new URL('/.well-known/jwks.json', this.getBaseURL()).toString(),
+          this._serviceTokenJwksCache,
+        );
+      } catch (error) {
+        throw new OxyAccountEventError(
+          error instanceof Error ? error.message.replace('Service token', 'Account event') : 'Signing key is unavailable',
+        );
+      }
+      const signature = Buffer.from(signatureB64, 'base64url');
+      if (signature.toString('base64url') !== signatureB64 || signature.length !== 64) {
+        throw new OxyAccountEventError('Account event token signature is malformed');
+      }
+      let verified = false;
+      try {
+        const publicKey = nodeCrypto.createPublicKey({ key: jwk as unknown as JsonWebKey, format: 'jwk' });
+        verified = nodeCrypto.verify(null, Buffer.from(`${headerB64}.${payloadB64}`), publicKey, signature);
+      } catch {
+        verified = false;
+      }
+      if (!verified) throw new OxyAccountEventError('Account event token signature is invalid');
+
+      if (payload.iss !== OXY_JWT_ISSUER) {
+        throw new OxyAccountEventError('Account event token issuer is not Oxy');
+      }
+      const audience = options.audience ?? await this._configuredServiceAppId();
+      if (typeof payload.aud !== 'string' || payload.aud !== audience) {
+        throw new OxyAccountEventError('Account event token is addressed to another application');
+      }
+      if (typeof payload.jti !== 'string' || payload.jti.length === 0 || payload.jti.length > 128) {
+        throw new OxyAccountEventError('Account event token has no event id');
+      }
+      if (typeof payload.iat !== 'number' || !Number.isFinite(payload.iat)) {
+        throw new OxyAccountEventError('Account event token has no issue time');
+      }
+      const events = payload.events;
+      if (typeof events !== 'object' || events === null || Array.isArray(events)) {
+        throw new OxyAccountEventError('Account event token carries no events');
+      }
+      const entries = Object.entries(events as Record<string, unknown>);
+      const deleted = (events as Record<string, unknown>)[OXY_ACCOUNT_DELETED_EVENT_URI];
+      if (entries.length !== 1 || typeof deleted !== 'object' || deleted === null || Array.isArray(deleted)) {
+        throw new OxyAccountEventError('Account event token carries an unknown event');
+      }
+      const body = deleted as Record<string, unknown>;
+      if (typeof body.userId !== 'string' || body.userId.length === 0 || body.userId.length > 128) {
+        throw new OxyAccountEventError('Account event names no account');
+      }
+      if (typeof body.occurredAt !== 'string' || Number.isNaN(Date.parse(body.occurredAt))) {
+        throw new OxyAccountEventError('Account event has no occurrence time');
+      }
+      if (body.username !== undefined && body.username !== null && typeof body.username !== 'string') {
+        throw new OxyAccountEventError('Account event username is malformed');
+      }
+      return {
+        eventId: payload.jti,
+        type: 'account.deleted',
+        userId: body.userId,
+        username: typeof body.username === 'string' ? body.username : null,
+        occurredAt: body.occurredAt,
+        retained: body.retained === true,
+        applicationId: payload.aud,
+        issuedAt: payload.iat,
+      };
+    }
+
+    /**
+     * One page of account events addressed to this application, oldest first,
+     * from Oxy's pull feed — the reconciliation path behind the webhook. Needs
+     * the service credential (`configureServiceAuth`). Verify each entry's
+     * `token` with {@link verifyAccountEvent} before acting on it.
+     */
+    async listAccountEvents(
+      options: { after?: string; limit?: number } = {},
+    ): Promise<OxyAccountEventFeedPage> {
+      const serviceToken = await (this as unknown as OxyAuthInstance).getServiceToken();
+      const query: Record<string, string> = {};
+      if (options.after) query.after = options.after;
+      if (options.limit !== undefined) query.limit = String(options.limit);
+      return this.makeRequest<OxyAccountEventFeedPage>('GET', '/account-events', query, {
+        cache: false,
+        headers: { Authorization: `Bearer ${serviceToken}` },
+      });
+    }
+
+    /** @internal The `appId` claim of this client's own service token. */
+    async _configuredServiceAppId(): Promise<string> {
+      const serviceToken = await (this as unknown as OxyAuthInstance).getServiceToken();
+      const appId = jwtDecode<JwtPayload>(serviceToken).appId;
+      if (typeof appId !== 'string' || appId.length === 0) {
+        throw new OxyAccountEventError('No audience given and the service credential names no application');
+      }
+      return appId;
+    }
+
     /**
      * Express.js authentication middleware
      *

package/src/mixins/__tests__/accountEvents.test.ts

@@ -0,0 +1,158 @@
+import { generateKeyPairSync, sign as signBytes, type KeyObject } from 'node:crypto';
+import { OxyServices } from '../../OxyServices';
+import { OXY_ACCOUNT_DELETED_EVENT_URI, OxyAccountEventError } from '../OxyServices.utility';
+
+const b64url = (value: string | Uint8Array): string => Buffer.from(value).toString('base64url');
+
+function sign(
+  privateKey: KeyObject,
+  header: Record<string, unknown>,
+  payload: Record<string, unknown>,
+): string {
+  const signingInput = `${b64url(JSON.stringify(header))}.${b64url(JSON.stringify(payload))}`;
+  return `${signingInput}.${b64url(signBytes(null, Buffer.from(signingInput), privateKey))}`;
+}
+
+const KID = 'oxy-service-test';
+
+function eventToken(
+  privateKey: KeyObject,
+  overrides: { header?: Record<string, unknown>; payload?: Record<string, unknown>; event?: Record<string, unknown> } = {},
+): string {
+  return sign(
+    privateKey,
+    { alg: 'EdDSA', typ: 'secevent+jwt', kid: KID, ...overrides.header },
+    {
+      iss: 'oxy-auth',
+      aud: 'app-mention',
+      iat: 1_790_000_000,
+      jti: '019a0000-0000-7000-8000-000000000001',
+      events: {
+        [OXY_ACCOUNT_DELETED_EVENT_URI]: {
+          userId: 'user-deleted',
+          username: 'qatest0925',
+          occurredAt: '2026-09-26T09:14:00.000Z',
+          retained: false,
+          ...overrides.event,
+        },
+      },
+      ...overrides.payload,
+    },
+  );
+}
+
+describe('verifyAccountEvent', () => {
+  const oxyKey = generateKeyPairSync('ed25519');
+  const strangerKey = generateKeyPairSync('ed25519');
+  const jwk = { ...oxyKey.publicKey.export({ format: 'jwk' }), use: 'sig', alg: 'EdDSA', kid: KID };
+
+  let fetchSpy: jest.SpyInstance;
+  beforeEach(() => {
+    fetchSpy = jest.spyOn(globalThis, 'fetch').mockImplementation(async () => new Response(
+      JSON.stringify({ keys: [jwk] }),
+      { status: 200, headers: { 'content-type': 'application/json' } },
+    ));
+  });
+  afterEach(() => jest.restoreAllMocks());
+
+  const client = () => new OxyServices({ baseURL: 'https://api.oxy.test' });
+
+  it('returns the event from a genuine Oxy-signed token, verified against the public JWKS', async () => {
+    const event = await client().verifyAccountEvent(eventToken(oxyKey.privateKey), { audience: 'app-mention' });
+
+    expect(event).toEqual({
+      eventId: '019a0000-0000-7000-8000-000000000001',
+      type: 'account.deleted',
+      userId: 'user-deleted',
+      username: 'qatest0925',
+      occurredAt: '2026-09-26T09:14:00.000Z',
+      retained: false,
+      applicationId: 'app-mention',
+      issuedAt: 1_790_000_000,
+    });
+    expect(fetchSpy).toHaveBeenCalledWith(
+      'https://api.oxy.test/.well-known/jwks.json',
+      expect.objectContaining({ method: 'GET', redirect: 'error' }),
+    );
+  });
+
+  it('reads a token without `username` (issued before the field existed) as username null', async () => {
+    const token = eventToken(oxyKey.privateKey, { event: { username: undefined } });
+    const event = await client().verifyAccountEvent(token, { audience: 'app-mention' });
+    expect(event.username).toBeNull();
+  });
+
+  it('carries `retained` through for an archived account', async () => {
+    const token = eventToken(oxyKey.privateKey, { event: { retained: true } });
+    await expect(client().verifyAccountEvent(token, { audience: 'app-mention' }))
+      .resolves.toMatchObject({ retained: true });
+  });
+
+  it('defaults the audience to the appId of the configured service credential', async () => {
+    const oxy = client();
+    const serviceToken = `${b64url(JSON.stringify({ alg: 'EdDSA' }))}.${b64url(JSON.stringify({ appId: 'app-mention' }))}.sig`;
+    jest.spyOn(oxy, 'getServiceToken').mockResolvedValue(serviceToken);
+
+    await expect(oxy.verifyAccountEvent(eventToken(oxyKey.privateKey))).resolves.toMatchObject({
+      applicationId: 'app-mention',
+    });
+    await expect(oxy.verifyAccountEvent(eventToken(oxyKey.privateKey, { payload: { aud: 'app-other' } })))
+      .rejects.toThrow('addressed to another application');
+  });
+
+  const refusals: Array<[string, () => string, string]> = [
+    ['a token signed by a key Oxy did not publish', () => eventToken(strangerKey.privateKey), 'signature is invalid'],
+    ['a service token (typ JWT) replayed as an event', () => eventToken(oxyKey.privateKey, { header: { typ: 'JWT' } }), 'header is not supported'],
+    ['a token for another application', () => eventToken(oxyKey.privateKey, { payload: { aud: 'app-other' } }), 'addressed to another application'],
+    ['a token from another issuer', () => eventToken(oxyKey.privateKey, { payload: { iss: 'someone-else' } }), 'issuer is not Oxy'],
+    ['a token without an event id', () => eventToken(oxyKey.privateKey, { payload: { jti: undefined } }), 'no event id'],
+    ['a token with an unknown event', () => eventToken(oxyKey.privateKey, { payload: { events: { 'https://oxy.so/events/other': {} } } }), 'unknown event'],
+    ['a token naming no account', () => eventToken(oxyKey.privateKey, { event: { userId: '' } }), 'names no account'],
+    ['a token whose username is not a string', () => eventToken(oxyKey.privateKey, { event: { username: 42 } }), 'username is malformed'],
+    ['a token with an unknown key id', () => eventToken(oxyKey.privateKey, { header: { kid: 'rotated-away' } }), 'unknown'],
+  ];
+
+  it.each(refusals)('refuses %s', async (_label, build, message) => {
+    const attempt = client().verifyAccountEvent(build(), { audience: 'app-mention' });
+    await expect(attempt).rejects.toBeInstanceOf(OxyAccountEventError);
+    await expect(client().verifyAccountEvent(build(), { audience: 'app-mention' })).rejects.toThrow(message);
+  });
+
+  it('refuses a tampered payload', async () => {
+    const [header, , signature] = eventToken(oxyKey.privateKey).split('.');
+    const forged = b64url(JSON.stringify({
+      iss: 'oxy-auth',
+      aud: 'app-mention',
+      iat: 1,
+      jti: 'x',
+      events: { [OXY_ACCOUNT_DELETED_EVENT_URI]: { userId: 'someone-else', occurredAt: '2026-09-26T00:00:00Z' } },
+    }));
+    await expect(client().verifyAccountEvent(`${header}.${forged}.${signature}`, { audience: 'app-mention' }))
+      .rejects.toThrow('signature is invalid');
+  });
+
+  it('refuses garbage without fetching keys', async () => {
+    await expect(client().verifyAccountEvent('not-a-token', { audience: 'app-mention' }))
+      .rejects.toThrow('not a compact JWS');
+    expect(fetchSpy).not.toHaveBeenCalled();
+  });
+});
+
+describe('listAccountEvents', () => {
+  afterEach(() => jest.restoreAllMocks());
+
+  it('reads the pull feed with the service token and passes the cursor', async () => {
+    const oxy = new OxyServices({ baseURL: 'https://api.oxy.test' });
+    jest.spyOn(oxy, 'getServiceToken').mockResolvedValue('service-token');
+    const page = { events: [], nextCursor: 'cursor-1' };
+    const request = jest.spyOn(oxy, 'makeRequest').mockResolvedValue(page as never);
+
+    await expect(oxy.listAccountEvents({ after: 'cursor-1', limit: 50 })).resolves.toEqual(page);
+    expect(request).toHaveBeenCalledWith(
+      'GET',
+      '/account-events',
+      { after: 'cursor-1', limit: '50' },
+      expect.objectContaining({ cache: false, headers: { Authorization: 'Bearer service-token' } }),
+    );
+  });
+});