harden transport security and finalize v1.2 docs

Author: Traves-Theberge

.dockerignore

@@ -0,0 +1,14 @@
+.git
+.github
+node_modules
+npm-debug.log
+data
+config
+.wwebjs_auth
+docs
+tests
+coverage
+*.db
+*.sqlite
+*.sqlite-shm
+*.sqlite-wal

.env.docker.example

@@ -0,0 +1,22 @@
+# OpenCode server endpoint (usually running on host)
+OPENCODE_SERVER_URL=http://host.docker.internal:4096
+
+# Persistent DB path inside container
+STORAGE_DB_PATH=/app/data/opencode-remote.db
+
+# Required owner identity
+SECURITY_OWNER_NUMBER=+15551234567
+
+# Telegram config
+TELEGRAM_ENABLED=true
+TELEGRAM_BOT_TOKEN=replace-with-real-token
+TELEGRAM_OWNER_USER_ID=123456789
+TELEGRAM_POLLING_ENABLED=true
+TELEGRAM_WEBHOOK_ENABLED=false
+
+# Optional webhook profile values
+# TELEGRAM_WEBHOOK_URL=https://your-domain.example/telegram/webhook
+# TELEGRAM_WEBHOOK_SECRET=replace-with-random-secret
+
+# Keep default lightweight image path (disable WhatsApp runtime in container)
+WHATSAPP_ENABLED=false

.gitignore

@@ -1,9 +1,17 @@
 node_modules/
 .wwebjs_auth/
 data/
+config/
+.env
+.env.*
+!.env.docker.example
 *.log
 *.db
 *.sqlite
 *.sqlite3
 *.db-shm
 *.db-wal
+*.db-journal
+npm-debug.log*
+yarn-error.log*
+pnpm-debug.log*

CHANGELOG.md

@@ -6,7 +6,21 @@ All notable changes to this project are documented in this file.
 
 ### Added
 
-- Quality hardening follow-up plan: `docs/plans/2026-03-01-quality-hardening-followup-plan.md`.
+- Docker runtime support:
+  - `Dockerfile`
+  - `docker-compose.yml`
+  - `docker-compose.webhook.yml`
+  - `.dockerignore`
+  - `.env.docker.example`
+- Telegram UX + reliability overhaul plan: `docs/plans/2026-03-02-telegram-ux-reliability-overhaul-plan.md`.
+- Formatter regression test for prompt event-envelope filtering: `tests/formatter.test.ts`.
+- Storage lease coverage for transport single-instance behavior: `tests/storage.test.ts` lease test.
+- File-by-file audit checklist: `docs/plans/2026-03-02-file-audit-checklist.md`.
+- Security review register: `docs/SECURITY_REVIEW.md`.
+- Security/remediation backlog register: `TOFIX.md`.
+- Security redaction utility for audit/dead-letter storage: `src/security/redaction.ts`.
+- CLI security posture helper: `security rotate-token-check`.
+- Release notes for hardened release: `RELEASE_NOTES_v1.2.0.md`.
 - Architecture diagram set under `docs/architecture/`:
   - system/context/container/component
   - interaction sequences
@@ -101,6 +115,24 @@ All notable changes to this project are documented in this file.
 
 ### Changed
 
+- Chat command UX now supports slash commands and natural language without requiring `@oc` prefix (legacy prefix still accepted).
+- Help output is redesigned into a concise, task-oriented menu with command descriptions.
+- Telegram input normalization now maps plain shorthand (status/help/runs/sessions/diff/abort/pwd) to slash commands.
+- Telegram polling conflict handling now applies controlled backoff with degraded-state visibility.
+- Runtime `/status` output now includes transport health and polling conflict recovery timing.
+- SQLite schema now includes transport lease support (`transport_leases`) to protect polling ownership on shared DB deployments.
+- Webhook mode now fails fast unless `telegram.webhookSecret` is configured.
+- Bridge/TUI status views now surface Telegram polling degraded state, conflict count, and retry timing.
+- App ingress now enforces global and per-sender token-bucket throttling with `ingress.throttled` audit events.
+- Startup validation now supports env-only secret mode (`security.requireEnvTokens`) and placeholder-token warnings.
+- SQLite audit and dead-letter writes now redact token/secret/bearer-like values before persistence.
+- Removed dead code: `src/audit/logger.ts` and unused `OpenCodeAdapter.server` field.
+- Package versions bumped for release alignment:
+  - root `opencode-remote` -> `1.2.0`
+  - workspaces (`daemon`, `cli`, `tui`, `bridge`) -> `0.2.0`
+- `/opencode diagnostics` now includes runtime transport and lease status snapshot.
+- Documentation updated for prefix-optional command model and webhook-first production profile.
+- TSDoc coverage expanded across runtime, transport, bridge, and CLI/TUI entry modules.
 - Root TypeScript strict mode is re-enabled with passing project and workspace checks.
 - Lint pipeline now targets TypeScript across root and workspace code:
   - `src/**/*.ts`, `tests/**/*.ts`, `apps/**/*.ts`, `packages/**/*.ts`

