Extend authorizeEntry signing callbacks: payload argument and custom signature ScVals by Ryang-21 · Pull Request #1549 · stellar/js-stellar-sdk

Ryang-21 · 2026-07-16T18:28:15Z

What

Extends authorizeEntry / authorizeInvocation signing callbacks in two ways:

The callback now receives the 32-byte signing payload (hash(preimage.toXDR())) as a second argument alongside the preimage, so signers that only accept a digest — HSMs, remote signers — never have to re-derive it. Existing single-argument callbacks are unaffected (#1532).
The callback may return { signatureScVal: xdr.ScVal, address?: string } instead of a raw 64-byte signature. The given ScVal is written verbatim as the credentials' signature — no Ed25519 verification, no {public_key, signature} map, no scvVec wrapping. The optional address routes the signature to a specific credential node, like forAddress (#1530).

Why

Custom account contracts (smart wallets, passkey/WebAuthn signers) define their own signature structure in __check_auth, so the SDK's Ed25519-only callback contract forced them to hand-roll preimage construction and credential assembly. With these two changes, authorizeEntry handles the preimage, expiration, and credential plumbing while the caller supplies whatever signature ScVal their contract expects.

The concrete WebAuthn helpers (buildWebAuthnSignatureScVal, normalizeSecp256r1Signature) were originally part of this PR but have been reverted; this PR now ships only the generic callback extensions.

…ture ScVals

… normalizer

Copilot

Pull request overview

Adds WebAuthn/passkey authorization support for Soroban entries.

Changes:

Extends signing callbacks with payload and custom ScVal support.
Adds secp256r1 normalization and WebAuthn signature builders.
Adds tests, exports, dependencies, and documentation.

Reviewed changes

Copilot reviewed 9 out of 10 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
`src/base/auth.ts`	Extends authorization callbacks and custom signatures.
`src/base/webauthn.ts`	Implements WebAuthn signature helpers.
`src/base/index.ts`	Exports the new APIs.
`test/unit/base/auth.test.ts`	Tests callback and custom-signature behavior.
`test/unit/base/webauthn.test.ts`	Tests normalization and ScVal construction.
`package.json`	Adds the test dependency.
`pnpm-lock.yaml`	Locks the dependency versions.
`docs/reference/core-transactions.md`	Documents WebAuthn APIs.
`docs/reference/core-soroban-primitives.md`	Updates authorization API reference.
`CHANGELOG.md`	Records the new functionality.

Files not reviewed (1)

pnpm-lock.yaml: Generated file

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

+  return nativeToScVal(
+    {
+      authenticator_data: toBytes(parts.authenticatorData),
+      client_data_json: toBytes(parts.clientDataJSON),
+      signature,


-    ) {
-      signature = toBuffer(sigResult.signature);
-      publicKey = sigResult.publicKey;
+    sigResult = await signer(preimage, payload);


+  if (sig.length === 64) {
+    let der: [bigint, bigint] | null = null;
+    if (sig[0] === 0x30) {
+      try {
+        der = parseDerSignature(sig);
+      } catch {


…struct docs

…r1Signature

# Conflicts: # CHANGELOG.md

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

socket-security · 2026-07-22T21:06:21Z

Review the following changes in direct dependencies. Learn more about Socket for GitHub.

Diff	Package	Supply Chain Security	Vulnerability	Quality	Maintenance	License
	@noble/curves@2.2.0

View full report

quietbits · 2026-07-23T19:03:43Z

+function signPayloadCallback(preimage, payload) {
+   // `payload` is hash(preimage.toXDR()) — inspect `preimage` if you want
+   // to display/verify what is being authorized before signing.
+   return signer.sign(payload);
 }


In this example, do we need to pass in preimage if we don't use it? It's only mentioned in the comment.

Callbacks to functions can be omitted. In the case of the preimage param you would need to pass an _ if you still needed access to payload.

Shaptic · 2026-07-23T20:39:15Z

 export type SigningCallback = (
  preimage: xdr.HashIdPreimage,
-) => Promise<BufferLike | { signature: BufferLike; publicKey: string }>;
+  payload: Buffer,


Suggested change

payload: Buffer,

payload?: Buffer,

Can we make this optional so the signature is non-breaking?

Did further digging since our convo. The params of a function callback can be omitted

Shaptic · 2026-07-23T20:42:21Z

+      await expect(
+        authorizeEntry(
+          authEntry,
+          () =>


Can you try actually assigning the callback like let callback: SigningCallback = () { ... } and see if it compiles? If it does then we don't need the optional.

I also verified locally that this works

Shaptic · 2026-07-23T20:47:27Z

Are we sure this hand-rolled cryptography belongs in the SDK? Can we use a library or have it live elsewhere?

Yeah I would agree that it does not belong. Thats been reverted

Shaptic · 2026-07-23T20:49:51Z

+
+// Differential check against @noble/curves (a well-reviewed reference
+// implementation): for many real P-256 signatures, our DER parsing +
+// low-S normalization must agree byte-for-byte with noble's.


If noble does this, lets use noble?

…1 normalizer

Ryang-21 added 4 commits July 16, 2026 10:00

feat(auth): pass signing payload to callbacks and accept custom signa…

71af1f7

…ture ScVals

feat(webauthn): add passkey signature ScVal builder and secp256r1 DER…

5609dbd

… normalizer

fix(webauthn): harden signature normalization per security review

c6cd94f

docs: regenerate reference docs for webauthn helpers

7841af3

Copilot AI review requested due to automatic review settings July 16, 2026 18:28

github-project-automation Bot moved this to Backlog (Not Ready) in DevX Jul 16, 2026

github-project-automation Bot added this to DevX Jul 16, 2026

Copilot started reviewing on behalf of Ryang-21 July 16, 2026 18:28 View session

Copilot AI reviewed Jul 16, 2026

View reviewed changes

Ryang-21 added 4 commits July 16, 2026 12:10

fix(auth): pass signing callback a copy of the payload buffer

8e6d2f4

fix(webauthn): add explicit signature format param and clarify inner-…

40efb29

…struct docs

refactor(webauthn): require explicit format param in normalizeSecp256…

d1cf5c2

…r1Signature

regen docs

ff71736

Ryang-21 requested review from Shaptic, kalepail and quietbits July 16, 2026 21:19

Ryang-21 and others added 2 commits July 22, 2026 14:04

Merge remote-tracking branch 'origin/main' into webauthn-auth-helpers

5642a46

# Conflicts: # CHANGELOG.md

docs: regenerate after merging main

c5f22a4

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

quietbits approved these changes Jul 23, 2026

View reviewed changes

Shaptic reviewed Jul 23, 2026

View reviewed changes

revert(webauthn): remove passkey signature ScVal builder and secp256r…

5e0d7dd

…1 normalizer

Ryang-21 changed the title ~~Add WebAuthn/passkey auth helpers: signature ScVal builder and secp256r1 normalizer~~ Extend authorizeEntry signing callbacks: payload argument and custom signature ScVals Jul 24, 2026

Merge branch 'main' into webauthn-auth-helpers

fd86840

Ryang-21 merged commit 9526bd3 into main Jul 24, 2026
12 checks passed

Ryang-21 deleted the webauthn-auth-helpers branch July 24, 2026 21:07

github-project-automation Bot moved this from Backlog (Not Ready) to Done in DevX Jul 24, 2026

Ryang-21 linked an issue Jul 27, 2026 that may be closed by this pull request

Expose auth-entry signing primitives as public APIs #1470

Closed

Ryang-21 mentioned this pull request Jul 31, 2026

Merge main into v17-feature-branch #1579

Merged

Navigation Menu

Uh oh!

Extend authorizeEntry signing callbacks: payload argument and custom signature ScVals - #1549

Extend authorizeEntry signing callbacks: payload argument and custom signature ScVals#1549
Ryang-21 merged 12 commits into
mainfrom
webauthn-auth-helpers

Ryang-21 commented Jul 16, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

socket-security Bot commented Jul 22, 2026 •

edited

Loading

Uh oh!

quietbits Jul 23, 2026

Uh oh!

Ryang-21 Jul 24, 2026

Uh oh!

Shaptic Jul 23, 2026

Uh oh!

Ryang-21 Jul 24, 2026

Uh oh!

Shaptic Jul 23, 2026

Uh oh!

Ryang-21 Jul 24, 2026

Uh oh!

Shaptic Jul 23, 2026

Uh oh!

Ryang-21 Jul 24, 2026

Uh oh!

Shaptic Jul 23, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Uh oh!

Conversation

Ryang-21 commented Jul 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What

Why

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

socket-security Bot commented Jul 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Ryang-21 commented Jul 16, 2026 •

edited

Loading

socket-security Bot commented Jul 22, 2026 •

edited

Loading