@zooid/transport-matrix 0.7.4 → 0.8.0

package/src/attachments.test.ts

@@ -0,0 +1,58 @@
+import { describe, it, expect } from 'vitest'
+import { mkdtempSync, readFileSync, rmSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { writeAttachment } from './attachments.js'
+
+describe('writeAttachment', () => {
+  it('writes under .zooid/attachments/<event-id>/<filename> and returns both path views', () => {
+    const ws = mkdtempSync(join(tmpdir(), 'zooid-att-'))
+    try {
+      const out = writeAttachment({
+        workspaceDir: ws,
+        agentWorkspacePath: '/workspace',
+        eventId: '$abc123:localhost',
+        filename: 'report.pdf',
+        data: Buffer.from('hello'),
+      })
+      expect(out.hostPath).toBe(join(ws, '.zooid', 'attachments', 'abc123localhost', 'report.pdf'))
+      expect(out.agentPath).toBe('/workspace/.zooid/attachments/abc123localhost/report.pdf')
+      expect(readFileSync(out.hostPath, 'utf8')).toBe('hello')
+    } finally {
+      rmSync(ws, { recursive: true, force: true })
+    }
+  })
+
+  it('sanitizes path-traversal and separator characters in filenames', () => {
+    const ws = mkdtempSync(join(tmpdir(), 'zooid-att-'))
+    try {
+      const out = writeAttachment({
+        workspaceDir: ws,
+        agentWorkspacePath: '/workspace',
+        eventId: '$e1',
+        filename: '../../etc/passwd',
+        data: Buffer.from('x'),
+      })
+      expect(out.hostPath.startsWith(join(ws, '.zooid', 'attachments'))).toBe(true)
+      expect(out.hostPath).not.toContain('..')
+    } finally {
+      rmSync(ws, { recursive: true, force: true })
+    }
+  })
+
+  it('falls back to a default filename when body is empty', () => {
+    const ws = mkdtempSync(join(tmpdir(), 'zooid-att-'))
+    try {
+      const out = writeAttachment({
+        workspaceDir: ws,
+        agentWorkspacePath: '/workspace',
+        eventId: '$e2',
+        filename: '',
+        data: Buffer.from('x'),
+      })
+      expect(out.agentPath).toMatch(/\/file$/)
+    } finally {
+      rmSync(ws, { recursive: true, force: true })
+    }
+  })
+})

package/src/attachments.ts

@@ -0,0 +1,30 @@
+import { mkdirSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { posix } from 'node:path'
+
+function sanitize(s: string, fallback: string): string {
+  const cleaned = s.replace(/[^A-Za-z0-9._-]/g, '').replace(/^\.+/, '')
+  return cleaned || fallback
+}
+
+export interface WriteAttachmentInput {
+  workspaceDir: string
+  agentWorkspacePath: string
+  eventId: string
+  filename: string
+  data: Uint8Array
+}
+
+export function writeAttachment(input: WriteAttachmentInput): {
+  hostPath: string
+  agentPath: string
+} {
+  const dir = sanitize(input.eventId, 'event')
+  const name = sanitize(input.filename, 'file')
+  const hostDir = join(input.workspaceDir, '.zooid', 'attachments', dir)
+  mkdirSync(hostDir, { recursive: true })
+  const hostPath = join(hostDir, name)
+  writeFileSync(hostPath, input.data)
+  const agentPath = posix.join(input.agentWorkspacePath, '.zooid', 'attachments', dir, name)
+  return { hostPath, agentPath }
+}

package/src/context-provider.test.ts

@@ -314,4 +314,37 @@ describe('MatrixContextProvider', () => {
     const info = await provider.getChannelInfo('!room:hs')
     expect(info.name).toBe('!room:hs')
   })
+
+  it('renders media events as placeholders instead of skipping them', async () => {
+    const client = fakeClient({
+      fetchRoomMessages: vi.fn().mockResolvedValue({
+        chunk: [
+          {
+            event_id: '$img',
+            sender: '@alice:hs',
+            origin_server_ts: 1000,
+            type: 'm.room.message',
+            content: { msgtype: 'm.image', body: 'dog.jpg', url: 'mxc://hs/a' },
+          },
+          {
+            event_id: '$file',
+            sender: '@alice:hs',
+            origin_server_ts: 2000,
+            type: 'm.room.message',
+            content: { msgtype: 'm.file', body: 'report.pdf', url: 'mxc://hs/b' },
+          },
+        ],
+        end: undefined,
+      }),
+    } as unknown as Partial<MatrixClient>)
+    const provider = new MatrixContextProvider({
+      client,
+      asUserId: '@_zooid:hs',
+      agentBots: new Map(),
+    })
+    const page = await provider.getRoomHistory('!room:hs', {})
+    const byId = new Map(page.messages.map((m) => [m.id, m]))
+    expect(byId.get('$img')?.text).toBe('[image: dog.jpg]')
+    expect(byId.get('$file')?.text).toBe('[file: report.pdf]')
+  })
 })

