Contrib subpackage or similar

[peteris-zealid]

In discussions #29 and #53 Matthias suggested the need for a way to contribute implementation specific workflows to pyHanko.

As far as I understand there are generic implementations for PKCS11 and more recently for the CSC spec. However the end user is still responsible for configuration. Also the user will be somewhat helpless if quirks in the specific device or signing service provider does not confirm to the spec.

This discussion is aimed at how to best technically resolve the mentioned problem. (Matthias correct me if I am wrong)

[peteris-zealid]

What I think is safe to assume:

• companies tend to be possessive of their products and codebase. Most would not be comfortable to officially suggest an independently maintained package for operating with their product.
• for working with PDFs it is popular to use Java and to a lesser extent C#

When it is possible to write extensions for pyHanko it should be possible to publish them independently from pyHanko otherwise I fear the industry will not be cooperative.

Not super sure the second point is true. It is a vague feeling based on my attempts to find a lib to work with PDFs as well as my work with ZealiD.
If this lib or one of its extensions is to be used as an SDK for a specific product it would be worth considering to make the API work at the OS level. Also I think this is a good fit for pyHanko because it was initially intended as a CLI tool. (At ZealiD python is used though)

[MatthiasValvekens]

When it is possible to write extensions for pyHanko it should be possible to publish them independently from pyHanko otherwise I fear the industry will not be cooperative.

I completely agree with this, and I think this should remain the primary way of supplying software to be used with (or based on) the "core" pyHanko code base. Not only because of software politics, but also because modularity just makes technical sense.

companies tend to be possessive of their products and codebase. Most would not be comfortable to officially suggest an independently maintained package for operating with their product.

To clarify my position a little: I wouldn't necessarily use the contrib package for interop code targeted towards specific vendors, but rather for specific workflows that are still generic, but only useful to a (relatively) small subset of pyHanko's user base. In these contributed packages, the coupling with pyHanko's main codebase would be a bit looser, they might require additional dependencies, be less flexible in terms of what they expose from the pyHanko internals, etc.
The model I had in mind was the way the Django project offers certain modules as part of the "main" Django package, that are somehow easily pluggable.

To draw on #29 for inspiration: "an opinionated performant signing workflow where the PDF document state + signing process state is serialised and deserialised as necessary" is something I'd consider a prime candidate.
Then again, I definitely wouldn't object to publishing it as a separate package/repo either, since it reduces my own maintenance burden.

For short pieces of sample code (possibly even vendor-specific), I think straight up adding them to the documentation is also an option. Recently, I did just that with some code demonstrating how to use AWS KMS with pyHanko. But of course that's only feasible for small samples.

So in short: I'm all for doing things in separate repos/packages if that's what people prefer, and perhaps that's the right answer, rather than a contrib subpackage.

---

for working with PDFs it is popular to use Java and to a lesser extent C#

Indeed.

If this lib or one of its extensions is to be used as an SDK for a specific product it would be worth considering to make the API work at the OS level. Also I think this is a good fit for pyHanko because it was initially intended as a CLI tool.

Are you suggesting that such extensions should be written in a language that compiles to native code (with language-specific bindings), or that extensions should include a CLI that can integrate with other CLI tools on the system?

If it's the latter: making pyHanko's CLI more pluggable would also be quite nice... The current cli.py module needs refactoring anyway (see #34). With a sufficiently generic config/plugin API, we could allow vendors/external parties/etc. to initialise their own custom Signer implementations from the command line and/or config file, and make those usable to sign PDFs. Plugin registration and discovery could also be done using settings from the configuration file.

[peteris-zealid]

Regarding CSC spec there can be multiple ways of implementing authentication. To adapt this to a specific implementation will most likely not be a simple config change and will require code to be written -- most likely in the form of extending the Signer class. This was initially suggested by Matthias. I do not see a problem with this approach.

[MatthiasValvekens]

Yup, that's also what makes the most sense to me. In the context of my other comment here: if pyHanko would have a CLI plugin API, this would also be a good candidate to integrate using external plugins.