OMP Telegram Gateway

Archived reference implementation. This repository documents a security-focused design. It is not a hosted service. It does not maintain vendor integrations.

A single-user Telegram gateway for repository-grounded OMP assistance. It accepts requests from one configured private chat. It reads only allowlisted repositories. It gives the OMP subprocess explicit read-only tools and credentials.

Why this project exists

Repository-aware assistants need access to sensitive source material. This project provides repository context without broad filesystem access. The gateway has no repository Contents-write credential.

The primary design decision is the write boundary:

• The gateway synchronizes allowlisted repositories with read-only deploy keys.
• The OMP child receives only the selected checkout and read, grep, and glob tools.
• A plan can become a draft only after an explicit Telegram confirmation.
• The gateway creates a GitHub Issue request for a confirmed draft.
• An external GitHub Actions workflow owns the separate Contents-write permission.
• The gateway accepts a saved result only when it matches the request and draft digest.
• It also checks the branch, pull request URL, and github-actions[bot] author.

The external Actions workflow is deployment-specific. This repository does not include it. docs/architecture.md documents its protocol and trust boundary.

Architecture

sequenceDiagram
    participant U as Authorized Telegram user
    participant G as Gateway
    participant R as Read-only repository clone
    participant A as Restricted OMP process
    participant I as GitHub Issues API
    participant W as External GitHub Actions workflow

    U->>G: Private chat request
    G->>G: Validate configured user and chat
    G->>R: Fast-forward clean allowlisted clone
    G->>A: Query with selected checkout and read-only tools
    A-->>G: Grounded response with sources
    G-->>U: Response or draft
    U->>G: Confirm draft save
    G->>I: Create or recover digest-bound issue request
    I->>W: Workflow trigger
    W-->>I: Verified result comment and pull request
    G->>I: Validate workflow result
    G-->>U: Saved commit and pull request

Loading

Security properties

Boundary	Control
Telegram caller	One positive TELEGRAM_USER_ID and matching private TELEGRAM_CHAT_ID are required. Group messages stop before side effects.
Repository access	Only configured repositories are cloned. A checkout must be clean, have the expected origin, and stay under the fixed read root.
Git credentials	Each repository uses a read-only deploy key. SSH uses pinned host keys and disables interactive prompts.
OMP subprocess	The child environment is allowlisted. It receives selected model credentials and read-only OMP tools.
Filesystem scope	A policy extension rejects paths, URLs, glob expansion, and symlinks outside the selected checkout.
Write path	The gateway has no Contents-write credential. It validates the request ID, digest, branch, pull request URL, and workflow identity.
Operational state	SQLite records durable jobs and drafts. Voice bytes stay in memory and are not stored in SQLite.

See docs/architecture.md for the trust model and the Issue-mediated write decision.

Local verification

Prerequisites

• Python 3.9 or later
• Git
• Bun for the policy-extension test

python3 -m pip install .
python3 -m unittest discover -s tests -v
python3 scripts/local_smoke.py

The smoke scenario creates temporary Git repositories and a local GitHub Issues server. It exercises text requests and one-shot repository routing. It also exercises voice plans, save confirmation, result verification, and idempotent retry. It verifies that the gateway has no Contents-write credential. It contacts no external service.

GitHub Actions runs the test suite and smoke scenario on Python 3.9 and 3.12. It also scans reachable Git history for secrets.

Deployment reference

deploy/ is a reference installation for a dedicated Debian or Ubuntu host. It supports x86_64 and ARM64. The installer creates a virtual environment, installs this package, pins the OMP checksum, creates a service account, and installs a hardened systemd unit.

Before deployment:

1. Copy the repository registry values to repositories you own.
2. Add read-only deploy keys and the required API credentials outside the checkout.
3. Review the external GitHub Actions workflow that performs the separate Contents-write action.
4. Run gwbot check-config and gwbot bootstrap as the service account.

Do not use sample identifiers, credentials, state databases, or local virtual environments from another installation.

Repository layout

• omp_telegram_gateway/: application, state machine, external API clients, and policy enforcement.
• policy/: OMP extension that constrains read, grep, and glob calls to one checkout.
• config/: read-only OMP policy, prompt, and sanitized repository registry.
• deploy/: Debian or Ubuntu reference installer and systemd unit.
• scripts/local_smoke.py: local end-to-end demonstration.
• tests/: unit and integration-style tests for boundaries, state transitions, and external adapters.

Status and support

This is a frozen portfolio artifact. It has no uptime commitment, support window, or security response SLA. Review dependencies, the workflow contract, and your security requirements before deployment. See SECURITY.md for reporting guidance.

License

Released under the MIT License.