@atproto/dev-env 0.0.0-spaces-alpha-20260818163953

package/dist/util.js

@@ -0,0 +1,86 @@
+import * as plc from '@did-plc/lib';
+import { request } from 'undici';
+import { Secp256k1Keypair } from '@atproto/crypto';
+export const mockNetworkUtilities = (pds, bsky) => {
+    const pdses = Array.isArray(pds) ? pds : [pds];
+    for (const p of pdses) {
+        mockResolvers(p.ctx.idResolver, pdses);
+    }
+    if (bsky) {
+        mockResolvers(bsky.ctx.idResolver, pdses);
+        mockResolvers(bsky.dataplane.idResolver, pdses);
+    }
+};
+export const mockResolvers = (idResolver, pds, 
+// handles resolve against the matching pds by default, but may point
+// elsewhere e.g. an entryway
+handleResolveUrl) => {
+    const pdses = Array.isArray(pds) ? pds : [pds];
+    // Map pds public url to its local url when resolving from plc
+    const origResolveDid = idResolver.did.resolveNoCache;
+    idResolver.did.resolveNoCache = async (did) => {
+        const result = await origResolveDid.call(idResolver.did, did);
+        const service = result?.service?.find((svc) => svc.id === '#atproto_pds');
+        if (typeof service?.serviceEndpoint === 'string') {
+            for (const p of pdses) {
+                service.serviceEndpoint = service.serviceEndpoint.replace(p.ctx.cfg.service.publicUrl, `http://localhost:${p.port}`);
+            }
+        }
+        return result;
+    };
+    const origResolveHandleDns = idResolver.handle.resolveDns;
+    idResolver.handle.resolve = async (handle) => {
+        // Handle domains across PDSes are disjoint suffixes (.test, .test2, ...);
+        // first match wins.
+        const match = pdses.find((p) => p.ctx.cfg.identity.serviceHandleDomains.some((d) => handle.endsWith(d)));
+        if (!match) {
+            return origResolveHandleDns.call(idResolver.handle, handle);
+        }
+        const url = new URL(`/.well-known/atproto-did`, handleResolveUrl ?? match.url);
+        try {
+            const res = await request(url, { headers: { host: handle } });
+            if (res.statusCode !== 200) {
+                await res.body.dump();
+                return undefined;
+            }
+            return res.body.text();
+        }
+        catch (err) {
+            return undefined;
+        }
+    };
+};
+export const mockMailer = (pds) => {
+    const mailer = pds.ctx.mailer;
+    const _origSendMail = mailer.transporter.sendMail;
+    mailer.transporter.sendMail = async (opts) => {
+        const result = await _origSendMail.call(mailer.transporter, opts);
+        console.log(`✉️ Email: ${JSON.stringify(result, null, 2)}`);
+        return result;
+    };
+};
+const usedLockIds = new Set();
+export const uniqueLockId = () => {
+    let lockId;
+    do {
+        lockId = 1000 + Math.ceil(1000 * Math.random());
+    } while (usedLockIds.has(lockId));
+    usedLockIds.add(lockId);
+    return lockId;
+};
+export const createDidAndKey = async (opts) => {
+    const { plcUrl, handle, pds } = opts;
+    const key = await Secp256k1Keypair.create({ exportable: true });
+    const did = await new plc.Client(plcUrl).createDid({
+        signingKey: key.did(),
+        rotationKeys: [key.did()],
+        handle,
+        pds,
+        signer: key,
+    });
+    return {
+        key,
+        did,
+    };
+};
+//# sourceMappingURL=util.js.map

