# Contract: Secret Management

Version: 1.1

## Purpose

Общие правила, которые предотвращают утечку секретов в git, логи, конфиги, шаблоны и release-артефакты.

## No Secrets In Git

Secrets must never be committed to the repository, even temporarily.

This includes:
- API keys
- access tokens
- passwords
- DSNs with credentials
- private keys
- session secrets
- OAuth client secrets
- `.env` files with real values
- production or staging config files with real credentials

Rules:
- Real secrets must never appear in tracked files, commit history, tags, release assets, examples, fixtures, tests, or docs.
- `.gitignore` is required for runtime config and local secret files, but `.gitignore` alone is not considered sufficient protection.
- Commit only templates and examples with obvious placeholders, for example `CHANGEME`, `example`, or empty strings.
- Never place secrets in screenshots, pasted logs, SQL dumps, backups, or exported archives that could later be committed.

## Where Secrets Live

Rules:
- Store real secrets only in local runtime config, secret stores, environment injection, or deployment-specific configuration outside git.
- Keep committed config files secret-free: `config.example.yaml`, `.env.example`, and similar files must contain placeholders only.
- If a feature requires a new secret, document the config key name and format, not the real value.

## Required Git Checks

Before every commit:
- Verify that files with real secrets are gitignored.
- Inspect staged changes for secrets, not just working tree files.
- Run an automated secret scan against staged content using project tooling or a repository-approved scanner.
- If the scan cannot be run, stop and do not commit until an equivalent staged-content check is performed.

Before every push:
- Scan the commits being pushed for secrets again.
- Refuse the push if any potential secret is detected until it is reviewed and removed.

High-risk patterns that must be checked explicitly:
- PEM blocks (`BEGIN PRIVATE KEY`, `BEGIN OPENSSH PRIVATE KEY`, `BEGIN RSA PRIVATE KEY`)
- tokens in URLs or DSNs
- `password=`, `token=`, `secret=`, `apikey=`, `api_key=`
- cloud credentials
- webhook secrets
- JWT signing keys

## Scheduled Security Audit

Rules:
- Perform a security audit at least once per week.
- At least once per week, scan the git repository for leaked secrets, including current files, staged changes, commit history, and reachable tags.
- Treat weekly secret scanning as mandatory even if pre-commit and pre-push checks already exist.
- If the weekly audit finds a leaked secret, follow the Incident Response rules immediately.

## Logging and Generated Artifacts

Rules:
- Do not print secrets into terminal output, structured logs, panic messages, or debug dumps.
- Do not embed secrets into generated backups, exports, support bundles, or crash reports unless the artifact is explicitly treated as secret operational data and guaranteed to stay outside git.
- If secrets must appear in an operational artifact, that artifact inherits the same "never in git" rule as backups.

## Incident Response

If a secret is committed or pushed:
- Treat it as compromised immediately.
- Rotate or revoke the secret.
- Remove it from the current tree and from any generated artifacts.
- Remove it from all affected commits and from repository history, not just from the latest revision.
- Inform the user that history cleanup may be required.
- Do not claim safety merely because the repo is private.