cmem-plugin-graphsigning 0.5.0__py3-none-any.whl

cmem_plugin_graphsigning/create_graph_signature.py

@@ -0,0 +1,835 @@
+"""Create Graph Signature Task"""
+
+import base64
+import re
+import tempfile
+from collections import OrderedDict
+from collections.abc import Callable, Sequence
+from contextlib import suppress
+from dataclasses import dataclass
+from datetime import UTC, datetime, timedelta
+from pathlib import Path
+
+import rdflib
+from cmem_client.client import Client
+from cmem_client.repositories.protocols.import_item import ImportConflictPolicy
+from cmem_plugin_base.dataintegration.client import get_client
+from cmem_plugin_base.dataintegration.context import ExecutionContext, ExecutionReport
+from cmem_plugin_base.dataintegration.description import (
+    Icon,
+    Plugin,
+    PluginAction,
+    PluginParameter,
+)
+from cmem_plugin_base.dataintegration.entity import (
+    Entities,
+    Entity,
+    EntitySchema,
+)
+from cmem_plugin_base.dataintegration.parameter.choice import ChoiceParameterType
+from cmem_plugin_base.dataintegration.parameter.graph import GraphParameterType
+from cmem_plugin_base.dataintegration.parameter.password import Password, PasswordParameterType
+from cmem_plugin_base.dataintegration.plugins import WorkflowPlugin
+from cmem_plugin_base.dataintegration.ports import (
+    FixedNumberOfInputs,
+    FixedSchemaPort,
+)
+from cmem_plugin_base.dataintegration.typed_entities.file import FileEntitySchema, LocalFile
+from cryptography.hazmat.primitives import serialization
+from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey
+from cryptography.hazmat.primitives.asymmetric.rsa import generate_private_key
+from cryptography.hazmat.primitives.asymmetric.types import PrivateKeyTypes, PublicKeyTypes
+from rdflib import RDF, URIRef
+
+from cmem_plugin_graphsigning.graph_proof_utils import (
+    ProofMetadata,
+    build_digest_record,
+    build_proof_rdf,
+    canonical_digest,
+    multibase_decode,
+    new_proof_uri,
+    new_rdf_graph,
+    proof_graph_iri,
+    proof_payload,
+    proofs_by_other_keys,
+    signature_options,
+)
+from cmem_plugin_graphsigning.graph_store import (
+    download_and_parse,
+    download_and_parse_proof_graph,
+    graph_iri_input_schema,
+    hash_parsed_graph,
+)
+from cmem_plugin_graphsigning.signing import (
+    MINIMUM_RSA_KEY_SIZE,
+    check_signing_key_strength,
+    cryptosuite_for,
+    did_key_controller,
+    is_multikey,
+    public_key_from_did_key,
+    public_key_multibase,
+    sign_digest,
+    verification_method_id,
+    verify_digest,
+)
+from cmem_plugin_graphsigning.vocabulary import SEC
+
+OUTPUT_ONE_DOCUMENT = "one-document"
+OUTPUT_DOCUMENT_PER_GRAPH = "document-per-graph"
+OUTPUT_INTO_GRAPH = "into-graph"
+
+OUTPUT_CHOICES = OrderedDict(
+    [
+        (
+            OUTPUT_ONE_DOCUMENT,
+            ("One JSON-LD document - every graph's signature in a single file"),
+        ),
+        (
+            OUTPUT_DOCUMENT_PER_GRAPH,
+            (
+                "One JSON-LD document per graph - each signature its own file, to keep "
+                "or send on separately"
+            ),
+        ),
+        (
+            OUTPUT_INTO_GRAPH,
+            (
+                "Into a graph of its own - a companion proof graph beside the source graph, "
+                "which is left untouched; the task hands nothing on"
+            ),
+        ),
+    ]
+)
+
+_PROOF_VALUE_PLACEHOLDER = "cGxhY2Vob2xkZXI="
+"""Stands in for the signature while the triples it will cover are assembled."""
+
+GENERATED_RSA_KEY_SIZE = 3072
+"""Modulus, in bits, of the RSA keys the *Create RSA Key Pair* action issues.
+
+The shortest widely implemented length at or above ``signing.MINIMUM_RSA_KEY_SIZE``,
+so a key this action hands out is one the signing path accepts. The length is not
+configurable: an action that could issue a key the task then refuses would be a worse
+offer than one that issues a single good length.
+"""
+
+
+@dataclass(frozen=True)
+class ProofWrite:
+    """Everything one proof write needs about one graph."""
+
+    graph_iri: str
+    rdf_hash: str
+    private_key: PrivateKeyTypes
+    created: str
+
+
+@Plugin(
+    label="Create Graph Signature",
+    plugin_id="cmem_plugin_graphsigning-CreateGraphSignature",
+    description=(
+        "Compute a canonical SHA-256 digest of Knowledge Graphs and optionally sign it "
+        "as a W3C Data Integrity proof."
+    ),
+    documentation="""
+Compute a canonical SHA-256 digest (RDFC-1.0) of one or more Knowledge Graphs and, given a
+private key, sign each digest as a W3C Data Integrity proof. Without a key the task only
+hashes.
+
+## Ports
+
+Graph IRIs arrive on the input port, as `graph_iri` values, and are processed in order. The
+port is replaced by a parameter when a single graph is configured on the task itself. Keys
+never arrive on a port.
+
+What leaves depends on where the signature goes. Written to documents, it leaves the output
+port as JSON-LD files, one for the whole run or one per graph, ready to be stored in a file
+dataset beside the data. Written into a companion proof graph, it is already in the store, and
+the task declares no output port at all. A run without a key hands on documents that carry the
+digest alone, which still record what the content hashed to.
+
+## Where this task fits
+
+Every shape this task produces is one **Verify Graph Signature** reads, and the two default to
+the same one, so they wire together untouched. **Remove Graph Signature** takes the
+signatures back off a graph, and its output feeds this task again to sign afresh.
+
+## What a proof says
+
+A proof names the key that made it, states its purpose as `sec:assertionMethod`, and records
+the algorithm in `sec:cryptosuite`. Its signature covers all of that together with the digest,
+so no statement in a proof can be edited afterwards without invalidating it.
+
+An Ed25519 key names itself through its `did:key`, derived from the key material, so it is
+named identically in every graph it signs and nothing has to be configured; that identifier
+contains the key, so an Ed25519 proof always discloses its public key.
+
+Which key type to use is a choice between interoperability and a recommendation. Ed25519 is
+recommended here on interoperability grounds: its keys and signatures are small, it has no
+padding or hash settings to get wrong, and its proofs follow the registered
+`eddsa-rdfc-2022` cryptosuite, so another conformant implementation checks exactly the bytes
+this task signed. It is, however, recommended by no part of BSI TR-02102-1. RSA-PSS is, at a
+modulus of 3000 bits or more, which is the floor this task enforces when it is configured -
+but RSA proofs use this plugin's own `rsa-rdfc1-sha256-2026` cryptosuite, which only
+**Verify Graph Signature** checks. So choose RSA where an organizational key has to be used,
+or where TR-02102-1 has to be followed, and Ed25519 where a proof has to be verifiable by
+tooling other than this plugin.
+
+## Caveats
+
+- **The digest covers content, not the graph it came from.** The same triples hash the same
+  under any IRI, or loaded from a file. The link from a proof to its graph is not signed, so a
+  proof moved to another graph with identical content verifies there too.
+- Writing into a companion proof graph replaces your own earlier signature and keeps those
+  made with other keys; taking those off is what **Remove Graph Signature** is for. A proof is
+  yours when it names your verification method or your key's `did:key`, or when your key
+  verifies it against the content as it is now. Re-signing unchanged content yields the same
+  digest and a new proof, since two signing acts are two proofs.
+- A `sec:proof` resource in the companion proof graph that is not typed
+  `sec:DataIntegrityProof` is not recognized as a proof, and is dropped the next time any
+  signature is written into that graph.
+- The companion proof graph is read, changed and replaced in one step per graph. Two runs
+  signing the same graph with different keys at the same time can lose one of the two
+  signatures.
+- The source graph is never written to. Proof-shaped triples already sitting in it are not
+  recognized as a signature, and are hashed and signed as ordinary data.
+- A proof naming its key through `did:key`, or embedding it, verifies on its own but does not
+  say who signed. Anyone able to write the companion proof graph can re-sign altered content
+  with their own key; a verifier has to check against a key it trusts.
+- With one document for the whole run, a cancelled run writes no document at all rather than
+  one covering only the graphs done so far, which would read as a complete, passing set. With
+  one document per graph, the documents for the graphs done so far are handed on.
+- A graph that does not exist fails the run. Canonicalization is capped at five seconds per
+  graph; a graph large or blank-node-heavy enough to exceed that fails the run with a timeout.
+- A key that is neither Ed25519 nor RSA, an RSA key with a modulus under 3000 bits, a key the
+  passphrase does not open, and incomplete combinations - such as an RSA key with no
+  verification method - are refused when the task is configured, not when it runs.
+- A signature document is this plugin's own format, not a W3C secured document: it holds the
+  proof apart from the data it covers. A standard verifier needs a secured document assembled
+  from the graph's data and this proof first.
+""",
+    icon=Icon(file_name="create_graph_signature.svg", package=__package__),
+    actions=[
+        PluginAction(
+            name="create_key_pair",
+            label="Create Ed25519 Key Pair",
+            description=(
+                "Generate a new Ed25519 key pair and show it once, without storing it "
+                "anywhere. This is the recommended key type for interoperability, but it "
+                "is outside BSI TR-02102-1; where that recommendation has to be followed, "
+                "create an RSA key pair instead. Set Private Key Passphrase first to have "
+                "the generated private key encrypted with it."
+            ),
+        ),
+        PluginAction(
+            name="create_rsa_key_pair",
+            label="Create RSA Key Pair",
+            description=(
+                "Generate a new RSA key pair and show it once, without storing it anywhere. "
+                f"The key has a {GENERATED_RSA_KEY_SIZE} bit modulus, which is the shortest "
+                "this task signs with. Use this where an organizational RSA key is required, "
+                "or where BSI TR-02102-1 has to be followed. Set Private Key Passphrase "
+                "first to have the generated private key encrypted with it."
+            ),
+        ),
+    ],
+    parameters=[
+        PluginParameter(
+            name="input_graph",
+            label="Input Graph",
+            description=(
+                "The Knowledge Graph to hash. Leave empty to take graph IRIs from the input "
+                "port instead; setting this parameter removes that port."
+            ),
+            param_type=GraphParameterType(
+                show_di_graphs=False,
+                show_graphs_without_class=True,
+                show_system_graphs=True,
+                allow_only_autocompleted_values=False,
+            ),
+            default_value="",
+        ),
+        PluginParameter(
+            name="private_key",
+            label="Private Key",
+            description=(
+                "PEM-encoded Ed25519 or RSA private key that signs each digest. Leave "
+                "empty to hash without signing. The key type decides the algorithm, so "
+                "there is nothing else to choose. An RSA key needs a modulus of at least "
+                f"{MINIMUM_RSA_KEY_SIZE} bits."
+            ),
+            param_type=PasswordParameterType(),
+            default_value="",
+        ),
+        PluginParameter(
+            name="private_key_passphrase",
+            label="Private Key Passphrase",
+            description=(
+                "Passphrase of an encrypted private key. The key-pair actions encrypt the "
+                "private key they generate with it."
+            ),
+            param_type=PasswordParameterType(),
+            default_value="",
+        ),
+        PluginParameter(
+            name="output_shape",
+            label="Output",
+            description=(
+                "Where each signature goes. Writing into a graph of its own requires a "
+                "Private Key and removes the output port."
+            ),
+            param_type=ChoiceParameterType(OUTPUT_CHOICES),
+            default_value=OUTPUT_ONE_DOCUMENT,
+        ),
+        PluginParameter(
+            name="embed_public_key",
+            label="Embed Public Key",
+            description=(
+                "If enabled, embeds the signing key's public key in each proof as "
+                "sec:publicKeyMultibase, so the proof can be checked without a key supplied "
+                "separately. An Ed25519 proof needs no embedded key for that, since its "
+                "did:key already names the key. Requires a Private Key."
+            ),
+            default_value=False,
+            advanced=True,
+        ),
+        PluginParameter(
+            name="verification_method_iri",
+            label="Verification Method IRI",
+            description=(
+                "IRI naming the signing key, written as each proof's sec:verificationMethod. "
+                "Leave empty for an Ed25519 key, which is then named by its did:key; an RSA "
+                "key requires it."
+            ),
+            default_value="",
+            advanced=True,
+        ),
+        PluginParameter(
+            name="resolve_owl_imports",
+            label="Resolve owl:imports",
+            description=(
+                "If enabled, resolves owl:imports before hashing, so the digest and signature "
+                "cover every graph reachable through the source graph's owl:imports. Verify "
+                "Graph Signature has to use the same setting."
+            ),
+            default_value=False,
+            advanced=True,
+        ),
+        PluginParameter(
+            name="proof_validity_days",
+            label="Proof Validity (days)",
+            description=(
+                "Number of days after signing at which each proof expires, written as "
+                "sec:expiration. 0 writes proofs that never expire."
+            ),
+            default_value=0,
+            advanced=True,
+        ),
+    ],
+)
+class CreateGraphSignature(WorkflowPlugin):
+    """Compute a hash value from one or more Knowledge Graphs, with optional signing."""
+
+    # A plugin constructor takes one argument per PluginParameter, so its arity is
+    # fixed by the plugin's configuration surface, not by a style choice here.
+    def __init__(  # noqa: PLR0913, PLR0917
+        self,
+        input_graph: str = "",
+        private_key: Password | str = "",
+        private_key_passphrase: Password | str = "",
+        output_shape: str = OUTPUT_ONE_DOCUMENT,
+        embed_public_key: bool = False,
+        verification_method_iri: str = "",
+        resolve_owl_imports: bool = False,
+        proof_validity_days: int = 0,
+    ) -> None:
+        # A Password parameter is always truthy - even when the field was left blank it
+        # arrives as Password(""), so whether a key was given can only be told from the
+        # decrypted value. Only the answer is kept; the key itself stays encrypted until
+        # execute() needs it.
+        self.signing = bool(self._resolve_secret(private_key))
+        if self.signing:
+            # Refuse a key this plugin will not sign with here, rather than at execute
+            # time: cryptosuite_for raises for anything but Ed25519 and RSA, and
+            # check_signing_key_strength for an RSA key below the policy minimum.
+            key = self._load_private_key(private_key, private_key_passphrase)
+            cryptosuite_for(key)
+            check_signing_key_strength(key)
+        if embed_public_key and not self.signing:
+            raise ValueError("'Embed Public Key' requires a private key to be provided.")
+        if output_shape == OUTPUT_INTO_GRAPH and not self.signing:
+            raise ValueError(
+                "Writing into a graph of its own requires a private key to be provided."
+            )
+        if proof_validity_days < 0:
+            raise ValueError("'Proof Validity (days)' must not be negative.")
+        self.proof_validity_days = proof_validity_days
+        self.input_graph = input_graph
+        self.private_key = private_key
+        self.embed_public_key = embed_public_key
+        if self.signing and not verification_method_iri:
+            # Every proof has to name its key. An Ed25519 key identifies itself: its
+            # did:key is derived from the key material, so it needs no IRI of its own.
+            # Nothing else can do that.
+            public_key = self._load_private_key(private_key, private_key_passphrase).public_key()
+            if not is_multikey(public_key):
+                raise ValueError(
+                    "Signing with this key type requires a 'Verification Method IRI' to "
+                    "be provided. Every proof names the key that made it, and only an "
+                    "Ed25519 key can identify itself, through its did:key."
+                )
+        self.private_key_passphrase = private_key_passphrase
+        self.resolve_owl_imports = resolve_owl_imports
+        if output_shape not in OUTPUT_CHOICES:
+            raise ValueError(f"'Output' must be one of {', '.join(OUTPUT_CHOICES)}.")
+        self.output_shape = output_shape
+        self.verification_method_iri = verification_method_iri
+        if input_graph:
+            self.input_ports = FixedNumberOfInputs([])
+        else:
+            self.input_ports = FixedNumberOfInputs(
+                [FixedSchemaPort(schema=graph_iri_input_schema())]
+            )
+        self._documents_dir: Path | None = None
+        schema = self._output_entity_schema()
+        self.output_port = None if schema is None else FixedSchemaPort(schema=schema)
+
+    def _emit_for_graph(
+        self,
+        graph_iri: str,
+        rdf_hash: str,
+        proof_rdf: rdflib.Graph | None,
+        collected: rdflib.Graph,
+    ) -> Entity | None:
+        """Return the document one graph contributes to the output, or accumulate it.
+
+        Only the one-document-per-graph mode returns anything. The one-document-per-run
+        mode collects the graphs and writes them once the last of them has been signed,
+        and writing into a graph of its own hands nothing on.
+        """
+        if not self._writes_documents:
+            return None
+        signatures = proof_rdf if proof_rdf is not None else self._digest_only(graph_iri, rdf_hash)
+        if self.output_shape == OUTPUT_DOCUMENT_PER_GRAPH:
+            return FileEntitySchema().to_entity(self.signature_document(graph_iri, signatures))
+        for triple in signatures:
+            collected.add(triple)
+        return None
+
+    @property
+    def _writes_documents(self) -> bool:
+        """Whether this run hands signature documents to the next task."""
+        return self.output_shape in (OUTPUT_ONE_DOCUMENT, OUTPUT_DOCUMENT_PER_GRAPH)
+
+    @property
+    def _writes_into_graph(self) -> bool:
+        """Whether this run puts the signature into the source graph."""
+        return self.output_shape == OUTPUT_INTO_GRAPH
+
+    def operation_description(self) -> str:
+        """Describe what this run does to the graphs it processes, for the report."""
+        if not self.signing:
+            return "graphs hashed"
+        if self._writes_documents:
+            return "signature documents written"
+        return "graphs signed"
+
+    def _output_entity_schema(self) -> EntitySchema | None:
+        """Return the schema this task emits, or None where it emits nothing.
+
+        Both the declared port and the returned Entities read it from here. Declaring
+        one schema and returning another is accepted by the task itself and rejected by
+        whatever is wired downstream, which is a confusing place to find out.
+
+        Writing into a graph of its own produces no output at all: the signature is in
+        that graph, and a port would only invite something to be wired to a result that
+        says nothing the graph does not already say.
+        """
+        if self._writes_into_graph:
+            return None
+        return FileEntitySchema()
+
+    @staticmethod
+    def _resolve_secret(value: Password | str) -> str:
+        """Return the decrypted string for a Password parameter, decrypted at point of use."""
+        return value if isinstance(value, str) else value.decrypt()
+
+    @classmethod
+    def _load_private_key(
+        cls, private_key: Password | str, passphrase: Password | str
+    ) -> PrivateKeyTypes:
+        """Load the configured private key, decrypting both secrets at the point of use."""
+        passphrase_str = cls._resolve_secret(passphrase)
+        return serialization.load_pem_private_key(
+            data=cls._resolve_secret(private_key).encode("utf-8"),
+            password=passphrase_str.encode("utf-8") if passphrase_str else None,
+        )
+
+    @staticmethod
+    def _public_key_is_multikey(private_key: PrivateKeyTypes) -> bool:
+        """Whether the key of *private_key* may be typed sec:Multikey."""
+        return is_multikey(private_key.public_key())
+
+    @staticmethod
+    def _public_key_multibase(private_key: PrivateKeyTypes) -> str:
+        """Return the multibase public key of *private_key*, for embedding in a proof.
+
+        An RSA private key carries its public key, so the key embedded in a proof is
+        always derived here rather than supplied separately - a key that does not
+        belong to the signature could only ever produce a proof that fails to verify.
+        """
+        return public_key_multibase(private_key.public_key())
+
+    def create_key_pair(self) -> str:
+        """Generate an Ed25519 key pair and return it for display, storing nothing.
+
+        Backs the *Create Ed25519 Key Pair* action.
+        """
+        return self._key_pair_output(Ed25519PrivateKey.generate())
+
+    def create_rsa_key_pair(self) -> str:
+        """Generate an RSA key pair and return it for display, storing nothing.
+
+        Backs the *Create RSA Key Pair* action.
+        """
+        return self._key_pair_output(
+            generate_private_key(public_exponent=65537, key_size=GENERATED_RSA_KEY_SIZE)
+        )
+
+    def _key_pair_output(self, private_key: PrivateKeyTypes) -> str:
+        """Render a freshly generated key pair as Markdown, storing nothing.
+
+        The keys are held in memory for the length of this call and returned as
+        text: nothing is written to disk, not even a temporary file, because a
+        private key belongs in a password store and in this task's encrypted
+        parameter, not in a file someone has to remember to delete.
+        """
+        public_key = private_key.public_key()
+        passphrase = self._resolve_secret(self.private_key_passphrase)
+        encryption = (
+            serialization.BestAvailableEncryption(passphrase.encode("utf-8"))
+            if passphrase
+            else serialization.NoEncryption()
+        )
+        private_pem = private_key.private_bytes(
+            encoding=serialization.Encoding.PEM,
+            format=serialization.PrivateFormat.PKCS8,
+            encryption_algorithm=encryption,
+        ).decode("utf-8")
+        public_pem = public_key.public_bytes(
+            encoding=serialization.Encoding.PEM,
+            format=serialization.PublicFormat.SubjectPublicKeyInfo,
+        ).decode("utf-8")
+        protection = (
+            "encrypted with the passphrase configured on this task"
+            if passphrase
+            else "**not** encrypted - set a *Private Key Passphrase* first to encrypt it"
+        )
+        return (
+            "This key pair exists only in this message. It is stored nowhere, and it "
+            "cannot be shown again - copy both keys to your password store now.\n\n"
+            f"**Private key** ({protection}) - paste into *Private Key*:\n\n"
+            f"```\n{private_pem}```\n\n"
+            "**Public key** - paste into *Verify Graph Signature*'s *External Public "
+            f"Key*, where a verifier needs a key to trust:\n\n"
+            f"```\n{public_pem}```\n"
+        )
+
+    def _verification_method_iri(self, private_key: PrivateKeyTypes) -> str:
+        """Return the verification method every proof of this run names.
+
+        The configured IRI where there is one, and otherwise the key's own did:key -
+        which ``__init__`` has already ensured exists. The specification requires a
+        proof to name its verification method, since that is how anyone else finds
+        the key to check it with.
+        """
+        return self.verification_method_iri or verification_method_id(private_key.public_key())
+
+    def _own_signature(
+        self, graph: rdflib.Graph, private_key: PrivateKeyTypes, rdf_hash: str
+    ) -> Callable[[rdflib.term.Node, rdflib.term.Node | None], bool]:
+        """Return the test that tells this signer's own proofs from everybody else's.
+
+        A proof naming the verification method this run writes settles it outright:
+        that is the signer saying which key is theirs. So does a proof naming this
+        key's did:key, even where this run is configured to name the key another
+        way. Failing both, a proof this key made over the content as it is now is
+        one this key verifies.
+        """
+        own_method = self._verification_method_iri(private_key)
+        public_key = private_key.public_key()
+
+        def is_own(proof_uri: rdflib.term.Node, vm_uri: rdflib.term.Node | None) -> bool:
+            if vm_uri is not None and (
+                str(vm_uri) == own_method or self._names_key(str(vm_uri), public_key)
+            ):
+                return True
+            return self._made_by(graph, proof_uri, public_key, rdf_hash)
+
+        return is_own
+
+    @staticmethod
+    def _names_key(verification_method: str, public_key: PublicKeyTypes) -> bool:
+        """Whether *verification_method* is a did:key encoding *public_key*."""
+        try:
+            named = public_key_from_did_key(verification_method)
+        except ValueError:
+            return False
+        return named is not None and named == public_key
+
+    @staticmethod
+    def _made_by(
+        graph: rdflib.Graph,
+        proof_uri: rdflib.term.Node,
+        public_key: PublicKeyTypes,
+        rdf_hash: str,
+    ) -> bool:
+        """Whether *public_key* made the signature stored on *graph* at *proof_uri*.
+
+        A proof states no digest of its own - the specification's proof has no such
+        property - so this can only be checked against the content as it is now. A
+        proof this key made over content that has since changed is still recognized
+        whenever it names the key, which every proof this task writes does.
+        """
+        proof_value = str(next(graph.objects(proof_uri, SEC.proofValue), ""))
+        if not proof_value:
+            return False
+        try:
+            signature = multibase_decode(proof_value)
+        except (ValueError, TypeError):
+            # Proof material that will not decode is no signature this key can claim.
+            return False
+        options = signature_options(graph, proof_uri)
+        payload = proof_payload(canonical_digest(options), rdf_hash)
+        return verify_digest(public_key, payload, signature)
+
+    def _expires(self, created: str) -> str:
+        """Return this run's proof expiry, formatted like *created*, or empty for none.
+
+        Computed from *created* rather than from now, so every proof in a run whose
+        signing spans more than an instant still expires a fixed number of days after
+        its own creation, not after the run's.
+        """
+        if not self.proof_validity_days:
+            return ""
+        created_at = datetime.strptime(created, "%Y-%m-%dT%H:%M:%SZ").replace(tzinfo=UTC)
+        expires_at = created_at + timedelta(days=self.proof_validity_days)
+        return expires_at.strftime("%Y-%m-%dT%H:%M:%SZ")
+
+    def signed_proof(self, write: ProofWrite) -> rdflib.Graph:
+        """Build the signed proof for one graph, as triples.
+
+        The same proof either goes into a graph of its own or leaves as a signature
+        document, so both are produced here and cannot drift apart.
+        """
+        graph_iri, rdf_hash, private_key = write.graph_iri, write.rdf_hash, write.private_key
+        graph_uri_ref = URIRef(graph_iri)
+        embedded_key = self._public_key_multibase(private_key) if self.embed_public_key else ""
+        verification_method_iri = self._verification_method_iri(private_key)
+        metadata = ProofMetadata(
+            created=write.created,
+            verification_method_iri=verification_method_iri,
+            public_key_multibase=embedded_key,
+            cryptosuite=cryptosuite_for(private_key),
+            public_key_is_multikey=bool(embedded_key) and self._public_key_is_multikey(private_key),
+            expires=self._expires(write.created),
+            controller=did_key_controller(verification_method_iri),
+        )
+        # The proof is built twice: once with a placeholder to obtain its configuration -
+        # everything it asserts about itself, such as when it was created, its purpose
+        # and the verification method it names - and once for real, with a signature
+        # covering that configuration together with the document digest. Signing the
+        # digest alone would leave created, proofPurpose and verificationMethod
+        # editable after the fact.
+        proof_uri = new_proof_uri()
+        placeholder_proof = build_proof_rdf(
+            graph_uri=graph_uri_ref,
+            proof_uri=proof_uri,
+            signature_b64=_PROOF_VALUE_PLACEHOLDER,
+            metadata=metadata,
+        )
+        options = signature_options(placeholder_proof, proof_uri)
+        bound_signature = base64.b64encode(
+            sign_digest(private_key, proof_payload(canonical_digest(options), rdf_hash))
+        ).decode("ascii")
+        return build_proof_rdf(
+            graph_uri=graph_uri_ref,
+            proof_uri=proof_uri,
+            signature_b64=bound_signature,
+            metadata=metadata,
+        )
+
+    def _write_proof(self, client: Client, write: ProofWrite, proof_rdf: rdflib.Graph) -> None:
+        """Write this signer's proof into the data graph's companion proof graph.
+
+        The data graph itself plays no part in this write and is never downloaded,
+        reserialized or reimported here - only the companion proof graph is read and
+        written, holding every other signer's proof kept as it was, plus this one.
+        """
+        graph_iri = write.graph_iri
+        graph_uri = URIRef(graph_iri)
+        existing = download_and_parse_proof_graph(client, graph_iri)
+        if existing is None:
+            existing = new_rdf_graph()
+        kept, replaced = proofs_by_other_keys(
+            existing,
+            graph_uri,
+            self._own_signature(existing, write.private_key, write.rdf_hash),
+        )
+        self.log.info(
+            f"{graph_iri}: {len(replaced)} own signature(s) replaced, "
+            f"{len(list(kept.subjects(RDF.type, SEC.DataIntegrityProof)))} kept"
+        )
+        combined = new_rdf_graph()
+        for triple in kept:
+            combined.add(triple)
+        for triple in proof_rdf:
+            combined.add(triple)
+        turtle_bytes = combined.serialize(format="turtle").encode("utf-8")
+        with tempfile.NamedTemporaryFile(suffix=".ttl", delete=False) as tmp:
+            tmp.write(turtle_bytes)
+            tmp_path = Path(tmp.name)
+        proof_graph_key = str(proof_graph_iri(graph_iri))
+        try:
+            client.graphs.import_item(
+                path=tmp_path,
+                key=proof_graph_key,
+                on_conflict=ImportConflictPolicy.REPLACE,
+            )
+            self.log.info(f"Proof written to proof graph: {proof_graph_key}")
+        finally:
+            Path(tmp_path).unlink(missing_ok=True)
+
+    def _entities(self, output_entities: list[Entity]) -> Entities | None:
+        """Wrap the results, or return nothing where this task declares no port."""
+        schema = self._output_entity_schema()
+        if schema is None:
+            return None
+        return Entities(schema=schema, entities=iter(output_entities))
+
+    def _run_document(self, collected: rdflib.Graph, *, cancelled: bool) -> Entity | None:
+        """Return the one document covering a whole run, if this run writes one.
+
+        A cancelled run writes none. A document covering the graphs signed before
+        the cancellation is indistinguishable from one covering every graph asked
+        for, and anyone verifying against it would see only passes.
+        """
+        if self.output_shape != OUTPUT_ONE_DOCUMENT or len(collected) == 0:
+            return None
+        if cancelled:
+            self.log.warning("Run cancelled; no signature document written.")
+            return None
+        return FileEntitySchema().to_entity(self.signature_document("graph-signatures", collected))
+
+    def _document_directory(self) -> Path:
+        """Return the directory this run writes its signature documents into.
+
+        One directory per run rather than one per document, registered for cleanup
+        so a long-lived worker does not accumulate a directory per graph signed.
+        """
+        if self._documents_dir is None:
+            self._documents_dir = Path(tempfile.mkdtemp(prefix="graph-signatures-"))
+        return self._documents_dir
+
+    @staticmethod
+    def _digest_only(graph_iri: str, rdf_hash: str) -> rdflib.Graph:
+        """Return the digest record for a graph that was hashed but not signed."""
+        return build_digest_record(URIRef(graph_iri), rdf_hash)
+
+    def signature_document(self, graph_iri: str, proof_rdf: rdflib.Graph) -> LocalFile:
+        """Write one graph's signature to a JSON-LD document and return it as a file.
+
+        The document holds exactly the triples a proof written into a graph of its own
+        would, so the two say the same thing in two places.
+        """
+        # The context is pinned to the two namespaces the document actually uses.
+        # rdflib would otherwise emit its entire default prefix table, and naming the
+        # W3C Data Integrity context here would claim a conformance this does not have.
+        jsonld = proof_rdf.serialize(
+            format="json-ld",
+            auto_compact=True,
+            context={"sec": str(SEC)},
+        )
+        slug = re.sub(r"^https?-+", "", re.sub(r"[^A-Za-z0-9]+", "-", graph_iri).strip("-"))
+        slug = slug[:100] or "graph"
+        path = self._document_directory() / f"{slug}.signature.json"
+        path.write_text(jsonld, encoding="utf-8")
+        return LocalFile(path=str(path), mime="application/ld+json")
+
+    def execute(
+        self,
+        inputs: Sequence[Entities],
+        context: ExecutionContext,
+    ) -> Entities | None:
+        """Run the workflow operator."""
+        self.log.info("Start creating graph hash.")
+        client = get_client(context)
+
+        # Collect graph IRIs from port 0; fall back to the input_graph parameter
+        graph_iris: list[str] = []
+        if inputs:
+            graph_iris.extend(
+                entity.values[0][0]
+                for entity in inputs[0].entities
+                if entity.values and entity.values[0]
+            )
+        if not graph_iris and self.input_graph:
+            graph_iris = [self.input_graph]
+
+        # Load the private key when one was supplied; that is what turns on signing
+        private_key = (
+            self._load_private_key(self.private_key, self.private_key_passphrase)
+            if self.signing
+            else None
+        )
+
+        # Process each graph
+        output_entities: list[Entity] = []
+        collected = new_rdf_graph()
+        created = datetime.now(UTC).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+        cancelled = False
+        for processed, graph_iri in enumerate(graph_iris, start=1):
+            with suppress(AttributeError):
+                if context.workflow.status() == "Canceling":
+                    cancelled = True
+                    break
+
+            self.log.info(f"Processing graph: {graph_iri}")
+            full_graph = download_and_parse(
+                client=client, graph_iri=graph_iri, resolve_owl_imports=self.resolve_owl_imports
+            )
+
+            self.log.info(f"Graph size: {len(full_graph)}")
+            rdf_hash = hash_parsed_graph(full_graph)
+            self.log.info(rdf_hash)
+
+            proof_rdf = None
+            if private_key is not None:
+                write = ProofWrite(
+                    graph_iri=graph_iri,
+                    rdf_hash=rdf_hash,
+                    private_key=private_key,
+                    created=created,
+                )
+                proof_rdf = self.signed_proof(write)
+                if self._writes_into_graph:
+                    self._write_proof(client, write, proof_rdf)
+
+            emitted = self._emit_for_graph(graph_iri, rdf_hash, proof_rdf, collected)
+            if emitted is not None:
+                output_entities.append(emitted)
+
+            context.report.update(
+                ExecutionReport(
+                    entity_count=processed,
+                    operation="write" if self._writes_into_graph else "read",
+                    operation_desc=self.operation_description(),
+                )
+            )
+
+        run_document = self._run_document(collected, cancelled=cancelled)
+        if run_document is not None:
+            output_entities.append(run_document)
+
+        return self._entities(output_entities)