package/dist/util.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"util.js","sourceRoot":"","sources":["../src/util.ts"],"names":[],"mappings":"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","sourcesContent":["import * as plc from '@did-plc/lib'\nimport { request } from 'undici'\nimport { Secp256k1Keypair } from '@atproto/crypto'\nimport type { IdResolver } from '@atproto/identity'\nimport type { TestBsky } from './bsky.js'\nimport type { TestPds } from './pds.js'\nimport type { DidAndKey } from './types.js'\n\nexport const mockNetworkUtilities = (\n  pds: TestPds | TestPds[],\n  bsky?: TestBsky,\n) => {\n  const pdses = Array.isArray(pds) ? pds : [pds]\n  for (const p of pdses) {\n    mockResolvers(p.ctx.idResolver, pdses)\n  }\n  if (bsky) {\n    mockResolvers(bsky.ctx.idResolver, pdses)\n    mockResolvers(bsky.dataplane.idResolver, pdses)\n  }\n}\n\nexport const mockResolvers = (\n  idResolver: IdResolver,\n  pds: TestPds | TestPds[],\n  // handles resolve against the matching pds by default, but may point\n  // elsewhere e.g. an entryway\n  handleResolveUrl?: string,\n) => {\n  const pdses = Array.isArray(pds) ? pds : [pds]\n\n  // Map pds public url to its local url when resolving from plc\n  const origResolveDid = idResolver.did.resolveNoCache\n  idResolver.did.resolveNoCache = async (did: string) => {\n    const result = await (origResolveDid.call(\n      idResolver.did,\n      did,\n    ) as ReturnType<typeof origResolveDid>)\n    const service = result?.service?.find((svc) => svc.id === '#atproto_pds')\n    if (typeof service?.serviceEndpoint === 'string') {\n      for (const p of pdses) {\n        service.serviceEndpoint = service.serviceEndpoint.replace(\n          p.ctx.cfg.service.publicUrl,\n          `http://localhost:${p.port}`,\n        )\n      }\n    }\n    return result\n  }\n\n  const origResolveHandleDns = idResolver.handle.resolveDns\n  idResolver.handle.resolve = async (handle: string) => {\n    // Handle domains across PDSes are disjoint suffixes (.test, .test2, ...);\n    // first match wins.\n    const match = pdses.find((p) =>\n      p.ctx.cfg.identity.serviceHandleDomains.some((d) => handle.endsWith(d)),\n    )\n    if (!match) {\n      return origResolveHandleDns.call(idResolver.handle, handle)\n    }\n\n    const url = new URL(\n      `/.well-known/atproto-did`,\n      handleResolveUrl ?? match.url,\n    )\n    try {\n      const res = await request(url, { headers: { host: handle } })\n      if (res.statusCode !== 200) {\n        await res.body.dump()\n        return undefined\n      }\n\n      return res.body.text()\n    } catch (err) {\n      return undefined\n    }\n  }\n}\n\nexport const mockMailer = (pds: TestPds) => {\n  const mailer = pds.ctx.mailer\n  const _origSendMail = mailer.transporter.sendMail\n  mailer.transporter.sendMail = async (opts) => {\n    const result = await _origSendMail.call(mailer.transporter, opts)\n    console.log(`✉️ Email: ${JSON.stringify(result, null, 2)}`)\n    return result\n  }\n}\n\nconst usedLockIds = new Set()\nexport const uniqueLockId = () => {\n  let lockId: number\n  do {\n    lockId = 1000 + Math.ceil(1000 * Math.random())\n  } while (usedLockIds.has(lockId))\n  usedLockIds.add(lockId)\n  return lockId\n}\n\nexport const createDidAndKey = async (opts: {\n  plcUrl: string\n  handle: string\n  pds: string\n}): Promise<DidAndKey> => {\n  const { plcUrl, handle, pds } = opts\n  const key = await Secp256k1Keypair.create({ exportable: true })\n  const did = await new plc.Client(plcUrl).createDid({\n    signingKey: key.did(),\n    rotationKeys: [key.did()],\n    handle,\n    pds,\n    signer: key,\n  })\n  return {\n    key,\n    did,\n  }\n}\n"]}

