Class swarmauri_core.signing.ISigning.ISigning

swarmauri_core.signing.ISigning.ISigning

Bases: ABC

supports abstractmethod

supports()

Return capability information.

Keys (omit if unsupported): - "algs": iterable of signature algorithms (e.g., "Ed25519", "RSA-PSS-SHA256", "OpenPGP"). - "canons": iterable of canonicalization identifiers (e.g., "json", "cbor", "json-c14n"). - "signs": iterable describing supported signing surfaces. Expected tokens include • "bytes" → :meth:sign_bytes • "digest" → :meth:sign_digest • "envelope" → :meth:sign_envelope • "stream" → :meth:sign_stream - "verifies": iterable describing supported verification surfaces using the same tokens as "signs". - "envelopes": iterable describing supported envelope shapes (e.g., "mapping", "aead_ciphertext", "multi_recipient"). - "features": optional iterable of flags, e.g.: • "multi" → optimized for multi‑signature sets • "detached_only" → only detached signatures (default) • "attest" → can include attestation chains in Signature["chain"]

Source code in swarmauri_core/signing/ISigning.py

@abstractmethod
def supports(self) -> Mapping[str, Iterable[str]]:
    """
    Return capability information.

    Keys (omit if unsupported):
      - "algs": iterable of signature algorithms (e.g., "Ed25519", "RSA-PSS-SHA256", "OpenPGP").
      - "canons": iterable of canonicalization identifiers (e.g., "json", "cbor", "json-c14n").
      - "signs": iterable describing supported signing surfaces. Expected tokens include
            • "bytes"    → :meth:`sign_bytes`
            • "digest"   → :meth:`sign_digest`
            • "envelope" → :meth:`sign_envelope`
            • "stream"   → :meth:`sign_stream`
      - "verifies": iterable describing supported verification surfaces using the
        same tokens as "signs".
      - "envelopes": iterable describing supported envelope shapes (e.g.,
        "mapping", "aead_ciphertext", "multi_recipient").
      - "features": optional iterable of flags, e.g.:
            • "multi"          → optimized for multi‑signature sets
            • "detached_only"  → only detached signatures (default)
            • "attest"         → can include attestation chains in Signature["chain"]
    """
    ...

sign_bytes abstractmethod async

sign_bytes(key, payload, *, alg=None, opts=None)

Produce one or more detached signatures over raw bytes.

RETURNS	DESCRIPTION
Sequence[Signature]	Sequence[Signature] (typically length 1). Multiple signatures MAY be
Sequence[Signature]	returned if the provider is configured to co‑sign (e.g., hardware + software).

Source code in swarmauri_core/signing/ISigning.py

@abstractmethod
async def sign_bytes(
    self,
    key: KeyRef,
    payload: bytes,
    *,
    alg: Optional[Alg] = None,
    opts: Optional[Mapping[str, object]] = None,
) -> Sequence[Signature]:
    """
    Produce one or more detached signatures over raw bytes.

    Returns:
      Sequence[Signature] (typically length 1). Multiple signatures MAY be
      returned if the provider is configured to co‑sign (e.g., hardware + software).
    """
    ...

sign_digest abstractmethod async

sign_digest(key, digest, *, alg=None, opts=None)

Produce detached signatures over a pre-computed message digest.

Source code in swarmauri_core/signing/ISigning.py

@abstractmethod
async def sign_digest(
    self,
    key: KeyRef,
    digest: bytes,
    *,
    alg: Optional[Alg] = None,
    opts: Optional[Mapping[str, object]] = None,
) -> Sequence[Signature]:
    """Produce detached signatures over a pre-computed message digest."""
    ...

verify_bytes abstractmethod async

verify_bytes(
    payload, signatures, *, require=None, opts=None
)

Verify detached signatures over raw bytes.

PARAMETER	DESCRIPTION
signatures	sequence of Signature mappings.
require	optional policy hints, e.g. {"min_signers": 1, "algs": ["Ed25519"]}

RETURNS	DESCRIPTION
bool	True if the verification criteria are met, False otherwise.

Source code in swarmauri_core/signing/ISigning.py