package/src/context-provider.ts

@@ -147,15 +147,33 @@ export class MatrixContextProvider implements TransportContextProvider {
 
   private toMessage(ev: MatrixMessageEvent): Message | null {
     if (ev.type !== 'm.room.message') return null
-    if (ev.content?.msgtype !== 'm.text' || typeof ev.content.body !== 'string') return null
+    const msgtype = ev.content?.msgtype
+    const body = ev.content?.body
     const agent = this.opts.agentBots.get(ev.sender)
-    const relatesTo = ev.content['m.relates_to']
+    const relatesTo = ev.content?.['m.relates_to']
     const threadId =
       relatesTo?.rel_type === 'm.thread' && relatesTo.event_id ? relatesTo.event_id : undefined
+
+    // Media events render as context placeholders
+    if (msgtype === 'm.image' || msgtype === 'm.file' || msgtype === 'm.video' || msgtype === 'm.audio') {
+      const kind = msgtype.slice(2) // 'image', 'file', 'video', 'audio'
+      const name = typeof body === 'string' && body ? body : 'untitled'
+      return {
+        id: ev.event_id,
+        sender: ev.sender,
+        text: `[${kind}: ${name}]`,
+        timestamp: new Date(ev.origin_server_ts).toISOString(),
+        is_agent: agent !== undefined,
+        ...(agent !== undefined ? { agent_name: agent } : {}),
+        ...(threadId !== undefined ? { thread_id: threadId } : {}),
+      }
+    }
+
+    if (msgtype !== 'm.text' || typeof body !== 'string') return null
     return {
       id: ev.event_id,
       sender: ev.sender,
-      text: ev.content.body,
+      text: body,
       timestamp: new Date(ev.origin_server_ts).toISOString(),
       is_agent: agent !== undefined,
       ...(agent !== undefined ? { agent_name: agent } : {}),

package/src/index.ts

@@ -6,11 +6,11 @@ export { renderRegistration } from './registration.js'
 export type { MatrixTransportConfig } from './registration.js'
 export { extractMentions } from './mentions.js'
 export type { MaybeMessage } from './mentions.js'
-export { route } from './router.js'
+export { route, isMediaMsgtype, MEDIA_MSGTYPES } from './router.js'
 export type { AgentBinding, RouteMatch } from './router.js'
 export { BotPool } from './bot-pool.js'
 export { createMatrixTransport } from './transport.js'
-export type { CreateMatrixTransportOptions } from './transport.js'
+export type { CreateMatrixTransportOptions, MediaClientLike } from './transport.js'
 export { ensureDefaultChannel, ensureWorkforceSpace, serverNameFromMxid } from './space-provisioner.js'
 export type { EnsureDefaultChannelOpts, EnsureSpaceOpts } from './space-provisioner.js'
 export {
@@ -24,3 +24,9 @@ export type {
   PublisherHandle,
   StartOpts as StartWorkforcePublisherOpts,
 } from './workforce-publisher.js'
+export { MediaClient, parseMxcUri, MAX_INLINE_IMAGE_BYTES, INLINE_IMAGE_MIMES, MAX_DOWNLOAD_BYTES } from './media-client.js'
+export type { MediaClientOptions } from './media-client.js'
+export { PendingMediaStore, MAX_MEDIA_PER_TURN } from './pending-media.js'
+export type { PendingMediaItem } from './pending-media.js'
+export { writeAttachment } from './attachments.js'
+export type { WriteAttachmentInput } from './attachments.js'

package/src/media-client.test.ts

@@ -0,0 +1,102 @@
+import { describe, it, expect, vi } from 'vitest'
+import {
+  MediaClient,
+  parseMxcUri,
+  MAX_INLINE_IMAGE_BYTES,
+  INLINE_IMAGE_MIMES,
+} from './media-client.js'
+
+const TINY_PNG = Buffer.from(
+  'iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8z8BQDwAEhQGAhKmMIQAAAABJRU5ErkJggg==',
+  'base64',
+)
+
+function fakeFetch(response: Partial<Response> & { body?: Uint8Array; json?: unknown }) {
+  return vi.fn(async () => ({
+    ok: response.ok ?? true,
+    status: response.status ?? 200,
+    headers: new Headers(response.headers ?? { 'content-type': 'image/png' }),
+    arrayBuffer: async () => {
+      const buf = response.body ?? TINY_PNG
+      // Use byteOffset/byteLength so the slice covers exactly the bytes the Buffer references.
+      return buf.buffer.slice(buf.byteOffset, buf.byteOffset + buf.byteLength)
+    },
+    json: async () => response.json ?? {},
+    text: async () => '',
+  })) as unknown as typeof fetch
+}
+
+describe('parseMxcUri', () => {
+  it('splits server name and media id', () => {
+    expect(parseMxcUri('mxc://localhost/AbCd1234')).toEqual({
+      serverName: 'localhost',
+      mediaId: 'AbCd1234',
+    })
+  })
+
+  it('returns null for non-mxc uris', () => {
+    expect(parseMxcUri('https://example.com/x.png')).toBeNull()
+    expect(parseMxcUri('mxc://missing-id')).toBeNull()
+  })
+})
+
+describe('MediaClient.download', () => {
+  it('GETs the authenticated v1 endpoint with AS token and user_id', async () => {
+    const f = fakeFetch({ body: TINY_PNG })
+    const media = new MediaClient({ homeserver: 'http://hs', asToken: 'tok', fetch: f })
+    const out = await media.download({ mxcUri: 'mxc://localhost/abc', asUserId: '@dev:localhost' })
+
+    const [url, init] = (f as ReturnType<typeof vi.fn>).mock.calls[0] as [string, RequestInit]
+    expect(url).toBe(
+      'http://hs/_matrix/client/v1/media/download/localhost/abc?user_id=%40dev%3Alocalhost',
+    )
+    expect((init.headers as Record<string, string>).Authorization).toBe('Bearer tok')
+    expect(Buffer.from(out.data).equals(TINY_PNG)).toBe(true)
+    expect(out.contentType).toBe('image/png')
+  })
+
+  it('rejects bodies larger than maxBytes', async () => {
+    const big = new Uint8Array(64)
+    const f = fakeFetch({ body: big })
+    const media = new MediaClient({ homeserver: 'http://hs', asToken: 'tok', fetch: f })
+    await expect(
+      media.download({ mxcUri: 'mxc://localhost/abc', asUserId: '@dev:localhost', maxBytes: 16 }),
+    ).rejects.toThrow(/too large/i)
+  })
+
+  it('throws on non-OK responses with status in the message', async () => {
+    const f = fakeFetch({ ok: false, status: 404 })
+    const media = new MediaClient({ homeserver: 'http://hs', asToken: 'tok', fetch: f })
+    await expect(
+      media.download({ mxcUri: 'mxc://localhost/gone', asUserId: '@dev:localhost' }),
+    ).rejects.toThrow(/404/)
+  })
+})
+
+describe('MediaClient.upload', () => {
+  it('POSTs raw bytes to /_matrix/media/v3/upload with filename and user_id', async () => {
+    const f = fakeFetch({ json: { content_uri: 'mxc://localhost/up1' } })
+    const media = new MediaClient({ homeserver: 'http://hs', asToken: 'tok', fetch: f })
+    const out = await media.upload({
+      data: TINY_PNG,
+      contentType: 'image/png',
+      filename: 'shot.png',
+      asUserId: '@dev:localhost',
+    })
+
+    const [url, init] = (f as ReturnType<typeof vi.fn>).mock.calls[0] as [string, RequestInit]
+    expect(url).toBe('http://hs/_matrix/media/v3/upload?filename=shot.png&user_id=%40dev%3Alocalhost')
+    expect(init.method).toBe('POST')
+    expect((init.headers as Record<string, string>)['Content-Type']).toBe('image/png')
+    expect(out.content_uri).toBe('mxc://localhost/up1')
+  })
+})
+
+describe('inline routing constants', () => {
+  it('caps inline images at 0.5 MB and allowlists model-consumable mimes', () => {
+    expect(MAX_INLINE_IMAGE_BYTES).toBe(524_288)
+    expect(INLINE_IMAGE_MIMES).toContain('image/png')
+    expect(INLINE_IMAGE_MIMES).toContain('image/jpeg')
+    expect(INLINE_IMAGE_MIMES).not.toContain('image/svg+xml')
+  })
+})

package/src/media-client.ts

@@ -0,0 +1,69 @@
+/** Limits are routing policy, not enforcement — see ZOD057 (enforcement lives
+ *  in Tuwunel config + the Zoon composer). */
+export const MAX_INLINE_IMAGE_BYTES = 524_288
+export const INLINE_IMAGE_MIMES = ['image/png', 'image/jpeg', 'image/gif', 'image/webp']
+export const MAX_DOWNLOAD_BYTES = 33_554_432
+
+export interface MediaClientOptions {
+  homeserver: string
+  asToken: string
+  fetch?: typeof globalThis.fetch
+}
+
+export function parseMxcUri(uri: string): { serverName: string; mediaId: string } | null {
+  const m = /^mxc:\/\/([^/]+)\/(.+)$/.exec(uri)
+  return m ? { serverName: m[1], mediaId: m[2] } : null
+}
+
+export class MediaClient {
+  private readonly homeserver: string
+  private readonly asToken: string
+  private readonly fetch: typeof globalThis.fetch
+
+  constructor(opts: MediaClientOptions) {
+    this.homeserver = opts.homeserver.replace(/\/$/, '')
+    this.asToken = opts.asToken
+    this.fetch = opts.fetch ?? globalThis.fetch
+  }
+
+  async download(input: {
+    mxcUri: string
+    asUserId: string
+    maxBytes?: number
+  }): Promise<{ data: Uint8Array; contentType: string }> {
+    const parsed = parseMxcUri(input.mxcUri)
+    if (!parsed) throw new Error(`not an mxc uri: ${input.mxcUri}`)
+    const url =
+      `${this.homeserver}/_matrix/client/v1/media/download/` +
+      `${encodeURIComponent(parsed.serverName)}/${encodeURIComponent(parsed.mediaId)}` +
+      `?user_id=${encodeURIComponent(input.asUserId)}`
+    const r = await this.fetch(url, {
+      headers: { Authorization: `Bearer ${this.asToken}` },
+    })
+    if (!r.ok) throw new Error(`media download failed: ${r.status}`)
+    const buf = new Uint8Array(await r.arrayBuffer())
+    const max = input.maxBytes ?? MAX_DOWNLOAD_BYTES
+    if (buf.byteLength > max) {
+      throw new Error(`media too large: ${buf.byteLength} > ${max}`)
+    }
+    return { data: buf, contentType: r.headers.get('content-type') ?? 'application/octet-stream' }
+  }
+
+  async upload(input: {
+    data: Uint8Array
+    contentType: string
+    filename?: string
+    asUserId: string
+  }): Promise<{ content_uri: string }> {
+    const params = new URLSearchParams()
+    if (input.filename) params.set('filename', input.filename)
+    params.set('user_id', input.asUserId)
+    const r = await this.fetch(`${this.homeserver}/_matrix/media/v3/upload?${params}`, {
+      method: 'POST',
+      headers: { Authorization: `Bearer ${this.asToken}`, 'Content-Type': input.contentType },
+      body: input.data,
+    })
+    if (!r.ok) throw new Error(`media upload failed: ${r.status}`)
+    return (await r.json()) as { content_uri: string }
+  }
+}

package/src/pending-media.test.ts

@@ -0,0 +1,51 @@
+import { describe, it, expect } from 'vitest'
+import { PendingMediaStore, MAX_MEDIA_PER_TURN } from './pending-media.js'
+
+function item(over: Partial<{ eventId: string; sender: string; msgtype: string }> = {}) {
+  return {
+    eventId: over.eventId ?? '$m1',
+    sender: over.sender ?? '@alice:localhost',
+    msgtype: over.msgtype ?? 'm.image',
+    body: 'dog.jpg',
+    filename: 'dog.jpg',
+    url: 'mxc://localhost/abc',
+    info: { mimetype: 'image/jpeg', size: 1000 },
+  }
+}
+
+describe('PendingMediaStore', () => {
+  it('drains items for the same room+thread+sender and clears them', () => {
+    const s = new PendingMediaStore()
+    s.add('!r:hs', '$root', item({ eventId: '$m1' }))
+    s.add('!r:hs', '$root', item({ eventId: '$m2' }))
+    const drained = s.drain('!r:hs', '$root', '@alice:localhost')
+    expect(drained.map((i) => i.eventId)).toEqual(['$m1', '$m2'])
+    expect(s.drain('!r:hs', '$root', '@alice:localhost')).toEqual([])
+  })
+
+  it('does not leak across threads, rooms, or senders', () => {
+    const s = new PendingMediaStore()
+    s.add('!r:hs', '$rootA', item())
+    expect(s.drain('!r:hs', '$rootB', '@alice:localhost')).toEqual([])
+    expect(s.drain('!other:hs', '$rootA', '@alice:localhost')).toEqual([])
+    expect(s.drain('!r:hs', '$rootA', '@bob:localhost')).toEqual([])
+    // alice's item is still there after bob's miss
+    expect(s.drain('!r:hs', '$rootA', '@alice:localhost')).toHaveLength(1)
+  })
+
+  it('caps the queue at MAX_MEDIA_PER_TURN, dropping oldest first', () => {
+    const s = new PendingMediaStore()
+    for (let i = 0; i < MAX_MEDIA_PER_TURN + 3; i++) {
+      s.add('!r:hs', '$root', item({ eventId: `$m${i}` }))
+    }
+    const drained = s.drain('!r:hs', '$root', '@alice:localhost')
+    expect(drained).toHaveLength(MAX_MEDIA_PER_TURN)
+    expect(drained[0].eventId).toBe('$m3') // 0,1,2 dropped
+  })
+
+  it('uses a room-level key when the media event is unthreaded', () => {
+    const s = new PendingMediaStore()
+    s.add('!r:hs', undefined, item())
+    expect(s.drain('!r:hs', undefined, '@alice:localhost')).toHaveLength(1)
+  })
+})

package/src/pending-media.ts

@@ -0,0 +1,37 @@
+export const MAX_MEDIA_PER_TURN = 8
+
+export interface PendingMediaItem {
+  eventId: string
+  sender: string
+  msgtype: string
+  body: string
+  filename?: string
+  url: string
+  info?: { mimetype?: string; size?: number; w?: number; h?: number }
+}
+
+export class PendingMediaStore {
+  private readonly queues = new Map<string, PendingMediaItem[]>()
+
+  private key(roomId: string, threadKey: string | undefined): string {
+    return `${roomId} ${threadKey ?? 'main'}`
+  }
+
+  add(roomId: string, threadKey: string | undefined, item: PendingMediaItem): void {
+    const k = this.key(roomId, threadKey)
+    const q = this.queues.get(k) ?? []
+    q.push(item)
+    while (q.length > MAX_MEDIA_PER_TURN) q.shift()
+    this.queues.set(k, q)
+  }
+
+  drain(roomId: string, threadKey: string | undefined, sender: string): PendingMediaItem[] {
+    const k = this.key(roomId, threadKey)
+    const q = this.queues.get(k) ?? []
+    const mine = q.filter((i) => i.sender === sender)
+    const rest = q.filter((i) => i.sender !== sender)
+    if (rest.length) this.queues.set(k, rest)
+    else this.queues.delete(k)
+    return mine
+  }
+}

package/src/router.test.ts

@@ -1,5 +1,5 @@
 import { describe, it, expect } from 'vitest'
-import { route, type AgentBinding } from './router.js'
+import { route, isMediaMsgtype, type AgentBinding } from './router.js'
 
 const agents: AgentBinding[] = [
   {
@@ -88,3 +88,24 @@ describe('route', () => {
     expect(route(stateEvent as never, agents)).toEqual([])
   })
 })
+
+describe('media events', () => {
+  it('classifies media msgtypes', () => {
+    for (const t of ['m.image', 'm.file', 'm.video', 'm.audio']) {
+      expect(isMediaMsgtype(t)).toBe(true)
+    }
+    expect(isMediaMsgtype('m.text')).toBe(false)
+    expect(isMediaMsgtype('m.notice')).toBe(false)
+    expect(isMediaMsgtype(undefined)).toBe(false)
+  })
+
+  it('never routes media events to agents, even trigger=any', () => {
+    const monitorRoom = msg({ room: '!alerts:example.com', body: 'dog.jpg' })
+    const mediaEvent = {
+      ...monitorRoom,
+      content: { msgtype: 'm.image', body: 'dog.jpg', url: 'mxc://localhost/abc' },
+    }
+    const matches = route(mediaEvent, agents)
+    expect(matches).toEqual([])
+  })
+})

package/src/router.ts

@@ -16,6 +16,16 @@ export interface AgentBinding {
    */
   rooms: RoomBinding[]
   trigger: 'mention' | 'any'
+  /** Host path of the agent's workspace (resolved agent.workdir). Media files land here. */
+  workspaceDir?: string
+  /** Path prefix as the agent sees it: '/workspace' for containers, = workspaceDir for local. */
+  agentWorkspacePath?: string
+}
+
+export const MEDIA_MSGTYPES = new Set(['m.image', 'm.file', 'm.video', 'm.audio'])
+
+export function isMediaMsgtype(t: string | undefined): boolean {
+  return t !== undefined && MEDIA_MSGTYPES.has(t)
 }
 
 export interface ThreadState {
@@ -49,6 +59,7 @@ export function route(
 ): RouteMatch[] {
   if (event.type !== 'm.room.message') return []
   if (!event.content?.msgtype) return []
+  if (isMediaMsgtype(event.content.msgtype)) return []
   const mentions = new Set(extractMentions(event as never))
   const matches: RouteMatch[] = []
   const threadRoot = inboundThreadRoot(event)

package/src/space-provisioner.test.ts

@@ -75,7 +75,7 @@ describe('ensureWorkforceSpace', () => {
 })
 
 describe('ensureWorkforceSpace privacy', () => {
-  it('creates the space invite-only (overriding any public preset)', async () => {
+  it('creates the space invite-only by default (overriding any public preset)', async () => {
     const { client } = clientWithFetches(
       () => new Response(JSON.stringify({ errcode: 'M_NOT_FOUND' }), { status: 404 }),
       (url, init) => {
@@ -99,6 +99,31 @@ describe('ensureWorkforceSpace privacy', () => {
     })
     expect(id).toBe('!space:hs.zoon.local')
   })
+
+  it('creates a publicly-joinable space when joinRule is public (zooid dev)', async () => {
+    const { client } = clientWithFetches(
+      () => new Response(JSON.stringify({ errcode: 'M_NOT_FOUND' }), { status: 404 }),
+      (url, init) => {
+        expect(url).toContain('/_matrix/client/v3/createRoom')
+        const body = JSON.parse(init!.body as string)
+        expect(body.initial_state).toContainEqual({
+          type: 'm.room.join_rules',
+          state_key: '',
+          content: { join_rule: 'public' },
+        })
+        return new Response(JSON.stringify({ room_id: '!space:hs.zoon.local' }), { status: 200 })
+      },
+    )
+    const id = await ensureWorkforceSpace({
+      client,
+      asUserId: '@zooid:hs.zoon.local',
+      serverName: 'hs.zoon.local',
+      spaceLocalpart: 'dev',
+      preset: 'public_chat',
+      joinRule: 'public',
+    })
+    expect(id).toBe('!space:hs.zoon.local')
+  })
 })
 
 describe('ensureWorkforceSpace admins', () => {

package/src/space-provisioner.ts

@@ -13,6 +13,15 @@ export interface EnsureSpaceOpts {
    * if the alias already resolves we return the existing room untouched.
    */
   admins?: string[]
+  /**
+   * Join rule pinned on the space at creation. Defaults to `invite`: a
+   * workspace is joined by invitation, not self-service, so it can't be walked
+   * into (which would otherwise satisfy every restricted child room's `allow`).
+   * `zooid dev` passes `public` so a self-service-registered local account can
+   * join `#<space>` straight from the web client without an invite — acceptable
+   * because the dev homeserver is local-only and never deployed.
+   */
+  joinRule?: 'invite' | 'public'
 }
 
 export async function ensureWorkforceSpace(opts: EnsureSpaceOpts): Promise<string> {
@@ -26,10 +35,12 @@ export async function ensureWorkforceSpace(opts: EnsureSpaceOpts): Promise<strin
     name: display,
     preset: opts.preset,
     creation_content: { type: 'm.space' },
-    // A workspace is joined by invitation, not self-service. Pin the space's
-    // join rule to invite regardless of preset so it can't be walked into
-    // (which would otherwise satisfy every restricted child room's allow).
-    initial_state: [{ type: 'm.room.join_rules', state_key: '', content: { join_rule: 'invite' } }],
+    // Pin the join rule regardless of preset. Defaults to invite so the space
+    // can't be walked into (which would otherwise satisfy every restricted
+    // child room's allow); `zooid dev` opts into `public` for local-only use.
+    initial_state: [
+      { type: 'm.room.join_rules', state_key: '', content: { join_rule: opts.joinRule ?? 'invite' } },
+    ],
   }
   if (opts.admins && opts.admins.length > 0) {
     // Invite each admin so they actually become members — PL 100 alone does