package/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "@atproto/dev-env",
+  "version": "0.0.0-spaces-alpha-20260818163953",
+  "license": "MIT",
+  "description": "Local development environment helper for atproto development",
+  "keywords": [
+    "atproto"
+  ],
+  "homepage": "https://atproto.com",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/bluesky-social/atproto",
+    "directory": "packages/dev-env"
+  },
+  "files": [
+    "./src",
+    "./tsconfig.json",
+    "./tsconfig.build.json",
+    "./dist",
+    "./README.md",
+    "./CHANGELOG.md"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "dependencies": {
+    "@did-plc/lib": "^0.0.1",
+    "@did-plc/server": "^0.0.1",
+    "dotenv": "^16.0.3",
+    "express": "^4.18.2",
+    "get-port": "^5.1.1",
+    "http-terminator": "^3.2.0",
+    "multiformats": "^13.0.0",
+    "uint8arrays": "^5.0.0",
+    "undici": "^8.5.0",
+    "@atproto/api": "^0.0.0-spaces-alpha-20260818163953",
+    "@atproto/bsky": "^0.0.0-spaces-alpha-20260818163953",
+    "@atproto/common-web": "^0.0.0-spaces-alpha-20260818163953",
+    "@atproto/identity": "^0.0.0-spaces-alpha-20260818163953",
+    "@atproto/bsync": "^0.0.0-spaces-alpha-20260818163953",
+    "@atproto/lex": "^0.0.0-spaces-alpha-20260818163953",
+    "@atproto/lexicon": "^0.0.0-spaces-alpha-20260818163953",
+    "@atproto/crypto": "^0.0.0-spaces-alpha-20260818163953",
+    "@atproto/ozone": "^0.0.0-spaces-alpha-20260818163953",
+    "@atproto/pds": "^0.0.0-spaces-alpha-20260818163953",
+    "@atproto/sync": "^0.0.0-spaces-alpha-20260818163953",
+    "@atproto/xrpc-server": "^0.0.0-spaces-alpha-20260818163953",
+    "@atproto/syntax": "^0.0.0-spaces-alpha-20260818163953"
+  },
+  "devDependencies": {
+    "@types/express": "^4.17.13"
+  },
+  "scripts": {
+    "build": "tsc --build tsconfig.build.json",
+    "start": "../dev-infra/with-test-redis-and-db.sh node --enable-source-maps dist/bin.js",
+    "dev": "../dev-infra/with-test-redis-and-db.sh node --enable-source-maps --watch dist/bin.js",
+    "start:multi-pds": "node --enable-source-maps dist/bin-multi-pds.js"
+  },
+  "bin": {
+    "dev-env": "bin.js"
+  }
+}

package/src/bin-multi-pds.ts

