Build and test a signing worker

Build a signing worker when nobody runs one for your provider yet. If your provider already runs one, skip to Connect a signing worker.

Before you start

• Qualified signatures enabled on your SignatureAPI account. Test mode works right away with the sandbox worker.
• A provider account with API access, ideally with a test environment.
• A public HTTPS host on port 443, with a certificate from a public certificate authority.
• A store for idempotency outcomes and seen token IDs, shared by all instances.

1. Choose your model

Answer three questions about your provider: does the signer already have a certificate, when does the provider identify them, and does its signing call return a bare value or a finished CMS? Choose your provider’s model turns the answers into a signature format and the calls your worker pauses.

Then follow the closest recipe for the provider calls behind each operation:

2. Build the endpoints

app.get("/v1/health", async (req, res) => {
    const providerUp = await provider.ping();
    res.status(200).json({
        status: providerUp ? "ok" : "degraded",
        connection_tokens: [...ALLOWED_CONNECTION_TOKENS],
    });
});

async function withIdempotency(key, bodySha256, run) {
    const stored = await store.get(`idem:${key}`);
    if (stored) {
        return stored.bodySha256 === bodySha256
            ? stored.outcome
            : conflict(`Idempotency-Key ${key} was used with a different payload`);
    }
    if (!(await store.reserve(`lock:${key}`))) {
        return conflict(`Idempotency-Key ${key} is currently executing`);
    }
    try {
        const outcome = await run();
        const final = outcome.status === "completed"
            || (outcome.status === "failed" && outcome.retryable !== true);
        if (final) await store.set(`idem:${key}`, { bodySha256, outcome });
        return outcome;
    } finally {
        await store.release(`lock:${key}`); // Only after the outcome is stored
    }
}

const operations = { credential, authorize, sign };

app.post("/v1/:operation", express.raw({ type: "application/json" }), async (req, res) => {
    const run = operations[req.params.operation];
    if (!run) return res.status(404).json({ error: "invalid_request", error_description: "unknown operation" });

    const auth = await authenticate(req.headers, req.body, req.params.operation);
    if (auth.error) return res.status(auth.status).json({ error: auth.error, error_description: auth.error_description });

    const outcome = await withIdempotency(auth.idempotencyKey, auth.bodySha256, () => run(auth.body));
    if (outcome.refusal) return res.status(409).json(outcome.refusal);
    res.status(200).json(outcome); // completed, pending or failed
});

3. Configure connection tokens

Your worker accepts only the accounts whose connection tokens you list. For each account you serve, including your own, open Connect Test Worker or Connect Live Worker (or a connected worker’s card), copy the Connection token, and add it to your worker’s configuration.

4. Test in test mode

Also test the paths that are easy to miss:

Disconnect your test worker to go back to the sandbox worker for comparison.

5. Go live

When every test passes:

1. Switch your worker to your provider’s production environment, with qualified certificates.
2. Add the account’s live connection token to your worker.
3. Connect the worker with Connect Live Worker.
4. Send a live envelope and check the signature in a validator. The signer should now show as trusted.

See Go live for the account requirements.

Go-live checklist

Check every line before you connect for live mode.

• Serve POST /v1/credential, /v1/authorize, /v1/sign and GET /v1/health on a public HTTPS URL, port 443, without redirects.
• List the connection tokens you accept in /v1/health, and refuse requests carrying any other.
• Verify ES256, iss, aud, exp, swp.operation, swp.session and swp.body_sha256. Remember each jti until exp plus your clock tolerance.
• Refuse a request without an Idempotency-Key with 400, after verifying its token.
• Answer every operation with 200 and completed, pending or failed.
• Return the full chain, signer certificate first, with honest key_algo_oids and expires_at. For cms, return the chain in sign, and in credential too if you have it.
• Declare "signature_format": "cms" if your provider returns a complete CMS, with a max_signature_size that covers its largest output.
• In key_algo_oids, list a SHA-256 algorithm before any other full signature algorithm.
• Pause credential or authorize only where your provider needs the signer, and set expires_at on a pending answer when the provider’s request expires sooner than the connection’s timeout.
• Answer each poll from the provider’s current state. Never send a second push for one session.
• Show each digest’s label on any approval screen you host.
• End a redirect step at callback_url, with a single-use code. Never answer a request carrying callback.code with pending.
• Follow the idempotency rules. Never sign twice for one key.
• Sign the right input and return the right encoding. For cms, meet the CMS requirements.
• Use only the listed error codes, or x_-prefixed ones.
• Write error_description for the signer. The ceremony shows it when the session fails.
• Never log request bodies.