pysigned 0.1.0__tar.gz

pysigned-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Meg Hicks
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pysigned-0.1.0/PKG-INFO

@@ -0,0 +1,164 @@
+Metadata-Version: 2.4
+Name: pysigned
+Version: 0.1.0
+Summary: Sign and verify URLs with an expiry, using HMAC or Ed25519
+Author: Meg Hicks
+Author-email: Meg Hicks <meg.d.hicks@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+License-File: THIRD-PARTY-LICENSES
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Security :: Cryptography
+Classifier: Typing :: Typed
+Requires-Dist: cryptography>=40 ; extra == 'ed25519'
+Requires-Python: >=3.11
+Provides-Extra: ed25519
+Description-Content-Type: text/markdown
+
+# pysigned
+
+Sign and verify URLs with an expiry. `pysigned` appends a tamper-proof
+signature (`sig`) and an expiry (`exp`) to a URL's query string, so you can hand
+out time-limited links — download links, password resets, webhook callbacks —
+that can't be altered without invalidating the signature.
+
+📖 **[Documentation](https://meg-codes.github.io/pysigned/)**
+
+- **Two backends.** HMAC (symmetric) by default, or Ed25519 (asymmetric) when
+  the signer and verifier shouldn't share a secret.
+- **Key rotation.** Configure several keys; signing uses one, verification
+  accepts any of them, so you can roll keys without breaking links in flight.
+- **Canonical signing.** The query string is normalised before signing, so the
+  signature survives re-encoding and reordering of unrelated parameters.
+
+## Installation
+
+Requires Python 3.13+.
+
+```sh
+uv add pysigned
+```
+
+```sh
+pip install pysigned
+```
+
+The HMAC backend uses only the standard library. The Ed25519 backend depends on
+[`cryptography`](https://pypi.org/project/cryptography/), which is an optional
+extra — install it when you need asymmetric signing:
+
+```sh
+uv add 'pysigned[ed25519]'
+```
+
+```sh
+pip install 'pysigned[ed25519]'
+```
+
+## Usage
+
+### HMAC (symmetric)
+
+The same secret signs and verifies. Use this when a single trusted service does
+both. Keys must be at least 64 bytes (the SHA-512 digest size).
+
+```python
+import secrets
+from pysigned import URLAuth
+
+# A raw 64-byte secret is wrapped in an HMAC keyset automatically.
+signer = URLAuth([secrets.token_bytes(64)], ttl=60)
+
+signed = signer.sign("https://example.com/report?id=42&fmt=pdf")
+# https://example.com/report?id=42&fmt=pdf&sig=...&exp=...
+
+signer.verify(signed)                             # True
+signer.verify(signed.replace("id=42", "id=99"))   # False — tampered
+```
+
+`ttl` is the number of seconds a signature stays valid (default: 10 minutes).
+Once `exp` passes, `verify` returns `False`.
+
+### Key rotation
+
+Pass `(key_bytes, id)` tuples to give keys stable ids. The most recently added
+key signs by default; every configured key is accepted on verify, so signatures
+made with a rotated-out key keep working until they expire.
+
+```python
+import secrets
+from pysigned import HMACKeySet, URLAuth
+
+keys = HMACKeySet([
+    (secrets.token_bytes(64), "k-2024"),  # old key, still trusted for verify
+    (secrets.token_bytes(64), "k-2025"),  # newest -> used for signing
+])
+signer = URLAuth(keys, ttl=60)
+
+# Sign with a specific key instead of the default:
+signer = URLAuth(keys, signing_key_id="k-2024")
+```
+
+### Ed25519 (asymmetric)
+
+A private key signs; a public key only verifies. Use this when you sign in one
+place and verify somewhere less trusted — the verifier can't forge new
+signatures.
+
+```python
+from pysigned import Ed25519KeySet, Ed25519PrivateKey, Ed25519PublicKey, URLAuth
+
+# Signing side holds the private key.
+private = Ed25519PrivateKey.generate("ed-2025")
+signer = URLAuth(Ed25519KeySet([private]), ttl=60)
+signed = signer.sign("https://example.com/download?file=archive.zip")
+
+# Verifying side only needs the public key. It shares the private key's id.
+public = Ed25519PublicKey.from_public_bytes(private.public_bytes(), private.id)
+verifier = URLAuth(Ed25519KeySet([public]))
+
+verifier.verify(signed)  # True
+```
+
+### Ignoring query parameters
+
+Parameters you don't want to be part of the signature (for example a tracking
+token added downstream) can be excluded:
+
+```python
+signer = URLAuth(keys, ignore_query_params=["utm_source"])
+```
+
+### Clock skew
+
+Allow a grace period past expiry to tolerate clock differences between signer
+and verifier:
+
+```python
+signer.verify(signed, skew=30)  # accept up to 30s past exp
+```
+
+## Examples
+
+A runnable demo of both backends lives in [examples/sign_urls.py](examples/sign_urls.py):
+
+```sh
+uv run python examples/sign_urls.py # requires ed25519 support
+```
+
+## How it works
+
+`URLAuth.sign` builds a canonical byte string from the URL's scheme, host, path,
+and query (with `sig`/`exp` and any ignored params removed), appends the expiry,
+and signs it with the configured backend. Components are joined with newlines —
+a byte that can't appear in a URL component — so field boundaries can never be
+confused. `verify` rebuilds the same message and checks the signature against
+every configured key in constant time.

pysigned-0.1.0/README.md

@@ -0,0 +1,139 @@
+# pysigned
+
+Sign and verify URLs with an expiry. `pysigned` appends a tamper-proof
+signature (`sig`) and an expiry (`exp`) to a URL's query string, so you can hand
+out time-limited links — download links, password resets, webhook callbacks —
+that can't be altered without invalidating the signature.
+
+📖 **[Documentation](https://meg-codes.github.io/pysigned/)**
+
+- **Two backends.** HMAC (symmetric) by default, or Ed25519 (asymmetric) when
+  the signer and verifier shouldn't share a secret.
+- **Key rotation.** Configure several keys; signing uses one, verification
+  accepts any of them, so you can roll keys without breaking links in flight.
+- **Canonical signing.** The query string is normalised before signing, so the
+  signature survives re-encoding and reordering of unrelated parameters.
+
+## Installation
+
+Requires Python 3.13+.
+
+```sh
+uv add pysigned
+```
+
+```sh
+pip install pysigned
+```
+
+The HMAC backend uses only the standard library. The Ed25519 backend depends on
+[`cryptography`](https://pypi.org/project/cryptography/), which is an optional
+extra — install it when you need asymmetric signing:
+
+```sh
+uv add 'pysigned[ed25519]'
+```
+
+```sh
+pip install 'pysigned[ed25519]'
+```
+
+## Usage
+
+### HMAC (symmetric)
+
+The same secret signs and verifies. Use this when a single trusted service does
+both. Keys must be at least 64 bytes (the SHA-512 digest size).
+
+```python
+import secrets
+from pysigned import URLAuth
+
+# A raw 64-byte secret is wrapped in an HMAC keyset automatically.
+signer = URLAuth([secrets.token_bytes(64)], ttl=60)
+
+signed = signer.sign("https://example.com/report?id=42&fmt=pdf")
+# https://example.com/report?id=42&fmt=pdf&sig=...&exp=...
+
+signer.verify(signed)                             # True
+signer.verify(signed.replace("id=42", "id=99"))   # False — tampered
+```
+
+`ttl` is the number of seconds a signature stays valid (default: 10 minutes).
+Once `exp` passes, `verify` returns `False`.
+
+### Key rotation
+
+Pass `(key_bytes, id)` tuples to give keys stable ids. The most recently added
+key signs by default; every configured key is accepted on verify, so signatures
+made with a rotated-out key keep working until they expire.
+
+```python
+import secrets
+from pysigned import HMACKeySet, URLAuth
+
+keys = HMACKeySet([
+    (secrets.token_bytes(64), "k-2024"),  # old key, still trusted for verify
+    (secrets.token_bytes(64), "k-2025"),  # newest -> used for signing
+])
+signer = URLAuth(keys, ttl=60)
+
+# Sign with a specific key instead of the default:
+signer = URLAuth(keys, signing_key_id="k-2024")
+```
+
+### Ed25519 (asymmetric)
+
+A private key signs; a public key only verifies. Use this when you sign in one
+place and verify somewhere less trusted — the verifier can't forge new
+signatures.
+
+```python
+from pysigned import Ed25519KeySet, Ed25519PrivateKey, Ed25519PublicKey, URLAuth
+
+# Signing side holds the private key.
+private = Ed25519PrivateKey.generate("ed-2025")
+signer = URLAuth(Ed25519KeySet([private]), ttl=60)
+signed = signer.sign("https://example.com/download?file=archive.zip")
+
+# Verifying side only needs the public key. It shares the private key's id.
+public = Ed25519PublicKey.from_public_bytes(private.public_bytes(), private.id)
+verifier = URLAuth(Ed25519KeySet([public]))
+
+verifier.verify(signed)  # True
+```
+
+### Ignoring query parameters
+
+Parameters you don't want to be part of the signature (for example a tracking
+token added downstream) can be excluded:
+
+```python
+signer = URLAuth(keys, ignore_query_params=["utm_source"])
+```
+
+### Clock skew
+
+Allow a grace period past expiry to tolerate clock differences between signer
+and verifier:
+
+```python
+signer.verify(signed, skew=30)  # accept up to 30s past exp
+```
+
+## Examples
+
+A runnable demo of both backends lives in [examples/sign_urls.py](examples/sign_urls.py):
+
+```sh
+uv run python examples/sign_urls.py # requires ed25519 support
+```
+
+## How it works
+
+`URLAuth.sign` builds a canonical byte string from the URL's scheme, host, path,
+and query (with `sig`/`exp` and any ignored params removed), appends the expiry,
+and signs it with the configured backend. Components are joined with newlines —
+a byte that can't appear in a URL component — so field boundaries can never be
+confused. `verify` rebuilds the same message and checks the signature against
+every configured key in constant time.

pysigned-0.1.0/THIRD-PARTY-LICENSES

@@ -0,0 +1,407 @@
+Pygments
+2.20.0
+BSD-2-Clause
+Copyright (c) 2006-2022 by the respective authors (see AUTHORS file).
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are
+met:
+
+* Redistributions of source code must retain the above copyright
+  notice, this list of conditions and the following disclaimer.
+
+* Redistributions in binary form must reproduce the above copyright
+  notice, this list of conditions and the following disclaimer in the
+  documentation and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+
+anyio
+4.14.0
+MIT
+The MIT License (MIT)
+
+Copyright (c) 2018 Alex Grönholm
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+
+cffi
+2.0.0
+MIT
+
+Except when otherwise stated (look for LICENSE files in directories or
+information at the beginning of each file) all software and
+documentation is licensed as follows: 
+
+    MIT No Attribution
+
+    Permission is hereby granted, free of charge, to any person 
+    obtaining a copy of this software and associated documentation 
+    files (the "Software"), to deal in the Software without 
+    restriction, including without limitation the rights to use, 
+    copy, modify, merge, publish, distribute, sublicense, and/or 
+    sell copies of the Software, and to permit persons to whom the 
+    Software is furnished to do so.
+
+    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS 
+    OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 
+    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL 
+    THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 
+    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING 
+    FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER 
+    DEALINGS IN THE SOFTWARE.
+
+
+
+coverage
+7.14.1
+Apache-2.0
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+
+cryptography
+49.0.0
+Apache-2.0 OR BSD-3-Clause
+This software is made available under the terms of *either* of the licenses
+found in LICENSE.APACHE or LICENSE.BSD. Contributions to cryptography are made
+under the terms of *both* these licenses.
+
+
+idna
+3.18
+BSD-3-Clause
+BSD 3-Clause License
+
+Copyright (c) 2013-2026, Kim Davies and contributors.
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are
+met:
+
+1. Redistributions of source code must retain the above copyright
+   notice, this list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright
+   notice, this list of conditions and the following disclaimer in the
+   documentation and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
+TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
+PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
+LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+
+iniconfig
+2.3.0
+MIT
+The MIT License (MIT)
+
+Copyright (c) 2010 - 2023 Holger Krekel and others
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
+of the Software, and to permit persons to whom the Software is furnished to do
+so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+
+packaging
+26.2
+Apache-2.0 OR BSD-2-Clause
+This software is made available under the terms of *either* of the licenses
+found in LICENSE.APACHE or LICENSE.BSD. Contributions to this software is made
+under the terms of *both* these licenses.
+
+
+pluggy
+1.6.0
+MIT License
+The MIT License (MIT)
+
+Copyright (c) 2015 holger krekel (rather uses bitbucket/hpk42)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+
+pycparser
+3.0
+BSD-3-Clause
+pycparser -- A C parser in Python
+
+Copyright (c) 2008-2022, Eli Bendersky
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without modification,
+are permitted provided that the following conditions are met:
+
+* Redistributions of source code must retain the above copyright notice, this 
+  list of conditions and the following disclaimer.
+* Redistributions in binary form must reproduce the above copyright notice, 
+  this list of conditions and the following disclaimer in the documentation 
+  and/or other materials provided with the distribution.
+* Neither the name of the copyright holder nor the names of its contributors may 
+  be used to endorse or promote products derived from this software without 
+  specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND 
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED 
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE 
+LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 
+CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE 
+GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 
+HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 
+LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT 
+OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+
+pysigned
+0.1.0
+MIT
+UNKNOWN
+
+

pysigned-0.1.0/pyproject.toml

@@ -0,0 +1,66 @@
+[project]
+name = "pysigned"
+version = "0.1.0"
+description = "Sign and verify URLs with an expiry, using HMAC or Ed25519"
+readme = "README.md"
+authors = [
+    { name = "Meg Hicks", email = "meg.d.hicks@gmail.com" }
+]
+requires-python = ">=3.11"
+license = "MIT"
+license-files = ["LICENSE", "THIRD-PARTY-LICENSES"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Internet :: WWW/HTTP",
+    "Topic :: Security :: Cryptography",
+    "Typing :: Typed",
+]
+dependencies = []
+
+[project.optional-dependencies]
+# Ed25519 signing/verifying. The HMAC backend needs nothing beyond the stdlib.
+ed25519 = [
+    "cryptography>=40",
+]
+
+[build-system]
+requires = ["uv_build>=0.9.18,<0.10.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "pysigned[ed25519]",
+    "pip-licenses>=5.5.5",
+    "pytest>=9.1.0",
+    "pytest-cov>=7.1.0",
+    "mkdocs-material>=9.5.0",
+    "mkdocstrings[python]>=0.27.0",
+    "ruff>=0.15.17",
+    "ty>=0.0.49",
+]
+
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "--cov=pysigned --cov-report=term-missing"
+
+[tool.ty.src]
+include = ["src"]
+
+[tool.pip-licenses]
+ignore-packages = [
+  "pip-licenses",
+  "pytest",
+  "pytest-cov",
+  "mkdocs-material",
+  "mkdocstrings[python]",
+  "ruff",
+  "ty"
+]

pysigned-0.1.0/src/pysigned/__init__.py

@@ -0,0 +1,23 @@
+from .backends import (
+    Ed25519Backend,
+    Ed25519KeySet,
+    HMACKeySet,
+)
+
+from .keys import (
+    Ed25519PrivateKey,
+    Ed25519PublicKey,
+    HMACKey,
+)
+
+from .signature import URLAuth
+
+__all__ = [
+    "Ed25519Backend",
+    "Ed25519KeySet",
+    "Ed25519PrivateKey",
+    "Ed25519PublicKey",
+    "HMACKey",
+    "HMACKeySet",
+    "URLAuth",
+]

pysigned-0.1.0/src/pysigned/backends.py

@@ -0,0 +1,133 @@
+import hmac
+from abc import ABC, abstractmethod
+from collections.abc import Iterable, Mapping
+from types import MappingProxyType
+from typing import Generic, TypeVar
+
+
+from .keys import (
+    DIGEST,
+    Ed25519PrivateKey,
+    Ed25519PublicKey,
+    HMACKey,
+    Key,
+)
+
+
+K = TypeVar("K", bound=Key)
+
+
+class Backend(ABC, Generic[K]):
+    """Algorithm-specific key parsing and signing/verifying.
+
+    A backend turns user-supplied key values into :class:`~pysigned.keys.Key`
+    instances and knows how to sign a message and verify a signature with one.
+    Everything algorithm-agnostic (URL canonicalisation, expiry, key rotation)
+    lives in :class:`~pysigned.signature.URLAuth`.
+    """
+
+    @abstractmethod
+    def parse_key(self, value) -> K: ...
+
+    @abstractmethod
+    def sign(self, key: K, message: bytes) -> str: ...
+
+    @abstractmethod
+    def verify(self, key: K, message: bytes, signature: str) -> bool: ...
+
+
+HMACKeySetValue = tuple[bytes, str] | bytes | HMACKey
+
+
+class HMACBackend(Backend[HMACKey]):
+    def __init__(self, digest: str = DIGEST):
+        self.digest = digest
+
+    def parse_key(self, value: HMACKeySetValue) -> HMACKey:
+        match value:
+            case bytes():
+                return HMACKey(value)
+            case HMACKey():
+                return value
+            case (_bytes, _id):
+                if not isinstance(_bytes, bytes):
+                    raise ValueError("Keys in tuples must be bytes")
+                if not isinstance(_id, str):
+                    raise ValueError("Key ids must be strings.")
+                return HMACKey(_bytes, _id)
+            case _:
+                raise ValueError(f"Invalid key value: {value}")
+
+    def sign(self, key: HMACKey, message: bytes) -> str:
+        return hmac.new(bytes(key), message, self.digest).hexdigest()
+
+    def verify(self, key: HMACKey, message: bytes, signature: str) -> bool:
+        expected = self.sign(key, message)
+        # Constant-time comparison to avoid timing attacks.
+        return hmac.compare_digest(expected, signature)
+
+
+class Ed25519Backend(Backend[Key]):
+    def parse_key(self, value) -> Key:
+        if isinstance(value, (Ed25519PrivateKey, Ed25519PublicKey)):
+            return value
+        raise ValueError(
+            "Ed25519 keys must be wrapped as Ed25519PrivateKey or "
+            "Ed25519PublicKey; raw bytes are ambiguous (private vs public)."
+        )
+
+    def sign(self, key: Key, message: bytes) -> str:
+        if not isinstance(key, Ed25519PrivateKey):
+            raise TypeError(
+                "signing requires an Ed25519PrivateKey; "
+                f"got {type(key).__name__} (public keys cannot sign)"
+            )
+        return key._crypto_key().sign(message).hex()
+
+    def verify(self, key: Key, message: bytes, signature: str) -> bool:
+        if isinstance(key, Ed25519PrivateKey):
+            public = key._crypto_key().public_key()
+        elif isinstance(key, Ed25519PublicKey):
+            public = key._crypto_key()
+        else:
+            return False
+
+        from cryptography.exceptions import InvalidSignature
+
+        try:
+            public.verify(bytes.fromhex(signature), message)
+        except (InvalidSignature, ValueError):
+            return False
+        return True
+
+
+class KeySet:
+    """An id-keyed, read-only collection of keys parsed by a backend."""
+
+    def __init__(self, keys: Iterable, backend: Backend):
+        self.backend = backend
+        self._keys: Mapping[str, Key] = MappingProxyType(
+            {k.id: k for k in map(backend.parse_key, keys)}
+        )
+
+    def __getitem__(self, key: str):
+        return self._keys[key]
+
+    def __iter__(self):
+        return iter(self._keys.values())
+
+    def __reversed__(self):
+        return reversed(list(self._keys.values()))
+
+    def __len__(self):
+        return len(self._keys)
+
+
+class HMACKeySet(KeySet):
+    def __init__(self, keys: Iterable, backend: HMACBackend | None = None):
+        super().__init__(keys, backend or HMACBackend())
+
+
+class Ed25519KeySet(KeySet):
+    def __init__(self, keys: Iterable, backend: Ed25519Backend | None = None):
+        super().__init__(keys, backend or Ed25519Backend())

pysigned-0.1.0/src/pysigned/keys.py

@@ -0,0 +1,150 @@
+import hashlib
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from cryptography.hazmat.primitives.asymmetric import ed25519 as _ed25519
+
+
+def _load_ed25519():
+    """Import cryptography's ed25519 module, with a helpful error if it's missing.
+
+    ``cryptography`` is an optional dependency; only the Ed25519 key types pull
+    it in, and only when their signing/verifying machinery is actually used.
+    """
+    try:
+        from cryptography.hazmat.primitives.asymmetric import ed25519
+    except ModuleNotFoundError as exc:
+        raise ModuleNotFoundError(
+            "Ed25519 support requires the optional 'cryptography' dependency. "
+            "Install it with: pip install 'pysigned[ed25519]'"
+        ) from exc
+    return ed25519
+
+
+DIGEST = "sha512"
+# HMAC keys must be at least the digest's output size (NIST SP 800-107).
+MIN_KEY_BYTES = hashlib.new(DIGEST).digest_size
+# Ed25519 seeds and public keys are both fixed at 32 bytes (RFC 8032).
+ED25519_KEY_BYTES = 32
+
+
+@dataclass(frozen=True, eq=False, repr=False)
+class Key:
+    """A signing/verifying key: raw bytes plus a stable id.
+
+    Subclasses supply two hooks: ``_validate`` (raise on bad key material) and
+    ``_id_bytes`` (the bytes the ``id`` fingerprint is hashed from).
+
+    ``_id_bytes`` is **not** "the public part" of the key. It is only what the
+    fingerprint is computed over. A symmetric HMAC key has no public counterpart,
+    so its ``_id_bytes`` is the *secret* key itself -- safe to hash into an id only
+    because SHA-256 is one-way, and safe to show in ``repr`` only because ``repr``
+    truncates. An asymmetric Ed25519 key uses its genuinely public bytes.
+    """
+
+    key: bytes
+    id: str = ""
+
+    def __post_init__(self):
+        self._validate()
+        # Own an immutable copy so a mutable bytearray argument can't change
+        # underneath the frozen instance.
+        object.__setattr__(self, "key", bytes(self.key))
+        if not self.id:
+            object.__setattr__(self, "id", hashlib.sha512(self._id_bytes()).hexdigest())
+
+    def _validate(self) -> None:
+        raise NotImplementedError
+
+    def _id_bytes(self) -> bytes:
+        raise NotImplementedError
+
+    def __hash__(self):
+        return hash(self.key)
+
+    def __eq__(self, other: object) -> bool:
+        if isinstance(other, Key):
+            other = other.key
+        return self.key == other
+
+    def __bytes__(self):
+        return self.key
+
+    def __repr__(self):
+        return f"<{type(self).__name__} id={self.id}, bytes={self._id_bytes().hex()[:5]}...>"
+
+
+class HMACKey(Key):
+    """A symmetric HMAC key."""
+
+    def _validate(self) -> None:
+        if len(self.key) < MIN_KEY_BYTES:
+            raise ValueError(
+                f"key is {len(self.key)} bytes; "
+                f"{DIGEST} requires keys of at least {MIN_KEY_BYTES} bytes"
+            )
+
+    def _id_bytes(self) -> bytes:
+        return self.key
+
+
+class Ed25519PrivateKey(Key):
+    """An Ed25519 private key. ``key`` holds the 32-byte raw seed.
+
+    Can both sign and verify. Its ``id`` is fingerprinted from the derived public
+    key, so it matches the id of the corresponding :class:`Ed25519PublicKey`, and
+    neither the id nor the repr ever expose the seed.
+    """
+
+    @classmethod
+    def generate(cls, id: str = "") -> "Ed25519PrivateKey":
+        raw = _load_ed25519().Ed25519PrivateKey.generate().private_bytes_raw()
+        return cls(raw, id)
+
+    @classmethod
+    def from_private_bytes(cls, seed: bytes, id: str = "") -> "Ed25519PrivateKey":
+        return cls(seed, id)
+
+    def _validate(self) -> None:
+        if len(self.key) != ED25519_KEY_BYTES:
+            raise ValueError(
+                f"Ed25519 private seed must be {ED25519_KEY_BYTES} bytes, "
+                f"got {len(self.key)}"
+            )
+
+    def _crypto_key(self) -> "_ed25519.Ed25519PrivateKey":
+        return _load_ed25519().Ed25519PrivateKey.from_private_bytes(self.key)
+
+    def public_bytes(self) -> bytes:
+        return self._crypto_key().public_key().public_bytes_raw()
+
+    def public_key(self) -> "Ed25519PublicKey":
+        """The verify-side key, sharing this key's id."""
+        return Ed25519PublicKey(self.public_bytes(), self.id)
+
+    def _id_bytes(self) -> bytes:
+        return self.public_bytes()
+
+
+class Ed25519PublicKey(Key):
+    """An Ed25519 public key. ``key`` holds the 32-byte raw public key. Verify only."""
+
+    @classmethod
+    def from_public_bytes(cls, public: bytes, id: str = "") -> "Ed25519PublicKey":
+        return cls(public, id)
+
+    def _validate(self) -> None:
+        if len(self.key) != ED25519_KEY_BYTES:
+            raise ValueError(
+                f"Ed25519 public key must be {ED25519_KEY_BYTES} bytes, "
+                f"got {len(self.key)}"
+            )
+        # Reject points that aren't valid public keys.
+        _load_ed25519().Ed25519PublicKey.from_public_bytes(self.key)
+
+    def _crypto_key(self) -> "_ed25519.Ed25519PublicKey":
+        return _load_ed25519().Ed25519PublicKey.from_public_bytes(self.key)
+
+    def _id_bytes(self) -> bytes:
+        return self.key

pysigned-0.1.0/src/pysigned/signature.py

@@ -0,0 +1,141 @@
+from collections.abc import Iterable
+from time import time
+from urllib.parse import (
+    parse_qsl,
+    urlencode,
+    urlparse,
+    ParseResult,
+)
+
+from .backends import (
+    Backend,
+    Ed25519Backend,
+    Ed25519KeySet,
+    HMACBackend,
+    HMACKeySet,
+    KeySet,
+)
+from .keys import (
+    DIGEST,
+    MIN_KEY_BYTES,
+    Ed25519PrivateKey,
+    Ed25519PublicKey,
+    HMACKey,
+    Key,
+)
+
+# Re-exported for backwards compatibility; importers historically reach for
+# these via ``pysigned.signature``.
+__all__ = [
+    "DIGEST",
+    "MIN_KEY_BYTES",
+    "Backend",
+    "Ed25519Backend",
+    "Ed25519KeySet",
+    "Ed25519PrivateKey",
+    "Ed25519PublicKey",
+    "HMACBackend",
+    "HMACKey",
+    "HMACKeySet",
+    "Key",
+    "KeySet",
+    "URLAuth",
+]
+
+
+class URLAuth:
+    """Sign and verify URLs over the URL and an expiry, via a pluggable backend.
+
+    A signer is configured with a set of ``keys``. Several keys may be supplied
+    so that keys can be rotated without invalidating signatures that are still
+    in flight: signing uses one key, but :meth:`verify` accepts any of them.
+
+    The cryptography is delegated to the keyset's backend (HMAC by default; pass
+    an :class:`~pysigned.backends.Ed25519KeySet` for Ed25519). Everything else --
+    query canonicalisation, expiry, rotation -- is backend-agnostic.
+
+    Args:
+        keys: A :class:`~pysigned.backends.KeySet`, or raw values that are
+            wrapped in an HMAC keyset for backwards compatibility.
+        signing_key_id: Id of the key to sign with. Defaults to the most
+            recently added key.
+        ttl: Seconds a signature stays valid (default 10 minutes).
+    """
+
+    def __init__(
+        self,
+        keys: KeySet | Iterable,
+        *,
+        signing_key_id: str = "",
+        ignore_query_params: Iterable[str] | None = None,
+        ttl: int = 60 * 10,
+    ) -> None:
+        self.keys = keys if isinstance(keys, KeySet) else HMACKeySet(keys)
+        self.backend = self.keys.backend
+        self.signing_key_id = signing_key_id or next(reversed(self.keys)).id
+        # Params excluded from the signed message: our own sig/exp plus any the
+        # caller wants ignored. Materialised once so a one-shot iterable works.
+        self._excluded = frozenset(("sig", "exp", *(ignore_query_params or ())))
+        self.ttl = ttl
+
+    def sign(self, url: str) -> str:
+        """Sign a URL, returning it with ``sig`` and ``exp`` query params added.
+
+        Args:
+            url: The URL being signed as a string.
+
+        Returns:
+            The signed URL as a string.
+        """
+        parsed = urlparse(url)
+        exp = int(time()) + self.ttl
+        signing_key = self.keys[self.signing_key_id]
+        signature = self.backend.sign(signing_key, self._message(parsed, exp))
+        query = parse_qsl(parsed.query) + [("sig", signature), ("exp", str(exp))]
+        return parsed._replace(query=urlencode(query)).geturl()
+
+    def verify(self, url: str, *, skew: int = 0) -> bool:
+        """Verify a signature produced by :meth:`sign`.
+
+        Every configured key is checked, so signatures made with a rotated-out
+        key still verify.
+        """
+        parsed = urlparse(url)
+        params = dict(parse_qsl(parsed.query))
+
+        sig = params.get("sig")
+        try:
+            exp = int(params.get("exp", ""))
+        except ValueError:
+            return False
+
+        if not sig or not exp:
+            return False
+        if exp + skew <= int(time()):
+            return False
+
+        message = self._message(parsed, exp)
+        for key in self.keys:
+            if self.backend.verify(key, message, sig):
+                return True
+        return False
+
+    def _message(self, parsed: ParseResult, exp: int) -> bytes:
+        """Build a stable, unambiguous byte string from the inputs.
+
+        The query is normalised (sig/exp dropped, then re-encoded) so that
+        sign() and verify() agree regardless of the incoming encoding.
+        Components are joined with a newline (a byte that cannot appear in a URL
+        component) so that different field boundaries can never collide.
+        """
+        pairs = [(k, v) for k, v in parse_qsl(parsed.query) if k not in self._excluded]
+        canonical = parsed._replace(query=urlencode(pairs))
+        parts = (
+            str(exp),
+            canonical.scheme,
+            canonical.netloc,
+            canonical.path,
+            canonical.params,
+            canonical.query,
+        )
+        return "\n".join(parts).encode("utf-8")