Dockerfile

@@ -0,0 +1,25 @@
+FROM node:20-bookworm-slim
+
+WORKDIR /app
+
+ENV PUPPETEER_SKIP_DOWNLOAD=true
+
+# better-sqlite3 may need native build tooling during install.
+RUN apt-get update \
+  && apt-get install -y --no-install-recommends python3 make g++ \
+  && rm -rf /var/lib/apt/lists/*
+
+COPY package.json package-lock.json ./
+COPY apps ./apps
+COPY packages ./packages
+COPY scripts ./scripts
+COPY src ./src
+COPY tsconfig.json ./
+
+RUN npm ci
+
+ENV XDG_CONFIG_HOME=/app/config
+
+RUN mkdir -p /app/data /app/config /app/.wwebjs_auth
+
+CMD ["npm", "start"]

README.md

@@ -5,7 +5,7 @@ OpenCode Remote is a local-first control layer for OpenCode with dual transport
 - WhatsApp (`whatsapp-web.js`)
 - Telegram (Bot API)
 
-It routes chat input into a deterministic command model (`@oc`) and persists control-plane state in SQLite.
+It routes chat input into a deterministic command model (slash commands + natural language) and persists control-plane state in SQLite.
 
 Implementation is TypeScript-first (`src/**/*.ts`, `tests/**/*.ts`) with strict mode enabled and zero explicit `any` usage.
 
@@ -29,7 +29,7 @@ Request flow:
 1. Transport receives message/update
 2. App builds a composite dedupe key (`channel:sender:transport_message_id`)
 3. Access controller validates allowlist/role
-4. Router parses `@oc` prompt or slash command
+4. Router parses prompt or slash command
 5. Safety engine enforces guardrails
 6. Executor calls OpenCode adapter
 7. Response returns via originating transport
@@ -44,7 +44,60 @@ Request flow:
 
 ## Quick Start
 
-Install from curl (fresh machine):
+### Local (recommended)
+
+Start OpenCode server first (required):
+
+```bash
+opencode serve --hostname 127.0.0.1 --port 4096
+```
+
+In a second terminal, install and run setup:
+
+```bash
+npm install
+npm run cli -- setup
+npm start
+```
+
+### Docker (lightweight, Telegram-first)
+
+The Docker image is optimized for lightweight operation and disables WhatsApp by default.
+
+1) Start OpenCode server on the host:
+
+```bash
+opencode serve --hostname 127.0.0.1 --port 4096
+```
+
+2) Configure docker env:
+
+```bash
+cp .env.docker.example .env
+```
+
+3) Edit `.env` with your owner number and Telegram bot token.
+
+4) Start:
+
+```bash
+docker compose up --build -d
+docker compose logs -f remote
+```
+
+Webhook-first production profile:
+
+```bash
+docker compose -f docker-compose.yml -f docker-compose.webhook.yml up -d --build
+```
+
+Token hygiene:
+
+- If a token is exposed, rotate it in `@BotFather` and update `.env`.
+- Polling with one bot token supports one active consumer.
+- Run posture check: `npm run cli -- security rotate-token-check`
+
+Install from curl (fresh local machine):
 
 ```bash
 curl -fsSL https://raw.githubusercontent.com/Traves-Theberge/opencode-remote/master/scripts/install.sh | bash
@@ -82,6 +135,28 @@ npm start
 
 Then pair WhatsApp from QR (if enabled), and message your Telegram bot.
 
+## Environment Overrides
+
+Config values can be overridden with environment variables using uppercase key names.
+
+Examples:
+
+```bash
+OPENCODE_SERVER_URL=http://127.0.0.1:4096
+WHATSAPP_ENABLED=false
+TELEGRAM_ENABLED=true
+TELEGRAM_BOT_TOKEN=replace-with-real-token
+TELEGRAM_OWNER_USER_ID=123456789
+SECURITY_OWNER_NUMBER=+15551234567
+STORAGE_DB_PATH=./data/opencode-remote.db
+```
+
+Notes:
+
+- `TELEGRAM_OWNER_USER_ID` auto-binds owner access on startup.
+- Telegram polling supports one active consumer per bot token. Use a single running instance for a token.
+- Set `SECURITY_REQUIRE_ENV_TOKENS=true` to force env-only secret loading and reject persisted plaintext token config.
+
 ## Monorepo Layout
 
 - `apps/daemon/` - workspace-native daemon entrypoint
@@ -149,62 +224,68 @@ npx conf set telegram.webhookSecret "<random-secret>"
 
 If both are enabled, webhook mode takes precedence and polling is skipped with a warning.
 
+When polling is used, OpenCode Remote reports polling conflict backoff in `/status` to make collisions visible.
+
 ## Security Defaults
 
 - Telegram group chats blocked by default (`telegram.allowGroupChats=false`)
 - Telegram retry controls are transport-specific:
   - `telegram.messageMaxRetries`
   - `telegram.messageRetryDelayMs`
+- Ingress rate limiting enabled with token-bucket controls:
+  - `security.ingressPerSenderPerMinute`
+  - `security.ingressGlobalPerMinute`
+  - `security.ingressBurst`
 - Dangerous commands require explicit confirmation
 
 ## Command Model
 
-- `@oc <text>`: pass-through prompt
-- `@oc /<command>`: control-plane command
+- `<text>`: pass-through prompt
+- `/<command>`: control-plane command
 
 Telegram normalization:
 
-- Plain text is normalized to `@oc <text>`
-- Supported Telegram slash aliases are normalized to shared `@oc` commands
+- Plain text shorthand is normalized to slash commands where available (`status`, `help`, `runs`, `sessions`, ...)
+- Other plain text is treated as prompt input
 
 Common commands:
 
-- `@oc /status`
-- `@oc /session list`
-- `@oc /run <command>`
-- `@oc /shell <command>`
-- `@oc /runs`
-- `@oc /get <runId>`
+- `/status`
+- `/session list`
+- `/run <command>`
+- `/shell <command>`
+- `/runs`
+- `/get <runId>`
 
 Advanced control-plane namespaces:
 
-- `@oc /model status`
-- `@oc /model list`
-- `@oc /model set <providerId> <modelId>`
-- `@oc /tools ids`
-- `@oc /tools list [providerId] [modelId]`
-- `@oc /mcp status`
-- `@oc /mcp add <name> <command>`
-- `@oc /mcp connect <server>`
-- `@oc /mcp disconnect <server>`
-- `@oc /skills list`
-- `@oc /opencode status`
-- `@oc /opencode providers`
-- `@oc /opencode commands`
-- `@oc /opencode diagnostics`
+- `/model status`
+- `/model list`
+- `/model set <providerId> <modelId>`
+- `/tools ids`
+- `/tools list [providerId] [modelId]`
+- `/mcp status`
+- `/mcp add <name> <command>`
+- `/mcp connect <server>`
+- `/mcp disconnect <server>`
+- `/skills list`
+- `/opencode status`
+- `/opencode providers`
+- `/opencode commands`
+- `/opencode diagnostics`
 
 Permission/safety policy matrix is documented in `docs/COMMAND_MODEL.md`.
 
 Admin commands:
 
-- `@oc /users list`
-- `@oc /users add <+number>`
-- `@oc /users remove <+number>`
-- `@oc /users bindtg <telegramUserId> <+number> [username]`
-- `@oc /users unbindtg <telegramUserId>`
-- `@oc /users tglist`
-- `@oc /lock`
-- `@oc /unlock`
+- `/users list`
+- `/users add <+number>`
+- `/users remove <+number>`
+- `/users bindtg <telegramUserId> <+number> [username]`
+- `/users unbindtg <telegramUserId>`
+- `/users tglist`
+- `/lock`
+- `/unlock`
 
 ## Data and Reliability
 
@@ -260,3 +341,4 @@ npm run verify
 - `docs/OPERATIONS.md`
 - `docs/ONBOARDING.md`
 - `CHANGELOG.md`
+- `TOFIX.md`

RELEASE_NOTES_v1.1.0.md

@@ -33,15 +33,15 @@ v1.1.0 upgrades OpenCode Remote from a prototype-grade runtime to a durable loca
 npx conf set security.ownerNumber "+15551234567"
 ```
 
-5. Confirm health with WhatsApp command `@oc /status`.
+5. Confirm health with command `/status`.
 
 ## Verification Checklist
 
 - [ ] OpenCode server reachable from app host
 - [ ] WhatsApp QR pairing succeeds
-- [ ] `@oc /status` returns online state
-- [ ] `@oc /session list` returns session metadata
-- [ ] `@oc /runs` and `@oc /get <id>` work
+- [ ] `/status` returns online state
+- [ ] `/session list` returns session metadata
+- [ ] `/runs` and `/get <id>` work
 - [ ] Permission prompt events appear and accept `/allow` or `/deny`
 
 ## Known Limitations