# Discord Dot Bridge

An experimental, owner-only Discord bridge to an **existing ChatGPT dot**.
Use a bot DM or explicit bot mentions in one configured private guild text channel.
MIT licensed. This project is not affiliated with OpenAI or Discord.

**Status:** real Discord Gateway/REST, MCP HTTP, OAuth resource-server, and signed
webhook adapters are implemented and tested against local mock services. A real
ChatGPT account, dot, bot and identity provider have **not** been tested together.
Metadata-only Docker staging is verified; live bridge activation remains pending.
There is no claim of verified end-to-end operation with ChatGPT.

```text
Owner DM -> Discord bot Gateway -> verified owner DM -> SQLite outbox
         -> signed MCP Events callback -> existing dot subscription
         -> OAuth-authenticated discord_reply -> original owner DM
```

The dot supplies the reasoning and existing context. No separate model API,
OpenAI API key, private ChatGPT API, browser scraping, selfbot, or context-export
tool is used. Only the explicit reply text returns to Discord.

## Quick start: local tests

Python 3.12 is the tested runtime. Create and activate a virtual environment, then:

```sh
python -m pip install -r requirements.lock
python -m tests
python -m integration
python -m bridge demo
```

`tests` blocks all sockets and DNS. `integration` permits loopback only: it runs
real local HTTP and WebSocket mock services, real `discord.py` parsing/reconnect,
real JWT validation, signed callback verification, and a real MCP HTTP listener.
Keys generated by integration tests are ephemeral and synthetic. No accounts,
working tokens, external messages, or platform grants are needed.

## Implemented

- Official Discord bot API through `discord.py`: DM intent (4096) by default;
  opt-in guild mention mode uses Guilds + Guild Messages (513), never the privileged
  Message Content intent. Identity, exact destination and fresh channel checks
  reject other guilds/channels, group DMs, threads, non-owner authors and bot echoes.
- Version-specific MCP **2026-07-28** Streamable HTTP JSON responses: stateless
  POST `/mcp`, required metadata/header validation, `server/discover`, tools and
  webhook events. Legacy `initialize`, polling and streaming events are not supported.
- OAuth resource-server verification using PyJWT: RS256 signatures, pinned public
  JWKS file, exact issuer/audience/subject, expiry/not-before and `discord:bridge`
  scope. Protected-resource metadata is exposed for the platform's OAuth discovery.
  An established external identity provider handles login, consent, PKCE and tokens.
- Standard Webhooks library signatures, verification challenges, rotation overlap,
  persistent subscriptions, expiry and idempotent unsubscribe. Event callbacks use
  public-IP validation, pinned-IP TLS with original Host/SNI, and no redirects/proxies.
- Durable inbound deduplication, stable event IDs, bounded retry outbox and fixed
  reply destinations. Duplicate reply calls do not resend. Discord send uncertainty
  remains `unknown`, requiring reconciliation instead of automatic resend.
- Strict configuration validation, secure token-file input, loopback-only listener,
  persistent disable file, bounded serialized worker, and no content/request logs.
- Owner-only `/setup`, `/status`, `/disconnect` commands, restricted to User Install
  and the app DM, with private responses and explicit command registration.
  [Discord setup](docs/DISCORD-SETUP.md) explains their limits.
- A separate [metadata-only setup mode](docs/SETUP-MODE.md) rejects all MCP actions
  while infrastructure is being prepared, without loading Discord credentials.

## Platform prerequisites

OpenAI's [MCP Events guide](https://developers.openai.com/plugins/build/mcp-events)
documents support with dots and MCP 2.0. Availability and workspace permissions
must still be confirmed for each account. See [protocol compatibility](docs/PROTOCOL.md).

Discord's [Gateway documentation](https://docs.discord.com/developers/events/gateway)
documents DM messages and the DM content exception to Message Content intent.
The bridge requests no guild, member, presence or privileged Message Content intent.

## Private setup

Follow [the setup and live acceptance guide](docs/LIVE-PLAN.md). You need an owner
numeric Discord ID, a bot you own, an existing dot with custom MCP Events access,
an OAuth identity provider, and an approved HTTPS endpoint or supported tunnel.
ChatGPT cannot send a custom static API key; the live adapter uses OAuth.
See [provider compatibility options](docs/OAUTH-PROVIDERS.md); no vendor is required.

Copy `config.example.json` to ignored `config.local.json`, replace all synthetic
IDs/hosts and absolute paths, and validate without connecting or reading secrets:

```sh
python -m bridge validate-config --config config.local.json
```

After secure setup and explicit authorization for networking/deployment:

```sh
python -m bridge serve --config config.local.json --enable-network
```

This starts the real bot and loopback MCP service. An approved HTTPS reverse proxy
must reach the listener. The example is Linux-oriented; use absolute Windows paths
when testing there. The enable file must contain exactly `enabled`; changing it
disables new actions and event delivery. Never paste credentials into chat or Git.

## Docker

```sh
docker compose build
docker compose run --rm proof
docker compose run --rm proof python -m integration
```

The included Compose file is a **network-disabled test harness**, not a deployed
service. The image contains the real runtime but defaults to the offline demo.
It runs non-root with a read-only root, dropped capabilities and temporary state.
A production compose/proxy arrangement needs separate review and approval.
Dependencies are version-pinned; pin a verified base-image digest for deployment.

## Limits

Single owner, bot and callback; one worker; text-only messages up to 2000 characters;
30 accepted messages/minute; 1000 retained records; five event attempts; ten-minute
delivery/reply lifetime. Capacity fails closed. No historical replay is advertised.
Attachments, edits and reactions are not forwarded. OAuth access-token expiry caps
subscriptions, so the platform must refresh them. Local public JWKS rotation is
operator-managed. Storage is plaintext under private filesystem permissions.

No lossless delivery or exactly-once guarantee is claimed. See [SECURITY.md](SECURITY.md)
and [validation evidence](docs/VALIDATION.md) for remaining operational limits.

## License and contributions

[MIT](LICENSE). Keep real IDs, secrets, databases, callback URLs and private messages
out of issues, pull requests and fixtures. The CI template uses synthetic data only.
It is supplied at `ci/github-actions.yml` but is **not installed or running**:
the publishing credential lacked GitHub's workflow permission. An authorized
maintainer can copy it to `.github/workflows/test.yml` using suitable access.
Contributions
should preserve the existing-dot design and document any protocol-version changes.