Repository navigation
feat(node): production guard, hosted-form boot checks and the hosted-form presets - #84
Merged
Merged
Conversation
blink-admin
added this pull request to stack #88
September 10, 2026 20:20
grimen
force-pushed
the
feat/node-production
branch
from
September 10, 2026 20:28
ad2dcfe to
5a9b754
Compare
![github-advanced-security[bot]](https://avatars.githubusercontent.com/in/57789?s=60&v=4){kind=small}
grimen
marked this pull request as ready for review
September 10, 2026 22:03
blink-admin
previously approved these changes
Sep 10, 2026
grimen
dismissed
blink-admin’s stale review
September 10, 2026 22:14
The merge-base changed after approval.
… sources A deployment that says it is production must not run on demo settings. The new provider-agnostic guard (src/production.ts) keys on ESIGN_ENV alone - never NODE_ENV, which every Node image sets and CI smokes with the mock - and ESIGN_ALLOW_DEMO=true is the one explicit override. defaultRegistry now checks at selection time instead of on the first mutation: the DocuSign entry asserts the settings the host declared required (none by default, so existing hosts are unaffected) and refuses demo hosts in production; the mock entry refuses itself in production. The raw adapter the mock mirrors webhooks with stays unguarded. hostedFormProviderFromEnv is the one call a mint-only host makes: DocuSign by default, HOSTED_FORM_SETTINGS required, and the hosted-form capability checked. The DocuSign config gains the private-key sources a container deployment needs (DOCUSIGN_PRIVATE_KEY, then _BASE64, then _FILE, literal \n normalised in every path, the reader injectable so tests never touch disk) and the demo-host detection the guard reports with.
The mint-only surface, twice: as an Express router for a host that already
runs Express, and as one Fetch entry point for a Vercel route, a Worker or
a Node server. Both serve POST {path} (default /webform/instance), the
return-URL bridge the instance comes back to and a health check, and
nothing else - no envelope domain, no store, no webhook route.
They share their decisions: the mint route is mounted through one extracted
mountMintRoute, both go through mintWebFormInstanceHttp (so 401 / 400 with
the reason / 502 are identical), and both take the same prefill hook, which
receives the caller's validated prefill and returns the prefill actually
minted - client values are input, never trusted for a read-only field. Only
the request object differs: `req` on Express, `request` on Fetch.
Review round 1. An unreadable DOCUSIGN_PRIVATE_KEY_FILE threw a bare ENOENT
out of docuSignConfigFromEnv with no hint of which variable was at fault; it
is now rethrown as "DOCUSIGN_PRIVATE_KEY_FILE=<path>: <reason>", still
without any key material. The missing-configuration message names all three
accepted key sources when the key is what is missing, so an operator who set
_BASE64 or _FILE is not sent hunting DOCUSIGN_PRIVATE_KEY.
The DocuSign registry entry now reads its configuration once per selection
(a mounted PEM was read from disk twice) and threads the injectable reader
through defaultRegistry and hostedFormProviderFromEnv, where an explicit
`{ docusign: { required: undefined } }` no longer defeats the
HOSTED_FORM_SETTINGS default. The Fetch app's CORS answers all carry
`Vary: Origin`, so a shared cache cannot hand the header-less response to an
allow-listed origin.
mintWebFormInstanceHttp's catch-all mapped every thrown error from the
mint call - including a `prefill` hook rejecting the caller's own input -
to a generic 502 "Could not create signing session", indistinguishable
from a real provider/network failure. A hook now rejects a request by
throwing `Errors.validationError(message)` (-> 400 { error: message }) or
`Errors.unauthorized()` (-> 401 { error: 'Unauthorized' }); any other
thrown error still falls through to the unchanged 502 path and log line.
Documents the contract on HostedFormPrefillHook's doc comment, the
packages/esign-node README (the mint-only preset section and the route
table), and docs/upgrading.md (additive since 0.3). Tests added to
handlers.test.ts (direct mintWebFormInstanceHttp coverage: validation,
unauthorized, a coded-but-non-Error rejection, and an unrelated Error
still 502) and to both createHostedFormApp and createHostedFormRouter
(express.test.ts) so the hook-throws-validationError path is covered at
every layer that exposes it.
Scoped to packages/esign-node only so it can move into PR (a).
CodeQL high (js/insecure-temporary-file): the test covering the default
file reader wrote the PEM to `os.tmpdir()/esign-key-<pid>.pem`. That path is
predictable and the directory is world-writable, so another process can
pre-create the name, plant a symlink, or read what lands there - the shape of
the finding, even for a throwaway key in a test.
`fs.mkdtempSync(path.join(os.tmpdir(), 'esign-key-'))` instead: a fresh,
owner-only directory with an unguessable suffix, the key written inside it,
and `fs.rmSync(dir, { recursive: true, force: true })` in the finally. The
test itself is unchanged in what it proves - `privateKeyFromEnv` really does
read from disk when no reader is injected - and the package stays at 100%.
grimen
force-pushed
the
feat/node-production
branch
from
September 10, 2026 22:14
50400b6 to
b66933a
Compare
blink-admin
approved these changes
Sep 10, 2026
Merged
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Stack 2/5 (base:
refactor/rename-packages). Production hardening of@blinkbitcoin/esign-nodeplus two hosted-form presets, additive only.ESIGN_ENV=productionrefuses the mock provider and the DocuSign demo hosts unlessESIGN_ALLOW_DEMO=true. Keyed onESIGN_ENV, neverNODE_ENV.HOSTED_FORM_SETTINGScovers the JWT grant,DOCUSIGN_WEBFORM_IDandDOCUSIGN_RETURN_URLat selection time (a missing return URL used to fail silently: the form completed and the app never heard).DOCUSIGN_PRIVATE_KEY→_BASE64→_FILE, literal\nnormalised, read errors name the variable and never the key.hostedFormProviderFromEnv(env)for the mint-only shape.createHostedFormRouter(Express) andcreateHostedFormApp(Fetch): mint + return-URL bridge +/health, with aprefillhook so the host computes locked terms from its own data. A host rejects a mint by throwingErrors.validationError→ 400.README Configuration table and
docs/upgrading.mdupdated. 100% coverage kept.