feat(teams): persist trusted conversation registry

[NeoHsu]

Important

Stacked draft: logical base stack/teams-10-text-commands is PR #1502. GitHub requires an upstream PR base to exist in openabdev/openab, so this draft temporarily targets main and may show preceding stack layers. Do not merge it until #1502 is merged and this branch is rebased onto current main; then review only its single incremental commit.

What problem does this solve?

Create an opt-in, versioned, bounded, filesystem-safe Teams conversation
registry that promotes only JWT-valid routes which Core has admitted through
shared L2/L3 trust, survives a Gateway restart, refreshes only from new trusted
inbound evidence, records disable/revocation state, and never exposes the
persistent reference or serviceUrl to Core or ACP.

Discord Discussion URL: https://discord.com/channels/1491295327620169908/1491365158868619404/1531339032527765655
Microsoft Teams roadmap discussion.

Review Contract

This is the proposed PR-body contract. It is not frozen until the owner or a
maintainer approves it and records the reviewed head plus an immutable contract
revision or hash.

Goal

Create an opt-in, versioned, bounded, filesystem-safe Teams conversation
registry that promotes only JWT-valid routes which Core has admitted through
shared L2/L3 trust, survives a Gateway restart, refreshes only from new trusted
inbound evidence, records disable/revocation state, and never exposes the
persistent reference or serviceUrl to Core or ACP.

Non-goals

Sending proactive messages, Teams cron/reminders, a user-facing registry CRUD
command, Graph app installation or discovery, RSC/ambient reading, a durable
inbound queue, restart-persistent activity ownership or dedupe, multi-replica
coordination, cross-process file locking, encryption at rest, or sovereign-cloud
expansion are outside PR 11.

Accepted Residual Risks

The opt-in JSON file is protected by filesystem permissions but is not
encrypted; a principal able to read the Gateway account or mounted volume can
read its routing identifiers and service URL. Reactive turns continue when a
background promotion fails, so a trusted conversation may temporarily lack a
persistent route; correlated outcomes and count-only diagnostics make that
visible, and a later independent inbound activity may promote it. Wall-clock
changes can affect TTL ordering. The store is safe only for one Gateway writer,
and uninstall evidence can be delayed or absent until a later explicit 403 or
trusted reinstallation activity. Non-Unix deployments rely on the containing
directory's ACL rather than POSIX mode bits.

Acceptance Criteria

Persistence is disabled by default; configured paths and records pass the
specified traversal, symlink, permission, size, schema, atomicity, recovery,
TTL, and capacity gates; the complete app/tenant/channel/conversation identity
is enforced; only post-structural and post-L2/L3 Allow events can issue a
capability-negotiated correlated promotion; Gateway derives every persisted
field from its authenticated ephemeral route rather than Core input; denied or
cross-scope events perform no filesystem mutation; registration does not depend
on ACP success or deadlock the Standalone reader; Unified and Standalone are
semantically equivalent; refresh, disable, reactivation, and authenticated
uninstall revocation follow the declared state machine; unsupported rolling
pairs preserve process-local behavior; and persistent references and service URLs
never reach Core, ACP, responses, or logs.

Follow-ups

PR 12 may consume only active, non-stale references for Teams cron and must feed
its classified delivery outcomes back into the registry. Later work may add an
operator CRUD/audit interface, encryption or an OS key store, cross-process
locking or a transactional shared database, durable inbound/outbound queues,
persistent bot-owned activity reconciliation, or sovereign-cloud endpoint sets.

At a Glance

Authenticated Teams activity / operator target
                    │
                    ▼
            [this PR’s bounded layer]
                    │
                    ▼
          explicit outcome or fail-closed stop

Prior Art & Industry Research

OpenClaw: its Microsoft Teams extension separates access checks, Bot Framework route context, and outbound operations. For this slice the relevant comparison is persistent Teams conversation context and Gateway-local route storage.

Hermes Agent: its Teams platform adapter keeps Teams-specific transport and message shaping behind a platform adapter. It does not provide OpenAB’s negotiated Core/Gateway outcome contract, so this PR keeps the useful adapter boundary but adds explicit fail-closed semantics.

Proposed Solution

• Add an explicit-path, default-off persistent Teams conversation registry.
• Promote only authenticated routes admitted by Core trust, before turn side effects.
• Use versioned, bounded, atomic JSON with filesystem and lifecycle safeguards.

Why this approach?

Explicit-path opt-in and atomic bounded storage add proactive route authority without changing process-local behavior by default.

Alternatives Considered

Store routes in Core/ACP (rejected: leaks serviceUrl) or enable persistence implicitly (rejected: backward-incompatible authority expansion).

Validation

• cargo test -p openab-gateway --features teams teams_registry::tests (14 passed)
• Core/Gateway compilation
• Helm default-off and explicit-path rendering