@joeywallet/wallet-sdk 0.2.0 → 0.3.0

package/README.md

@@ -372,32 +372,91 @@ that screen. Both are unambiguous; only the pair "transaction 2 of 5" next to
 
 ## Sign in
 
-`signIn` authenticates a user without a transaction. The default mode signs a
-[CAIP-122](https://namespaces.chainagnostic.org/xrpl/caip122) message under a
-non-transaction domain separator, so the signature is cryptographically
+`signIn` authenticates a user without a transaction. For a software account it
+signs a [CAIP-122](https://namespaces.chainagnostic.org/xrpl/caip122) message
+under a non-transaction domain separator, so the signature is cryptographically
 incapable of being replayed as a transaction signature.
 
+**It has two result shapes, and you must narrow before reading either.** Which
+one you get is the wallet’s decision, not yours: it depends on the account the
+user picks, and they pick it inside the wallet after your call has been made.
+
 ```ts
+import { isChallengeSignIn } from '@joeywallet/wallet-sdk'
+
 const result = await joey.signIn({
   statement: 'Sign in to Example Exchange',
   // nonce defaults to one the wallet generates; supply your own if your
   // backend issues it.
 })
 
-await fetch('/api/session', {
-  method: 'POST',
-  headers: { 'content-type': 'application/json' },
-  body: JSON.stringify({
-    address: result.address,
-    publicKey: result.publicKey,
-    message: result.message,
-    signature: result.signature,
-  }),
-})
+if (isChallengeSignIn(result)) {
+  // A hardware account. Verify the signed transaction.
+  await fetch('/api/session/tx', {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify({ address: result.address, signedTx: result.signedTx }),
+  })
+} else {
+  await fetch('/api/session', {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify({
+      address: result.address,
+      publicKey: result.publicKey,
+      message: result.message,
+      signature: result.signature,
+    }),
+  })
+}
+```
+
+Verify the CAIP-122 signature server-side against `result.message` and check the
+nonce, the domain and the issue time inside that message before trusting it.
+
+### Hardware accounts sign a transaction instead
+
+A Ledger cannot produce the result above. The XRP app signs transactions and has
+no message primitive at all, so there is no command to ask it for a CAIP-122
+signature. Rather than refuse the sign-in, the wallet proves ownership by having
+the device sign a canonical 1-drop Payment and hands you the signed transaction
+as `signedTx`.
+
+That transaction is built entirely by the wallet and is unsubmittable twice
+over: `Sequence` is `0`, which is never valid for a funded account, and the
+destination is the signing account itself, which `rippled` refuses as
+`temREDUNDANT`. Your challenge travels in a memo as
+`{"wallet":"joey","challenge":"<nonce>"}`, hex-encoded.
+
+`signedTx` is `JSON.stringify` of the **bare** decoded transaction — not wrapped
+in `{ tx_json: … }` — so `JSON.parse` it and use the result as a transaction
+object. To verify one, re-encode it and check the signature, then check the
+signer is the address you are about to trust:
+
+```ts
+import { encode } from 'ripple-binary-codec'
+import { verifySignature } from 'ripple-keypairs' // or your verifier of choice
+
+const tx = JSON.parse(signedTx)
+const ok = verifySignature(encode(tx)) // signatureValid, signedBy
+// Bind the session to the address that actually signed, never to one the
+// client claimed: without that check a valid signature made with any key can
+// mint a session for any account.
 ```
 
-Verify the signature server-side against `result.message` and check the nonce,
-the domain and the issue time inside that message before trusting it.
+This is byte-identical to what the Joey mobile wallet puts in a WalletConnect
+session's `xrpl_signin_v1_signed_tx`, so a backend that already verifies mobile
+Joey sign-ins verifies these unchanged.
+
+Narrow with `isChallengeSignIn`, which tests for the `signedTx` field rather
+than for `mode`. Wallets older than this shape send no `mode` at all, so a check
+written the other way round misroutes every one of them.
+
+> **If you skip the narrowing**, a verifier written for the CAIP-122 shape reads
+> `publicKey`, `message` and `signature` as `undefined`, posts them, and reports
+> "signature did not verify" — for a signature the user made correctly on their
+> device, seconds earlier. The failure is silent on the wallet side and looks
+> like a rejected login on yours.
 
 Pass `resources` to name the scope you are asking for. It is shown on the
 approval screen and written into the message's `Resources:` section, so it is

package/dist/index.d.ts

@@ -8,6 +8,6 @@ export { getJoey, isJoeyAvailable, requireJoey, resetJoeyDetection, waitForJoey,
 export { createJoeyClient, readAccounts, readChain, readNetwork, type Joey, } from './client.js';
 export { JOEY_ERROR_CODES, JoeyRpcError, isUserRejection, notInstalledError, userRejectedError, type JoeyErrorCode, } from './errors.js';
 export { APPROVAL_TIMEOUT_MS, CAIP294_ANNOUNCE_EVENT, CAIP294_PROMPT_EVENT, JOEY_DAPP_FORBIDDEN_TRANSACTION_TYPES, JOEY_RDNS, JOEY_RPC_METHODS, JOEY_WALLET_NAME, MAX_BULK_TRANSACTIONS, REQUEST_TIMEOUT_MS, WALLET_STANDARD_APP_READY_EVENT, WALLET_STANDARD_REGISTER_EVENT, invoke, isJoeyInjectedProvider, subscribe, type JoeyInjectedProvider, type JoeyProviderEventName, type JoeyRequestArguments, type JoeyRpcMethod, } from './provider.js';
-export { JOEY_CHAINS, chainForNetworkId, isJoeyChain, networkIdForChain, type Amount, type AnyTransaction, type ConnectParams, type ConnectResult, type IssuedCurrencyAmount, type JoeyAccount, type JoeyChain, type JoeyEventListener, type JoeyEventMap, type JoeyEventName, type JoeyNetwork, type Memo, type MPTAmount, type Path, type PathStep, type SignAndSubmitTransactionResult, type SigningContextParams, type SignInMode, type SignInParams, type SignInResult, type BulkEntryResult, type BulkEntryStatus, type SignTransactionBulkFailure, type SignTransactionBulkParams, type SignTransactionForParams, type SignTransactionParams, type SignTransactionResult, type Signer, type TransactionLike, } from './types.js';
+export { JOEY_CHAINS, chainForNetworkId, isChallengeSignIn, isJoeyChain, networkIdForChain, type Amount, type AnyTransaction, type ConnectParams, type ConnectResult, type IssuedCurrencyAmount, type JoeyAccount, type JoeyChain, type JoeyEventListener, type JoeyEventMap, type JoeyEventName, type JoeyNetwork, type Memo, type MPTAmount, type Path, type PathStep, type SignAndSubmitTransactionResult, type SigningContextParams, type Caip122SignInResult, type ChallengeSignInResult, type SignInMode, type SignInParams, type SignInResult, type BulkEntryResult, type BulkEntryStatus, type SignTransactionBulkFailure, type SignTransactionBulkParams, type SignTransactionForParams, type SignTransactionParams, type SignTransactionResult, type Signer, type TransactionLike, } from './types.js';
 export { initialMutationState, mutationReducer, toPublicState, type MutationAction, type MutationState, type MutationStatus, } from './mutation.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EACL,OAAO,EACP,eAAe,EACf,WAAW,EACX,kBAAkB,EAClB,WAAW,EACX,KAAK,kBAAkB,GACxB,MAAM,aAAa,CAAA;AAEpB,OAAO,EACL,gBAAgB,EAChB,YAAY,EACZ,SAAS,EACT,WAAW,EACX,KAAK,IAAI,GACV,MAAM,aAAa,CAAA;AAEpB,OAAO,EACL,gBAAgB,EAChB,YAAY,EACZ,eAAe,EACf,iBAAiB,EACjB,iBAAiB,EACjB,KAAK,aAAa,GACnB,MAAM,aAAa,CAAA;AAEpB,OAAO,EACL,mBAAmB,EACnB,sBAAsB,EACtB,oBAAoB,EACpB,qCAAqC,EACrC,SAAS,EACT,gBAAgB,EAChB,gBAAgB,EAChB,qBAAqB,EACrB,kBAAkB,EAClB,+BAA+B,EAC/B,8BAA8B,EAC9B,MAAM,EACN,sBAAsB,EACtB,SAAS,EACT,KAAK,oBAAoB,EACzB,KAAK,qBAAqB,EAC1B,KAAK,oBAAoB,EACzB,KAAK,aAAa,GACnB,MAAM,eAAe,CAAA;AAEtB,OAAO,EACL,WAAW,EACX,iBAAiB,EACjB,WAAW,EACX,iBAAiB,EACjB,KAAK,MAAM,EACX,KAAK,cAAc,EACnB,KAAK,aAAa,EAClB,KAAK,aAAa,EAClB,KAAK,oBAAoB,EACzB,KAAK,WAAW,EAChB,KAAK,SAAS,EACd,KAAK,iBAAiB,EACtB,KAAK,YAAY,EACjB,KAAK,aAAa,EAClB,KAAK,WAAW,EAChB,KAAK,IAAI,EACT,KAAK,SAAS,EACd,KAAK,IAAI,EACT,KAAK,QAAQ,EACb,KAAK,8BAA8B,EACnC,KAAK,oBAAoB,EACzB,KAAK,UAAU,EACf,KAAK,YAAY,EACjB,KAAK,YAAY,EACjB,KAAK,eAAe,EACpB,KAAK,eAAe,EACpB,KAAK,0BAA0B,EAC/B,KAAK,yBAAyB,EAC9B,KAAK,wBAAwB,EAC7B,KAAK,qBAAqB,EAC1B,KAAK,qBAAqB,EAC1B,KAAK,MAAM,EACX,KAAK,eAAe,GACrB,MAAM,YAAY,CAAA;AAEnB,OAAO,EACL,oBAAoB,EACpB,eAAe,EACf,aAAa,EACb,KAAK,cAAc,EACnB,KAAK,aAAa,EAClB,KAAK,cAAc,GACpB,MAAM,eAAe,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EACL,OAAO,EACP,eAAe,EACf,WAAW,EACX,kBAAkB,EAClB,WAAW,EACX,KAAK,kBAAkB,GACxB,MAAM,aAAa,CAAA;AAEpB,OAAO,EACL,gBAAgB,EAChB,YAAY,EACZ,SAAS,EACT,WAAW,EACX,KAAK,IAAI,GACV,MAAM,aAAa,CAAA;AAEpB,OAAO,EACL,gBAAgB,EAChB,YAAY,EACZ,eAAe,EACf,iBAAiB,EACjB,iBAAiB,EACjB,KAAK,aAAa,GACnB,MAAM,aAAa,CAAA;AAEpB,OAAO,EACL,mBAAmB,EACnB,sBAAsB,EACtB,oBAAoB,EACpB,qCAAqC,EACrC,SAAS,EACT,gBAAgB,EAChB,gBAAgB,EAChB,qBAAqB,EACrB,kBAAkB,EAClB,+BAA+B,EAC/B,8BAA8B,EAC9B,MAAM,EACN,sBAAsB,EACtB,SAAS,EACT,KAAK,oBAAoB,EACzB,KAAK,qBAAqB,EAC1B,KAAK,oBAAoB,EACzB,KAAK,aAAa,GACnB,MAAM,eAAe,CAAA;AAEtB,OAAO,EACL,WAAW,EACX,iBAAiB,EACjB,iBAAiB,EACjB,WAAW,EACX,iBAAiB,EACjB,KAAK,MAAM,EACX,KAAK,cAAc,EACnB,KAAK,aAAa,EAClB,KAAK,aAAa,EAClB,KAAK,oBAAoB,EACzB,KAAK,WAAW,EAChB,KAAK,SAAS,EACd,KAAK,iBAAiB,EACtB,KAAK,YAAY,EACjB,KAAK,aAAa,EAClB,KAAK,WAAW,EAChB,KAAK,IAAI,EACT,KAAK,SAAS,EACd,KAAK,IAAI,EACT,KAAK,QAAQ,EACb,KAAK,8BAA8B,EACnC,KAAK,oBAAoB,EACzB,KAAK,mBAAmB,EACxB,KAAK,qBAAqB,EAC1B,KAAK,UAAU,EACf,KAAK,YAAY,EACjB,KAAK,YAAY,EACjB,KAAK,eAAe,EACpB,KAAK,eAAe,EACpB,KAAK,0BAA0B,EAC/B,KAAK,yBAAyB,EAC9B,KAAK,wBAAwB,EAC7B,KAAK,qBAAqB,EAC1B,KAAK,qBAAqB,EAC1B,KAAK,MAAM,EACX,KAAK,eAAe,GACrB,MAAM,YAAY,CAAA;AAEnB,OAAO,EACL,oBAAoB,EACpB,eAAe,EACf,aAAa,EACb,KAAK,cAAc,EACnB,KAAK,aAAa,EAClB,KAAK,cAAc,GACpB,MAAM,eAAe,CAAA"}

package/dist/index.js

@@ -8,6 +8,6 @@ export { getJoey, isJoeyAvailable, requireJoey, resetJoeyDetection, waitForJoey,
 export { createJoeyClient, readAccounts, readChain, readNetwork, } from './client.js';
 export { JOEY_ERROR_CODES, JoeyRpcError, isUserRejection, notInstalledError, userRejectedError, } from './errors.js';
 export { APPROVAL_TIMEOUT_MS, CAIP294_ANNOUNCE_EVENT, CAIP294_PROMPT_EVENT, JOEY_DAPP_FORBIDDEN_TRANSACTION_TYPES, JOEY_RDNS, JOEY_RPC_METHODS, JOEY_WALLET_NAME, MAX_BULK_TRANSACTIONS, REQUEST_TIMEOUT_MS, WALLET_STANDARD_APP_READY_EVENT, WALLET_STANDARD_REGISTER_EVENT, invoke, isJoeyInjectedProvider, subscribe, } from './provider.js';
-export { JOEY_CHAINS, chainForNetworkId, isJoeyChain, networkIdForChain, } from './types.js';
+export { JOEY_CHAINS, chainForNetworkId, isChallengeSignIn, isJoeyChain, networkIdForChain, } from './types.js';
 export { initialMutationState, mutationReducer, toPublicState, } from './mutation.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EACL,OAAO,EACP,eAAe,EACf,WAAW,EACX,kBAAkB,EAClB,WAAW,GAEZ,MAAM,aAAa,CAAA;AAEpB,OAAO,EACL,gBAAgB,EAChB,YAAY,EACZ,SAAS,EACT,WAAW,GAEZ,MAAM,aAAa,CAAA;AAEpB,OAAO,EACL,gBAAgB,EAChB,YAAY,EACZ,eAAe,EACf,iBAAiB,EACjB,iBAAiB,GAElB,MAAM,aAAa,CAAA;AAEpB,OAAO,EACL,mBAAmB,EACnB,sBAAsB,EACtB,oBAAoB,EACpB,qCAAqC,EACrC,SAAS,EACT,gBAAgB,EAChB,gBAAgB,EAChB,qBAAqB,EACrB,kBAAkB,EAClB,+BAA+B,EAC/B,8BAA8B,EAC9B,MAAM,EACN,sBAAsB,EACtB,SAAS,GAKV,MAAM,eAAe,CAAA;AAEtB,OAAO,EACL,WAAW,EACX,iBAAiB,EACjB,WAAW,EACX,iBAAiB,GA8BlB,MAAM,YAAY,CAAA;AAEnB,OAAO,EACL,oBAAoB,EACpB,eAAe,EACf,aAAa,GAId,MAAM,eAAe,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EACL,OAAO,EACP,eAAe,EACf,WAAW,EACX,kBAAkB,EAClB,WAAW,GAEZ,MAAM,aAAa,CAAA;AAEpB,OAAO,EACL,gBAAgB,EAChB,YAAY,EACZ,SAAS,EACT,WAAW,GAEZ,MAAM,aAAa,CAAA;AAEpB,OAAO,EACL,gBAAgB,EAChB,YAAY,EACZ,eAAe,EACf,iBAAiB,EACjB,iBAAiB,GAElB,MAAM,aAAa,CAAA;AAEpB,OAAO,EACL,mBAAmB,EACnB,sBAAsB,EACtB,oBAAoB,EACpB,qCAAqC,EACrC,SAAS,EACT,gBAAgB,EAChB,gBAAgB,EAChB,qBAAqB,EACrB,kBAAkB,EAClB,+BAA+B,EAC/B,8BAA8B,EAC9B,MAAM,EACN,sBAAsB,EACtB,SAAS,GAKV,MAAM,eAAe,CAAA;AAEtB,OAAO,EACL,WAAW,EACX,iBAAiB,EACjB,iBAAiB,EACjB,WAAW,EACX,iBAAiB,GAgClB,MAAM,YAAY,CAAA;AAEnB,OAAO,EACL,oBAAoB,EACpB,eAAe,EACf,aAAa,GAId,MAAM,eAAe,CAAA"}

package/dist/types.d.ts

@@ -363,14 +363,70 @@ export interface SignInParams {
      */
     resources?: string[];
 }
-export interface SignInResult {
+/**
+ * What a software account answers with: a signature over a CAIP-122 message.
+ *
+ * `mode` is optional because wallets predating the second shape do not send
+ * it. Do not branch on it being `caip122` — branch on the *other* shape, with
+ * {@link isChallengeSignIn}, so an older wallet still takes this path.
+ */
+export interface Caip122SignInResult {
     address: string;
     publicKey: string;
     /** Hex-encoded signature. */
     signature: string;
     /** The exact string that was signed. Rebuild it to verify the signature. */
     message: string;
+    mode?: 'caip122';
+}
+/**
+ * What a hardware account answers with instead.
+ *
+ * A Ledger cannot produce the result above. The XRP app signs transactions and
+ * has no message primitive at all, so there is no command to ask it for a
+ * CAIP-122 signature — the wallet proves ownership by signing a canonical
+ * 1-drop Payment on the device instead, and hands you the signed transaction.
+ *
+ * The transaction is built entirely by the wallet and is unsubmittable twice
+ * over: `Sequence` is `0`, which is never valid for a funded account, and the
+ * destination is the signing account itself, which `rippled` refuses as
+ * `temREDUNDANT`. It carries your challenge in a memo, as
+ * `{"wallet":"joey","challenge":"<nonce>"}` hex-encoded.
+ *
+ * ## Verifying one
+ *
+ * `signedTx` is `JSON.stringify` of the *bare* decoded transaction — not
+ * wrapped in `{ tx_json: … }` — so `JSON.parse` it and use the result as a
+ * transaction object. Re-encode it with `ripple-binary-codec` and check the
+ * signature, then check the signer is the address you are about to trust.
+ *
+ * There is no `message` or `signature` field here, and that is the trap this
+ * type exists to close: a verifier written for the CAIP-122 shape reads three
+ * `undefined`s, sends them, and reports "signature did not verify" for a
+ * signature the user made correctly on their device.
+ */
+export interface ChallengeSignInResult {
+    address: string;
+    /** The bare signed transaction, JSON-encoded. */
+    signedTx: string;
+    mode: 'challenge-v1';
 }
+/**
+ * The result of {@link SignInParams}, in whichever form the account can make.
+ *
+ * Which one you get is the wallet’s decision and not yours: it depends on the
+ * account the user picks, and they pick it after your call has been made.
+ * Narrow with {@link isChallengeSignIn} before reading either shape.
+ */
+export type SignInResult = Caip122SignInResult | ChallengeSignInResult;
+/**
+ * Whether a sign-in came back as a signed transaction rather than a message.
+ *
+ * Tests for the field rather than for `mode`, deliberately: wallets older than
+ * the second shape send no `mode` at all, and a check written the other way
+ * round would misroute every one of them.
+ */
+export declare function isChallengeSignIn(result: SignInResult): result is ChallengeSignInResult;
 export interface JoeyEventMap {
     /** The origin became authorised. */
     connect: {

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -35,4 +35,14 @@ export function networkIdForChain(chain) {
         return null;
     return Number(chain.slice('xrpl:'.length));
 }
+/**
+ * Whether a sign-in came back as a signed transaction rather than a message.
+ *
+ * Tests for the field rather than for `mode`, deliberately: wallets older than
+ * the second shape send no `mode` at all, and a check written the other way
+ * round would misroute every one of them.
+ */
+export function isChallengeSignIn(result) {
+    return 'signedTx' in result;
+}
 //# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,gFAAgF;AAEhF,iFAAiF;AACjF,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,QAAQ,EAAE,QAAQ,EAAE,QAAQ,CAAU,CAAA;AAYlE,MAAM,UAAU,WAAW,CAAC,KAAc;IACxC,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAK,WAAiC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAA;AACxF,CAAC;AAED,sEAAsE;AACtE,MAAM,UAAU,iBAAiB,CAAC,SAAiB;IACjD,MAAM,KAAK,GAAG,QAAQ,SAAS,EAAE,CAAA;IACjC,IAAI,CAAC,WAAW,CAAC,KAAK,CAAC,EAAE,CAAC;QACxB,MAAM,IAAI,UAAU,CAAC,iCAAiC,SAAS,EAAE,CAAC,CAAA;IACpE,CAAC;IACD,OAAO,KAAK,CAAA;AACd,CAAC;AAED,oFAAoF;AACpF,MAAM,UAAU,iBAAiB,CAAC,KAAa;IAC7C,IAAI,CAAC,WAAW,CAAC,KAAK,CAAC;QAAE,OAAO,IAAI,CAAA;IACpC,OAAO,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAA;AAC5C,CAAC"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,gFAAgF;AAEhF,iFAAiF;AACjF,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,QAAQ,EAAE,QAAQ,EAAE,QAAQ,CAAU,CAAA;AAYlE,MAAM,UAAU,WAAW,CAAC,KAAc;IACxC,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAK,WAAiC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAA;AACxF,CAAC;AAED,sEAAsE;AACtE,MAAM,UAAU,iBAAiB,CAAC,SAAiB;IACjD,MAAM,KAAK,GAAG,QAAQ,SAAS,EAAE,CAAA;IACjC,IAAI,CAAC,WAAW,CAAC,KAAK,CAAC,EAAE,CAAC;QACxB,MAAM,IAAI,UAAU,CAAC,iCAAiC,SAAS,EAAE,CAAC,CAAA;IACpE,CAAC;IACD,OAAO,KAAK,CAAA;AACd,CAAC;AAED,oFAAoF;AACpF,MAAM,UAAU,iBAAiB,CAAC,KAAa;IAC7C,IAAI,CAAC,WAAW,CAAC,KAAK,CAAC;QAAE,OAAO,IAAI,CAAA;IACpC,OAAO,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAA;AAC5C,CAAC;AAwaD;;;;;;GAMG;AACH,MAAM,UAAU,iBAAiB,CAC/B,MAAoB;IAEpB,OAAO,UAAU,IAAI,MAAM,CAAA;AAC7B,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@joeywallet/wallet-sdk",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Dependency-free TypeScript SDK for the Joey Wallet browser extension (XLS-72d / Wallet Standard).",
   "license": "MIT",
   "homepage": "https://github.com/Joey-Wallet/joey-wallet-sdk#readme",

package/src/index.ts

@@ -54,6 +54,7 @@ export {
 export {
   JOEY_CHAINS,
   chainForNetworkId,
+  isChallengeSignIn,
   isJoeyChain,
   networkIdForChain,
   type Amount,
@@ -73,6 +74,8 @@ export {
   type PathStep,
   type SignAndSubmitTransactionResult,
   type SigningContextParams,
+  type Caip122SignInResult,
+  type ChallengeSignInResult,
   type SignInMode,
   type SignInParams,
   type SignInResult,

package/src/types.ts

@@ -413,13 +413,76 @@ export interface SignInParams {
   resources?: string[]
 }
 
-export interface SignInResult {
+/**
+ * What a software account answers with: a signature over a CAIP-122 message.
+ *
+ * `mode` is optional because wallets predating the second shape do not send
+ * it. Do not branch on it being `caip122` — branch on the *other* shape, with
+ * {@link isChallengeSignIn}, so an older wallet still takes this path.
+ */
+export interface Caip122SignInResult {
   address: string
   publicKey: string
   /** Hex-encoded signature. */
   signature: string
   /** The exact string that was signed. Rebuild it to verify the signature. */
   message: string
+  mode?: 'caip122'
+}
+
+/**
+ * What a hardware account answers with instead.
+ *
+ * A Ledger cannot produce the result above. The XRP app signs transactions and
+ * has no message primitive at all, so there is no command to ask it for a
+ * CAIP-122 signature — the wallet proves ownership by signing a canonical
+ * 1-drop Payment on the device instead, and hands you the signed transaction.
+ *
+ * The transaction is built entirely by the wallet and is unsubmittable twice
+ * over: `Sequence` is `0`, which is never valid for a funded account, and the
+ * destination is the signing account itself, which `rippled` refuses as
+ * `temREDUNDANT`. It carries your challenge in a memo, as
+ * `{"wallet":"joey","challenge":"<nonce>"}` hex-encoded.
+ *
+ * ## Verifying one
+ *
+ * `signedTx` is `JSON.stringify` of the *bare* decoded transaction — not
+ * wrapped in `{ tx_json: … }` — so `JSON.parse` it and use the result as a
+ * transaction object. Re-encode it with `ripple-binary-codec` and check the
+ * signature, then check the signer is the address you are about to trust.
+ *
+ * There is no `message` or `signature` field here, and that is the trap this
+ * type exists to close: a verifier written for the CAIP-122 shape reads three
+ * `undefined`s, sends them, and reports "signature did not verify" for a
+ * signature the user made correctly on their device.
+ */
+export interface ChallengeSignInResult {
+  address: string
+  /** The bare signed transaction, JSON-encoded. */
+  signedTx: string
+  mode: 'challenge-v1'
+}
+
+/**
+ * The result of {@link SignInParams}, in whichever form the account can make.
+ *
+ * Which one you get is the wallet’s decision and not yours: it depends on the
+ * account the user picks, and they pick it after your call has been made.
+ * Narrow with {@link isChallengeSignIn} before reading either shape.
+ */
+export type SignInResult = Caip122SignInResult | ChallengeSignInResult
+
+/**
+ * Whether a sign-in came back as a signed transaction rather than a message.
+ *
+ * Tests for the field rather than for `mode`, deliberately: wallets older than
+ * the second shape send no `mode` at all, and a check written the other way
+ * round would misroute every one of them.
+ */
+export function isChallengeSignIn(
+  result: SignInResult,
+): result is ChallengeSignInResult {
+  return 'signedTx' in result
 }
 
 /* -------------------------------------------------------------------- events */