freemygpt 0.1.0__tar.gz

freemygpt-0.1.0/.github/dependabot.yml

@@ -0,0 +1,20 @@
+version: 2
+
+updates:
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+      day: "monday"
+    open-pull-requests-limit: 5
+    commit-message:
+      prefix: "deps"
+
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+      day: "monday"
+    open-pull-requests-limit: 5
+    commit-message:
+      prefix: "ci"

freemygpt-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,43 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    name: test (${{ matrix.os }} / py${{ matrix.python }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+        python: ["3.10", "3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: install uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          version: "0.9.9"
+
+      - name: set up python
+        run: uv python install ${{ matrix.python }}
+
+      - name: install freemygpt with dev extras
+        run: uv pip install --system -e ".[dev]"
+
+      - name: ruff
+        run: uv run --no-sync ruff check src tests
+
+      - name: mypy
+        run: uv run --no-sync mypy src
+
+      - name: pytest
+        run: uv run --no-sync pytest -q

freemygpt-0.1.0/.github/workflows/fork-watch.yml

@@ -0,0 +1,33 @@
+name: fork-watch
+
+# Logs every new fork and every new star to the Actions summary so the
+# maintainer can monitor supply-chain interest and detect suspicious
+# cloning. GitHub already tracks both in the Insights tab — this file
+# makes the same events visible in the notifications feed and produces
+# a job summary for each event.
+
+on:
+  fork:
+  watch:
+    types: [started]
+
+jobs:
+  log-event:
+    runs-on: ubuntu-latest
+    steps:
+      - name: log fork event
+        if: github.event_name == 'fork'
+        run: |
+          echo "## New fork" >> "$GITHUB_STEP_SUMMARY"
+          echo "" >> "$GITHUB_STEP_SUMMARY"
+          echo "- forker: [\`${{ github.event.forkee.owner.login }}\`](${{ github.event.forkee.owner.html_url }})" >> "$GITHUB_STEP_SUMMARY"
+          echo "- new repo: [${{ github.event.forkee.full_name }}](${{ github.event.forkee.html_url }})" >> "$GITHUB_STEP_SUMMARY"
+          echo "- at: \`${{ github.event.forkee.created_at }}\`" >> "$GITHUB_STEP_SUMMARY"
+
+      - name: log star event
+        if: github.event_name == 'watch'
+        run: |
+          echo "## New star" >> "$GITHUB_STEP_SUMMARY"
+          echo "" >> "$GITHUB_STEP_SUMMARY"
+          echo "- user: [\`${{ github.event.sender.login }}\`](${{ github.event.sender.html_url }})" >> "$GITHUB_STEP_SUMMARY"
+          echo "- stargazers now: \`${{ github.event.repository.stargazers_count }}\`" >> "$GITHUB_STEP_SUMMARY"

freemygpt-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,63 @@
+name: release
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  build:
+    name: build wheel + sdist
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: install uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          version: "0.9.9"
+
+      - name: set up python
+        run: uv python install 3.12
+
+      - name: build
+        run: uv build
+
+      - name: upload dist artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/*
+
+  pypi-publish:
+    name: pypi publish
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write  # OIDC trusted publisher
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist
+      - name: publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+  github-release:
+    name: github release
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist
+      - name: create release
+        uses: softprops/action-gh-release@v2
+        with:
+          files: dist/*
+          generate_release_notes: true

freemygpt-0.1.0/.gitignore

@@ -0,0 +1,14 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+dist/
+build/
+*.db
+*.db-journal
+*.sqlite3
+*.sqlite3-journal
+.DS_Store

freemygpt-0.1.0/CHANGELOG.md

@@ -0,0 +1,50 @@
+# Changelog
+
+All notable changes to FreeMyGPT are documented here. The format is
+based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and
+this project adheres to
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] — 2026-04-08
+
+First public alpha. Single flat commit on `main` with the full
+HTTP-to-MCP gateway, two backend adapters, the session store, CLI,
+tests, CI, and release workflow.
+
+### Added
+
+- **FastAPI HTTP gateway** with GET-only endpoints so ChatGPT's
+  built-in browse tool (which cannot emit POST requests or custom
+  headers) can drive local MCP servers without any Custom GPT Action,
+  OpenAPI spec, or GitHub plugin.
+- **Two backend adapters** behind a shared `Backend` Protocol:
+  - `McpStdioBackend` — wraps the official `mcp` Python SDK
+    `stdio_client` + `ClientSession` so any stdio MCP server can be
+    exposed through the HTTP surface
+  - `CodexBackend` — bundled subprocess wrapper that spawns
+    `codex exec <prompt>` and exposes a single synthetic `chat` tool
+    so Codex looks like any other MCP backend from the HTTP side
+- **Bearer token auth** — required on every endpoint except
+  `/healthz`, accepted via `?token=` query param (for ChatGPT browse)
+  or `Authorization: Bearer` header, compared in constant time via
+  `hmac.compare_digest`
+- **Refusal to start unauthenticated** — gateway raises at startup if
+  `FREEMYGPT_TOKEN` is unset
+- **Thread-safe SQLite session store** with WAL mode and RLock
+  serialization so FastAPI worker threads can share one connection
+- **YAML config file** at `~/.freemygpt/config.yaml` mapping backend
+  names to launchers, with per-backend env and timeout overrides
+- **CLI**: `freemygpt serve | doctor | new-token`
+- **Tests**: 16 passing (config loader + full HTTP app with a fake
+  backend swapped in for the factory)
+- **CI**: ruff, mypy `--strict`, pytest on macOS + Ubuntu across
+  Python 3.10 / 3.11 / 3.12
+- **Release workflow**: tag-triggered wheel build, PyPI publish via
+  OIDC trusted publisher, and GitHub release creation
+- **Security posture**: `SECURITY.md` with private disclosure via
+  GitHub advisories, `CODEOWNERS`, Dependabot weekly updates,
+  `fork-watch` workflow that logs every fork and star to the Actions
+  summary, branch protection on `main` blocking force pushes and
+  deletions with linear history required

freemygpt-0.1.0/CODEOWNERS

@@ -0,0 +1,7 @@
+# Every path in this repository is owned by the repository maintainer.
+# GitHub auto-requests review from CODEOWNERS on every pull request.
+#
+# Maintainer: Michael Adam Groberman
+#   GitHub:   https://github.com/MichaelAdamGroberman
+#   LinkedIn: https://www.linkedin.com/in/michael-adam-groberman/
+* @MichaelAdamGroberman

freemygpt-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 FreeMyGPT contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

freemygpt-0.1.0/PKG-INFO

@@ -0,0 +1,166 @@
+Metadata-Version: 2.4
+Name: freemygpt
+Version: 0.1.0
+Summary: FreeMyGPT — HTTP gateway that lets ChatGPT (and any LLM) drive any local MCP server via simple GET requests. Hybrid: MCP stdio backends by default, Codex CLI and other runtimes via bundled adapters.
+Project-URL: Homepage, https://github.com/MichaelAdamGroberman/FreeMyGPT
+Project-URL: Issues, https://github.com/MichaelAdamGroberman/FreeMyGPT/issues
+Author: FreeMyGPT contributors
+License: MIT
+License-File: LICENSE
+Keywords: bridge,chatgpt,claude,codex,freemygpt,gateway,mcp,openai
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: FastAPI
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: <3.13,>=3.10
+Requires-Dist: fastapi<0.120,>=0.115
+Requires-Dist: httpx<1.0,>=0.28
+Requires-Dist: mcp<2.0,>=1.26.0
+Requires-Dist: pyyaml<7.0,>=6.0
+Requires-Dist: uvicorn[standard]<0.40,>=0.32
+Provides-Extra: dev
+Requires-Dist: mypy>=1.13; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest>=8.3; extra == 'dev'
+Requires-Dist: ruff>=0.8; extra == 'dev'
+Requires-Dist: types-pyyaml>=6.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# FreeMyGPT
+
+> **Free ChatGPT from its sandbox.** FreeMyGPT is a tiny HTTP gateway that lets ChatGPT (and any other LLM with an HTTP fetcher) drive **any local MCP server** — Gr0m_Mem, Codex CLI, Kali MCP, Home Assistant MCP, or anything else that speaks the Model Context Protocol — using nothing but **simple GET requests**. No Custom GPT Actions, no GitHub plugin, no OAuth dance, no POST bodies.
+
+```
+ChatGPT  ──GET──►  FreeMyGPT  ──stdio──►  MCP server (any)
+                                  └─────►  Codex CLI (subprocess)
+```
+
+## Why
+
+- ChatGPT's built-in browse tool can **read URLs** but cannot send POST requests or custom headers. Everyone else's "let ChatGPT call your API" guide assumes Custom GPT Actions. FreeMyGPT assumes you do not have that option.
+- Local MCP servers are powerful (Gr0m_Mem, the Kali server, Home Assistant, Codex) but they only speak stdio. They cannot be reached from a ChatGPT conversation by default.
+- FreeMyGPT is the thinnest possible layer between them: a FastAPI app that spawns each MCP server on first use, forwards `call_tool` requests, and returns the result as JSON in the HTTP response. Bearer token auth via `?token=…` query param so ChatGPT can pass it without setting headers.
+
+## Architecture
+
+- **HTTP frontend** (FastAPI, stdio) — GET-only, JSON responses
+- **Hybrid backends**:
+  - `mcp` — any stdio MCP server (official `mcp` Python SDK client)
+  - `codex` — bundled wrapper that spawns `codex exec <prompt>` and exposes a single `chat` tool, so Codex looks like any other MCP backend from the HTTP side
+- **Bearer token auth** — required on every endpoint except `/healthz`, read from an env var, matched in constant time
+- **Session store** — SQLite; stores chat transcripts so ChatGPT can poll long-running sessions without losing history
+- **One config file** — YAML with an `auth` block and a `backends` map; see `config.example.yaml`
+
+## HTTP surface
+
+```
+GET /healthz                                        (no auth)
+GET /backends                                       ?token=...
+GET /{backend}/tools                                ?token=...
+GET /{backend}/call/{tool}                          ?token=...&arg1=...&arg2=...
+GET /{backend}/sessions/new                         ?token=...&label=...
+GET /{backend}/sessions/{sid}/send                  ?token=...&message=...
+GET /{backend}/sessions/{sid}/poll                  ?token=...&since=<id>
+GET /{backend}/sessions/{sid}/close                 ?token=...
+```
+
+**Tool arguments** are passed as query parameters. Simple scalars (strings, ints, floats, bools) are coerced automatically. For structured arguments, pass them as a JSON blob in `args_json`:
+
+```
+GET /gr0m_mem/call/mem_record_decision?token=...&args_json={"subject":"db","decision":"Postgres","rationale":"concurrent writes"}
+```
+
+## Quick start
+
+```bash
+pip install freemygpt
+
+# 1. Make a token
+export FREEMYGPT_TOKEN="$(freemygpt new-token)"
+
+# 2. Write a config
+mkdir -p ~/.freemygpt
+cp $(python -c "import freemygpt, os; print(os.path.join(os.path.dirname(freemygpt.__file__), '..', '..', 'config.example.yaml'))") ~/.freemygpt/config.yaml
+# edit to enable the backends you want
+
+# 3. Sanity check
+freemygpt doctor
+
+# 4. Run
+freemygpt serve --host 127.0.0.1 --port 8933
+```
+
+## Exposing it to ChatGPT
+
+ChatGPT needs to reach the gateway over the public internet. Pick any reverse tunnel:
+
+### Option A — Cloudflare Tunnel (recommended, free, no account required for quick tunnels)
+
+```bash
+brew install cloudflared
+cloudflared tunnel --url http://127.0.0.1:8933
+```
+
+Cloudflared prints a `https://<random>.trycloudflare.com` URL. Paste it into your ChatGPT conversation with the token appended:
+
+```
+https://<random>.trycloudflare.com/gr0m_mem/call/mem_wakeup?token=<your token>
+```
+
+ChatGPT will browse the URL and inline the JSON response.
+
+### Option B — Tailscale Funnel
+
+If your machine is already on Tailscale, enable Funnel on port 8933 and use the `*.ts.net` hostname. Token auth still applies.
+
+### Option C — ngrok
+
+```bash
+ngrok http 8933
+```
+
+Same idea.
+
+## Using it from a ChatGPT conversation
+
+Once the URL is live and the token is in the query string, a ChatGPT conversation looks like:
+
+> **You:** Fetch `https://tunnel.example.com/gr0m_mem/call/mem_wakeup?token=XYZ` and summarize the response.
+>
+> **ChatGPT:** *(browses the URL, receives the JSON snapshot)* You're Michael, a software engineer on macOS; active project is the FreeMyGPT launch; recent decisions locked in: Postgres for the database (concurrent writes), Clerk over Auth0 (better DX), SQLite FTS5 is the zero-dep default for Gr0m_Mem.
+
+Because the responses are plain JSON, any LLM with an HTTP fetcher (Claude browsing, Gemini's `google_search_retrieval`, local Llama with a URL-fetching tool, etc.) can use the exact same URLs.
+
+## Security posture
+
+- Bearer token required on every authenticated endpoint, compared in constant time
+- Gateway refuses to start if the configured env var is empty
+- Every backend runs as a subprocess of the gateway — no network listener exposed
+- Session state in SQLite with `PRAGMA foreign_keys=ON`; sessions delete their messages on close
+- `SECURITY.md` documents private vulnerability reporting via GitHub advisories
+- Branch protection on every long-lived branch (no force pushes, no deletions, linear history)
+- CI runs ruff, mypy `--strict`, and the full test suite on every push
+
+See [`SECURITY.md`](SECURITY.md) for the full disclosure policy and out-of-scope list.
+
+## Status
+
+v0.1.0 alpha. API surface is stable; the wire format (`{"text": ..., "structured": ..., "is_error": ...}`) is not expected to change. Breaking changes will bump the minor version until v1.0.
+
+## License
+
+MIT — see [LICENSE](LICENSE).
+
+## Contact
+
+Maintained by **Michael Adam Groberman**.
+
+- **GitHub**: [@MichaelAdamGroberman](https://github.com/MichaelAdamGroberman)
+- **LinkedIn**: [michael-adam-groberman](https://www.linkedin.com/in/michael-adam-groberman/)
+
+For security reports, use GitHub private vulnerability advisories (see [SECURITY.md](SECURITY.md)) — **do not** use LinkedIn DMs for sensitive disclosures.

freemygpt-0.1.0/README.md

@@ -0,0 +1,133 @@
+# FreeMyGPT
+
+> **Free ChatGPT from its sandbox.** FreeMyGPT is a tiny HTTP gateway that lets ChatGPT (and any other LLM with an HTTP fetcher) drive **any local MCP server** — Gr0m_Mem, Codex CLI, Kali MCP, Home Assistant MCP, or anything else that speaks the Model Context Protocol — using nothing but **simple GET requests**. No Custom GPT Actions, no GitHub plugin, no OAuth dance, no POST bodies.
+
+```
+ChatGPT  ──GET──►  FreeMyGPT  ──stdio──►  MCP server (any)
+                                  └─────►  Codex CLI (subprocess)
+```
+
+## Why
+
+- ChatGPT's built-in browse tool can **read URLs** but cannot send POST requests or custom headers. Everyone else's "let ChatGPT call your API" guide assumes Custom GPT Actions. FreeMyGPT assumes you do not have that option.
+- Local MCP servers are powerful (Gr0m_Mem, the Kali server, Home Assistant, Codex) but they only speak stdio. They cannot be reached from a ChatGPT conversation by default.
+- FreeMyGPT is the thinnest possible layer between them: a FastAPI app that spawns each MCP server on first use, forwards `call_tool` requests, and returns the result as JSON in the HTTP response. Bearer token auth via `?token=…` query param so ChatGPT can pass it without setting headers.
+
+## Architecture
+
+- **HTTP frontend** (FastAPI, stdio) — GET-only, JSON responses
+- **Hybrid backends**:
+  - `mcp` — any stdio MCP server (official `mcp` Python SDK client)
+  - `codex` — bundled wrapper that spawns `codex exec <prompt>` and exposes a single `chat` tool, so Codex looks like any other MCP backend from the HTTP side
+- **Bearer token auth** — required on every endpoint except `/healthz`, read from an env var, matched in constant time
+- **Session store** — SQLite; stores chat transcripts so ChatGPT can poll long-running sessions without losing history
+- **One config file** — YAML with an `auth` block and a `backends` map; see `config.example.yaml`
+
+## HTTP surface
+
+```
+GET /healthz                                        (no auth)
+GET /backends                                       ?token=...
+GET /{backend}/tools                                ?token=...
+GET /{backend}/call/{tool}                          ?token=...&arg1=...&arg2=...
+GET /{backend}/sessions/new                         ?token=...&label=...
+GET /{backend}/sessions/{sid}/send                  ?token=...&message=...
+GET /{backend}/sessions/{sid}/poll                  ?token=...&since=<id>
+GET /{backend}/sessions/{sid}/close                 ?token=...
+```
+
+**Tool arguments** are passed as query parameters. Simple scalars (strings, ints, floats, bools) are coerced automatically. For structured arguments, pass them as a JSON blob in `args_json`:
+
+```
+GET /gr0m_mem/call/mem_record_decision?token=...&args_json={"subject":"db","decision":"Postgres","rationale":"concurrent writes"}
+```
+
+## Quick start
+
+```bash
+pip install freemygpt
+
+# 1. Make a token
+export FREEMYGPT_TOKEN="$(freemygpt new-token)"
+
+# 2. Write a config
+mkdir -p ~/.freemygpt
+cp $(python -c "import freemygpt, os; print(os.path.join(os.path.dirname(freemygpt.__file__), '..', '..', 'config.example.yaml'))") ~/.freemygpt/config.yaml
+# edit to enable the backends you want
+
+# 3. Sanity check
+freemygpt doctor
+
+# 4. Run
+freemygpt serve --host 127.0.0.1 --port 8933
+```
+
+## Exposing it to ChatGPT
+
+ChatGPT needs to reach the gateway over the public internet. Pick any reverse tunnel:
+
+### Option A — Cloudflare Tunnel (recommended, free, no account required for quick tunnels)
+
+```bash
+brew install cloudflared
+cloudflared tunnel --url http://127.0.0.1:8933
+```
+
+Cloudflared prints a `https://<random>.trycloudflare.com` URL. Paste it into your ChatGPT conversation with the token appended:
+
+```
+https://<random>.trycloudflare.com/gr0m_mem/call/mem_wakeup?token=<your token>
+```
+
+ChatGPT will browse the URL and inline the JSON response.
+
+### Option B — Tailscale Funnel
+
+If your machine is already on Tailscale, enable Funnel on port 8933 and use the `*.ts.net` hostname. Token auth still applies.
+
+### Option C — ngrok
+
+```bash
+ngrok http 8933
+```
+
+Same idea.
+
+## Using it from a ChatGPT conversation
+
+Once the URL is live and the token is in the query string, a ChatGPT conversation looks like:
+
+> **You:** Fetch `https://tunnel.example.com/gr0m_mem/call/mem_wakeup?token=XYZ` and summarize the response.
+>
+> **ChatGPT:** *(browses the URL, receives the JSON snapshot)* You're Michael, a software engineer on macOS; active project is the FreeMyGPT launch; recent decisions locked in: Postgres for the database (concurrent writes), Clerk over Auth0 (better DX), SQLite FTS5 is the zero-dep default for Gr0m_Mem.
+
+Because the responses are plain JSON, any LLM with an HTTP fetcher (Claude browsing, Gemini's `google_search_retrieval`, local Llama with a URL-fetching tool, etc.) can use the exact same URLs.
+
+## Security posture
+
+- Bearer token required on every authenticated endpoint, compared in constant time
+- Gateway refuses to start if the configured env var is empty
+- Every backend runs as a subprocess of the gateway — no network listener exposed
+- Session state in SQLite with `PRAGMA foreign_keys=ON`; sessions delete their messages on close
+- `SECURITY.md` documents private vulnerability reporting via GitHub advisories
+- Branch protection on every long-lived branch (no force pushes, no deletions, linear history)
+- CI runs ruff, mypy `--strict`, and the full test suite on every push
+
+See [`SECURITY.md`](SECURITY.md) for the full disclosure policy and out-of-scope list.
+
+## Status
+
+v0.1.0 alpha. API surface is stable; the wire format (`{"text": ..., "structured": ..., "is_error": ...}`) is not expected to change. Breaking changes will bump the minor version until v1.0.
+
+## License
+
+MIT — see [LICENSE](LICENSE).
+
+## Contact
+
+Maintained by **Michael Adam Groberman**.
+
+- **GitHub**: [@MichaelAdamGroberman](https://github.com/MichaelAdamGroberman)
+- **LinkedIn**: [michael-adam-groberman](https://www.linkedin.com/in/michael-adam-groberman/)
+
+For security reports, use GitHub private vulnerability advisories (see [SECURITY.md](SECURITY.md)) — **do not** use LinkedIn DMs for sensitive disclosures.

freemygpt-0.1.0/SECURITY.md

@@ -0,0 +1,70 @@
+# Security Policy
+
+## Supported versions
+
+FreeMyGPT is in `0.1.x` alpha. Only the latest tagged release on `main`
+receives security fixes.
+
+| Branch  | Status  | Fixes |
+|---------|---------|-------|
+| `main`  | current | ✅    |
+| earlier | n/a     | ❌    |
+
+## Reporting a vulnerability
+
+**Please do not open a public issue for security reports.** Instead:
+
+1. Open a GitHub **private vulnerability report** via the "Report a
+   vulnerability" button on the Security tab:
+   <https://github.com/MichaelAdamGroberman/FreeMyGPT/security/advisories/new>
+2. Or email the maintainer directly (see GitHub profile).
+
+Include:
+
+- The affected version and commit SHA
+- A minimal reproduction (the exact request sequence that demonstrates
+  the issue)
+- Impact — what data, state, or capability an attacker could gain
+
+You will receive an initial response within 72 hours. Fixes for
+confirmed vulnerabilities are prioritized; credit is given by default
+unless you request anonymity.
+
+## Scope
+
+In scope:
+
+- Authentication bypasses (missing / weak / timing-sensitive token
+  checks on any authenticated endpoint)
+- Command injection through query parameters into subprocess backends
+  (the Codex backend and any `mcp` backend that forwards arguments to
+  a child process)
+- Session-state leakage between tenants
+- Denial of service from an unauthenticated caller (authenticated DoS
+  is out of scope — bring your own rate limiter)
+- Supply chain issues in the build and release workflows
+
+Out of scope:
+
+- Attacks that require an attacker already on the same machine with
+  read access to `~/.freemygpt/sessions.db`
+- Vulnerabilities in the backends themselves (the MCP server or the
+  Codex CLI) — report those upstream
+- Misconfigurations (missing token, exposed port) — the gateway
+  refuses to start without a token but cannot defend against a user
+  deliberately binding it to `0.0.0.0` behind no firewall
+
+## Hardening applied by default
+
+- Bearer token required on every endpoint except `/healthz`; compared
+  in constant time via `hmac.compare_digest`
+- The gateway raises at startup if the token env var is unset
+- Every subprocess backend inherits a scrubbed environment (only the
+  keys explicitly listed in the config's `env` block plus the
+  process's own environment) — no secret leakage via child env
+- Session-owned SQLite databases enable `foreign_keys=ON` and
+  `journal_mode=WAL` and cascade-delete messages when a session closes
+- Branch protection on `main` blocks force pushes, deletions, and
+  non-linear history; code owner reviews required on every PR
+- Secret scanning + push protection + Dependabot security updates
+  enabled on the repository

freemygpt-0.1.0/config.example.yaml

@@ -0,0 +1,39 @@
+# FreeMyGPT — example config
+#
+# Copy this file to ~/.freemygpt/config.yaml and edit it, or set
+# FREEMYGPT_CONFIG to point at a different location. The bridge refuses
+# to start if no config is found or no backends are defined.
+
+auth:
+  # Bearer token required on every authenticated request. Generate a
+  # fresh one with:
+  #     freemygpt new-token
+  # and export it in the environment before running `freemygpt serve`:
+  #     export FREEMYGPT_TOKEN="<value>"
+  token_env: FREEMYGPT_TOKEN
+
+backends:
+  # Example 1: the Gr0m_Mem persistent memory brain over stdio MCP.
+  # Install Gr0m_Mem first: pip install gr0m-mem
+  gr0m_mem:
+    type: mcp
+    command: python
+    args: ["-m", "gr0m_mem.mcp_server"]
+
+  # Example 2: OpenAI Codex CLI as a single `chat` tool. The bridge
+  # spawns `codex exec <message>` per call. Adjust the args if your
+  # local Codex binary uses a different calling convention.
+  codex:
+    type: codex
+    command: codex
+    args: ["exec"]
+    default_timeout_s: 300
+
+  # Example 3: any other stdio MCP server — Kali tools, Home Assistant,
+  # your own project — just point `command` + `args` at the launcher.
+  # kali:
+  #   type: mcp
+  #   command: /usr/local/bin/kali-mcp
+  #   args: []
+  #   env:
+  #     KALI_HOST: 10.0.0.29