component

workflow-plugin-signal

Signal protocol primitives for Workflow

Installation

wfctl plugin install workflow-plugin-signal

Development

# Build
make build

# Test
make test

# Install locally
make install-local

Step Types

• step.signal_session_prepare - create a public pre-key bundle for a local identity store.
• step.signal_public_prekey_publish - publish a host-owned public pre-key bundle for an intake ref.
• step.signal_public_prekey_resolve - resolve a public intake bundle by ref, with expiry and audience checks.
• step.signal_encrypt - encrypt plaintext into a Signal session envelope.
• step.signal_decrypt - decrypt an inbound Signal session envelope after the configured principal gate passes.
• step.signal_outbox_enqueue - queue a ciphertext envelope with sender, recipient, custody, authorization, and message refs.
• step.signal_outbox_claim - claim a queued outbox envelope for host transport without exposing plaintext.
• step.signal_inbox_receive - admit a ciphertext envelope into an inbox queue for a recipient ref.
• step.signal_inbox_decrypt - decrypt an inbox envelope only when the caller supplies custody and authorization refs.
• step.signal_blob_encrypt - encrypt blob bytes with a random content key and Signal-encrypt the blob manifest/key material to a recipient.
• step.signal_blob_decrypt - decrypt a Signal-encrypted blob manifest, verify ciphertext and digest metadata, and release plaintext only with custody and authorization refs.
• step.signal_fingerprint - compute a Signal safety number and scannable fingerprint from serialized identity public keys.
• step.signal_account_keys - derive account entropy, SVR, backup, backup-id, and PIN hash keys.
• step.signal_username_link_create - create an encrypted Signal username link payload.
• step.signal_username_link_decrypt - decrypt an encrypted Signal username link payload.
• step.signal_service_contract_check - validate the disabled/test-double official-service boundary and return upstream compatibility metadata.
• step.signal_service_compliance_check - report official-service readiness requirements, blocked live actions, and upstream service metadata without opening live transport.
• step.signal_service_policy_check - evaluate live-service approval metadata and requested actions without opening live transport.
• step.signal_service_approval_validate - validate machine-checkable live-service approval metadata and return denial reasons.
• step.signal_service_live_submit - submit fake/sandbox service operations through a registered transport or return a no-egress live denial/dry-run acceptance.
• step.signal_service_register_prepare - build a register operation envelope without submitting it, enriched from registered account/custody refs when available.
• step.signal_service_link_prepare - build a linked-device operation envelope with consent, revocation, and unlink proof metadata.
• step.signal_service_send_prepare - build a send operation envelope using recipient and payload refs only, with custody attestation metadata when account custody is registered.
• step.signal_service_receive_admit - build a receive admission envelope using cursor refs only, with custody attestation metadata when account custody is registered.
• step.signal_service_challenge_respond - build a challenge response envelope using challenge and response refs only, with custody attestation metadata when account custody is registered.
• step.signal_username_proof_prepare - report username proof readiness without reserving usernames.
• step.signal_backup_manifest_verify - report backup manifest readiness without uploading or downloading backups.
• step.signal_backup_auth_prepare - report backup auth readiness without opening service transport.
• step.signal_service_test_register - exercise deterministic fake registration with idempotency and ref-only outputs.
• step.signal_service_test_link_device - exercise deterministic fake linked-device setup with idempotency and ref-only outputs.
• step.signal_service_test_send - exercise deterministic fake sends, including challenge-required status.
• step.signal_service_test_receive - exercise deterministic fake receives with idempotency and ref-only outputs.
• step.signal_service_test_username_reserve - exercise deterministic fake username reservation with idempotency and ref-only outputs.
• step.signal_service_test_backup_upload - exercise deterministic fake backup upload with idempotency and ref-only outputs.
• step.signal_service_test_backup_download - exercise deterministic fake backup download with idempotency and ref-only outputs.
• step.signal_custody_create - create account/device custody refs and return sealed custody metadata.
• step.signal_custody_rotate - rotate custody KEK metadata while preserving ref-only outputs.
• step.signal_custody_restore - restore a sealed custody bundle through host-managed KEK refs.
• step.signal_custody_revoke - mark a custody ref revoked and return redacted audit metadata.
• step.signal_custody_inspect - inspect custody metadata without exposing key material.
• step.signal_custody_attest - return custody attestation and evidence refs for application policy checks.
• step.signal_custody_export_request - create ref-only export review metadata that remains approval-required.

