# Security Policy

`mgf-alembic` is a federation sibling of [`mgf-common`](https://pypi.org/project/mgf-common/),
shipping an async-aware Alembic `env.py` helper
(`configure_env`) — one call replaces the ~40-line
async-alembic boilerplate. A vulnerability here may affect
every consumer that runs migrations via this library, so we
take security reports seriously.

## Supported versions

In the 0.x window, **only the latest MINOR receives security
patches.** Per [SemVer 0.x](https://semver.org/#spec-item-4) and
rule **AP-03** from `mgf-standard/docs/standards/API_DESIGN.md`,
each MINOR release MAY break the public API.

| Version | Supported |
|---------|-----------|
| `0.2.x`  | ✅ — latest MINOR; security patches ship as `0.2.Y` |
| `0.1.x`  | ❌ — superseded by `0.2.x` |

## Reporting a vulnerability

**Please do not open a public issue or pull request** until we have
had a chance to triage and patch.

- **Email:** `bassam@magogi.org` with subject prefix
  `[mgf-alembic security]`.
- **Codeberg private security advisory:** open a private
  vulnerability report at
  [the repository's Security tab](https://codeberg.org/magogi-admin/mgf-alembic/security).

### What to include

- A description of the vulnerability and its impact.
- Steps to reproduce — a minimal failing migration that
  demonstrates the issue is ideal.
- The version(s) of `mgf-alembic`, `mgf-common`,
  `mgf-sqlalchemy`, and `alembic` affected.
- Python version + OS + DB engine + driver versions.

### What to expect

| Stage | Timeline |
|---|---|
| Acknowledgement | within 3 business days |
| Initial assessment + severity rating | within 7 business days |
| Patch + release | within 30 days for high-severity, 90 days for medium |
| Credit + public disclosure | coordinated with the reporter |

90-day default embargo.

## Scope

**In scope:**

- Code in `src/mgf/alembic/` (the published `mgf-alembic`
  package). Specifically: the async-vs-sync URL detection
  (mistakenly routing an async-driver URL through the sync
  path could attempt to run the migration on an unsupported
  connection) and the `include_object` / `include_schemas`
  pass-through (mishandling these could leak un-migrated
  tables into autogenerate output).
- Build / release infrastructure (`pyproject.toml`, the manual
  release flow specified in
  [`mgf-standard/docs/standards/RELEASING.md`](https://codeberg.org/magogi-admin/mgf-standard/src/branch/main/docs/standards/RELEASING.md)).

**Out of scope:**

- Vulnerabilities in `alembic`, `sqlalchemy`, `asyncpg`,
  `psycopg`, or other transitive deps — report to the
  upstream project.
- Vulnerabilities in `mgf-common` itself — report to
  [`mgf-common/SECURITY.md`](https://codeberg.org/magogi-admin/mgf-common/src/branch/main/SECURITY.md).
- Vulnerabilities in `mgf-sqlalchemy` — report to
  [`mgf-sqlalchemy/SECURITY.md`](https://codeberg.org/magogi-admin/mgf-sqlalchemy/src/branch/main/SECURITY.md).
- Consumer-authored migration scripts that contain unsafe SQL
  (DROP TABLE without backup, schema-incompatible changes
  without a backward-compatible window). The library wraps
  alembic's harness; it doesn't review the migrations.

## Hardening recommendations for consumers

- **Backup before `alembic upgrade head` in production.**
  The library doesn't enforce this; the runbook should
  (per **DEP-06** reversible-deploys + **OP-12**
  backup-restore-drill).
- **Run migrations in a transaction.** Alembic does this by
  default for most drivers; verify `transaction_per_migration`
  / `transactional_ddl` semantics for your DB.
- **Naming-convention discipline.** `configure_env`'s
  `naming_convention=` propagates to
  `target_metadata.naming_convention` — set it from day one
  (Postgres-compatible names) so auto-generated constraints
  don't drift between dev / staging / prod.

## A note on the standards

`mgf-alembic` is a **federation sibling** under the
project-shape taxonomy from
[`mgf-standard/docs/standards/DOCUMENTATION.md`](https://codeberg.org/magogi-admin/mgf-standard/src/branch/main/docs/standards/DOCUMENTATION.md) §2.0.
The cross-project engineering standards live in `mgf-common`;
this project inherits them. See
[`docs/standards/README.md`](docs/standards/README.md) for the
pointer.
