Design note · part of §2.5 SmartSigner in the design proposal · added 2026-07-02 per owner decision

Design Note: Signing Pathways

Every write operation in this node needs to get signed somehow. This page lays out the three ways that can happen. Scope note, straight from the source document: this describes the conceptual decision model only — the exact HIL/ApprovalNode message schema, how an "optionally attach a signature" field is carried on an approval reply, and how a workflow decides whether a given transaction category needs HIL at all, are implementation details left to the developer building this node, not specified here.

3 pathways Applies to every write operation Composes with SS04 multi-sig

The decision, at a glance

Which pathway a given write operation takes

flowchart TD
  START["A write operation needs to be signed
e.g. TA02 Send Tokens, DA02 Write Data"] --> Q1{"Already gated by an
automated check upstream?
(AML check, KYC check)"}
  Q1 -- "Yes — compliance already happened" --> P1["Pathway 1: Auto-sign
Agent's shared credential signs immediately,
no ApprovalNode / HIL step at all"]
  Q1 -- "No" --> AN["ApprovalNode step gates the transaction"]
  AN --> Q2{"Did the approver's reply already
carry their own signature?"}
  Q2 -- "Yes" --> P3["Pathway 3: Bring your own signature
SS05 submits the envelope as-is —
SmartSigner and the credential vault are never touched"]
  Q2 -- "No, node must sign on their behalf" --> Q3{"Sign with the approving user's
own vault credential, or the Agent's?"}
  Q3 -- "User's personal Ed25519 credential" --> P2a["Pathway 2a: node signs
as that specific human"]
  Q3 -- "Agent's shared credential" --> P2b["Pathway 2b: node signs
as the workflow/tenant, human approved the action"]

Pathway 1 — Auto-sign, no human approval

For transaction categories already gated by an automated check upstream in the workflow — the owner's own examples are an AML check or a KYC check — compliance already happened, just not via a human clicking "approve." The workflow skips ApprovalNode/HIL entirely and the node signs immediately using the Agent's credential (the workflow/tenant's own shared, non-personal credential). This is the same custodial signing every other operation in the SmartSigner resource already uses — resolved via SignerFactory/ICredentialResolver per the mandatory Credential Pattern — the only thing that varies is that no human was in the loop for this specific transaction.

Pathway 2 — HIL approval, no signature attached

An ApprovalNode step gates the transaction; the approving user clicks "approve" but does not supply their own signature in the reply. The node must still sign on someone's behalf — and there are two credential options here, both custodial, chosen per user/workflow configuration rather than hardcoded:

The approving user's own key — if that specific user has their own personal Ed25519 credential registered in BizFirst's credential vault, the system signs as that individual human, using a key that belongs to them personally.
The Agent's credentials, used optionally instead — the human approves the action, but the actual cryptographic signature comes from the workflow/tenant's shared signing key, not a key personally owned by the approver.

Pathway 3 — HIL approval, signature already attached

The approving user's reply already carries a signature they produced themselves, entirely outside this node — their own wallet, their own key custody. In this case no further signing is needed at all: the system recognizes a signature is already present and the transaction flows straight into SS05 (Submit Pre-Signed Transaction) — submit as-is and recognize the transaction's parameters — never touching SmartSigner, SignerFactory, or the credential vault for this transaction.

A per-transaction runtime decision, not a fixed property of an operation

The same TA02 Send Tokens, for example, could go through any of the three pathways above depending on whether HIL is configured for it and whether the approver brought their own signature. SS04 (multi-sig co-sign) composes with this too: each of the N required approvers independently goes through Pathway 2 or Pathway 3 for their own signature contribution — a workflow doesn't have to use the same pathway for every co-signer.

Why this is scoped the way it is

Decided 2026-07-02 — describe the model, defer the wiring

The owner's instruction, per the design proposal: describe how a user signs, but leave the actual HIL/ApprovalNode integration mechanics to the developer building this node. This page exists to make that decision model explicit and reviewable, without over-specifying a wire format or message schema that hasn't been designed yet.

SmartSigner resource · SS01–SS05, including SS05 (bring your own signature) and SS04 (multi-sig co-sign)
Open · does the SDK support decoding an arbitrary signed envelope back into structured parameters?

Pathway 3 depends on SS05's "recognize the transaction parameters" capability, which needs the reverse of what TxBody's factory methods do (encoding). See the SmartSigner page for the full open question on the SDK's Codec/ namespace.