Modules

• signal.identity_store - in-memory identity, pre-key, and session state for local composition and conformance tests.
• signal.envelope_store - memory or explicit local-file ciphertext queues for outbox/inbox application flows.
• signal.space - typed configuration surface for binding encrypted spaces to rooms/eventbus.
• signal.official_service_boundary - typed disabled/test-double boundary for selected upstream service wire shapes.
• signal.service_transport - registered fake, sandbox, or approval-gated live transport boundary.
• signal.live_policy - operation-specific approval and local operator-fixture policy metadata.
• signal.key_custody - host-managed key custody refs for exportable secret refs or non-exportable key handles.
• signal.persistent_custody - host-secret-backed encrypted local custody for non-exportable key handles.
• signal.custody_store - v2 custody-store contract with backend, KEK, schema, and storage metadata.
• signal.account_ref - account/device/consent/audit refs bound to host custody for fake official-service tests.
• signal.public_prekey_directory - local public intake directory for host-published pre-key bundles.
• trigger.signal_envelope - typed trigger-module contract for encrypted envelope transports.
• trigger.signal_service_envelope - typed trigger-module contract for service-envelope transports; no live stream is opened unless a host supplies an approved transport.

The built-in identity store remains in-memory for application composition and conformance testing. Production deployments should bind identities to signal.key_custody and host-managed persistence before relying on restart survival.

signal.public_prekey_directory provides a public-intake directory for Workflow apps such as website contact forms, support intake, private reports, and encrypted upload flows. A host app publishes an intake bundle with step.signal_public_prekey_publish; unauthenticated callers resolve it with step.signal_public_prekey_resolve and then use the existing encrypt/blob steps to send ciphertext. Directory outputs contain public bundle material, bundle hash, public identity-key fingerprint, expiry, audience, and redacted metadata only. The default backend is memory. The explicit file backend requires allow_file_backend: true and storage_path, writes a schema-versioned checksum snapshot through a temp-file plus rename sequence, and reloads published entries after restart. The http backend delegates storage to a host-managed service and is the only backend accepted under policy_mode: production. It requires endpoint_url, rejects URL userinfo, rejects plain http:// unless allow_insecure_http: true is set for local fixtures, and optionally sends an auth header by reading auth_header_env at call time and writing it to auth_header_name. request_timeout_ms defaults to 5000 and is capped at 60000.

The HTTP backend calls POST <endpoint_url>/entries with directory_ref, intake_ref, and an entry object containing bundle, public_metadata, bundle_sha256, and identity_key_fingerprint. Resolves call GET <endpoint_url>/entries/<path-escaped intake_ref> with optional audience_ref and requested_at_unix query parameters. Resolve responses use status: resolved with an entry, or not_found, expired, or audience_mismatch without an entry. The plugin recomputes bundle hashes and fingerprints, validates refs and audience/expiry, rejects denied responses that carry a bundle, and reports non-2xx failures by status code only. This module does not contact the official Signal service, implement one-time pre-key depletion, package a browser SDK, provide sealed sender, or solve intake abuse controls.

signal.envelope_store keeps queued outbox and inbox payloads as Signal ciphertext plus redacted routing metadata. The memory backend is intended for application composition and conformance tests. The local_file backend must be explicitly enabled, is rejected under production policy mode, and persists only ciphertext envelopes and refs. Inbox decrypt requires both custody and authorization refs before it delegates to the local Signal decrypt primitive.

