@zooid/transport-matrix 0.7.0 → 0.7.2

package/src/matrix-client.test.ts

@@ -305,3 +305,163 @@ describe('MatrixClient', () => {
     })
   })
 })
+
+describe('MatrixClient.invite', () => {
+  it('POSTs to /invite with the user_id payload, impersonating the inviter', async () => {
+    const fetch = fakeFetch(async ({ url, init }) => {
+      expect(url).toBe(
+        'https://hs.example.com/_matrix/client/v3/rooms/!space%3Aexample.com/invite' +
+          '?user_id=%40zooid%3Aexample.com',
+      )
+      expect(init.method).toBe('POST')
+      expect(JSON.parse(init.body as string)).toEqual({ user_id: '@planner:example.com' })
+      return new Response('{}', { status: 200 })
+    })
+    const client = new MatrixClient({
+      homeserver: 'https://hs.example.com',
+      asToken: 'as',
+      fetch: fetch as unknown as typeof globalThis.fetch,
+    })
+    await client.invite({
+      roomId: '!space:example.com',
+      asUserId: '@zooid:example.com',
+      targetUserId: '@planner:example.com',
+    })
+  })
+
+  it('silently swallows the idempotent "already in the room" 403', async () => {
+    const fetch = fakeFetch(async () =>
+      new Response(
+        JSON.stringify({ errcode: 'M_FORBIDDEN', error: 'User is already in the room' }),
+        { status: 403 },
+      ),
+    )
+    const client = new MatrixClient({
+      homeserver: 'https://hs.example.com',
+      asToken: 'as',
+      fetch: fetch as unknown as typeof globalThis.fetch,
+    })
+    await expect(
+      client.invite({
+        roomId: '!r:example.com',
+        asUserId: '@zooid:example.com',
+        targetUserId: '@planner:example.com',
+      }),
+    ).resolves.toBeUndefined()
+  })
+
+  it('rethrows a real permission 403 (no idempotency phrase in body)', async () => {
+    const fetch = fakeFetch(async () =>
+      new Response(
+        JSON.stringify({ errcode: 'M_FORBIDDEN', error: 'You do not have power to invite' }),
+        { status: 403 },
+      ),
+    )
+    const client = new MatrixClient({
+      homeserver: 'https://hs.example.com',
+      asToken: 'as',
+      fetch: fetch as unknown as typeof globalThis.fetch,
+    })
+    await expect(
+      client.invite({
+        roomId: '!r:example.com',
+        asUserId: '@zooid:example.com',
+        targetUserId: '@planner:example.com',
+      }),
+    ).rejects.toThrow(/invite/)
+  })
+})
+
+describe('MatrixClient.createRoom userPowerLevels', () => {
+  it('forwards userPowerLevels into power_level_content_override.users', async () => {
+    const fetch = fakeFetch(async ({ init }) => {
+      const body = JSON.parse(init.body as string)
+      expect(body.power_level_content_override).toEqual({
+        users: {
+          '@zooid:example.com': 100,
+          '@admin:example.com': 100,
+          '@mod:example.com': 50,
+        },
+      })
+      return new Response(JSON.stringify({ room_id: '!r:example.com' }), { status: 200 })
+    })
+    const client = new MatrixClient({
+      homeserver: 'https://hs.example.com',
+      asToken: 'as',
+      fetch: fetch as unknown as typeof globalThis.fetch,
+    })
+    await client.createRoom({
+      roomAliasName: 'x',
+      invite: [],
+      senderUserId: '@zooid:example.com',
+      userPowerLevels: {
+        '@zooid:example.com': 100,
+        '@admin:example.com': 100,
+        '@mod:example.com': 50,
+      },
+    })
+  })
+
+  it('omits power_level_content_override when userPowerLevels is empty or absent', async () => {
+    const fetch = fakeFetch(async ({ init }) => {
+      const body = JSON.parse(init.body as string)
+      expect(body.power_level_content_override).toBeUndefined()
+      return new Response(JSON.stringify({ room_id: '!r:example.com' }), { status: 200 })
+    })
+    const client = new MatrixClient({
+      homeserver: 'https://hs.example.com',
+      asToken: 'as',
+      fetch: fetch as unknown as typeof globalThis.fetch,
+    })
+    await client.createRoom({
+      roomAliasName: 'x',
+      invite: [],
+      senderUserId: '@zooid:example.com',
+    })
+  })
+})
+
+describe('MatrixClient.createRoom restricted', () => {
+  it('injects a restricted join rule referencing the space when restrictedToSpaceId is set', async () => {
+    const fetch = fakeFetch(async ({ url, init }) => {
+      expect(url).toContain('/_matrix/client/v3/createRoom')
+      const body = JSON.parse(init.body as string)
+      expect(body.room_alias_name).toBe('design')
+      expect(body.initial_state).toContainEqual({
+        type: 'm.room.join_rules',
+        state_key: '',
+        content: {
+          join_rule: 'restricted',
+          allow: [{ type: 'm.room_membership', room_id: '!space:example.com' }],
+        },
+      })
+      return new Response(JSON.stringify({ room_id: '!new:example.com' }), { status: 200 })
+    })
+    const client = new MatrixClient({
+      homeserver: 'https://hs.example.com',
+      asToken: 'as-secret',
+      fetch: fetch as unknown as typeof globalThis.fetch,
+    })
+    const id = await client.createRoom({
+      roomAliasName: 'design',
+      invite: [],
+      senderUserId: '@architect:example.com',
+      restrictedToSpaceId: '!space:example.com',
+    })
+    expect(id).toBe('!new:example.com')
+  })
+
+  it('omits the restricted join rule when no space is given (public room, unchanged)', async () => {
+    const fetch = fakeFetch(async ({ init }) => {
+      const body = JSON.parse(init.body as string)
+      expect(body.initial_state).toBeUndefined()
+      return new Response(JSON.stringify({ room_id: '!r:example.com' }), { status: 200 })
+    })
+    const client = new MatrixClient({
+      homeserver: 'https://hs.example.com',
+      asToken: 'as-secret',
+      fetch: fetch as unknown as typeof globalThis.fetch,
+    })
+    await client.createRoom({ roomAliasName: 'x', invite: [], senderUserId: '@a:example.com' })
+  })
+})

package/src/matrix-client.ts

@@ -80,6 +80,20 @@ export class MatrixClient {
     /** Optional `m.room.name`. When set, sent in the createRoom body so the
      *  room has a display name from the moment it exists. */
     name?: string
+    /** When set, the room is created with a `restricted` join rule whose allow
+     *  condition references this space room ID — i.e. joinable by space members
+     *  only, rather than the whole homeserver. */
+    restrictedToSpaceId?: string
+    /** Explicit room version. Restricted join rules require v8+; omit to use the
+     *  homeserver default (modern Tuwunel defaults to v10/v11). */
+    roomVersion?: string
+    /**
+     * Seeds `m.room.power_levels.users` at creation via
+     * `power_level_content_override.users`. The caller owns the full map —
+     * typically the AS bot at 100, plus operator and any agents with
+     * declared PLs. Empty/absent → no override (the preset's defaults apply).
+     */
+    userPowerLevels?: Record<string, number>
   }): Promise<string> {
     const body: Record<string, unknown> = {
       room_alias_name: opts.roomAliasName,
@@ -87,6 +101,22 @@ export class MatrixClient {
       preset: opts.preset ?? 'public_chat',
     }
     if (opts.name !== undefined) body.name = opts.name
+    if (opts.roomVersion !== undefined) body.room_version = opts.roomVersion
+    if (opts.restrictedToSpaceId !== undefined) {
+      body.initial_state = [
+        {
+          type: 'm.room.join_rules',
+          state_key: '',
+          content: {
+            join_rule: 'restricted',
+            allow: [{ type: 'm.room_membership', room_id: opts.restrictedToSpaceId }],
+          },
+        },
+      ]
+    }
+    if (opts.userPowerLevels && Object.keys(opts.userPowerLevels).length > 0) {
+      body.power_level_content_override = { users: opts.userPowerLevels }
+    }
     const r = await this.fetch(
       `${this.homeserver}/_matrix/client/v3/createRoom?user_id=${encodeURIComponent(opts.senderUserId)}`,
       {
@@ -147,6 +177,40 @@ export class MatrixClient {
     return (await r.json()) as { event_id: string }
   }
 
+  /**
+   * Invite a user to a room. Sent as the inviter (`asUserId`) — that user
+   * needs invite power in the room. Tolerates the "already in room /
+   * already invited" responses idempotently so bootstrap can run on a
+   * fresh AND a populated homeserver without branching.
+   */
+  async invite(opts: {
+    roomId: string
+    asUserId: string
+    targetUserId: string
+  }): Promise<void> {
+    const url =
+      `${this.homeserver}/_matrix/client/v3/rooms/${encodeURIComponent(opts.roomId)}/invite` +
+      `?user_id=${encodeURIComponent(opts.asUserId)}`
+    const r = await this.fetch(url, {
+      method: 'POST',
+      headers: {
+        Authorization: `Bearer ${this.asToken}`,
+        'content-type': 'application/json',
+      },
+      body: JSON.stringify({ user_id: opts.targetUserId }),
+    })
+    if (r.ok) return
+    if (r.status === 403) {
+      // Tuwunel/Synapse use M_FORBIDDEN both for permission errors AND for
+      // "already a member / already invited". Inspect the body so we only
+      // swallow the idempotent case.
+      const body = await r.text()
+      if (/already (in the room|invited|a member|joined)/i.test(body)) return
+      throw new Error(`invite(${opts.targetUserId}) failed: 403 ${body}`)
+    }
+    throw new Error(`invite(${opts.targetUserId}) failed: ${r.status}`)
+  }
+
   async joinRoom(roomIdOrAlias: string, asUserId: string): Promise<void> {
     const url =
       `${this.homeserver}/_matrix/client/v3/join/${encodeURIComponent(roomIdOrAlias)}` +

package/src/router.test.ts

@@ -5,13 +5,13 @@ const agents: AgentBinding[] = [
   {
     name: 'architect',
     userId: '@architect:example.com',
-    rooms: ['!room1:example.com'],
+    rooms: [{ alias: '!room1:example.com' }],
     trigger: 'mention',
   },
   {
     name: 'monitor',
     userId: '@monitor:example.com',
-    rooms: ['!alerts:example.com'],
+    rooms: [{ alias: '!alerts:example.com' }],
     trigger: 'any',
   },
 ]
@@ -67,7 +67,7 @@ describe('route', () => {
       {
         name: 'qa',
         userId: '@qa:example.com',
-        rooms: ['!room1:example.com'],
+        rooms: [{ alias: '!room1:example.com' }],
         trigger: 'mention',
       },
     ]

package/src/router.ts

@@ -1,11 +1,20 @@
+import type { RoomBinding } from '@zooid/core'
 import { extractMentions } from './mentions.js'
 
+export type { RoomBinding }
+
 export interface AgentBinding {
   name: string
   userId: string
   /** Optional human-readable display name. Falls back to the user_id localpart. */
   displayName?: string
-  rooms: string[]
+  /**
+   * Rooms this agent is bound to. Each entry's `alias` starts out as the
+   * configured `#alias` (or `!id`) and is rewritten to the canonical room
+   * ID by `BotPool.bootstrap`. Optional `powerLevel` is seeded into the
+   * room's `m.room.power_levels.users` at room creation only.
+   */
+  rooms: RoomBinding[]
   trigger: 'mention' | 'any'
 }
 
@@ -47,7 +56,7 @@ export function route(
 
   for (const a of agents) {
     if (event.sender === a.userId) continue
-    if (!a.rooms.includes(event.room_id ?? '')) continue
+    if (!a.rooms.some((r) => r.alias === event.room_id)) continue
     if (a.trigger === 'any') {
       matches.push(a)
       continue

package/src/space-provisioner.test.ts

@@ -1,6 +1,6 @@
 import { describe, expect, it, vi } from 'vitest'
 import { MatrixClient } from './matrix-client.js'
-import { ensureWorkforceSpace, serverNameFromMxid } from './space-provisioner.js'
+import { ensureDefaultChannel, ensureWorkforceSpace, serverNameFromMxid } from './space-provisioner.js'
 
 function clientWithFetches(...handlers: Array<(url: string, init?: RequestInit) => Response>) {
   let i = 0
@@ -74,6 +74,196 @@ describe('ensureWorkforceSpace', () => {
   })
 })
 
+describe('ensureWorkforceSpace privacy', () => {
+  it('creates the space invite-only (overriding any public preset)', 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.creation_content).toEqual({ type: 'm.space' })
+        expect(body.initial_state).toContainEqual({
+          type: 'm.room.join_rules',
+          state_key: '',
+          content: { join_rule: 'invite' },
+        })
+        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',
+    })
+    expect(id).toBe('!space:hs.zoon.local')
+  })
+})
+
+describe('ensureWorkforceSpace admins', () => {
+  it('emits power_level_content_override with bot + admins at 100 on creation', 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.power_level_content_override).toEqual({
+          users: {
+            '@zooid:hs.zoon.local': 100,
+            '@admin:hs.zoon.local': 100,
+          },
+        })
+        return new Response(JSON.stringify({ room_id: '!space:hs.zoon.local' }), { status: 200 })
+      },
+    )
+    await ensureWorkforceSpace({
+      client,
+      asUserId: '@zooid:hs.zoon.local',
+      serverName: 'hs.zoon.local',
+      spaceLocalpart: 'dev',
+      preset: 'public_chat',
+      admins: ['@admin:hs.zoon.local'],
+    })
+  })
+
+  it('invites the admins so they can actually enter the invite-only space', async () => {
+    const { client } = clientWithFetches(
+      () => new Response(JSON.stringify({ errcode: 'M_NOT_FOUND' }), { status: 404 }),
+      (_url, init) => {
+        const body = JSON.parse(init!.body as string)
+        expect(body.invite).toEqual(['@admin:hs.zoon.local'])
+        return new Response(JSON.stringify({ room_id: '!space:hs.zoon.local' }), { status: 200 })
+      },
+    )
+    await ensureWorkforceSpace({
+      client,
+      asUserId: '@zooid:hs.zoon.local',
+      serverName: 'hs.zoon.local',
+      spaceLocalpart: 'dev',
+      preset: 'public_chat',
+      admins: ['@admin:hs.zoon.local'],
+    })
+  })
+
+  it('omits the override when admins is empty/absent', async () => {
+    const { client } = clientWithFetches(
+      () => new Response(JSON.stringify({ errcode: 'M_NOT_FOUND' }), { status: 404 }),
+      (_url, init) => {
+        const body = JSON.parse(init!.body as string)
+        expect(body.power_level_content_override).toBeUndefined()
+        return new Response(JSON.stringify({ room_id: '!space:hs.zoon.local' }), { status: 200 })
+      },
+    )
+    await ensureWorkforceSpace({
+      client,
+      asUserId: '@zooid:hs.zoon.local',
+      serverName: 'hs.zoon.local',
+      spaceLocalpart: 'dev',
+      preset: 'public_chat',
+    })
+  })
+})
+
+describe('ensureDefaultChannel', () => {
+  it('returns the existing #general room when its alias resolves', async () => {
+    const { client, fetch } = clientWithFetches((url) => {
+      expect(url).toContain('/_matrix/client/v3/directory/room/%23general%3Ahs.zoon.local')
+      return new Response(JSON.stringify({ room_id: '!gen:hs.zoon.local' }), { status: 200 })
+    })
+    const id = await ensureDefaultChannel({
+      client,
+      asUserId: '@zooid:hs.zoon.local',
+      serverName: 'hs.zoon.local',
+      spaceId: '!space:hs.zoon.local',
+      channelLocalpart: 'general',
+    })
+    expect(id).toBe('!gen:hs.zoon.local')
+    expect(fetch).toHaveBeenCalledTimes(1)
+  })
+
+  it('creates a restricted #general and attaches it to the space when absent', async () => {
+    const { client, fetch } = 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.room_alias_name).toBe('general')
+        expect(body.initial_state).toContainEqual({
+          type: 'm.room.join_rules',
+          state_key: '',
+          content: {
+            join_rule: 'restricted',
+            allow: [{ type: 'm.room_membership', room_id: '!space:hs.zoon.local' }],
+          },
+        })
+        return new Response(JSON.stringify({ room_id: '!gen:hs.zoon.local' }), { status: 200 })
+      },
+      (url, init) => {
+        expect(url).toContain(
+          '/_matrix/client/v3/rooms/!space%3Ahs.zoon.local/state/m.space.child/!gen%3Ahs.zoon.local',
+        )
+        expect(JSON.parse(init!.body as string)).toMatchObject({ via: ['hs.zoon.local'] })
+        return new Response(JSON.stringify({ event_id: '$e' }), { status: 200 })
+      },
+    )
+    const id = await ensureDefaultChannel({
+      client,
+      asUserId: '@zooid:hs.zoon.local',
+      serverName: 'hs.zoon.local',
+      spaceId: '!space:hs.zoon.local',
+      channelLocalpart: 'general',
+    })
+    expect(id).toBe('!gen:hs.zoon.local')
+    expect(fetch).toHaveBeenCalledTimes(3)
+  })
+})
+
+describe('ensureDefaultChannel admins', () => {
+  it('seeds operator + bot at PL 100 in the default channel on creation', 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.power_level_content_override).toEqual({
+          users: {
+            '@zooid:hs.zoon.local': 100,
+            '@admin:hs.zoon.local': 100,
+          },
+        })
+        return new Response(JSON.stringify({ room_id: '!gen:hs.zoon.local' }), { status: 200 })
+      },
+      () => new Response(JSON.stringify({ event_id: '$e' }), { status: 200 }),
+    )
+    await ensureDefaultChannel({
+      client,
+      asUserId: '@zooid:hs.zoon.local',
+      serverName: 'hs.zoon.local',
+      spaceId: '!space:hs.zoon.local',
+      admins: ['@admin:hs.zoon.local'],
+    })
+  })
+
+  it('omits the override when admins is empty/absent', async () => {
+    const { client } = clientWithFetches(
+      () => new Response(JSON.stringify({ errcode: 'M_NOT_FOUND' }), { status: 404 }),
+      (_url, init) => {
+        const body = JSON.parse(init!.body as string)
+        expect(body.power_level_content_override).toBeUndefined()
+        return new Response(JSON.stringify({ room_id: '!gen:hs.zoon.local' }), { status: 200 })
+      },
+      () => new Response(JSON.stringify({ event_id: '$e' }), { status: 200 }),
+    )
+    await ensureDefaultChannel({
+      client,
+      asUserId: '@zooid:hs.zoon.local',
+      serverName: 'hs.zoon.local',
+      spaceId: '!space:hs.zoon.local',
+    })
+  })
+})
+
 describe('serverNameFromMxid', () => {
   it('returns the part after the first colon', () => {
     expect(serverNameFromMxid('@zooid:zoon.local')).toBe('zoon.local')

package/src/space-provisioner.ts

@@ -6,6 +6,13 @@ export interface EnsureSpaceOpts {
   serverName: string
   spaceLocalpart: string
   preset: 'public_chat' | 'private_chat'
+  /**
+   * Operator MXIDs to seed at PL 100 in the space's `m.room.power_levels`
+   * at creation. The AS bot is always included. Empty/absent → no override
+   * (the preset's PL defaults apply). Only consulted on first creation —
+   * if the alias already resolves we return the existing room untouched.
+   */
+  admins?: string[]
 }
 
 export async function ensureWorkforceSpace(opts: EnsureSpaceOpts): Promise<string> {
@@ -14,15 +21,78 @@ export async function ensureWorkforceSpace(opts: EnsureSpaceOpts): Promise<strin
   if (existing) return existing
 
   const display = opts.spaceLocalpart.charAt(0).toUpperCase() + opts.spaceLocalpart.slice(1)
-  return opts.client.createRoomRaw({
+  const body: Record<string, unknown> = {
+    room_alias_name: opts.spaceLocalpart,
+    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' } }],
+  }
+  if (opts.admins && opts.admins.length > 0) {
+    // Invite each admin so they actually become members — PL 100 alone does
+    // not grant membership in an invite-only space.
+    body.invite = opts.admins
+    const users: Record<string, number> = { [opts.asUserId]: 100 }
+    for (const a of opts.admins) users[a] = 100
+    body.power_level_content_override = { users }
+  }
+  return opts.client.createRoomRaw({ asUserId: opts.asUserId, body })
+}
+
+export interface EnsureDefaultChannelOpts {
+  client: MatrixClient
+  asUserId: string
+  serverName: string
+  spaceId: string
+  /** Localpart of the default channel; defaults to `general`. */
+  channelLocalpart?: string
+  /**
+   * Operator MXIDs to seed at PL 100 in the channel's `m.room.power_levels`
+   * at creation. The AS bot is always included. Empty/absent → no override
+   * (the preset's PL defaults apply). Only consulted on first creation —
+   * if the alias already resolves we return the existing room untouched.
+   */
+  admins?: string[]
+}
+
+/**
+ * Ensure a space has a default channel (`#general` by default), restricted to
+ * the space's members and attached as an `m.space.child`. Idempotent: returns
+ * the existing room if the alias already resolves. Has no agent — it's the
+ * human landing room, so it is created here at provisioning time rather than
+ * via the agent-room path.
+ */
+export async function ensureDefaultChannel(opts: EnsureDefaultChannelOpts): Promise<string> {
+  const localpart = opts.channelLocalpart ?? 'general'
+  const alias = `#${localpart}:${opts.serverName}`
+  const existing = await opts.client.resolveAlias(alias)
+  if (existing) return existing
+
+  let userPowerLevels: Record<string, number> | undefined
+  if (opts.admins && opts.admins.length > 0) {
+    userPowerLevels = { [opts.asUserId]: 100 }
+    for (const a of opts.admins) userPowerLevels[a] = 100
+  }
+
+  const roomId = await opts.client.createRoom({
+    roomAliasName: localpart,
+    invite: [],
+    senderUserId: opts.asUserId,
+    name: localpart.charAt(0).toUpperCase() + localpart.slice(1),
+    restrictedToSpaceId: opts.spaceId,
+    ...(userPowerLevels ? { userPowerLevels } : {}),
+  })
+  await opts.client.sendStateEvent({
+    roomId: opts.spaceId,
     asUserId: opts.asUserId,
-    body: {
-      room_alias_name: opts.spaceLocalpart,
-      name: display,
-      preset: opts.preset,
-      creation_content: { type: 'm.space' },
-    },
+    eventType: 'm.space.child',
+    stateKey: roomId,
+    content: { via: [opts.serverName] },
   })
+  return roomId
 }
 
 export function serverNameFromMxid(mxid: string): string {