# External AI Ecosystem Gateway

A security-oriented Python gateway that exposes permission-scoped tools to MCP-compatible
assistant clients while mediating access to external systems such as Slack. It demonstrates
tenant isolation, delegated authorization, human confirmation for sensitive writes,
idempotent execution, signed webhook verification, revocation-ready grant storage, and a
hash-chained audit trail.

> This is a portfolio/reference implementation, not a production identity provider. The
> header-based development auth adapter must be replaced by the OIDC validation middleware
> described in `docs/security.md` before deployment.

## Architecture

```text
Assistant / Slack client
          |
          v
  FastAPI edge + auth adapter
          |
          v
 Policy + tenant boundary ----> confirmation tokens
          |
          v
 Sandboxed tool registry -----> Slack / OpenAI / Claude adapters
          |
          +--------------------> idempotency store
          +--------------------> append-only hash-chained audit log
```

## Quick start

```bash
python -m venv .venv
source .venv/bin/activate
pip install -e '.[dev]'
uvicorn ecosystem_gateway.app:app --reload
```

List tools:

```bash
curl localhost:8000/mcp/tools \
  -H 'X-Subject: user-1' -H 'X-Tenant-Id: tenant-a' -H 'X-Roles: operator'
```

Run the test suite with `pytest`. When no Slack token is configured, connectors run in a safe
sandbox mode and return the request they would issue.

## Security properties

- Every principal and idempotency key is tenant-namespaced.
- Tool policies combine least-privilege roles with delegated scopes.
- Sensitive writes require a short-lived token bound to subject, tenant, tool, and arguments.
- Webhook signatures use constant-time comparison and reject stale requests.
- Audit records form a SHA-256 chain so deletion or mutation is detectable.
- OAuth grants support revocation and never expose refresh tokens through tool results.

See [docs/security.md](docs/security.md) for the production hardening checklist and threat model.

## License

MIT