@@ -0,0 +1,166 @@
+import './env.js'
+import getPort from 'get-port'
+import { IntrospectServer } from './introspect.js'
+import { TestPds } from './pds.js'
+import { TestPlc } from './plc.js'
+import { LexiconAuthorityProfile } from './service-profile-lexicon.js'
+import { mockMailer, mockNetworkUtilities } from './util.js'
+
+const INTROSPECT_PORT = 2581
+const PRIMARY_PDS_PORT = 2583
+const PLC_PORT = 2582
+
+// The lex-authority account hosts permission-set / space lexicon docs that
+// dev-env PDSes resolve via `lexiconDidAuthority`. Demo apps can log into this
+// account to publish new lexicons (e.g. `space`-typed documents) at runtime.
+const LEX_AUTHORITY_USER = {
+  email: 'lex-authority@test.com',
+  handle: 'lex-authority.test',
+  password: 'hunter2',
+}
+
+const parsePdsCount = (): number => {
+  const arg = process.argv[2]
+  if (arg === undefined) return 3
+  const n = Number.parseInt(arg, 10)
+  if (!Number.isFinite(n) || n < 1) {
+    throw new Error(`Invalid PDS count "${arg}": must be an integer >= 1`)
+  }
+  return n
+}
+
+const run = async () => {
+  const totalPdsCount = parsePdsCount()
+  const extraPdsCount = totalPdsCount - 1
+
+  console.log(`
+██████╗
+██╔═══██╗
+██║██╗██║
+██║██║██║
+╚█║████╔╝
+ ╚╝╚═══╝  protocol
+
+[ created by Bluesky ]`)
+
+  const plc = await TestPlc.create({ port: PLC_PORT })
+
+  // Step 1 — scratch PDS. We need an existing PDS to host the lex-authority
+  // account creation, but we don't want the scratch to live past startup. The
+  // account migrates to the primary PDS once we know its DID.
+  const scratchPds = await TestPds.create({
+    didPlcUrl: plc.url,
+    inviteRequired: false,
+    port: await getPort(),
+  })
+
+  // Step 2 — create the lex-authority account on the scratch PDS so we can
+  // capture its DID before any "real" PDS spins up with `lexiconDidAuthority`
+  // pointing at it.
+  const lexAuthority = await LexiconAuthorityProfile.create(
+    scratchPds,
+    LEX_AUTHORITY_USER,
+  )
+  const lexAuthorityDid = lexAuthority.did
+
+  // Step 3 — primary PDS, configured to resolve lexicons from the authority.
+  const primary = await TestPds.create({
+    port: PRIMARY_PDS_PORT,
+    hostname: 'localhost',
+    enableDidDocWithSession: true,
+    didPlcUrl: plc.url,
+    lexiconDidAuthority: lexAuthorityDid,
+  })
+
+  // Step 4 — migrate the authority account to the primary PDS, then publish
+  // the seed lexicon docs (permission sets, etc.) at the new home.
+  await lexAuthority.migrateTo(primary)
+  await lexAuthority.createRecords()
+
+  // Step 5 — extra PDSes, each pointing at the same lex authority.
+  const extraPdses: TestPds[] = []
+  for (let i = 0; i < extraPdsCount; i++) {
+    const domain = `.test${i + 2}`
+    const extra = await TestPds.create({
+      didPlcUrl: plc.url,
+      port: await getPort(),
+      serviceHandleDomains: [domain],
+      lexiconDidAuthority: lexAuthorityDid,
+    })
+    extraPdses.push(extra)
+  }
+
+  // Step 6 — close the scratch PDS now that the authority lives on primary.
+  await scratchPds.close()
+
+  // Mock network utilities (handle/DID resolution) across the surviving PDSes.
+  const allPdsesArray = [primary, ...extraPdses]
+  mockNetworkUtilities(allPdsesArray)
+  for (const pds of allPdsesArray) {
+    mockMailer(pds)
+  }
+
+  const introspect = await IntrospectServer.start(
+    INTROSPECT_PORT,
+    plc,
+    allPdsesArray,
+    undefined,
+    undefined,
+    undefined,
+    {
+      did: lexAuthorityDid,
+      handle: LEX_AUTHORITY_USER.handle,
+      password: LEX_AUTHORITY_USER.password,
+      pds: primary.url,
+    },
+  )
+
+  console.log(`🔍 Introspection server http://localhost:${introspect.port}`)
+  console.log(`👤 DID Placeholder server ${plc.url}`)
+
+  const allPdses: { label: string; pds: TestPds; domain: string }[] = [
+    { label: 'pds1 (primary)', pds: primary, domain: 'test' },
+    ...extraPdses.map((pds, i) => ({
+      label: `pds${i + 2}`,
+      pds,
+      domain: `test${i + 2}`,
+    })),
+  ]
+
+  for (const { label, pds } of allPdses) {
+    console.log(`🌞 ${label} http://localhost:${pds.port}`)
+  }
+
+  console.log(
+    `\n📚 Lex authority ${LEX_AUTHORITY_USER.handle} (${lexAuthorityDid})`,
+  )
+  console.log(
+    `   hosted on pds1 — log in with password "${LEX_AUTHORITY_USER.password}"`,
+  )
+
+  // Seed alice/bob/carol on each PDS so each has data that's reachable cross-PDS.
+  const seedNames = ['alice', 'bob', 'carol']
+  const seeded: { handle: string; did: string; pds: string }[] = []
+  for (const { label, pds, domain } of allPdses) {
+    const agent = pds.getAgent()
+    for (const name of seedNames) {
+      const handle = `${name}.${domain}`
+      const res = await agent.com.atproto.server.createAccount({
+        handle,
+        email: `${name}-${domain}@test.com`,
+        password: `${name}-pass`,
+      })
+      seeded.push({ handle, did: res.data.did, pds: label })
+    }
+  }
+
+  console.log('\n👥 Seeded accounts:')
+  for (const acct of seeded) {
+    console.log(
+      `  ${acct.pds.padEnd(16)} handle=${acct.handle.padEnd(20)} did=${acct.did}`,
+    )
+  }
+  console.log('  (passwords: alice-pass / bob-pass / carol-pass)')
+}
+
+run()

