derivepassphrase.git

Fill out README and documentation front page
Parent d3ddbf5
Marco Ricci

Marco Ricci commited on 2024-06-30 22:04:58
Zeige 6 geänderte Dateien mit 57 Einfügungen und 14 Löschungen. 

Also update some settings in the documentation, now that there is an
actual landing page.
README.md
Zeige Datei @ 205eab0
... ... 
@@ -3,19 +3,50 @@
3 3 
 [![PyPI - Version](https://img.shields.io/pypi/v/derivepassphrase.svg)](https://pypi.org/project/derivepassphrase)
4 4 
 [![PyPI - Python Version](https://img.shields.io/pypi/pyversions/derivepassphrase.svg)](https://pypi.org/project/derivepassphrase)
5 5
6 
------
6 
+An almost faithful Python reimplementation of [James Coglan's `vault`][VAULT], a deterministic password manager/generator.
7 
+
8 
+Using a master passphrase or a master SSH key, derive a passphrase for a given named service, subject to length, character and character repetition constraints.
9 
+The derivation is cryptographically strong, meaning that even if a single passphrase is compromised, guessing the master passphrase or a different service's passphrase is computationally infeasible.
10 
+The derivation is also deterministic, given the same inputs, thus the resulting passphrase need not be stored explicitly.
11 
+The service name and constraints themselves also need not be kept secret; the latter are usually stored in a world-readable file.
7 12
8 
-## Table of Contents
13 
+[VAULT]: https://getvau.lt
9 14
10 
-- [Installation](#installation)
11 
-- [License](#license)
15 
+-----
12 16
13 17 
 ## Installation
14 18
19 
+### With `pip`
20 
+
21 
+```console
22 
+$ pip install derivepassphrase
23 
+```
24 
+
25 
+### Manually
26 
+
27 
+`derivepassphrase` is a pure Python package, and may be easily installed manually by placing the respective files into Python's import path.
28 
+`derivepassphrase` requires Python 3.11 or higher for its core functionality and programmatic interface, and [`click`][CLICK] 8.1 or higher for its command-line interface.
29 
+
30 
+[CLICK]: https://click.palletsprojects.com/
31 
+
32 
+## Quick Usage
33 
+
34 
+```console
35 
+$ derivepassphrase -p --length 30 --upper 3 --lower 1 --number 2 --space 0 --symbol 0 my-email-account
36 
+Passphrase: This passphrase is for demonstration purposes only.
37 
+JKeet7GeBpxysOgdCEJo6UzmP8A0Ih
38 
+```
39 
+
40 
+Some time later…
41 
+
15 42 
 ```console
16 
-pip install derivepassphrase
43 
+$ derivepassphrase -p --length 30 --upper 3 --lower 1 --number 2 --space 0 --symbol 0 my-email-account
44 
+Passphrase: This passphrase is for demonstration purposes only.
45 
+JKeet7GeBpxysOgdCEJo6UzmP8A0Ih
17 46 
 ```
18 47
48 
+(The user input `This passphrase is for demonstration purposes only.` for the passphrase prompt is not actually displayed on-screen.)
49 
+
19 50 
 ## License
20 51
21 52 
 `derivepassphrase` is distributed under the terms of the [MIT](https://spdx.org/licenses/MIT.html) license.
docs/index.md
Zeige Datei @ d3ddbf5
... ... 
@@ -1 +0,0 @@
1 
-Great documentation will appear here.
docs/index.md
Zeige Datei @ 205eab0
... ... 
@@ -0,0 +1 @@
1 
+../README.md
0 2 
\ No newline at end of file
mkdocs.yml
Zeige Datei @ 205eab0
... ... 
@@ -1,9 +1,9 @@
1 
-site_name: derivepassphrase documentation
1 
+site_name: derivepassphrase
2 2 
 site_url: null
3 3 
 repo_url: https://github.com/the-13th-letter/derivepassphrase
4 4 
 site_description: An almost faithful Python reimplementation of James Coglan's vault.
5 5 
 site_author: Marco Ricci
6 
-copyright: Copyright 2024 Marco Ricci (the-13th-letter).  All rights reserved.
6 
+copyright: Copyright 2024 Marco Ricci (the-13th-letter).  All rights reserved.  Distributed under the MIT license.
7 7
8 8 
 docs_dir: docs
9 9 
 site_dir: html
... ... 
@@ -75,7 +75,7 @@ plugins:
75 75 
             - src
76 76
77 77 
 nav:
78 
-  - derivepassphrase documentation: index.md
78 
+  - Overview: index.md
79 79 
   #- tutorials.md
80 80 
   #- How-Tos: how-tos.md
81 81 
   - Reference:
pyproject.toml
Zeige Datei @ 205eab0
... ... 
@@ -78,9 +78,17 @@ requires = [
78 78 
 [tool.hatch.env.collectors.mkdocs.docs]
79 79 
 path = "mkdocs.yml"
80 80
81 
+[tool.hatch.envs.docs]
82 
+extra-dependencies = [
83 
+  "black",
84 
+  "mkdocs-material",
85 
+]
86 
+detached = false
87 
+
81 88 
 [tool.hatch.envs.types]
82 89 
 extra-dependencies = [
83 90 
   "mypy>=1.0.0",
91 
+  "pytest",
84 92 
 ]
85 93 
 [tool.hatch.envs.types.scripts]
86 94 
 check = "mypy --install-types --non-interactive {args:src/derivepassphrase tests}"
src/derivepassphrase/cli.py
Zeige Datei @ 205eab0
... ... 
@@ -572,11 +572,15 @@ def derivepassphrase(
572 572 
 ) -> None:
573 573 
     """Derive a strong passphrase, deterministically, from a master secret.
574 574
575 
-    Using a master passphrase or a master SSH key, derive a strong
576 
-    passphrase for SERVICE, deterministically, subject to length,
577 
-    character and character repetition constraints.  The service name
578 
-    and constraints themselves need not be kept secret; the latter are
579 
-    usually stored in a world-readable file.
575 
+    Using a master passphrase or a master SSH key, derive a passphrase
576 
+    for SERVICE, subject to length, character and character repetition
577 
+    constraints.  The derivation is cryptographically strong, meaning
578 
+    that even if a single passphrase is compromised, guessing the master
579 
+    passphrase or a different service's passphrase is computationally
580 
+    infeasible.  The derivation is also deterministic, given the same
581 
+    inputs, thus the resulting passphrase need not be stored explicitly.
582 
+    The service name and constraints themselves also need not be kept
583 
+    secret; the latter are usually stored in a world-readable file.
580 584
581 585 
     If operating on global settings, or importing/exporting settings,
582 586 
     then SERVICE must be omitted.  Otherwise it is required.\f
583 587