@abstractmethod
async def verify_bytes(
    self,
    payload: bytes,
    signatures: Sequence[Signature],
    *,
    require: Optional[Mapping[str, object]] = None,
    opts: Optional[Mapping[str, object]] = None,
) -> bool:
    """
    Verify detached signatures over raw bytes.

    Parameters:
      signatures : sequence of Signature mappings.
      require    : optional policy hints, e.g. {"min_signers": 1, "algs": ["Ed25519"]}

    Returns:
      True if the verification criteria are met, False otherwise.
    """
    ...

sign_stream abstractmethod async

sign_stream(key, payload, *, alg=None, opts=None)

Produce detached signatures over streaming byte payloads.

Implementations MAY buffer the stream to reuse :meth:sign_bytes.

Source code in swarmauri_core/signing/ISigning.py

@abstractmethod
async def sign_stream(
    self,
    key: KeyRef,
    payload: ByteStream,
    *,
    alg: Optional[Alg] = None,
    opts: Optional[Mapping[str, object]] = None,
) -> Sequence[Signature]:
    """
    Produce detached signatures over streaming byte payloads.

    Implementations MAY buffer the stream to reuse :meth:`sign_bytes`.
    """
    ...

verify_stream abstractmethod async

verify_stream(
    payload, signatures, *, require=None, opts=None
)

Source code in swarmauri_core/signing/ISigning.py

@abstractmethod
async def verify_stream(
    self,
    payload: ByteStream,
    signatures: Sequence[Signature],
    *,
    require: Optional[Mapping[str, object]] = None,
    opts: Optional[Mapping[str, object]] = None,
) -> bool: ...

canonicalize_envelope abstractmethod async

canonicalize_envelope(env, *, canon=None, opts=None)

Deterministically canonicalize an envelope to bytes prior to signing/verifying.

Implementations MUST document the exact canonicalization performed for each 'canon' token and ensure stable byte output for semantically identical envelopes.

Source code in swarmauri_core/signing/ISigning.py

@abstractmethod
async def canonicalize_envelope(
    self,
    env: Envelope,
    *,
    canon: Optional[Canon] = None,
    opts: Optional[Mapping[str, object]] = None,
) -> bytes:
    """
    Deterministically canonicalize an envelope to bytes prior to signing/verifying.

    Implementations MUST document the exact canonicalization performed for each
    'canon' token and ensure stable byte output for semantically identical envelopes.
    """
    ...

sign_envelope abstractmethod async

sign_envelope(key, env, *, alg=None, canon=None, opts=None)

Produce one or more detached signatures over a canonicalized envelope.

Source code in swarmauri_core/signing/ISigning.py

@abstractmethod
async def sign_envelope(
    self,
    key: KeyRef,
    env: Envelope,
    *,
    alg: Optional[Alg] = None,
    canon: Optional[Canon] = None,
    opts: Optional[Mapping[str, object]] = None,
) -> Sequence[Signature]:
    """
    Produce one or more detached signatures over a canonicalized envelope.
    """
    ...

verify_envelope abstractmethod async

verify_envelope(
    env, signatures, *, canon=None, require=None, opts=None
)

Verify detached signatures against the canonicalized envelope.

'require' can express policy such as:

Source code in swarmauri_core/signing/ISigning.py

@abstractmethod
async def verify_envelope(
    self,
    env: Envelope,
    signatures: Sequence[Signature],
    *,
    canon: Optional[Canon] = None,
    require: Optional[Mapping[str, object]] = None,
    opts: Optional[Mapping[str, object]] = None,
) -> bool:
    """
    Verify detached signatures against the canonicalized envelope.

    'require' can express policy such as:
      {"min_signers": 2, "algs": ["Ed25519", "RSA-PSS-SHA256"], "kids": ["..."]}
    """
    ...

verify_digest abstractmethod async

verify_digest(
    digest, signatures, *, require=None, opts=None
)

Verify detached signatures produced over a pre-computed digest.

Source code in swarmauri_core/signing/ISigning.py

@abstractmethod
async def verify_digest(
    self,
    digest: bytes,
    signatures: Sequence[Signature],
    *,
    require: Optional[Mapping[str, object]] = None,
    opts: Optional[Mapping[str, object]] = None,
) -> bool:
    """Verify detached signatures produced over a pre-computed digest."""
    ...