step.signal_blob_encrypt and step.signal_blob_decrypt provide a local hybrid attachment pattern for Workflow apps. Blob bytes are encrypted with AES-256-GCM using a random content key; the content key, nonce, blob ref, plaintext digest, ciphertext digest, size, and media metadata live only inside a Signal-encrypted manifest envelope. The clear blob output contains ciphertext, nonce, size, and ciphertext digest so untrusted object stores, queues, and app routes can move bytes without seeing plaintext, plaintext digests, or content keys. Blob decrypt requires custody and authorization refs, validates the manifest against the blob, and fails on tampering. These steps do not implement official Signal attachment upload/download or any bundled production service egress.

signal.persistent_custody stores encrypted custody state in a host-selected file and registers only non-exportable key handles with Workflow. local_file requires both allow_local_file_custody: true and a host secret resolver. test_file is explicitly marked non-production and requires opt-in for conformance tests. Production policy mode rejects both file-backed custody backends; production hosts should provide approved KMS/HSM/security service refs instead of local files. Hermetic test://signal/... KEK refs derive deterministic test secrets only when no host resolver is configured.

signal.custody_store is the v2 custody contract for durable host-managed key custody. Its step contracts return custody refs and metadata only; plain key bytes are not ordinary Workflow outputs. Attestation and export-request steps return refs/evidence/status metadata for application policy checks and do not restore sealed material. The existing signal.persistent_custody module remains available for backward compatibility.

The scenarios/signal-custody-restart fixture covers the v2 custody lifecycle: create a sealed custody ref, reload the store after a simulated restart, restore by ref, rotate KEK metadata, inspect redacted metadata, revoke the ref, and reject restore after revocation. The scenario uses the test_file backend only; production hosts should use local_file with host-managed KEK custody. The standalone testdata/pipelines/signal-custody.yaml fixture is validated by make pipeline-test against a locally built plugin install. It can be executed through wfctl pipeline run only in hosts where external plugin loading is available for pipeline execution, or after installing the plugin into the host's normal plugin path. testdata/pipelines/signal-public-prekeys.yaml validates the public-intake publish/resolve contract against the same locally built external plugin.

Official Signal service registration, linked-device, send, and receive steps support deterministic libsignal-service-go/fake clients and host-supplied sandbox/operator fixtures. They return request IDs, statuses, challenge refs, and host secret refs; they do not register accounts, link devices, send messages, receive messages, reserve usernames, upload backups, download backups, or contact the official Signal service via any bundled production endpoint client. Official Signal service egress remains unavailable unless a host supplies an approved transport and a complete machine-checkable approval package.

Operation-specific *_prepare, receive_admit, and challenge_respond steps produce ServiceOperationEnvelope metadata for application composition and approval review. When signal.account_ref and signal.key_custody or signal.persistent_custody are registered, prepare steps inherit device, credential, consent, audit, custody, and non-exportable key refs, validate custody ownership, and return custody attestation metadata plus readiness warnings. Linked-device envelopes require display name, consent evidence, consent expiry, revocation URI, and unlink proof refs, and reject replayed or revoked ceremony artifacts. Username and backup steps expose readiness classifications rather than claiming upstream parity without vector proof.

step.signal_service_live_submit supports fake and sandbox transport exercises for register, linked device, send, receive, username reserve, backup upload/download, and challenge response operations. Live mode never invokes a bundled production endpoint. Incomplete approval packages return status: denied with approval_ready: false; complete approval packages without egress_dry_run return status: denied, approval_ready: true, and denial reason egress_dry_run_required; complete approval packages with egress_dry_run: true return status: dry_run_accepted, approval_ready: true, egress_dry_run: true, and live_egress_attempted: false without constructing a fake/sandbox transport.

scenarios/signal-service-operator-fixture documents the local operator-fixture path for operation-specific prepare/admit steps. The fixture uses loopback transport metadata only and remains default-deny for production egress. Optional official live smoke tests require an external operator approval package, account-owner consent, custody policy, abuse policy, audit policy, and endpoint allowlist supplied by the host application; they are not CI or release gates.

Module

Go module: github.com/GoCodeAlone/workflow-plugin-signal