feat(matrix): optional password login alongside access token (#14)

## Added

- Matrix can authenticate with `MATRIX_USER` and `MATRIX_PASSWORD`
  when no access token is available; token auth remains supported.

## Changed

- Helm: optional `config.matrix.user` and `secrets.matrixPassword`
  for password-based installs.

## Fixed

- Use `client.loginRequest` instead of deprecated `client.login` for
  password flows.

Author: kgrubb

README.md

@@ -101,7 +101,7 @@ Kaytoo is configured via environment variables. For a minimal example, see `.env
 **Chat adapters** - configure at least one to run in chat mode. Kaytoo posts scheduled insights to every configured platform and answers chat replies on the same platform a message arrives from. See the per-platform setup and full variable tables below:
 
 - [Slack](#slack): `SLACK_BOT_TOKEN`, `SLACK_APP_TOKEN`, `SLACK_CHANNEL_ID`
-- [Matrix](#matrix): `MATRIX_HOMESERVER`, `MATRIX_ACCESS_TOKEN`, `MATRIX_DEFAULT_ROOM_ID`
+- [Matrix](#matrix): `MATRIX_HOMESERVER`, `MATRIX_DEFAULT_ROOM_ID`, plus either `MATRIX_ACCESS_TOKEN` or `MATRIX_USER` + `MATRIX_PASSWORD`
 - [Mattermost](#mattermost): `MATTERMOST_URL`, `MATTERMOST_TOKEN`, `MATTERMOST_CHANNEL_ID`
 
 **Search backend** (Choose either OpenSearch or Elasticsearch. Do not set both)
@@ -202,21 +202,27 @@ Uses [`matrix-js-sdk`](https://github.com/matrix-org/matrix-js-sdk) with an in-m
 | Variable | Required | Default | Notes |
 | --- | --- | --- | --- |
 | `MATRIX_HOMESERVER` | yes | - | Homeserver base URL. |
-| `MATRIX_ACCESS_TOKEN` | yes | - | Access token for the bot user. |
+| `MATRIX_ACCESS_TOKEN` | one-of | - | Long-lived access token for the bot user. Required if `MATRIX_USER`/`MATRIX_PASSWORD` are not set. |
+| `MATRIX_USER` | one-of | - | Username or full MXID for password login. Required together with `MATRIX_PASSWORD` if no access token is provided. |
+| `MATRIX_PASSWORD` | one-of | - | Password for `MATRIX_USER`. Kaytoo logs in via `matrix-js-sdk` using `m.login.password` at startup. |
 | `MATRIX_DEFAULT_ROOM_ID` | yes | - | Room for scheduled insight posts. Kaytoo also attempts to join it on startup. |
 
+Provide **either** `MATRIX_ACCESS_TOKEN` **or** the `MATRIX_USER` + `MATRIX_PASSWORD` pair, not both. Token auth is preferred when the homeserver supports it.
+
 ##### Setup
 
 1. **Create a dedicated Matrix user** for Kaytoo (recommended) on your homeserver.
    - If registration is closed, have a homeserver admin create the account.
    - Log in once with a Matrix client (for example Element) to confirm the account works.
 
-2. **Create an access token** for that user.
-   - In Element Web: open **Help & About** -> **Advanced** -> **Access Token** (wording varies by client).
+2. **Pick an authentication method:**
+   - **Access token** (preferred when available): in Element Web open **Help & About** -> **Advanced** -> **Access Token** (wording varies by client).
+   - **Username + password** (fallback for homeservers that do not expose a token UI): use the same credentials your bot logs in with.
 
 3. **Set Kaytoo env vars**:
    - `MATRIX_HOMESERVER` should be the **client API base URL** for your homeserver (often `https://matrix.example.com`, not always the same host as your MXID server part).
-   - `MATRIX_ACCESS_TOKEN` is the token from step 2.
+   - For token auth: set `MATRIX_ACCESS_TOKEN` from step 2.
+   - For password auth: set `MATRIX_USER` (localpart `kaytoo` or full MXID `@kaytoo:matrix.example.org`) and `MATRIX_PASSWORD`.
 
 4. **Room membership**:
    - Invite the bot user into each room where Kaytoo should respond.

helm/kaytoo/templates/configmap.yaml

@@ -30,6 +30,9 @@ data:
   {{- if .Values.config.matrix.defaultRoomId }}
   MATRIX_DEFAULT_ROOM_ID: {{ .Values.config.matrix.defaultRoomId | quote }}
   {{- end }}
+  {{- if .Values.config.matrix.user }}
+  MATRIX_USER: {{ .Values.config.matrix.user | quote }}
+  {{- end }}
 
   {{- if .Values.config.mattermost.url }}
   MATTERMOST_URL: {{ .Values.config.mattermost.url | quote }}

helm/kaytoo/templates/secret.yaml

@@ -16,6 +16,9 @@ stringData:
   {{- if .Values.secrets.matrixAccessToken }}
   MATRIX_ACCESS_TOKEN: {{ .Values.secrets.matrixAccessToken | quote }}
   {{- end }}
+  {{- if .Values.secrets.matrixPassword }}
+  MATRIX_PASSWORD: {{ .Values.secrets.matrixPassword | quote }}
+  {{- end }}
   {{- if .Values.secrets.mattermostToken }}
   MATTERMOST_TOKEN: {{ .Values.secrets.mattermostToken | quote }}
   {{- end }}

helm/kaytoo/values.yaml

@@ -33,6 +33,9 @@ config:
   matrix:
     homeserver: ""
     defaultRoomId: ""
+    # Optional username for password login (alternative to secrets.matrixAccessToken).
+    # Pair with secrets.matrixPassword. Accepts the localpart (`kaytoo`) or full MXID (`@kaytoo:example.org`).
+    user: ""
   mattermost:
     url: ""
     channelId: ""
@@ -54,6 +57,8 @@ secrets:
   slackBotToken: ""
   slackAppToken: ""
   matrixAccessToken: ""
+  # Set instead of matrixAccessToken when the homeserver only allows password login.
+  matrixPassword: ""
   mattermostToken: ""
   opensearchUsername: ""
   opensearchPassword: ""

src/chat/adapters/matrix.ts

@@ -13,6 +13,8 @@ import type { ChatEvent } from '../types.js';
 
 const log = getLogger({ component: 'chat.matrix' });
 
+export type MatrixAuth = { accessToken: string } | { user: string; password: string };
+
 async function whoamiUserId(baseUrl: string, accessToken: string): Promise<string | undefined> {
   const root = baseUrl.endsWith('/') ? baseUrl : `${baseUrl}/`;
   const url = new URL('_matrix/client/v3/account/whoami', root);
@@ -22,25 +24,40 @@ async function whoamiUserId(baseUrl: string, accessToken: string): Promise<strin
   return typeof body.user_id === 'string' ? body.user_id : undefined;
 }
 
+function loginIdentifier(user: string): { type: 'm.id.user'; user: string } {
+  const localpart = user.startsWith('@') ? user.replace(/^@/, '').split(':')[0]! : user;
+  return { type: 'm.id.user', user: localpart };
+}
+
 export async function startMatrixAdapter(opts: {
   homeserverUrl: string;
-  accessToken: string;
+  auth: MatrixAuth;
   matrixSdkLevel: MatrixSdkLevel;
   defaultRoomId?: string;
   onEvent: (evt: ChatEvent) => Promise<void>;
 }): Promise<{ stop: () => Promise<void>; client: MatrixClient }> {
   const logger = createMatrixJsSdkLogger(opts.matrixSdkLevel);
-  const userId = await whoamiUserId(opts.homeserverUrl, opts.accessToken);
+  const userId =
+    'accessToken' in opts.auth ? await whoamiUserId(opts.homeserverUrl, opts.auth.accessToken) : undefined;
 
   const client = createClient({
     baseUrl: opts.homeserverUrl,
-    accessToken: opts.accessToken,
+    ...('accessToken' in opts.auth ? { accessToken: opts.auth.accessToken } : {}),
     ...(userId ? { userId } : {}),
     store: new MemoryStore(),
     logger,
     timelineSupport: true,
   });
 
+  if ('user' in opts.auth) {
+    await client.loginRequest({
+      type: 'm.login.password',
+      identifier: loginIdentifier(opts.auth.user),
+      password: opts.auth.password,
+      initial_device_display_name: 'kaytoo',
+    });
+  }
+
   const onTimeline = async (
     event: MatrixEvent,
     room: Room | undefined,

src/config.ts

@@ -64,8 +64,14 @@ const configSchema = z
     matrix: z
       .object({
         homeserver: z.string().url(),
-        accessToken: z.string().min(1),
         defaultRoomId: z.string().min(1),
+        accessToken: z.string().min(1).optional(),
+        user: z.string().min(1).optional(),
+        password: z.string().min(1).optional(),
+      })
+      .refine((m) => !!m.accessToken || (!!m.user && !!m.password), {
+        message: 'Matrix requires MATRIX_ACCESS_TOKEN or both MATRIX_USER and MATRIX_PASSWORD',
+        path: ['accessToken'],
       })
       .optional(),
     mattermost: z
@@ -161,13 +167,18 @@ function slackFromEnv(env: NodeJS.ProcessEnv) {
 }
 
 function matrixFromEnv(env: NodeJS.ProcessEnv) {
-  if (!optStr(env.MATRIX_HOMESERVER) && !optStr(env.MATRIX_ACCESS_TOKEN) && !optStr(env.MATRIX_DEFAULT_ROOM_ID)) {
-    return undefined;
-  }
+  const homeserver = optStr(env.MATRIX_HOMESERVER);
+  const accessToken = optStr(env.MATRIX_ACCESS_TOKEN);
+  const user = optStr(env.MATRIX_USER);
+  const password = optStr(env.MATRIX_PASSWORD);
+  const defaultRoomId = optStr(env.MATRIX_DEFAULT_ROOM_ID);
+  if (!homeserver && !accessToken && !user && !password && !defaultRoomId) return undefined;
   return {
-    homeserver: optStr(env.MATRIX_HOMESERVER),
-    accessToken: optStr(env.MATRIX_ACCESS_TOKEN),
-    defaultRoomId: optStr(env.MATRIX_DEFAULT_ROOM_ID),
+    homeserver,
+    defaultRoomId,
+    ...(accessToken ? { accessToken } : {}),
+    ...(user ? { user } : {}),
+    ...(password ? { password } : {}),
   };
 }
 

src/main.ts

@@ -110,11 +110,17 @@ if (config.output === 'console') {
   const slackNotifier =
     slackWeb && config.slack ? slackChat.createSlackChatNotifier({ slack: slackWeb }) : undefined;
 
-  const matrixNotifier: Notifier | undefined = config.matrix
+  const matrixAuth = config.matrix?.accessToken
+    ? { accessToken: config.matrix.accessToken }
+    : config.matrix?.user && config.matrix?.password
+      ? { user: config.matrix.user, password: config.matrix.password }
+      : undefined;
+
+  const matrixNotifier: Notifier | undefined = config.matrix && matrixAuth
     ? createPromiseBackedNotifier(
         startMatrixAdapter({
           homeserverUrl: config.matrix.homeserver,
-          accessToken: config.matrix.accessToken,
+          auth: matrixAuth,
           matrixSdkLevel: config.logging.matrixSdkLevel,
           defaultRoomId: config.matrix.defaultRoomId,
           onEvent,

test/config.test.ts

@@ -232,5 +232,53 @@ describe('getConfig', () => {
     expect(cfg.slack?.botToken).toBe('xoxb-test');
     expect(cfg.matrix?.defaultRoomId).toBe('!room:example.com');
   });
+
+  it('accepts Matrix username + password as an alternative to access token', () => {
+    const cfg = getConfig({
+      MATRIX_HOMESERVER: 'https://matrix.example.com',
+      MATRIX_USER: 'kaytoo',
+      MATRIX_PASSWORD: 'pw',
+      MATRIX_DEFAULT_ROOM_ID: '!room:example.com',
+      OPENSEARCH_URL: 'https://opensearch.example.com',
+      OPENSEARCH_USERNAME: 'user',
+      OPENSEARCH_PASSWORD: 'pass',
+      LLM_BASE_URL: 'https://llm.example.com',
+      LLM_API_KEY: 'key',
+    });
+
+    expect(cfg.output).toBe('chat');
+    expect(cfg.matrix?.user).toBe('kaytoo');
+    expect(cfg.matrix?.password).toBe('pw');
+    expect(cfg.matrix?.accessToken).toBeUndefined();
+  });
+
+  it('rejects Matrix config with neither access token nor user+password', () => {
+    expect(() =>
+      getConfig({
+        MATRIX_HOMESERVER: 'https://matrix.example.com',
+        MATRIX_DEFAULT_ROOM_ID: '!room:example.com',
+        OPENSEARCH_URL: 'https://opensearch.example.com',
+        OPENSEARCH_USERNAME: 'user',
+        OPENSEARCH_PASSWORD: 'pass',
+        LLM_BASE_URL: 'https://llm.example.com',
+        LLM_API_KEY: 'key',
+      }),
+    ).toThrowError(/MATRIX_ACCESS_TOKEN or both MATRIX_USER and MATRIX_PASSWORD/);
+  });
+
+  it('rejects Matrix config with only a username and no password', () => {
+    expect(() =>
+      getConfig({
+        MATRIX_HOMESERVER: 'https://matrix.example.com',
+        MATRIX_USER: 'kaytoo',
+        MATRIX_DEFAULT_ROOM_ID: '!room:example.com',
+        OPENSEARCH_URL: 'https://opensearch.example.com',
+        OPENSEARCH_USERNAME: 'user',
+        OPENSEARCH_PASSWORD: 'pass',
+        LLM_BASE_URL: 'https://llm.example.com',
+        LLM_API_KEY: 'key',
+      }),
+    ).toThrowError(/MATRIX_ACCESS_TOKEN or both MATRIX_USER and MATRIX_PASSWORD/);
+  });
 });