package/src/bin.ts

@@ -0,0 +1,64 @@
+import './env.js'
+import { generateMockSetup } from './mock/index.js'
+import { TestNetwork } from './network.js'
+import { mockMailer } from './util.js'
+
+const run = async () => {
+  console.log(`
+██████╗
+██╔═══██╗
+██║██╗██║
+██║██║██║
+╚█║████╔╝
+ ╚╝╚═══╝  protocol
+
+[ created by Bluesky ]`)
+
+  const network = await TestNetwork.create({
+    pds: {
+      port: 2583,
+      hostname: 'localhost',
+      enableDidDocWithSession: true,
+    },
+    bsky: {
+      dbPostgresSchema: 'bsky',
+      port: 2584,
+      publicUrl: 'http://localhost:2584',
+    },
+    plc: { port: 2582 },
+    ozone: {
+      port: 2587,
+      chatUrl: 'http://localhost:2590', // must run separate chat service
+      chatDid: 'did:example:chat',
+      dbMaterializedViewRefreshIntervalMs: 30_000,
+    },
+    introspect: { port: 2581 },
+  })
+  mockMailer(network.pds)
+
+  if (network.introspect) {
+    console.log(
+      `🔍 Dev-env introspection server http://localhost:${network.introspect.port}`,
+    )
+  }
+  console.log(`👤 DID Placeholder server http://localhost:${network.plc.port}`)
+  console.log(`🌞 Main PDS http://localhost:${network.pds.port}`)
+  console.log(`🌞 Main PDS account DB`, network.pds.ctx.cfg.db.accountDbLoc)
+  console.log(
+    `🔨 Lexicon authority DID ${network.pds.ctx.cfg.lexicon.didAuthority}`,
+  )
+  console.log(`🗼 Ozone server http://localhost:${network.ozone.port}`)
+  console.log(`🗼 Ozone service DID ${network.ozone.ctx.cfg.service.did}`)
+  console.log(`🔄 Bsync server http://localhost:${network.bsync.port}`)
+  console.log(`🌅 Bsky Appview http://localhost:${network.bsky.port}`)
+  console.log(`🌅 Bsky Appview DID ${network.bsky.serverDid}`)
+  for (const fg of network.feedGens) {
+    console.log(`🤖 Feed Generator (${fg.did}) http://localhost:${fg.port}`)
+  }
+
+  console.time('✅ Dev environment is ready')
+  await generateMockSetup(network)
+  console.timeEnd('✅ Dev environment is ready')
+}
+
+run()

package/src/bsky.ts

