<!-- Copyright (C) 2026 Moko Consulting <hello@mokoconsulting.tech>
SPDX-License-Identifier: GPL-3.0-or-later
DEFGROUP: gitea-api-mcp.Documentation
REPO: https://git.mokoconsulting.tech/MokoConsulting/gitea-api-mcp
-->

# Security Policy

## Supported Versions

| Version | Supported |
|---------|-----------|
| 0.0.x | Yes |

## Reporting a Vulnerability

To report a security vulnerability, please email **hello@mokoconsulting.tech** with the subject line `[SECURITY] gitea-api-mcp`. Do not open a public issue for security vulnerabilities.

We will acknowledge receipt within 48 hours and provide an initial assessment within 5 business days.

## Token Storage Security

### Configuration File

The config file `~/.gitea-api-mcp.json` stores Gitea API tokens in plaintext. Follow these practices to protect your tokens:

#### File Permissions

Set restrictive permissions on the config file so only your user can read it:

```bash
chmod 600 ~/.gitea-api-mcp.json
```

On Windows, ensure the file is only readable by your user account through the file properties security tab.

#### What to Avoid

- **Never** commit `~/.gitea-api-mcp.json` or any file containing tokens to version control
- **Never** share config files containing real tokens
- **Never** log or print token values in debug output
- **Never** store tokens in environment variables visible to other processes if avoidable

#### Token Scope

When generating Gitea access tokens, follow the principle of least privilege:

- Only grant the scopes (permissions) your workflow requires
- Use separate tokens for separate purposes or environments
- Rotate tokens periodically
- Revoke tokens that are no longer needed

#### Token Generation

1. Navigate to your Gitea instance Settings > Applications
2. Under "Manage Access Tokens," enter a token name
3. Select only the required scopes
4. Click "Generate Token"
5. Copy the token immediately -- it will not be shown again

### Network Security

#### TLS Verification

By default, the client verifies TLS certificates. The `insecure: true` option disables certificate verification for self-signed certificates. Use this only for:

- Local development instances
- Internal instances with self-signed certificates where the network is trusted

**Never** use `insecure: true` for production instances accessible over the public internet.

#### API Prefix

All requests are sent to `/api/v1` endpoints with:

- `Authorization: token <your-token>` header
- `Content-Type: application/json` header
- 30-second request timeout

### MCP Transport Security

This server uses stdio transport, meaning it communicates through standard input/output with the MCP client (e.g., Claude Code). The token is never exposed through network ports or HTTP endpoints by the MCP server itself.

## Security Checklist

- [ ] Config file permissions set to `600` (Unix) or user-only (Windows)
- [ ] Tokens scoped to minimum required permissions
- [ ] Config file excluded from version control (`.gitignore`)
- [ ] `insecure` flag only used for trusted internal instances
- [ ] Tokens rotated on a regular schedule
- [ ] Unused tokens revoked promptly