@rhizogrip/spore-plugin-teams 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/NOTICE

@@ -0,0 +1,2 @@
+spore-plugin-teams
+Copyright 2026 Christophe Le Bars <clb@toort.net>

package/README.md

@@ -1,3 +1,107 @@
-# Temporary Holding Version
+# @rhizogrip/spore-plugin-teams
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A service that puts your spores in Microsoft Teams: a person's personal chat with the bot reaches
+their spore, and a channel reaches its spore when someone there mentions the bot. It runs on the
+machine the spores are on, once per bot, as a systemd user unit. It gives spores nothing, so it
+needs no `spore plugin allow`: `spore service` offers it once it is installed.
+
+```bash
+npm i -g @rhizogrip/spore-plugin-teams
+echo 'OPS_TEAMS_SECRET=…' >> ~/.config/spore/environment     # the app registration's client secret; it never reaches a spore
+mkdir -p ~/.config/spore/teams
+cat > ~/.config/spore/teams/ops.json <<'JSON'
+{ "app": "<app id>", "tenant": "<tenant id>", "secret": "${OPS_TEAMS_SECRET}",
+  "listen": "127.0.0.1:3978", "people": {} }
+JSON
+spore service define teams@ops && spore service start teams@ops
+```
+
+## The bot
+
+Teams reaches a bot through Azure: an **Azure Bot**, single-tenant, whose app registration in
+Entra ID gives the bot file its `app` (the Microsoft App ID), its `tenant`, and a client secret,
+kept in `environment` under the variable `secret` names. The Azure Bot's messaging endpoint is a
+public HTTPS address of yours ending in `/api/messages`, which your proxy forwards to `listen` —
+a loopback address: the service never faces the internet itself. Turn on the Azure Bot's Teams
+channel, and install a Teams app for the bot in your tenant with the personal and team scopes.
+
+Every activity is checked before it is read: a token Microsoft signed for this app id, with a key
+it endorses for Teams, for the `serviceUrl` the activity names. One that fails is answered 401 and
+logged with what failed. An activity from another tenant than the bot's is dropped and logged.
+
+`spore service define` first runs the service's checks (`--check`), which ask Microsoft for the
+bot's token: a wrong app id, tenant or secret is refused there, with exit status 2.
+
+## People and channels
+
+```json
+{ "app": "…", "tenant": "…", "secret": "${OPS_TEAMS_SECRET}", "listen": "127.0.0.1:3978",
+  "people": { "3f2b…-object-id": "triage", "8a41…-object-id": { "spore": "ledger", "details": true } },
+  "channels": { "19:a1b2…@thread.tacv2": { "spores": ["triage"], "people": ["3f2b…-object-id", "*"] } } }
+```
+
+`people` is each person's personal chat with the bot, by their Entra object id, and the spore it
+reaches. `channels` is each standard channel by its id — in the channel's link, `19:…@thread.tacv2`
+— with its one spore and `people`, who may address it there: object ids, or `"*"` for everyone in
+the channel, written out. A channel has one spore: the bot speaks there as itself, so a second spore
+is a second bot. `details` shows the calls themselves in the `working…` message rather than their
+kinds. The file is read on every message, so a person or a channel is added by editing a line.
+
+Someone not in the file gets silence, and the log gets the line to add:
+
+```
+refused Alice Martin (3f2b…) — to allow them, add "3f2b…": "<a spore>" to the people of …/teams/ops.json
+```
+
+which is also how you learn object ids: start with `"people": {}` and write to the bot.
+
+## A turn
+
+In a personal chat, anything written reaches the spore. In a channel, a message reaches it when
+it mentions the bot, and the mention is not part of what the spore is told; the spore is told who
+wrote and where. The bot posts `working…` and shows what kind of call runs as it runs; the answer
+is a new message — in a channel, in the thread of the message it answers — and `working…` is then
+removed, or marked `answered below` where Teams will not remove it. The answer is sent as Teams
+markdown. What the turn left in `data/out/` is named, one line a file: files do not cross yet,
+either way.
+
+```
+/status    what the spore is doing, its turns and what they cost, and the running turn's limits
+/stop      end the turn it is running, and set aside what you sent that it had not read
+/wrap [10m]        ask the running turn to wrap up, now or in a while
+/extend wall 30m   give it more — wall, cost or rounds — up to the extend.<limit> its spore.cmk grants
+```
+
+In a channel, after the mention; there `/stop`, `/wrap` and `/extend` are for the people the
+channel lists by id, not everyone `"*"` lets talk.
+
+## Turns nobody in Teams started
+
+A schedule, a job or a webhook starts a turn no one in Teams asked for. Its answer goes to the
+spore's `replyTo` in `config.json`: `teams:<bot>/<object id>` for a person — the bot opens a
+personal chat with them if they never wrote to it — or `teams:<bot>/<channel id>`, a new post in
+the channel. A place this bot's file does not route to the spore is refused, and the log says why.
+
+## What it guarantees
+
+- **A message reaches its spore once,** under `teams:<conversation id>:<activity id>` as its
+  `requestId`, and Microsoft's delivery is answered only once the spore has it: one Microsoft sends
+  again is not said twice.
+- **A finished turn reaches its conversation at least once.** What it owes a conversation is an
+  entry in the spore's outbox, settled only once Teams took it; one the service was posting when it
+  stopped is posted again opening with `(this may repeat an earlier message)`. One Teams refuses is
+  settled refused with Teams' reason; a rate limit is waited out, as long as Teams says.
+- **An answer never waits behind progress.** Under a rate limit the `working…` edits are dropped.
+
+## Not yet
+
+Group chats (logged and left), private and shared channels, files in either direction, and a bot
+serving tenants other than its own.
+
+## What it keeps
+
+`$XDG_STATE_HOME/spore/teams/<bot>/state.json`, mode 0600: where it stands in each spore, the
+`working…` messages waiting for an answer, each person's chat with the bot and each channel's
+service address, as Teams last gave them.
+
+It imports `@rhizogrip/spore`, declared as a peer.