@@ -0,0 +1,198 @@
+import { Client as PlcClient } from '@did-plc/lib'
+import getPort from 'get-port'
+import * as ui8 from 'uint8arrays'
+import { AtpAgent } from '@atproto/api'
+import * as bsky from '@atproto/bsky'
+import { Secp256k1Keypair } from '@atproto/crypto'
+import { Client } from '@atproto/lex'
+import type { DidString } from '@atproto/syntax'
+import { ADMIN_PASSWORD, EXAMPLE_LABELER } from './const.js'
+import type { BskyConfig } from './types.js'
+export * from '@atproto/bsky'
+
+export class TestBsky {
+  constructor(
+    public url: string,
+    public port: number,
+    public db: bsky.Database,
+    public server: bsky.BskyAppView,
+    public dataplane: bsky.DataPlaneServer,
+    public bsyncSub: bsky.BsyncSubscription,
+    public sub: bsky.RepoSubscription,
+    public serverDid: string,
+  ) {}
+
+  static async create(cfg: BskyConfig): Promise<TestBsky> {
+    const serviceKeypair = cfg.privateKey
+      ? await Secp256k1Keypair.import(cfg.privateKey)
+      : await Secp256k1Keypair.create()
+    const plcClient = new PlcClient(cfg.plcUrl)
+
+    const port = cfg.port || (await getPort())
+    const url = `http://localhost:${port}`
+    const serverDid = (await plcClient.createDid({
+      signingKey: serviceKeypair.did(),
+      rotationKeys: [serviceKeypair.did()],
+      handle: 'bsky.test',
+      pds: `http://localhost:${port}`,
+      signer: serviceKeypair,
+    })) as DidString
+
+    const endpoint = `http://localhost:${port}`
+
+    await plcClient.updateData(serverDid, serviceKeypair, (x) => {
+      x.services['bsky_notif'] = {
+        type: 'BskyNotificationService',
+        endpoint,
+      }
+      x.services['bsky_appview'] = {
+        type: 'BskyAppView',
+        endpoint,
+      }
+      return x
+    })
+
+    // shared across server, ingester, and indexer in order to share pool, avoid too many pg connections.
+    const db = new bsky.Database({
+      url: cfg.dbPostgresUrl,
+      schema: cfg.dbPostgresSchema,
+      poolSize: 10,
+    })
+
+    const dataplanePort = await getPort()
+    const dataplane = await bsky.DataPlaneServer.create(
+      db,
+      dataplanePort,
+      cfg.plcUrl,
+    )
+
+    const config = new bsky.ServerConfig({
+      version: 'unknown',
+      port,
+      didPlcUrl: cfg.plcUrl,
+      publicUrl: 'https://bsky.public.url',
+      serverDid,
+      alternateAudienceDids: [],
+      dataplaneUrls: [`http://localhost:${dataplanePort}`],
+      dataplaneHttpVersion: '1.1',
+      bsyncHttpVersion: '1.1',
+      bsyncApiKey: 'bsync-api-key',
+      modServiceDid: cfg.modServiceDid ?? 'did:example:invalidMod',
+      labelsFromIssuerDids: [EXAMPLE_LABELER],
+      bigThreadUris: new Set(),
+      maxThreadParents: cfg.maxThreadParents ?? 50,
+      disableSsrfProtection: true,
+      searchTagsHide: new Set(),
+      searchTagsHideAll: new Set(),
+      threadTagsBumpDown: new Set(),
+      threadTagsHide: new Set(),
+      visibilityTagHide: '',
+      visibilityTagRankPrefix: '',
+      debugFieldAllowedDids: new Set(),
+      draftsLimit: 500,
+      ...cfg,
+      adminPasswords: [ADMIN_PASSWORD],
+      etcdHosts: [],
+    })
+
+    // Separate migration db in case migration changes some connection state that we need in the tests, e.g. "alter database ... set ..."
+    const migrationDb = new bsky.Database({
+      url: cfg.dbPostgresUrl,
+      schema: cfg.dbPostgresSchema,
+    })
+    if (cfg.migration) {
+      await migrationDb.migrateToOrThrow(cfg.migration)
+    } else {
+      await migrationDb.migrateToLatestOrThrow()
+    }
+    await migrationDb.close()
+
+    // api server
+    const server = bsky.BskyAppView.create({
+      config,
+      signingKey: serviceKeypair,
+    })
+
+    const bsyncSub = new bsky.BsyncSubscription({
+      config,
+      db,
+    })
+
+    const sub = new bsky.RepoSubscription({
+      service: cfg.repoProvider,
+      db,
+      idResolver: dataplane.idResolver,
+    })
+
+    await server.start()
+
+    bsyncSub.start()
+    void sub.start()
+
+    return new TestBsky(
+      url,
+      port,
+      db,
+      server,
+      dataplane,
+      bsyncSub,
+      sub,
+      serverDid,
+    )
+  }
+
+  get ctx(): bsky.AppContext {
+    return this.server.ctx
+  }
+
+  getAgent(): AtpAgent {
+    const agent = new AtpAgent({ service: this.url })
+    agent.configureLabelers([EXAMPLE_LABELER])
+    return agent
+  }
+
+  getClient(): Client {
+    const client = new Client({ service: this.url })
+    client.setLabelers([EXAMPLE_LABELER])
+    return client
+  }
+
+  adminAuth(): string {
+    const [password] = this.ctx.cfg.adminPasswords
+    return (
+      'Basic ' +
+      ui8.toString(ui8.fromString(`admin:${password}`, 'utf8'), 'base64pad')
+    )
+  }
+
+  adminAuthHeaders() {
+    return {
+      authorization: this.adminAuth(),
+    }
+  }
+
+  async close() {
+    // @TODO Use disposable stack when it becomes available (Node24+)
+    try {
+      await this.server.destroy()
+    } finally {
+      try {
+        await this.bsyncSub.destroy()
+      } finally {
+        try {
+          await this.dataplane.destroy()
+        } finally {
+          try {
+            await this.sub.destroy()
+          } finally {
+            await this.db.close()
+          }
+        }
+      }
+    }
+  }
+
+  async [Symbol.asyncDispose]() {
+    await this.close()
+  }
+}

