fromscratch-pycrypt 0.2.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- fromscratch_pycrypt-0.2.0/.github/workflows/ci.yml +14 -0
- fromscratch_pycrypt-0.2.0/.github/workflows/docs.yml +16 -0
- fromscratch_pycrypt-0.2.0/.github/workflows/release.yml +58 -0
- fromscratch_pycrypt-0.2.0/.gitignore +14 -0
- fromscratch_pycrypt-0.2.0/.pre-commit-config.yaml +56 -0
- fromscratch_pycrypt-0.2.0/CLAUDE.md +53 -0
- fromscratch_pycrypt-0.2.0/CONTRIBUTING.md +199 -0
- fromscratch_pycrypt-0.2.0/LICENSE +21 -0
- fromscratch_pycrypt-0.2.0/PKG-INFO +225 -0
- fromscratch_pycrypt-0.2.0/README.md +193 -0
- fromscratch_pycrypt-0.2.0/conftest.py +21 -0
- fromscratch_pycrypt-0.2.0/docs/concepts/caesar.md +48 -0
- fromscratch_pycrypt-0.2.0/docs/concepts/hashing.md +46 -0
- fromscratch_pycrypt-0.2.0/docs/concepts/hmac.md +51 -0
- fromscratch_pycrypt-0.2.0/docs/concepts/key-derivation.md +57 -0
- fromscratch_pycrypt-0.2.0/docs/concepts/signatures.md +68 -0
- fromscratch_pycrypt-0.2.0/docs/concepts/xor.md +66 -0
- fromscratch_pycrypt-0.2.0/docs/index.md +67 -0
- fromscratch_pycrypt-0.2.0/docs/property-testing.md +235 -0
- fromscratch_pycrypt-0.2.0/mkdocs.yml +81 -0
- fromscratch_pycrypt-0.2.0/overrides/main.html +7 -0
- fromscratch_pycrypt-0.2.0/pyproject.toml +158 -0
- fromscratch_pycrypt-0.2.0/src/pycrypt/__init__.py +1 -0
- fromscratch_pycrypt-0.2.0/src/pycrypt/_version.py +24 -0
- fromscratch_pycrypt-0.2.0/src/pycrypt/caesar.py +76 -0
- fromscratch_pycrypt-0.2.0/src/pycrypt/cli.py +71 -0
- fromscratch_pycrypt-0.2.0/src/pycrypt/errors.py +13 -0
- fromscratch_pycrypt-0.2.0/src/pycrypt/hashing.py +56 -0
- fromscratch_pycrypt-0.2.0/src/pycrypt/hmac.py +67 -0
- fromscratch_pycrypt-0.2.0/src/pycrypt/kdf.py +49 -0
- fromscratch_pycrypt-0.2.0/src/pycrypt/py.typed +0 -0
- fromscratch_pycrypt-0.2.0/src/pycrypt/signatures.py +63 -0
- fromscratch_pycrypt-0.2.0/src/pycrypt/xor.py +80 -0
- fromscratch_pycrypt-0.2.0/tests/__init__.py +1 -0
- fromscratch_pycrypt-0.2.0/tests/test_caesar.py +87 -0
- fromscratch_pycrypt-0.2.0/tests/test_cli.py +13 -0
- fromscratch_pycrypt-0.2.0/tests/test_hashing.py +73 -0
- fromscratch_pycrypt-0.2.0/tests/test_hmac.py +75 -0
- fromscratch_pycrypt-0.2.0/tests/test_kdf.py +57 -0
- fromscratch_pycrypt-0.2.0/tests/test_properties.py +177 -0
- fromscratch_pycrypt-0.2.0/tests/test_signatures.py +61 -0
- fromscratch_pycrypt-0.2.0/tests/test_xor.py +92 -0
- fromscratch_pycrypt-0.2.0/uv.lock +920 -0
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
name: Deploy Docs
|
|
2
|
+
|
|
3
|
+
on:
|
|
4
|
+
push:
|
|
5
|
+
branches: [main]
|
|
6
|
+
workflow_dispatch: {}
|
|
7
|
+
|
|
8
|
+
jobs:
|
|
9
|
+
docs:
|
|
10
|
+
uses: robcox2910/robcox2910.github.io/.github/workflows/docs.yml@v1
|
|
11
|
+
permissions:
|
|
12
|
+
contents: read
|
|
13
|
+
pages: write
|
|
14
|
+
id-token: write
|
|
15
|
+
with:
|
|
16
|
+
coverage-report: false
|
|
@@ -0,0 +1,58 @@
|
|
|
1
|
+
name: Release
|
|
2
|
+
|
|
3
|
+
on:
|
|
4
|
+
push:
|
|
5
|
+
tags:
|
|
6
|
+
- "v*.*.*"
|
|
7
|
+
|
|
8
|
+
permissions:
|
|
9
|
+
contents: write
|
|
10
|
+
id-token: write
|
|
11
|
+
|
|
12
|
+
jobs:
|
|
13
|
+
build:
|
|
14
|
+
runs-on: ubuntu-latest
|
|
15
|
+
steps:
|
|
16
|
+
- uses: actions/checkout@v7
|
|
17
|
+
with:
|
|
18
|
+
fetch-depth: 0
|
|
19
|
+
|
|
20
|
+
- name: Install uv
|
|
21
|
+
uses: astral-sh/setup-uv@v7
|
|
22
|
+
with:
|
|
23
|
+
version: "latest"
|
|
24
|
+
|
|
25
|
+
- name: Set up Python
|
|
26
|
+
run: uv python install 3.14
|
|
27
|
+
|
|
28
|
+
- name: Build distributions
|
|
29
|
+
run: uv build
|
|
30
|
+
|
|
31
|
+
- name: Upload build artifacts
|
|
32
|
+
uses: actions/upload-artifact@v7
|
|
33
|
+
with:
|
|
34
|
+
name: dist
|
|
35
|
+
path: dist/
|
|
36
|
+
|
|
37
|
+
- name: Upload to GitHub Release
|
|
38
|
+
uses: softprops/action-gh-release@v3
|
|
39
|
+
with:
|
|
40
|
+
files: dist/*
|
|
41
|
+
|
|
42
|
+
publish:
|
|
43
|
+
needs: build
|
|
44
|
+
runs-on: ubuntu-latest
|
|
45
|
+
environment:
|
|
46
|
+
name: pypi
|
|
47
|
+
url: https://pypi.org/project/fromscratch-pycrypt/
|
|
48
|
+
permissions:
|
|
49
|
+
id-token: write
|
|
50
|
+
steps:
|
|
51
|
+
- name: Download build artifacts
|
|
52
|
+
uses: actions/download-artifact@v8
|
|
53
|
+
with:
|
|
54
|
+
name: dist
|
|
55
|
+
path: dist/
|
|
56
|
+
|
|
57
|
+
- name: Publish to PyPI
|
|
58
|
+
uses: pypa/gh-action-pypi-publish@release/v1
|
|
@@ -0,0 +1,56 @@
|
|
|
1
|
+
default_language_version:
|
|
2
|
+
python: python3.14
|
|
3
|
+
|
|
4
|
+
repos:
|
|
5
|
+
- repo: https://github.com/pre-commit/pre-commit-hooks
|
|
6
|
+
rev: v5.0.0
|
|
7
|
+
hooks:
|
|
8
|
+
# Pages paste real pytest output, trailing spaces included.
|
|
9
|
+
- id: trailing-whitespace
|
|
10
|
+
exclude: ^docs/property-testing\.md$
|
|
11
|
+
- id: end-of-file-fixer
|
|
12
|
+
exclude: ^docs/property-testing\.md$
|
|
13
|
+
- id: check-yaml
|
|
14
|
+
args: ['--unsafe']
|
|
15
|
+
- id: check-added-large-files
|
|
16
|
+
- id: check-json
|
|
17
|
+
- id: check-toml
|
|
18
|
+
- id: check-merge-conflict
|
|
19
|
+
- id: debug-statements
|
|
20
|
+
|
|
21
|
+
- repo: https://github.com/astral-sh/ruff-pre-commit
|
|
22
|
+
rev: v0.15.4
|
|
23
|
+
hooks:
|
|
24
|
+
- id: ruff
|
|
25
|
+
args: [--fix, --exit-non-zero-on-fix]
|
|
26
|
+
- id: ruff-format
|
|
27
|
+
|
|
28
|
+
- repo: https://github.com/RobertCraigie/pyright-python
|
|
29
|
+
rev: v1.1.408
|
|
30
|
+
hooks:
|
|
31
|
+
- id: pyright
|
|
32
|
+
|
|
33
|
+
- repo: local
|
|
34
|
+
hooks:
|
|
35
|
+
- id: pip-audit
|
|
36
|
+
name: pip-audit
|
|
37
|
+
language: system
|
|
38
|
+
pass_filenames: false
|
|
39
|
+
files: ^(pyproject\.toml|uv\.lock)$
|
|
40
|
+
entry: >-
|
|
41
|
+
bash -c 'f=$(mktemp) &&
|
|
42
|
+
uv export --frozen --no-emit-project --all-extras --no-hashes -o "$f" >/dev/null &&
|
|
43
|
+
uvx pip-audit==2.10.0 -r "$f" --disable-pip --no-deps;
|
|
44
|
+
status=$?; rm -f "$f"; exit $status'
|
|
45
|
+
|
|
46
|
+
- repo: https://github.com/rhysd/actionlint
|
|
47
|
+
rev: v1.7.7
|
|
48
|
+
hooks:
|
|
49
|
+
- id: actionlint
|
|
50
|
+
|
|
51
|
+
- repo: https://github.com/commitizen-tools/commitizen
|
|
52
|
+
rev: v4.13.8
|
|
53
|
+
hooks:
|
|
54
|
+
- id: commitizen
|
|
55
|
+
stages: [commit-msg]
|
|
56
|
+
additional_dependencies: [typing_extensions]
|
|
@@ -0,0 +1,53 @@
|
|
|
1
|
+
# Claude Code Instructions
|
|
2
|
+
|
|
3
|
+
<!-- standard:start -->
|
|
4
|
+
## Code Style
|
|
5
|
+
|
|
6
|
+
- All public functions, methods, classes, and modules **must** have a docstring
|
|
7
|
+
- Use imperative mood: "Return the result." not "Returns the result."
|
|
8
|
+
- One-line docstrings for simple functions; multi-line with summary + details for complex ones
|
|
9
|
+
- Follow the Google docstring convention (D211, D212 selected via ruff)
|
|
10
|
+
|
|
11
|
+
## Linting
|
|
12
|
+
|
|
13
|
+
- Ruff enforces a comprehensive rule set -- run `uv run ruff check .` before committing
|
|
14
|
+
- Pyright runs in strict mode -- run `uv run pyright src tests` before committing
|
|
15
|
+
- All violations must be fixed, not ignored. Exceptions are the repo-owned `ignore` and `per-file-ignores` lists in `pyproject.toml`, which belong to this repo; the series sync never edits them
|
|
16
|
+
|
|
17
|
+
## Testing
|
|
18
|
+
|
|
19
|
+
- TDD workflow: Red-Green-Refactor
|
|
20
|
+
- Coverage is enforced by pytest-cov; the floor in `pyproject.toml` is repo-owned
|
|
21
|
+
- Test classes and methods also require docstrings
|
|
22
|
+
- Use named constants instead of magic values (PLR2004)
|
|
23
|
+
- Run `uv run pytest` before committing
|
|
24
|
+
- Property-based tests (Hypothesis) live in `tests/test_properties.py` and `tests/test_model.py`; the shared profiles are in the root `conftest.py` (owned by `series sync`). Run `uv run pytest --hypothesis-profile=thorough` before a release.
|
|
25
|
+
|
|
26
|
+
## Commits
|
|
27
|
+
|
|
28
|
+
- Use conventional commits: `feat:`, `fix:`, `refactor:`, `test:`, `docs:`, `ci:`, `chore:`
|
|
29
|
+
- All changes go via PR from a feature branch (main is protected); merge when CI is green
|
|
30
|
+
|
|
31
|
+
## Dependencies
|
|
32
|
+
|
|
33
|
+
- Package manager: uv
|
|
34
|
+
- Run `uv sync --all-extras` after modifying dependencies
|
|
35
|
+
- `uv.lock` is committed; CI and pre-commit audit it with pip-audit through `uvx`, so pip-audit is not a project dependency
|
|
36
|
+
- Sibling projects, where used, are pinned release tags in `[tool.uv.sources]` (git + tag); never use `path` sources
|
|
37
|
+
|
|
38
|
+
## Releasing
|
|
39
|
+
|
|
40
|
+
- A release is a `vX.Y.Z` tag on main after the PR is merged
|
|
41
|
+
- Docs-only and tooling-only changes do not get a release tag
|
|
42
|
+
- Docs are built with `mkdocs build --strict` and deployed to GitHub Pages by the docs workflow
|
|
43
|
+
<!-- standard:end -->
|
|
44
|
+
|
|
45
|
+
## Project notes
|
|
46
|
+
|
|
47
|
+
- Use imperative mood: "Return the response." not "Returns the response."
|
|
48
|
+
- Pyright in strict mode -- run `uv run pyright src tests` before committing
|
|
49
|
+
- All violations must be fixed, not ignored (except D203/D213 incompatible pair)
|
|
50
|
+
- Minimum 80% coverage enforced by pytest-cov
|
|
51
|
+
- Use conventional commits (enforced by commitizen): `feat:`, `fix:`, `refactor:`, `test:`, `docs:`, `ci:`, `chore:`
|
|
52
|
+
- All changes go via PR from a feature branch (main is protected)
|
|
53
|
+
- Add production deps to `[project.dependencies]`
|
|
@@ -0,0 +1,199 @@
|
|
|
1
|
+
# Contributing to PyCrypt
|
|
2
|
+
|
|
3
|
+
Thanks for your interest in contributing! This guide covers everything you need
|
|
4
|
+
to get started.
|
|
5
|
+
|
|
6
|
+
## Prerequisites
|
|
7
|
+
|
|
8
|
+
| Tool | Version | Install |
|
|
9
|
+
|------|---------|---------|
|
|
10
|
+
| Python | 3.14+ | [python.org](https://www.python.org/downloads/) |
|
|
11
|
+
| uv | latest | `curl -LsSf https://astral.sh/uv/install.sh \| sh` |
|
|
12
|
+
| git | 2.x+ | [git-scm.com](https://git-scm.com/) |
|
|
13
|
+
|
|
14
|
+
## Setup
|
|
15
|
+
|
|
16
|
+
```bash
|
|
17
|
+
# Clone the repo
|
|
18
|
+
git clone https://github.com/robcox2910/pycrypt.git
|
|
19
|
+
cd pycrypt
|
|
20
|
+
|
|
21
|
+
# Install all dependencies (including dev tools)
|
|
22
|
+
uv sync --all-extras
|
|
23
|
+
|
|
24
|
+
# Install pre-commit hooks (linting + commit message validation)
|
|
25
|
+
uv run pre-commit install
|
|
26
|
+
uv run pre-commit install --hook-type commit-msg
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
Verify everything works:
|
|
30
|
+
|
|
31
|
+
```bash
|
|
32
|
+
uv run pytest --cov # tests pass, >= 80% coverage
|
|
33
|
+
uv run ruff check src/ tests/ # no lint errors
|
|
34
|
+
uv run pyright src tests # no type errors
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
## TDD Workflow
|
|
38
|
+
|
|
39
|
+
We follow **Red-Green-Refactor** for every code change:
|
|
40
|
+
|
|
41
|
+
1. **Red** -- Write a failing test that describes the behaviour you want.
|
|
42
|
+
2. **Green** -- Write the simplest code that makes the test pass.
|
|
43
|
+
3. **Refactor** -- Clean up while keeping all tests green.
|
|
44
|
+
|
|
45
|
+
Never skip the red step. If you can't write a failing test first, take a moment
|
|
46
|
+
to think about what the code should actually do.
|
|
47
|
+
|
|
48
|
+
## Branch Naming
|
|
49
|
+
|
|
50
|
+
Create a branch from `main` using one of these prefixes:
|
|
51
|
+
|
|
52
|
+
| Prefix | When to use |
|
|
53
|
+
|--------|-------------|
|
|
54
|
+
| `feat/` | New cryptography feature or algorithm |
|
|
55
|
+
| `fix/` | Bug fix |
|
|
56
|
+
| `refactor/` | Restructuring without behaviour change |
|
|
57
|
+
| `test/` | Test-only changes |
|
|
58
|
+
| `docs/` | Documentation updates |
|
|
59
|
+
| `ci/` | CI/CD workflow changes |
|
|
60
|
+
| `chore/` | Dependency bumps, config tweaks |
|
|
61
|
+
|
|
62
|
+
Example: `feat/aes-encryption`, `fix/hmac-verification`
|
|
63
|
+
|
|
64
|
+
## Conventional Commits
|
|
65
|
+
|
|
66
|
+
Every commit message must follow [Conventional Commits](https://www.conventionalcommits.org/):
|
|
67
|
+
|
|
68
|
+
```
|
|
69
|
+
<type>: <short description in imperative mood>
|
|
70
|
+
|
|
71
|
+
Optional longer explanation.
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
Types match the branch prefixes: `feat:`, `fix:`, `refactor:`, `test:`,
|
|
75
|
+
`docs:`, `ci:`, `chore:`.
|
|
76
|
+
|
|
77
|
+
Good examples:
|
|
78
|
+
|
|
79
|
+
```
|
|
80
|
+
feat: add XOR cipher encryption
|
|
81
|
+
fix: resolve HMAC key encoding issue
|
|
82
|
+
docs: add Caesar cipher concept page
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
Bad examples:
|
|
86
|
+
|
|
87
|
+
```
|
|
88
|
+
updated stuff # no type, vague description
|
|
89
|
+
feat: adds hashing # not imperative mood ("adds" -> "add")
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+
## Code Style
|
|
93
|
+
|
|
94
|
+
### Modern Python
|
|
95
|
+
|
|
96
|
+
Use Python 3.14 idioms everywhere:
|
|
97
|
+
|
|
98
|
+
- `X | Y` for union types (not `Union[X, Y]` or `Optional[X]`)
|
|
99
|
+
- `StrEnum` for string enumerations
|
|
100
|
+
- `match/case` instead of if/elif chains where appropriate
|
|
101
|
+
- Direct imports: `from enum import StrEnum` not `import enum`
|
|
102
|
+
|
|
103
|
+
### Docstrings
|
|
104
|
+
|
|
105
|
+
Every public function, method, class, and module needs a docstring:
|
|
106
|
+
|
|
107
|
+
- Use **imperative mood**: "Return the record." not "Returns the record."
|
|
108
|
+
- One-liner for simple functions, multi-line (Google style) for complex ones.
|
|
109
|
+
|
|
110
|
+
```python
|
|
111
|
+
def sha256(data: str) -> str:
|
|
112
|
+
"""Calculate the SHA-256 hash of a string."""
|
|
113
|
+
|
|
114
|
+
def derive_key(
|
|
115
|
+
password: str,
|
|
116
|
+
salt: bytes | None = None,
|
|
117
|
+
) -> tuple[bytes, bytes]:
|
|
118
|
+
"""Derive a cryptographic key from a password.
|
|
119
|
+
|
|
120
|
+
Args:
|
|
121
|
+
password: The password to derive from.
|
|
122
|
+
salt: Random salt bytes (generated if not provided).
|
|
123
|
+
|
|
124
|
+
Returns:
|
|
125
|
+
A tuple of (derived_key, salt).
|
|
126
|
+
|
|
127
|
+
Raises:
|
|
128
|
+
ValueError: If the password is empty.
|
|
129
|
+
"""
|
|
130
|
+
```
|
|
131
|
+
|
|
132
|
+
### Named Constants
|
|
133
|
+
|
|
134
|
+
Use named constants instead of magic numbers in tests and source code. Ruff
|
|
135
|
+
rule PLR2004 enforces this.
|
|
136
|
+
|
|
137
|
+
```python
|
|
138
|
+
# Good
|
|
139
|
+
SHA256_HEX_LENGTH = 64
|
|
140
|
+
assert len(result) == SHA256_HEX_LENGTH
|
|
141
|
+
|
|
142
|
+
# Bad
|
|
143
|
+
assert len(result) == 64
|
|
144
|
+
```
|
|
145
|
+
|
|
146
|
+
## Linting and Type Checking
|
|
147
|
+
|
|
148
|
+
Run these before every commit (pre-commit hooks enforce them automatically):
|
|
149
|
+
|
|
150
|
+
```bash
|
|
151
|
+
uv run ruff check src/ tests/ # lint
|
|
152
|
+
uv run ruff format src/ tests/ # format (or --check to verify)
|
|
153
|
+
uv run pyright src tests # type check (strict mode)
|
|
154
|
+
```
|
|
155
|
+
|
|
156
|
+
Fix all violations. Inline `# noqa:` is acceptable only when tools genuinely
|
|
157
|
+
conflict (e.g., ARG002 vs pyright protocol parameter names).
|
|
158
|
+
|
|
159
|
+
## Testing
|
|
160
|
+
|
|
161
|
+
```bash
|
|
162
|
+
uv run pytest # run all tests
|
|
163
|
+
uv run pytest --cov # with coverage report
|
|
164
|
+
uv run pytest tests/test_x.py # run a specific file
|
|
165
|
+
uv run pytest -k "test_name" # run tests matching a pattern
|
|
166
|
+
```
|
|
167
|
+
|
|
168
|
+
- Minimum **80% coverage** is enforced.
|
|
169
|
+
- Test classes and methods need docstrings too.
|
|
170
|
+
- Use `pytest.raises` as a context manager for exception testing.
|
|
171
|
+
|
|
172
|
+
## Documentation Style
|
|
173
|
+
|
|
174
|
+
Our docs target a **12-year-old with an interest in computing**. Keep language
|
|
175
|
+
simple, use analogies, and avoid jargon without explanation.
|
|
176
|
+
|
|
177
|
+
Good:
|
|
178
|
+
|
|
179
|
+
> A hash is like a meat grinder: put any data in, get a fixed-size fingerprint
|
|
180
|
+
> out. You can't reverse it, but the same input always gives the same result.
|
|
181
|
+
|
|
182
|
+
Bad:
|
|
183
|
+
|
|
184
|
+
> A cryptographic hash function is a deterministic one-way mapping from an
|
|
185
|
+
> arbitrary-length input domain to a fixed-length output codomain.
|
|
186
|
+
|
|
187
|
+
## Pull Request Process
|
|
188
|
+
|
|
189
|
+
1. Create a feature branch from `main`.
|
|
190
|
+
2. Make your changes following TDD.
|
|
191
|
+
3. Ensure all checks pass: `uv run ruff check .`, `uv run pyright src tests`,
|
|
192
|
+
`uv run pytest --cov`.
|
|
193
|
+
4. Push your branch and open a PR against `main`.
|
|
194
|
+
5. PRs are squash-merged to keep history clean.
|
|
195
|
+
|
|
196
|
+
## Questions?
|
|
197
|
+
|
|
198
|
+
Open an issue on [GitHub](https://github.com/robcox2910/pycrypt/issues) --
|
|
199
|
+
we're happy to help!
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Rob Cox
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1,225 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: fromscratch-pycrypt
|
|
3
|
+
Version: 0.2.0
|
|
4
|
+
Summary: An educational cryptography library built from scratch in Python
|
|
5
|
+
Project-URL: Homepage, https://github.com/robcox2910/pycrypt
|
|
6
|
+
Project-URL: Repository, https://github.com/robcox2910/pycrypt
|
|
7
|
+
Project-URL: Issues, https://github.com/robcox2910/pycrypt/issues
|
|
8
|
+
Project-URL: Documentation, https://robcox2910.github.io/pycrypt/
|
|
9
|
+
Author: Rob Cox
|
|
10
|
+
License: MIT
|
|
11
|
+
License-File: LICENSE
|
|
12
|
+
Keywords: cryptography,education,encryption,hashing
|
|
13
|
+
Classifier: Development Status :: 3 - Alpha
|
|
14
|
+
Classifier: Intended Audience :: Education
|
|
15
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
16
|
+
Classifier: Programming Language :: Python :: 3
|
|
17
|
+
Classifier: Programming Language :: Python :: 3.14
|
|
18
|
+
Classifier: Topic :: Education
|
|
19
|
+
Classifier: Topic :: Security :: Cryptography
|
|
20
|
+
Classifier: Typing :: Typed
|
|
21
|
+
Requires-Python: >=3.14
|
|
22
|
+
Provides-Extra: dev
|
|
23
|
+
Requires-Dist: commitizen>=4.4.0; extra == 'dev'
|
|
24
|
+
Requires-Dist: hypothesis>=6.170; extra == 'dev'
|
|
25
|
+
Requires-Dist: pip-audit>=2.10.0; extra == 'dev'
|
|
26
|
+
Requires-Dist: pre-commit>=4.0.1; extra == 'dev'
|
|
27
|
+
Requires-Dist: pyright>=1.1.400; extra == 'dev'
|
|
28
|
+
Requires-Dist: pytest-cov>=6.0.0; extra == 'dev'
|
|
29
|
+
Requires-Dist: pytest>=8.3.4; extra == 'dev'
|
|
30
|
+
Requires-Dist: ruff>=0.9.3; extra == 'dev'
|
|
31
|
+
Description-Content-Type: text/markdown
|
|
32
|
+
|
|
33
|
+
# PyCrypt
|
|
34
|
+
|
|
35
|
+
**An educational cryptography library in plain Python.** The classic
|
|
36
|
+
ciphers (Caesar, XOR) are built from scratch; the modern primitives
|
|
37
|
+
(SHA-256, HMAC, PBKDF2) wrap Python's battle-tested `hashlib`/`hmac`
|
|
38
|
+
standard library so you can see how the pieces fit together.
|
|
39
|
+
|
|
40
|
+
> ⚠️ **For LEARNING, not real security.** The Caesar and XOR ciphers
|
|
41
|
+
> and the homemade-style signatures here are easy to break. Never use
|
|
42
|
+
> PyCrypt to protect real passwords, messages, or secrets -- use a
|
|
43
|
+
> vetted library like `cryptography` for that.
|
|
44
|
+
|
|
45
|
+
## What Is Cryptography?
|
|
46
|
+
|
|
47
|
+
Imagine you want to pass a secret note to your friend in class, but you don't
|
|
48
|
+
want anyone else to read it. You could write it in a secret code that only you
|
|
49
|
+
and your friend understand. That's cryptography!
|
|
50
|
+
|
|
51
|
+
Cryptography is the science of keeping information secret and safe. It's used
|
|
52
|
+
every time you:
|
|
53
|
+
|
|
54
|
+
- Send a text message
|
|
55
|
+
- Log in to a website
|
|
56
|
+
- Pay for something online
|
|
57
|
+
- Download an app
|
|
58
|
+
|
|
59
|
+
PyCrypt teaches you how all of this works by building each piece from scratch.
|
|
60
|
+
|
|
61
|
+
## Examples
|
|
62
|
+
|
|
63
|
+
### Hashing -- One-Way Fingerprints
|
|
64
|
+
|
|
65
|
+
A hash turns any text into a fixed-size "fingerprint." You can't reverse it,
|
|
66
|
+
but the same input always gives the same fingerprint.
|
|
67
|
+
|
|
68
|
+
```python
|
|
69
|
+
from pycrypt.hashing import sha256
|
|
70
|
+
|
|
71
|
+
# Same input always gives the same hash
|
|
72
|
+
print(sha256("hello")) # "2cf24dba5fb0a30e..."
|
|
73
|
+
print(sha256("hello")) # "2cf24dba5fb0a30e..." (identical!)
|
|
74
|
+
|
|
75
|
+
# Even a tiny change makes a completely different hash
|
|
76
|
+
print(sha256("Hello")) # "185f8db32271fe25..." (totally different!)
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
### Caesar Cipher -- The Secret Decoder Ring
|
|
80
|
+
|
|
81
|
+
Shift every letter by a number. A becomes D (shift 3), B becomes E, and so on.
|
|
82
|
+
It wraps around, so Z becomes C.
|
|
83
|
+
|
|
84
|
+
```python
|
|
85
|
+
from pycrypt.caesar import encrypt, decrypt, brute_force
|
|
86
|
+
|
|
87
|
+
secret = encrypt("HELLO WORLD", shift=3)
|
|
88
|
+
print(secret) # "KHOOR ZRUOG"
|
|
89
|
+
|
|
90
|
+
original = decrypt(secret, shift=3)
|
|
91
|
+
print(original) # "HELLO WORLD"
|
|
92
|
+
|
|
93
|
+
# Try all 26 possible shifts to crack it!
|
|
94
|
+
for shift, text in brute_force(secret):
|
|
95
|
+
print(f"Shift {shift}: {text}")
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
### XOR Cipher -- Flipping Switches
|
|
99
|
+
|
|
100
|
+
XOR is its own inverse -- encrypt and decrypt use the exact same operation.
|
|
101
|
+
Real ciphers like AES use XOR inside, but a short repeating key like ours is
|
|
102
|
+
easy to break -- **for learning only**.
|
|
103
|
+
|
|
104
|
+
```python
|
|
105
|
+
from pycrypt.xor import xor_encrypt, xor_encrypt_bytes
|
|
106
|
+
|
|
107
|
+
encrypted = xor_encrypt("secret message", key="mykey")
|
|
108
|
+
print(encrypted) # looks like random bytes
|
|
109
|
+
|
|
110
|
+
# Decrypt by XOR-ing again with the same key
|
|
111
|
+
decrypted = xor_encrypt_bytes(encrypted, b"mykey").decode("utf-8")
|
|
112
|
+
print(decrypted) # "secret message"
|
|
113
|
+
```
|
|
114
|
+
|
|
115
|
+
### HMAC -- Tamper-Evident Seals
|
|
116
|
+
|
|
117
|
+
HMAC is like a wax seal on an envelope. If someone changes the message, the
|
|
118
|
+
seal breaks.
|
|
119
|
+
|
|
120
|
+
```python
|
|
121
|
+
from pycrypt.hmac import hmac_sign, hmac_verify
|
|
122
|
+
|
|
123
|
+
tag = hmac_sign("transfer $10", key="shared-secret")
|
|
124
|
+
print(hmac_verify("transfer $10", tag, key="shared-secret")) # True
|
|
125
|
+
print(hmac_verify("transfer $1000", tag, key="shared-secret")) # False!
|
|
126
|
+
```
|
|
127
|
+
|
|
128
|
+
### Digital Signatures -- A Shared Wax Seal
|
|
129
|
+
|
|
130
|
+
A digital signature proves who wrote a message and that it hasn't been
|
|
131
|
+
changed. Our version is like a wax seal that only you and your friend
|
|
132
|
+
know how to make: you both share one secret key, and that same key is
|
|
133
|
+
used to sign *and* to verify. (Real systems like RSA use a separate
|
|
134
|
+
private key to sign and a public key anyone can verify with.)
|
|
135
|
+
|
|
136
|
+
```python
|
|
137
|
+
import os
|
|
138
|
+
from pycrypt.signatures import sign, verify
|
|
139
|
+
|
|
140
|
+
# You and your friend share this one secret key.
|
|
141
|
+
key = os.urandom(32)
|
|
142
|
+
|
|
143
|
+
signature = sign("I wrote this!", key)
|
|
144
|
+
print(verify("I wrote this!", signature, key)) # True
|
|
145
|
+
print(verify("I didn't write this", signature, key)) # False
|
|
146
|
+
```
|
|
147
|
+
|
|
148
|
+
## Features
|
|
149
|
+
|
|
150
|
+
- **Hashing** -- SHA-256 and MD5 fingerprints
|
|
151
|
+
- **Caesar Cipher** -- Shift-based encryption with brute-force cracking
|
|
152
|
+
- **XOR Cipher** -- Symmetric encryption using bitwise XOR
|
|
153
|
+
- **Key Derivation** -- Turn passwords into strong keys with PBKDF2
|
|
154
|
+
- **HMAC** -- Tamper-proof message authentication codes
|
|
155
|
+
- **Digital Signatures** -- Sign and verify messages with a shared secret key
|
|
156
|
+
- **CLI Tool** -- A demo that prints hashing, Caesar, XOR, and HMAC examples
|
|
157
|
+
- **100% Typed** -- Full type annotations with strict Pyright checking
|
|
158
|
+
|
|
159
|
+
## Quick Start
|
|
160
|
+
|
|
161
|
+
```bash
|
|
162
|
+
# Install with uv
|
|
163
|
+
uv add pycrypt
|
|
164
|
+
|
|
165
|
+
# Or install from source
|
|
166
|
+
git clone https://github.com/robcox2910/pycrypt.git
|
|
167
|
+
cd pycrypt
|
|
168
|
+
uv sync --all-extras
|
|
169
|
+
|
|
170
|
+
# Run the CLI demo
|
|
171
|
+
uv run pycrypt
|
|
172
|
+
|
|
173
|
+
# Run the tests
|
|
174
|
+
uv run pytest
|
|
175
|
+
```
|
|
176
|
+
|
|
177
|
+
<!-- docs:start -->
|
|
178
|
+
## Documentation
|
|
179
|
+
|
|
180
|
+
Full docs (with kid-friendly explanations of every idea): https://robcox2910.github.io/pycrypt/
|
|
181
|
+
<!-- docs:end -->
|
|
182
|
+
|
|
183
|
+
## Releasing
|
|
184
|
+
|
|
185
|
+
Other projects in the series ([PyStack](https://github.com/robcox2910/pystack)) use a pinned release of this one,
|
|
186
|
+
not whatever is on `main`. To publish a change for them:
|
|
187
|
+
|
|
188
|
+
1. Merge the change to `main`.
|
|
189
|
+
2. Tag it: `git tag -a vX.Y.Z -m vX.Y.Z && git push origin vX.Y.Z`.
|
|
190
|
+
A change to the public API bumps the minor version (`v0.1.0` → `v0.2.0`);
|
|
191
|
+
anything else bumps the patch (`v0.1.0` → `v0.1.1`).
|
|
192
|
+
3. In each project that uses it, edit the tag in `[tool.uv.sources]`, run
|
|
193
|
+
`uv lock --upgrade-package <name>`, and open a pull request so CI checks
|
|
194
|
+
the pair together.
|
|
195
|
+
|
|
196
|
+
<!-- series:start -->
|
|
197
|
+
## Related Projects
|
|
198
|
+
|
|
199
|
+
This project is one of a series that builds real systems "from scratch in Python" to teach how they work. See the [series home](https://robcox2910.github.io/) for the full story.
|
|
200
|
+
|
|
201
|
+
| Project | What it teaches | Repository | Docs |
|
|
202
|
+
| --- | --- | --- | --- |
|
|
203
|
+
| PyOS | Operating systems | [py-os](https://github.com/robcox2910/py-os) | [Docs](https://robcox2910.github.io/py-os/) |
|
|
204
|
+
| Pebble | Compilers and programming languages | [pebble-lang](https://github.com/robcox2910/pebble-lang) | [Docs](https://robcox2910.github.io/pebble-lang/) |
|
|
205
|
+
| PyDB | Relational databases | [pydb](https://github.com/robcox2910/pydb) | [Docs](https://robcox2910.github.io/pydb/) |
|
|
206
|
+
| PyKV | Key-value stores | [pykv](https://github.com/robcox2910/pykv) | [Docs](https://robcox2910.github.io/pykv/) |
|
|
207
|
+
| PyDocDB | Document databases | [pydoc-db](https://github.com/robcox2910/pydoc-db) | [Docs](https://robcox2910.github.io/pydoc-db/) |
|
|
208
|
+
| PyGraphDB | Graph databases | [pygraphdb](https://github.com/robcox2910/pygraphdb) | [Docs](https://robcox2910.github.io/pygraphdb/) |
|
|
209
|
+
| PyTSDB | Time-series databases | [pytsdb](https://github.com/robcox2910/pytsdb) | [Docs](https://robcox2910.github.io/pytsdb/) |
|
|
210
|
+
| PyVecDB | Vector databases | [pyvecdb](https://github.com/robcox2910/pyvecdb) | [Docs](https://robcox2910.github.io/pyvecdb/) |
|
|
211
|
+
| PyColDB | Column-family databases | [pycoldb](https://github.com/robcox2910/pycoldb) | [Docs](https://robcox2910.github.io/pycoldb/) |
|
|
212
|
+
| **PyCrypt** | **Cryptography** | [pycrypt](https://github.com/robcox2910/pycrypt) | [Docs](https://robcox2910.github.io/pycrypt/) |
|
|
213
|
+
| PyNet | Computer networking | [pynet](https://github.com/robcox2910/pynet) | [Docs](https://robcox2910.github.io/pynet/) |
|
|
214
|
+
| PyWeb | HTTP web servers | [pyweb](https://github.com/robcox2910/pyweb) | [Docs](https://robcox2910.github.io/pyweb/) |
|
|
215
|
+
| PyGit | Version control | [pygit](https://github.com/robcox2910/pygit) | [Docs](https://robcox2910.github.io/pygit/) |
|
|
216
|
+
| PySearch | Search engines | [pysearch](https://github.com/robcox2910/pysearch) | [Docs](https://robcox2910.github.io/pysearch/) |
|
|
217
|
+
| PyMQ | Message queues | [pymq](https://github.com/robcox2910/pymq) | [Docs](https://robcox2910.github.io/pymq/) |
|
|
218
|
+
| PyLLM | Language models (the brain) | [pyllm](https://github.com/robcox2910/pyllm) | [Docs](https://robcox2910.github.io/pyllm/) |
|
|
219
|
+
| PyScheduler | Job scheduling | [pyscheduler](https://github.com/robcox2910/pyscheduler) | [Docs](https://robcox2910.github.io/pyscheduler/) |
|
|
220
|
+
| PyStack | Full-stack integration | [pystack](https://github.com/robcox2910/pystack) | [Docs](https://robcox2910.github.io/pystack/) |
|
|
221
|
+
<!-- series:end -->
|
|
222
|
+
|
|
223
|
+
## License
|
|
224
|
+
|
|
225
|
+
MIT -- see [LICENSE](LICENSE) for details.
|