package/bin/spore-teams.js

@@ -0,0 +1,25 @@
+#!/usr/bin/env node
+import { dirname, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+import { readBot, runService } from '@rhizogrip/spore/relay'
+
+import { createConnector } from '../src/api.js'
+import { createToken, createVerifier } from '../src/auth.js'
+import { TEAMS, createAdapter, listenOf } from '../src/adapter.js'
+import { serve } from '../src/server.js'
+
+await runService({
+  spec: TEAMS,
+  program: 'spore-teams',
+  root: resolve(dirname(fileURLToPath(import.meta.url)), '..'),
+  open: async ({ file, credentials }) => {
+    const { app, tenant, ...raw } = readBot(TEAMS, file)
+    const { host, port } = listenOf(raw, file)
+    const token = createToken({ app, tenant, secret: credentials.secret })
+    await token()
+    const verify = createVerifier({ app })
+    const receive = ({ onActivity, signal, log }) => serve({ host, port, verify, onActivity, signal, log })
+    return { adapter: createAdapter({ connector: createConnector({ token }), receive, app, tenant }), who: `app ${app} on ${host}:${port}` }
+  }
+})

package/package.json

@@ -1,6 +1,69 @@
 {
   "name": "@rhizogrip/spore-plugin-teams",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Microsoft Teams for spores: a bot of yours in personal chats and channels, each reaching its spore, run as a service",
+  "author": {
+    "name": "Christophe Le Bars",
+    "email": "clb@toort.net"
+  },
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/RHIZOGRIP/spore.git",
+    "directory": "plugins/teams"
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "os": [
+    "linux"
+  ],
+  "cpu": [
+    "x64"
+  ],
+  "files": [
+    "bin/",
+    "src/",
+    "README.md",
+    "NOTICE"
+  ],
+  "peerDependencies": {
+    "@rhizogrip/spore": "^1.22.0"
+  },
+  "scripts": {
+    "test": "vitest run"
+  },
+  "spore": {
+    "works": "^1.22.0",
+    "services": {
+      "teams": {
+        "what": "a bot of yours in Microsoft Teams, each personal chat and channel reaching its spore",
+        "program": "./bin/spore-teams.js",
+        "instances": {
+          "dir": "teams",
+          "ext": ".json",
+          "called": "bot"
+        },
+        "check": [
+          "--check"
+        ]
+      }
+    }
+  },
+  "release-it": {
+    "git": {
+      "requireBranch": "main",
+      "commitMessage": "release: plugin-teams v${version}",
+      "tagName": "plugin-teams-v${version}",
+      "requireUpstream": false,
+      "push": true
+    },
+    "npm": {
+      "publish": false
+    },
+    "github": {
+      "release": false
+    }
+  },
+  "license": "Apache-2.0"
+}

package/src/adapter.js

@@ -0,0 +1,250 @@
+/**
+ * Microsoft Teams for the relay (`@rhizogrip/spore/relay`): the bot file, the activities the Bot
+ * Connector delivers, and the Bot Connector calls that answer them. A person's personal chat with
+ * the bot is a conversation keyed by their Entra object id; a channel's is a thread in it,
+ * `<channel id>;messageid=<root>`, routed by its channel.
+ */
+
+import { SporeError } from '@rhizogrip/spore'
+
+const FIELDS = ['app', 'tenant', 'secret', 'listen', 'people', 'channels']
+const PERSON_FIELDS = ['spore', 'details']
+const CHANNEL_FIELDS = ['spores', 'people', 'details']
+const PERSON = /^[0-9a-f][0-9a-f-]*$/i
+const CHANNEL = /^19:[^\s;]+@thread\.[a-z0-9]+$/i
+const LOOPBACK = new Set(['127.0.0.1', '::1', 'localhost'])
+const THREAD = ';messageid='
+const COMMAND = /^\/([a-z]+)(?:\s+(.+))?$/is
+const SERVICE_URL = 'https://smba.trafficmanager.net/teams/'
+const SHAPE = '{ "app": "<app id>", "tenant": "<tenant id>", "secret": "${OPS_TEAMS_SECRET}", "listen": "127.0.0.1:3978", "people": { "<object id>": "<spore>" }, "channels": { "<channel id>": { "spores": ["<spore>"], "people": ["<object id>"] } } }' // eslint-disable-line no-template-curly-in-string
+
+const invalid = (path, problem, detail = `a bot is ${SHAPE}`) => new SporeError(`${path} ${problem}`, { type: 'TEAMS_BOT_INVALID', detail })
+
+const record = (value) => typeof value === 'object' && value !== null && !Array.isArray(value)
+
+const strays = (path, kind, id, entry, takes) => {
+  const extra = Object.keys(entry).filter(key => !takes.includes(key))
+  if (!extra.length) return
+  const bots = extra.filter(key => FIELDS.includes(key))
+  throw invalid(path, `gives ${kind} ${id} ${extra.join(', ')}, which a ${kind} does not take`, `a ${kind} takes ${takes.join(', ')}${bots.length ? `; ${bots.join(', ')} is the bot's, beside people and channels` : ''}`)
+}
+
+/** Where the service listens, `<loopback host>:<port>`: the operator's proxy is what faces Microsoft. */
+export function listenOf (raw, path) {
+  const found = /^(.+):(\d+)$/.exec(raw.listen ?? '')
+  const host = found?.[1].replace(/^\[(.*)\]$/, '$1')
+  if (!found || !LOOPBACK.has(host) || Number(found[2]) > 65535) {
+    throw invalid(path, `listens on ${JSON.stringify(raw.listen)}`, 'listen is a loopback address and a port, as 127.0.0.1:3978 — a proxy of yours gives it the public HTTPS address the Azure Bot names')
+  }
+  return { host, port: Number(found[2]) }
+}
+
+/**
+ * The bot's app and tenant, where it listens, and its routing: `people`, each person's personal
+ * chat by their Entra object id — `"<spore>"` or `{ "spore", "details" }` — and `channels`, each
+ * standard channel by its id, with its one spore and who may address it there: object ids, or `*`
+ * for everyone in the channel. `details` shows the calls themselves rather than their kinds.
+ */
+function routes (raw, path) {
+  for (const field of ['app', 'tenant']) {
+    if (typeof raw[field] !== 'string' || !raw[field]) throw invalid(path, `has no ${field}`, `${field} is the Azure Bot's ${field === 'app' ? 'Microsoft App ID' : 'app tenant ID'}`)
+  }
+  listenOf(raw, path)
+  if (raw.people === undefined && raw.channels === undefined) {
+    throw invalid(path, 'has no people and no channels', `a bot is ${SHAPE} — "people": {} while you learn the ids: the log names everyone it refuses`)
+  }
+  const entries = (field) => {
+    const value = raw[field] ?? {}
+    if (!record(value)) throw invalid(path, `has ${field} that is not { "<id>": … }`)
+    return Object.entries(value)
+  }
+  const table = new Map()
+  for (const [person, entry] of entries('people')) {
+    if (!PERSON.test(person)) throw invalid(path, `names "${person}" among its people, which is not an Entra object id`, 'a person is their object id in Entra ID; a channel\'s id begins 19: and goes under channels')
+    if (record(entry)) {
+      strays(path, 'person', person, entry, PERSON_FIELDS)
+      if (entry.details !== undefined && typeof entry.details !== 'boolean') throw invalid(path, `has a person ${person} whose details is not true or false`)
+    }
+    const spore = record(entry) ? entry.spore : entry
+    if (typeof spore !== 'string' || !spore) throw invalid(path, `maps person ${person} to something that is not a spore`, 'each person is their object id against the name of the spore they reach, or { "spore": "<name>", "details": true }')
+    table.set(person, { spores: [spore], details: record(entry) && entry.details === true, show: null, people: null, overhear: false })
+  }
+  for (const [channel, entry] of entries('channels')) {
+    if (!CHANNEL.test(channel)) throw invalid(path, `names "${channel}" among its channels, which is not a channel id`, 'a channel id is 19:…@thread.tacv2, from the channel\'s link in Teams')
+    if (!record(entry)) throw invalid(path, `has a channel ${channel} that is not { "spores": [...], "people": [...] }`)
+    strays(path, 'channel', channel, entry, CHANNEL_FIELDS)
+    if (entry.details !== undefined && typeof entry.details !== 'boolean') throw invalid(path, `has a channel ${channel} whose details is not true or false`)
+    if (!Array.isArray(entry.spores) || !entry.spores.length || !entry.spores.every(spore => typeof spore === 'string' && spore)) throw invalid(path, `has a channel ${channel} with no spores`)
+    if (entry.spores.length > 1) throw invalid(path, `gives channel ${channel} ${entry.spores.length} spores`, 'a bot speaks in a channel as itself, so a channel has one spore — a second spore there is a second bot')
+    if (!Array.isArray(entry.people) || !entry.people.every(who => who === '*' || (typeof who === 'string' && PERSON.test(who)))) {
+      throw invalid(path, `has a channel ${channel} whose people are not object ids or *`, 'people is who may address its spore — ["<object id>", …], or ["*"] for everyone in the channel, written out')
+    }
+    table.set(channel, { spores: entry.spores, details: entry.details === true, show: null, people: entry.people, overhear: false })
+  }
+  return table
+}
+
+const HELP = 'Anything you write to me in a personal chat goes to the spore; in a channel, mention me. /status says what it is doing; /stop ends the turn it is running and sets aside what you sent that it had not read; /wrap [10m] asks it to wrap up; /extend wall 30m gives it more, as far as its spore.cmk allows.'
+
+export const TEAMS = {
+  kind: 'teams',
+  label: 'Teams',
+  noun: 'conversation',
+  fields: FIELDS,
+  credentials: ['secret'],
+  stateFields: ['chats', 'channels'],
+  sourceVariables: [],
+  refusals: ['TEAMS_REFUSED', 'TEAMS_LISTEN_REFUSED'],
+  example: SHAPE,
+  routes,
+  routeOf: (conversation) => conversation.split(THREAD)[0],
+  usage: { help: HELP, extend: '/extend wall 30m, /extend cost 1.50 or /extend rounds 20' },
+  limits: { message: 40000, file: 0, editEveryMs: 2500, typingEveryMs: 4000 },
+  can: { upload: false, remove: true, react: false, typing: false, reply: true },
+  reactions: null,
+  showShared: 'working',
+  hint (err, { file }) {
+    if (err.type === 'TEAMS_NO_BOT') return `mkdir -p ${file.slice(0, file.lastIndexOf('/'))} — then ${file} as ${SHAPE}`
+    if (err.type === 'TEAMS_REFUSED') return 'the app id, its tenant and a client secret come from the Azure Bot\'s app registration in Entra ID; the secret goes in environment beside config.json'
+    if (err.type === 'TEAMS_LISTEN_REFUSED') return `another process holds that address — change listen in ${file}`
+    return null
+  },
+  refusal: (message, botFile) => message.shared
+    ? `refused ${message.where}, ${message.conversation.split(THREAD)[0]} — to allow it, add "${message.conversation.split(THREAD)[0]}": { "spores": ["<a spore>"], "people": ["${message.person.id}"] } to the channels of ${botFile}`
+    : `refused ${message.person.name} (${message.person.id}) — to allow them, add "${message.person.id}": "<a spore>" to the people of ${botFile}`
+}
+
+const ENTITIES = { '&amp;': '&', '&lt;': '<', '&gt;': '>', '&quot;': '"', '&#39;': '\'', '&nbsp;': ' ' }
+
+/** Teams' markup made plain: the bot's own mention gone, anyone else's as `@name`, tags dropped. */
+const plain = (html, own) => html
+  .replace(/<at[^>]*>(.*?)<\/at>/gis, (whole, name) => own.includes(whole) ? '' : `@${name}`)
+  .replace(/<br\s*\/?>|<\/p>/gi, '\n')
+  .replace(/<[^>]+>/g, '')
+  .replace(/&(amp|lt|gt|quot|#39|nbsp);/g, (entity) => ENTITIES[entity])
+  .replace(/\n{3,}/g, '\n\n')
+  .trim()
+
+/**
+ * A message activity as the relay takes it, or null for none it takes: one in a personal chat
+ * reaches the person's spore; one in a channel reaches the channel's when it mentions the bot,
+ * and names no spore otherwise.
+ */
+export function normalize (activity) {
+  const personal = activity.conversation.conversationType === 'personal'
+  const own = (activity.entities ?? []).filter(entity => entity.type === 'mention' && entity.mentioned?.id === activity.recipient.id).map(entity => entity.text)
+  const text = plain(activity.text ?? '', own) || null
+  const command = text?.match(COMMAND)
+  const channel = activity.channelData?.channel
+  return {
+    id: `${activity.conversation.id}:${activity.id}`,
+    conversation: personal ? activity.from.aadObjectId : activity.conversation.id,
+    message: activity.id,
+    person: { id: activity.from.aadObjectId, name: activity.from.name, groups: [] },
+    spore: null,
+    where: personal ? 'a personal chat in Teams' : channel?.name ? `the Teams channel "${channel.name}"` : 'a Teams channel',
+    shared: !personal,
+    text,
+    command: command ? { verb: command[1].toLowerCase(), args: command[2] ?? '' } : null,
+    addresses: personal || own.length ? null : [],
+    files: (activity.attachments ?? []).filter(attachment => attachment.contentType !== 'text/html').length
+  }
+}
+
+const tenantOf = (activity) => activity.conversation?.tenantId ?? activity.channelData?.tenant?.id
+
+/**
+ * The live adapter. `receive({ onActivity, signal, log })` is the transport — the listener, or a
+ * test's — and hands over each activity already checked. A post to a person goes to the chat they
+ * have with the bot, made when there is none yet; to a channel thread, into the thread; to a
+ * channel, as a new post. A note is `<conversation id> <activity id>`, where the post went.
+ */
+export function createAdapter ({ connector, receive, app, tenant }) {
+  let kept = null
+  let save = null
+
+  /** What came with an activity that says where to answer: the person's chat, or the channel's service. */
+  const remember = (activity) => {
+    const { serviceUrl } = activity
+    if (activity.conversation.conversationType === 'personal' && activity.from.aadObjectId) {
+      const was = kept.chats[activity.from.aadObjectId]
+      if (was?.conversation === activity.conversation.id && was.serviceUrl === serviceUrl) return
+      kept.chats[activity.from.aadObjectId] = { conversation: activity.conversation.id, serviceUrl }
+      save()
+    } else if (activity.channelData?.channel?.id) {
+      const channel = activity.channelData.channel.id
+      if (kept.channels[channel]?.serviceUrl === serviceUrl) return
+      kept.channels[channel] = { serviceUrl }
+      save()
+    }
+  }
+
+  const serviceOf = (conversation) => conversation.startsWith('19:')
+    ? kept.channels[conversation.split(THREAD)[0]]?.serviceUrl ?? SERVICE_URL
+    : kept.chats[conversation]?.serviceUrl ?? SERVICE_URL
+
+  const chatOf = async (person) => {
+    if (!kept.chats[person]) {
+      const made = await connector.create(SERVICE_URL, { bot: { id: `28:${app}` }, members: [{ id: person }], channelData: { tenant: { id: tenant } }, isGroup: false })
+      kept.chats[person] = { conversation: made.id, serviceUrl: SERVICE_URL }
+      save()
+    }
+    return kept.chats[person].conversation
+  }
+
+  const placeOf = (note) => {
+    const at = note.lastIndexOf(' ')
+    return { conversation: note.slice(0, at), id: note.slice(at + 1) }
+  }
+
+  const activity = (text, { markdown = false, answering = null } = {}) => ({
+    type: 'message',
+    text,
+    textFormat: markdown ? 'markdown' : 'plain',
+    ...(answering === null ? {} : { replyToId: answering })
+  })
+
+  return {
+    ...TEAMS,
+
+    restore (state, persist) {
+      kept = state
+      save = persist
+    },
+
+    listen: ({ onMessage, signal, log }) => receive({
+      signal,
+      log,
+      onActivity: async (one) => {
+        if (tenantOf(one) !== tenant) return log(`dropped an activity from tenant ${tenantOf(one)}: this bot serves ${tenant}`)
+        remember(one)
+        if (one.type !== 'message') return
+        if (one.conversation.conversationType === 'groupChat') return log(`group chat ${one.conversation.id}: group chats are not served yet`)
+        if (!one.from?.aadObjectId) return log(`a message in ${one.conversation.id} from ${one.from?.name ?? 'someone'} with no Entra object id, not taken`)
+        await onMessage(normalize(one))
+      }
+    }),
+
+    post: async (conversation, text, { answering = null, markdown = false } = {}) => {
+      if (!conversation.startsWith('19:')) {
+        const chat = await chatOf(conversation)
+        return `${chat} ${await connector.send(serviceOf(conversation), chat, activity(text, { markdown, answering }))}`
+      }
+      if (conversation.includes(THREAD)) {
+        return `${conversation} ${await connector.send(serviceOf(conversation), conversation, activity(text, { markdown, answering }))}`
+      }
+      const made = await connector.create(serviceOf(conversation), { isGroup: true, channelData: { channel: { id: conversation }, tenant: { id: tenant } }, activity: activity(text, { markdown }) })
+      return `${made.id} ${made.activityId}`
+    },
+
+    edit: async (conversation, note, text) => {
+      const where = placeOf(note)
+      await connector.update(serviceOf(conversation), where.conversation, where.id, { ...activity(text), id: where.id })
+    },
+
+    remove: async (conversation, note) => {
+      const where = placeOf(note)
+      await connector.remove(serviceOf(conversation), where.conversation, where.id)
+    }
+  }
+}

package/src/api.js

@@ -0,0 +1,54 @@
+/**
+ * The Bot Connector's REST API, as the service uses it. Every failure is a `TEAMS_FAILED`,
+ * `retryable` for what Microsoft asks a bot to try again — 412, 429, 502, 503, 504, and a request
+ * that never reached it — with `context.status`, `context.code` and `context.retryAfter` (seconds,
+ * when Microsoft said how long to wait).
+ */
+
+import { SporeError } from '@rhizogrip/spore'
+
+const RETRYABLE = new Set([412, 429, 502, 503, 504])
+
+const base = (serviceUrl) => serviceUrl.endsWith('/') ? serviceUrl : `${serviceUrl}/`
+
+export function createConnector ({ token, fetchImpl = fetch }) {
+  const call = async (method, url, body) => {
+    const bearer = await token()
+    let response
+    try {
+      response = await fetchImpl(url, {
+        method,
+        headers: { authorization: `Bearer ${bearer}`, ...(body === undefined ? {} : { 'content-type': 'application/json' }) },
+        body: body === undefined ? undefined : JSON.stringify(body),
+        signal: AbortSignal.timeout(60_000)
+      })
+    } catch (err) {
+      throw new SporeError(`teams ${method} failed`, { type: 'TEAMS_FAILED', detail: err.message, retryable: true, context: { status: null, code: null, retryAfter: null } })
+    }
+    const answer = await response.json().catch(() => null)
+    if (!response.ok) {
+      const after = Number(response.headers.get('retry-after'))
+      throw new SporeError(`teams ${method} failed`, {
+        type: 'TEAMS_FAILED',
+        detail: answer?.error?.message ?? answer?.message ?? `HTTP ${response.status}`,
+        retryable: RETRYABLE.has(response.status),
+        context: { status: response.status, code: answer?.error?.code ?? null, retryAfter: Number.isFinite(after) && after > 0 ? after : null }
+      })
+    }
+    return answer
+  }
+
+  const activities = (serviceUrl, conversation) => `${base(serviceUrl)}v3/conversations/${encodeURIComponent(conversation)}/activities`
+
+  return {
+    /** An activity into a conversation; answers its id. */
+    send: async (serviceUrl, conversation, activity) => (await call('POST', activities(serviceUrl, conversation), activity)).id,
+
+    update: (serviceUrl, conversation, id, activity) => call('PUT', `${activities(serviceUrl, conversation)}/${encodeURIComponent(id)}`, activity),
+
+    remove: (serviceUrl, conversation, id) => call('DELETE', `${activities(serviceUrl, conversation)}/${encodeURIComponent(id)}`),
+
+    /** A conversation made — a person's chat with the bot, or a new post in a channel: `{ id, activityId }`. */
+    create: (serviceUrl, body) => call('POST', `${base(serviceUrl)}v3/conversations`, body)
+  }
+}

package/src/auth.js

@@ -0,0 +1,107 @@
+/**
+ * A bot's identity with Microsoft, both ways: the token it sends the Bot Connector, from its
+ * tenant's authority, and the check of the token the Bot Connector sends with each activity. A
+ * failure to reach Microsoft is a `TEAMS_FAILED`, retryable; Microsoft refusing the bot's app id or
+ * secret is a `TEAMS_REFUSED`, which a service cannot get past by waiting.
+ */
+
+import { createPublicKey, verify } from 'node:crypto'
+
+import { SporeError } from '@rhizogrip/spore'
+
+const AUTHORITY = 'https://login.microsoftonline.com'
+const OPENID = 'https://login.botframework.com/v1/.well-known/openidconfiguration'
+const ISSUER = 'https://api.botframework.com'
+const SCOPE = 'https://api.botframework.com/.default'
+const SKEW_S = 300
+const KEYS_EVERY_MS = 24 * 60 * 60 * 1000
+const UNKNOWN_KEY_EVERY_MS = 60 * 1000
+
+const unreachable = (what, err) => new SporeError(`${what} failed`, { type: 'TEAMS_FAILED', detail: err.message, retryable: true, context: { status: null, retryAfter: null } })
+
+/** The bot's bearer token for the Bot Connector, asked of its tenant and kept until shortly before it expires. */
+export function createToken ({ app, tenant, secret, fetchImpl = fetch, now = Date.now, authority = AUTHORITY }) {
+  let held = null
+  return async () => {
+    if (held && held.until > now()) return held.token
+    let response
+    try {
+      response = await fetchImpl(`${authority}/${encodeURIComponent(tenant)}/oauth2/v2.0/token`, {
+        method: 'POST',
+        headers: { 'content-type': 'application/x-www-form-urlencoded' },
+        body: new URLSearchParams({ grant_type: 'client_credentials', client_id: app, client_secret: secret, scope: SCOPE }),
+        signal: AbortSignal.timeout(30_000)
+      })
+    } catch (err) {
+      throw unreachable('asking Microsoft for a token', err)
+    }
+    const answer = await response.json().catch(() => null)
+    if (!response.ok || typeof answer?.access_token !== 'string') {
+      throw new SporeError('Microsoft gave the bot no token', {
+        type: response.status >= 500 ? 'TEAMS_FAILED' : 'TEAMS_REFUSED',
+        detail: answer?.error_description?.split('\r\n')[0] ?? `HTTP ${response.status}`,
+        retryable: response.status >= 500,
+        context: { status: response.status, retryAfter: null }
+      })
+    }
+    held = { token: answer.access_token, until: now() + (answer.expires_in - SKEW_S) * 1000 }
+    return held.token
+  }
+}
+
+const decoded = (part) => JSON.parse(Buffer.from(part, 'base64url').toString('utf8'))
+
+const sameService = (one, other) => typeof one === 'string' && typeof other === 'string' &&
+  one.toLowerCase().replace(/\/+$/, '') === other.toLowerCase().replace(/\/+$/, '')
+
+/**
+ * The check of an activity's `Authorization`: a JWT Microsoft signed with RS256, by a key it
+ * publishes and endorses for the activity's channel, issued by the Bot Connector for this app id,
+ * in its time, for the `serviceUrl` the activity names. Answers null when it holds, else why not.
+ * The keys are read from Microsoft's OpenID metadata, again each day and when a token names one
+ * they do not hold.
+ */
+export function createVerifier ({ app, fetchImpl = fetch, now = Date.now, openid = OPENID }) {
+  let keys = null
+  const load = async () => {
+    try {
+      const config = await (await fetchImpl(openid, { signal: AbortSignal.timeout(30_000) })).json()
+      const set = await (await fetchImpl(config.jwks_uri, { signal: AbortSignal.timeout(30_000) })).json()
+      keys = { at: now(), byKid: new Map(set.keys.map(key => [key.kid, key])) }
+    } catch (err) {
+      throw unreachable('reading the keys Microsoft signs activities with', err)
+    }
+  }
+  const keyOf = async (kid) => {
+    if (!keys || now() - keys.at > KEYS_EVERY_MS) await load()
+    if (!keys.byKid.has(kid) && now() - keys.at > UNKNOWN_KEY_EVERY_MS) await load()
+    return keys.byKid.get(kid) ?? null
+  }
+
+  return async (authorization, activity) => {
+    const token = /^Bearer (\S+)$/.exec(authorization ?? '')?.[1]
+    if (!token) return 'it carries no bearer token'
+    const parts = token.split('.')
+    let header, claims
+    try {
+      if (parts.length !== 3) throw new Error('three parts')
+      header = decoded(parts[0])
+      claims = decoded(parts[1])
+    } catch {
+      return 'its token is not a JWT'
+    }
+    if (header.alg !== 'RS256') return `its token is signed with ${header.alg}, not RS256`
+    const jwk = await keyOf(header.kid)
+    if (!jwk) return `its token names key ${header.kid}, which Microsoft does not publish`
+    if (!(jwk.endorsements ?? []).includes(activity.channelId)) return `key ${header.kid} is not endorsed for ${activity.channelId}`
+    const key = createPublicKey({ key: { kty: jwk.kty, n: jwk.n, e: jwk.e }, format: 'jwk' })
+    if (!verify('RSA-SHA256', Buffer.from(`${parts[0]}.${parts[1]}`), key, Buffer.from(parts[2], 'base64url'))) return 'its token\'s signature does not hold'
+    if (claims.iss !== ISSUER) return `its token was issued by ${claims.iss}`
+    if (claims.aud !== app) return `its token is for ${claims.aud}, not this bot`
+    const at = now() / 1000
+    if (typeof claims.exp !== 'number' || claims.exp + SKEW_S < at) return 'its token has expired'
+    if (typeof claims.nbf === 'number' && claims.nbf - SKEW_S > at) return 'its token is not valid yet'
+    if (!sameService(claims.serviceurl, activity.serviceUrl)) return 'its token is for another serviceUrl than the activity names'
+    return null
+  }
+}

package/src/server.js

@@ -0,0 +1,65 @@
+/**
+ * Where the Bot Connector delivers: `POST /api/messages` on a loopback address, which the
+ * operator's proxy makes the bot's public HTTPS endpoint. An activity is checked before it is
+ * read, and answered 200 only once `onActivity` has it, so one the service could not take is
+ * delivered again.
+ */
+
+import { createServer } from 'node:http'
+
+import { SporeError } from '@rhizogrip/spore'
+
+const PATH = '/api/messages'
+const MOST_BYTES = 1024 * 1024
+
+const bodyOf = (request) => new Promise((resolve, reject) => {
+  const chunks = []
+  let bytes = 0
+  request.on('data', (chunk) => {
+    bytes += chunk.length
+    if (bytes <= MOST_BYTES) chunks.push(chunk)
+  })
+  request.on('end', () => bytes > MOST_BYTES ? reject(Object.assign(new Error('too large'), { status: 413 })) : resolve(Buffer.concat(chunks).toString('utf8')))
+  request.on('error', reject)
+})
+
+/** Serves until `signal` aborts, telling `listening` the port once it listens. */
+export function serve ({ host, port, verify, onActivity, signal, log, listening = () => {} }) {
+  const server = createServer(async (request, response) => {
+    const answer = (status) => response.writeHead(status).end()
+    if (request.method !== 'POST' || request.url !== PATH) return answer(404)
+    let activity
+    try {
+      activity = JSON.parse(await bodyOf(request))
+    } catch (err) {
+      return answer(err.status ?? 400)
+    }
+    let refused
+    try {
+      refused = await verify(request.headers.authorization, activity)
+    } catch (err) {
+      log(`could not check an activity — ${err.message}${err.detail ? ` — ${err.detail}` : ''}`)
+      return answer(503)
+    }
+    if (refused) {
+      log(`refused an activity: ${refused}`)
+      return answer(401)
+    }
+    try {
+      await onActivity(activity)
+    } catch (err) {
+      log(`activity ${activity.id} not taken — ${err.message}${err.detail ? ` — ${err.detail}` : ''}`)
+      return answer(500)
+    }
+    answer(200)
+  })
+
+  return new Promise((resolve, reject) => {
+    server.once('error', (err) => reject(new SporeError(`cannot listen on ${host}:${port}`, { type: 'TEAMS_LISTEN_REFUSED', detail: err.message })))
+    server.listen(port, host, () => {
+      listening(server.address().port)
+      signal.addEventListener('abort', () => server.close(() => resolve()), { once: true })
+      if (signal.aborted) server.close(() => resolve())
+    })
+  })
+}