Signing boundaries in self-hosted gateways.

A gateway that can move value has a political architecture even when the code is simple. Who holds the keys decides who is a vendor and who is an operator. This note explains how we drew that line in StablePay, and why we drew it so plainly.

Software or service?

Keys, RPC, and the database are not implementation details. They are the product. If the studio holds them, you bought a service. If you hold them, you bought software. The distinction has commercial, legal, and operational consequences, and it should be discoverable from the architecture, not the marketing.

The boundary sentence

We wrote one sentence and built to it: the customer operates the environment, the software records what it was asked to do, and the studio is not in the path of funds.

That sentence has to survive two very different conversations: one with counsel, who asks whether the studio is a custodian, and one with the on-call engineer, who asks where the key actually is at 2am. If the answer changes between those rooms, the architecture is lying.

Where the studio is

Outside the path of funds. It ships software and documentation. It holds no keys, runs no signer, and cannot move value on your behalf.

What the implementation rules out

• No hidden hosted signer. There is no fallback path where a studio-run service signs on your behalf.
• No "we can hold this for you" mode. Convenience features that require custody are not built.
• No dashboard that implies visibility we do not have. We cannot see a production wallet we do not run, and the interface does not pretend otherwise.
• No phone-home for funds. Operation does not depend on the studio being reachable.

Who is allowed to sign?

Once the boundary is drawn, the interesting question moves inward: inside your environment, who can trigger a signature, and how do you prove it later?

Separate intent from authority

The gateway records payment intents. Authority to move funds belongs to whoever operates your signing process. Keeping those separate means an application bug cannot, on its own, become a transfer.

Make approvals explicit

For flows like contractor settlement, the sequence at Helios Grid was: a field-close event created a payable, a supervisor approval authorised it, and only then did a payment intent exist. Each step had a named human or system, and each left a record.

Leave a trail

An audit trail is not a log dump. It is the ability to answer, months later: who approved this, under what policy, and what did the system do next?

A one-page threat model

Not a substitute for a security review — a way to keep the conversation concrete. For each row, name the control and the person who owns it.

Operating the boundary

Owning the boundary also means owning its hygiene. Our handover guidance is deliberately dull:

• Keep signing keys in a secret store, not in environment files committed to a repository.
• Restrict who can reach the signing process, and log every use.
• Rotate on a schedule and after any personnel change that warrants it.
• Test recovery: can you rebuild the gateway from backups without the studio?
• Apply patch releases; a fixed vulnerability you have not deployed is still a vulnerability.

What we do not claim

StablePay is not a custodian, not a bank, and does not provide legal or compliance services. Whether a given operating model meets your regulatory obligations is a question for your counsel.

Questions to ask any gateway vendor

1. Where do production signing keys live, and who can use them?
2. Can the vendor move funds on my behalf, even in an emergency?
3. If the vendor disappeared tomorrow, what stops working?
4. Which parts of the payment record can I query directly?
5. How would I prove, to an auditor, who approved a specific payment?

The key lifecycle

Keys are not a thing you have; they are a thing you manage across a life. NIST's key management guidance ^[1] describes the lifecycle in phases, and the useful takeaway for a payments team is that every phase needs an owner and a procedure, not just the moment of creation.

Where keys can live: a comparison

There is no single right place for a key, only trade-offs between convenience, isolation, and cost. The important discipline is choosing deliberately and being able to explain the choice.

Whichever tier you choose, the signing interface should be narrow. A service that only signs transactions matching a policy — allowed destinations, amount limits, and required approvals — is much safer than one that signs whatever it is handed. The OWASP guidance on secrets management ^[2] and cryptographic storage ^[5] is a solid baseline for the surrounding controls.

Separating intent from authority in practice

The gateway records what your application wants to happen. The signing process decides whether that is allowed. Keeping those apart means a bug in the application cannot, by itself, move value. A policy layer between them is where business rules become enforceable.

type Payout = { id: string; to: string; amount: bigint; approvals: string[] };

const policy = {
  maxSingle: 50_000n * 10n ** 6n,           // per-payout ceiling (token minor units)
  requiredApprovals: (amount: bigint) => (amount > 10_000n * 10n ** 6n ? 2 : 1),
  allowedDestinations: new Set<string>(loadVerifiedAddresses()),
};

export function authorise(p: Payout): { ok: true } | { ok: false; reason: string } {
  if (p.amount > policy.maxSingle) return { ok: false, reason: "exceeds single-payment limit" };
  if (!policy.allowedDestinations.has(p.to)) return { ok: false, reason: "destination not verified" };
  const needed = policy.requiredApprovals(p.amount);
  if (new Set(p.approvals).size < needed) return { ok: false, reason: `needs ${needed} distinct approvals` };
  return { ok: true };
}

Separation of duties

No single person should be able to both authorise and execute a payment. The concept is old and well defined ^[6]; the implementation is a table of who may do what, enforced in code and reviewed on a schedule.

What to log, and what never to

Audit logs are evidence. Ship them to storage that the signing process cannot modify, and alert on the events that should be rare: a signature outside business hours, a policy override, a new destination.

A key compromise runbook

Plan for the worst case while calm. The first hour of a suspected compromise is not the time to design a procedure.

1. 01

   Contain

   Disable the signing endpoint or revoke the credential. Stopping further use matters more than understanding how it happened.

2. 02

   Preserve evidence

   Snapshot logs and note the time. Do not rebuild the environment yet.

3. 03

   Assess exposure

   What could the key sign, and what has it signed since the suspected time?

4. 04

   Move remaining funds

   To a newly generated destination controlled under the new procedure, if the policy requires it.

5. 05

   Rotate everything downstream

   Anything that trusted the old key or that shared its storage.

6. 06

   Review and record

   A blameless review with actions and dates, and a note for counsel where appropriate.

Rehearse this. A tabletop exercise once or twice a year exposes missing contact details and unclear authority far more cheaply than a real incident.

Closing

The implementation follows the sentence. If you can draw the boundary on a whiteboard and defend it to both counsel and the on-call engineer, you have software. If you cannot, you have a service with a nicer interface.