package/src/bsync.ts

@@ -0,0 +1,66 @@
+import getPort from 'get-port'
+import * as bsync from '@atproto/bsync'
+import type { BsyncConfig } from './types.js'
+
+export class TestBsync {
+  constructor(
+    public url: string,
+    public port: number,
+    public service: bsync.BsyncService,
+  ) {}
+
+  static async create(cfg: BsyncConfig): Promise<TestBsync> {
+    const port = cfg.port || (await getPort())
+    const url = `http://localhost:${port}`
+
+    const config = bsync.envToCfg({
+      port,
+      apiKeys: cfg.apiKeys ?? ['api-key'],
+      dbSchema: 'bsync',
+      // Keep the pool small: a bsync runs alongside every test network, so a
+      // default-sized pool per network quickly exhausts postgres connections.
+      dbPoolSize: cfg.dbPoolSize ?? 5,
+      ...cfg,
+    })
+
+    const service = await bsync.BsyncService.create(config)
+    await service.ctx.db.migrateToLatestOrThrow()
+    await service.start()
+
+    return new TestBsync(url, port, service)
+  }
+
+  get ctx(): bsync.AppContext {
+    return this.service.ctx
+  }
+
+  /**
+   * Current head (max id) of each operation stream. Used to wait for the bsky
+   * bsync subscription to catch up in tests, without waiting for the long-poll
+   * timeout.
+   */
+  async getStreamHeads(): Promise<{
+    op?: string
+    mute?: string
+    notif?: string
+  }> {
+    const db = this.ctx.db.db
+    const max = async (table: 'operation' | 'mute_op' | 'notif_op') => {
+      const row = await db
+        .selectFrom(table)
+        .select((eb) => eb.fn.max('id').as('id'))
+        .executeTakeFirst()
+      return row?.id != null ? String(row.id) : undefined
+    }
+    const [op, mute, notif] = await Promise.all([
+      max('operation'),
+      max('mute_op'),
+      max('notif_op'),
+    ])
+    return { op, mute, notif }
+  }
+
+  async close() {
+    await this.service.destroy()
+  }
+}

package/src/const.ts

@@ -0,0 +1,3 @@
+export const ADMIN_PASSWORD = 'admin-pass'
+export const JWT_SECRET = 'jwt-secret'
+export const EXAMPLE_LABELER = 'did:example:labeler'

package/src/env.ts

@@ -0,0 +1,9 @@
+// NOTE: this file should be imported first, particularly before `@atproto/common` (for logging), to ensure that environment variables are respected in library code
+import { config } from 'dotenv'
+
+const env = process.env.ENV
+if (env) {
+  config({ path: `./.${env}.env` })
+} else {
+  config()
+}