Skip to content

Harden 1.8 encoding, request validation, and relay handling - #35

Merged
shocknet-justin merged 3 commits into
stagingfrom
tlv-encoder-length-limit
Nov 9, 2026
Merged

shocknet-justin merged 3 commits into
stagingfrom
tlv-encoder-length-limit

Conversation

@shocknet-justin

@shocknet-justin shocknet-justin commented Nov 6, 2026 •

Copy link
Copy Markdown
Member

Summary

Addresses the remaining SDK findings from the 1.8 consistency/security review, in addition to the original oversized-TLV encoder fix. Targets staging, the branch behind SDK 1.8 PR #32.

Encoding and Decoding

  • Reject TLV values larger than 255 bytes before their one-byte length can wrap. Applies to noffer, ndebit, and nmanage, including UTF-8 string byte lengths and crafted identifiers containing routing TLVs.
  • Require exactly 32 raw public-key bytes in all three pointer encoders, rejecting truncated and compressed-key inputs before producing an invalid pointer.
  • Encode offer prices losslessly through Number.MAX_SAFE_INTEGER rather than truncating to 32 bits. Existing nonzero unsigned-32-bit prices keep their four-byte representation; larger values use wider big-endian integers.
  • Reject negative, fractional, non-finite, unsafe, or empty price values instead of returning truncated amounts, rounded numbers, or NaN.
  • Preserve explicit zero prices as TLV 4 and enforce currency/price exclusion even for zero or empty currency strings.
  • Route nip19.decodeNostrURI through the same printable-ASCII check as nip19.decode, preserving the URI helper's invalid-result shape.
  • Retain the existing decoder fix for a TLV tag missing its length byte; that is separate from the encoder length guard.
  • Align the price-width contract in the interop corpus and spec PR 1.6.0: re-exports, session ndebits (k1), CI compat suite #18. Add five- and seven-byte published price vectors and test every published Bech32 vector directly.

Receipt Lifecycle and Relay Publication

  • Close subscriptions and clear timers immediately after payer-data discovery, other errors, and malformed/non-invoice primary responses, even when a receipt callback was supplied.
  • Wait for receipts only after an invoice response on the expected offer kind. Preserve successful receipt delivery and resubscription behavior.
  • Ignore stale callbacks, close subscriptions returned after synchronous callbacks, and clean up even if a receipt callback throws.
  • A failed relay no longer aborts another relay's successful publication. Reject only when every publication attempt fails; explicitly handle empty relay lists, empty publication results, and synchronous publish errors.
  • A late publication rejection cannot override an already accepted response. No automatic payment retries are introduced.

Shutdown and Cancellation

  • Stop() cancels this instance's active requests, receipt subscriptions, and timers before destroying the pool. Pending requests reject with AbortError; already-resolved invoices remain resolved and their receipt listeners stop.
  • Shutdown is terminal and idempotent. Calls after Stop() reject without reconnecting; enrollment cannot restart a beacon lookup, PoW retry, or publish after shutdown.
  • Per-instance cancellation avoids cancelling another SDK instance's request state when a pool is shared. An injected pool is still destroyed as before.
  • Standalone request/fetch functions accept an optional trailing AbortSignal, preserving caller-provided abort reasons. Cancellation stops SDK activity, not a payment that the host may already have accepted.

Validated Wire Payloads

  • Require supplied offer amount_sats to be a positive safe integer and expires_in_seconds to be a non-negative safe integer. Zero expiry remains permitted; invoice expiry is determined by the host.
  • Reject empty offer IDs and overlong descriptions before encryption or relay contact.
  • Offer/debit validators return detached, normalized objects. Recognized scalar values are read once; nested payer data and budget frequency are copied, undefined optional fields are omitted, and unknown top-level fields are discarded.
  • Encrypt the validated payload rather than serializing the original caller object. Caller-defined toJSON() methods and changing getters cannot substitute different offer or debit terms after validation.

Verification

  • npm test: 164 passed, 0 failed, including TypeScript build and public type checks.
  • Offline compatibility against SDK 1.7.4: 4 passed, 0 failed.
  • GitHub CI: unit, offline compatibility, and live-relay compatibility passed on the updated commit. Socket Security checks also passed.
  • Regression coverage includes receipt-error cleanup, synchronous/stale callbacks, partial/all relay failures, exact price bytes and safe-integer boundaries, URI lookalikes, invalid numeric wire values, and decrypted request payloads under custom serializers/getters.
  • Shutdown regressions cover waiting for a receipt, pending requests without timeouts, post-stop calls, stale/synchronous callbacks, staged enrollment, repeated shutdown, and abort-listener cleanup. Encoding tests cover invalid public-key lengths and published wide-price vectors.

Related Release Work

  • Pub's reserved amount/invoice payer-field fix is separate, on its offer-payer-data-quantity branch.
  • Pub pre-authorization invoice replay reasons are fixed separately in Return debit replay reasons before authorization Lightning.Pub#1078, targeting dash2.
  • Spec PR Specify k1 hold/release and GFY 6 reason tokens CLINK#19 clarifies that abandoned approval sessions may expire, but retention, timeout, or restart cannot clear replay protection for successful, in-flight, or unknown-outcome payouts.
  • Spec PR Offer payer_data discovery and quantity pricing CLINK#18 now defines the nonempty unsigned big-endian price integer, safe bounds, leading zeroes, and compatible encoding widths.
  • Manage create/update wire shape and required/optional field policy are intentionally unchanged pending a separate decision (review item 4). The only Manage change here is cancellation plumbing.
  • No package version, dependency, or protocol-version changes. Nothing is published, tagged, or merged by this PR. Pub's SDK dependency remains unchanged until the SDK release is cut.

@shocknet-justin shocknet-justin changed the title Reject oversized TLV values before encoding Harden 1.8 encoding, request validation, and relay handling Nov 8, 2026
@shocknet-justin
shocknet-justin merged commit e810010 into staging Nov 9, 2026
5 checks passed
@shocknet-justin
shocknet-justin deleted the tlv-encoder-length-limit branch November 9, 2026 17:43
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants