@fluent.xyz/connect 0.5.3 → 0.6.0-rc.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/INTEGRATION.md +43 -1429
- package/README.md +89 -285
- package/dist/fluent-connect.css +1 -1
- package/dist/index.d.ts +1024 -2885
- package/dist/index.js +11734 -10200
- package/dist/index.js.map +1 -1
- package/docs/api.md +1789 -0
- package/docs/concepts.md +126 -0
- package/docs/configuration.md +276 -0
- package/docs/errors.md +213 -0
- package/docs/experimental.md +247 -0
- package/docs/getting-started.md +336 -0
- package/docs/guides/backend-auth.md +176 -0
- package/docs/guides/iframe.md +108 -0
- package/docs/guides/link-x.md +166 -0
- package/docs/guides/signing.md +157 -0
- package/docs/guides/sponsorship.md +248 -0
- package/docs/guides/transactions.md +251 -0
- package/docs/upgrading-0.5.md +376 -0
- package/package.json +5 -2
|
@@ -0,0 +1,176 @@
|
|
|
1
|
+
# Backend auth
|
|
2
|
+
|
|
3
|
+
How an App's backend learns who the connected person is: the page asks the widget for an Auth
|
|
4
|
+
token, sends it to the backend, and the backend verifies it once and issues its own session from
|
|
5
|
+
it. The Widget session the render context carries (`session`) is not a credential: anyone can
|
|
6
|
+
put an address in a request. Only an Auth token proves who the person is. The terms used here are
|
|
7
|
+
defined in [concepts.md](../concepts.md).
|
|
8
|
+
|
|
9
|
+
## Get an Auth token
|
|
10
|
+
|
|
11
|
+
`getAuthToken()` is on the render context that `renderHome` and `renderPage` receive, and on the
|
|
12
|
+
object `useFluentWidget()` returns, in any component rendered inside `<FluentWidget>`. It takes
|
|
13
|
+
no arguments and resolves a string. Call it once `widget.account.executionReady` is `true`, for
|
|
14
|
+
a Fluent ID and for an External wallet alike.
|
|
15
|
+
|
|
16
|
+
```tsx
|
|
17
|
+
import {
|
|
18
|
+
FluentAuthError,
|
|
19
|
+
FluentWidget,
|
|
20
|
+
useFluentWidget,
|
|
21
|
+
type FluentWidgetConfig,
|
|
22
|
+
} from "@fluent.xyz/connect";
|
|
23
|
+
import { useState } from "react";
|
|
24
|
+
|
|
25
|
+
const config: FluentWidgetConfig = {
|
|
26
|
+
appId: "app_0123456789abcdef0123456789abcdef",
|
|
27
|
+
privyClientId: "client-0123456789abcdef",
|
|
28
|
+
network: "testnet",
|
|
29
|
+
};
|
|
30
|
+
|
|
31
|
+
function BackendSignIn() {
|
|
32
|
+
const { widget, getAuthToken } = useFluentWidget();
|
|
33
|
+
const [message, setMessage] = useState("");
|
|
34
|
+
if (!widget.account.executionReady) return null;
|
|
35
|
+
|
|
36
|
+
const signIn = async () => {
|
|
37
|
+
try {
|
|
38
|
+
const token = await getAuthToken();
|
|
39
|
+
// Your backend verifies the token and answers with its own session cookie.
|
|
40
|
+
const response = await fetch("/api/login", {
|
|
41
|
+
method: "POST",
|
|
42
|
+
headers: { Authorization: `Bearer ${token}` },
|
|
43
|
+
credentials: "include",
|
|
44
|
+
});
|
|
45
|
+
setMessage(response.ok ? "Signed in." : "The backend refused the token.");
|
|
46
|
+
} catch (error) {
|
|
47
|
+
if (!(error instanceof FluentAuthError)) throw error;
|
|
48
|
+
switch (error.code) {
|
|
49
|
+
case "request_failed":
|
|
50
|
+
setMessage("Could not get a token. Try again.");
|
|
51
|
+
break;
|
|
52
|
+
case "origin_not_allowed":
|
|
53
|
+
setMessage("This page's origin is not registered for the App.");
|
|
54
|
+
break;
|
|
55
|
+
default:
|
|
56
|
+
setMessage(`Sign-in failed (${error.code}).`);
|
|
57
|
+
}
|
|
58
|
+
}
|
|
59
|
+
};
|
|
60
|
+
|
|
61
|
+
return (
|
|
62
|
+
<div>
|
|
63
|
+
<button onClick={() => void signIn()}>Sign in to the backend</button>
|
|
64
|
+
<p>{message}</p>
|
|
65
|
+
</div>
|
|
66
|
+
);
|
|
67
|
+
}
|
|
68
|
+
|
|
69
|
+
export function App() {
|
|
70
|
+
return <FluentWidget config={config} mode="page" renderPage={() => <BackendSignIn />} />;
|
|
71
|
+
}
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
## What the token says
|
|
75
|
+
|
|
76
|
+
The Auth token is a JSON Web Token ([RFC 7519](https://www.rfc-editor.org/rfc/rfc7519)) that
|
|
77
|
+
Fluent signs with ES256, valid for five minutes. Its fields:
|
|
78
|
+
|
|
79
|
+
| Field | What it holds |
|
|
80
|
+
|---|---|
|
|
81
|
+
| `iss` | The issuer that signed the token. Pin the value Fluent gives you for each Network. |
|
|
82
|
+
| `aud` | The App's `appId`, the same string the widget's `config` carries. |
|
|
83
|
+
| `exp` | When the token stops verifying, in Unix seconds. |
|
|
84
|
+
| `sub` | The Client subject: the name the token gives the person, one per person per App and stable across logins. Key your user records on it. |
|
|
85
|
+
|
|
86
|
+
A verified token proves that Fluent issued it, at most five minutes ago, for this person and your
|
|
87
|
+
App. It is not a session: verify it once, at sign-in, and issue your own session from it.
|
|
88
|
+
|
|
89
|
+
## Renewal
|
|
90
|
+
|
|
91
|
+
Call `getAuthToken()` each time you need a token instead of keeping one. The widget keeps the
|
|
92
|
+
token it last obtained and returns it while it is more than `authTokenRenewalOffsetSeconds`
|
|
93
|
+
(default 30) from its `exp`; a call after that gets a new token. Calls made while a request for a
|
|
94
|
+
token is still out share that request.
|
|
95
|
+
|
|
96
|
+
A new token comes from the Service session, the sign-in the service holds for the person in this
|
|
97
|
+
browser for up to thirty days. A renewal the service accepts asks the person nothing, for a
|
|
98
|
+
Fluent ID and for an External wallet alike:
|
|
99
|
+
|
|
100
|
+
- A Fluent ID's Service session opens from its Direct login, with no prompt.
|
|
101
|
+
- An External wallet signs a Sign-in challenge when the Service session opens, and the
|
|
102
|
+
renewals that follow ask it for nothing. A challenge the service refuses as used, expired or
|
|
103
|
+
signed with a prefix it refuses is retried once with a fresh one, which is a second prompt.
|
|
104
|
+
The wallet is asked to sign again when the thirty days run out, when the service refuses the
|
|
105
|
+
stored refresh credential, or when there is none (the person disconnected, cleared site data,
|
|
106
|
+
or opened another browser).
|
|
107
|
+
|
|
108
|
+
When the service refuses the refresh credential, `getAuthToken()` does not reject for it: it
|
|
109
|
+
forgets the credential and opens a new Service session within the same call, which for an
|
|
110
|
+
External wallet means a Sign-in challenge prompt. The call then resolves or rejects with the
|
|
111
|
+
outcome of that new Service session.
|
|
112
|
+
|
|
113
|
+
An External wallet can sign the Sign-in challenge if it is an ordinary key-held account or a
|
|
114
|
+
deployed smart-contract wallet; a smart account that is not deployed yet cannot sign it.
|
|
115
|
+
|
|
116
|
+
Disconnecting through the widget (its account drawer, or `disconnect()` from the render context)
|
|
117
|
+
asks the service to end the Service session. When that request fails, the disconnect completes
|
|
118
|
+
anyway and the Service session can stay open at the service. An External wallet disconnected
|
|
119
|
+
from the wallet itself does not ask. A token already issued is not recalled: it keeps verifying
|
|
120
|
+
until its `exp`.
|
|
121
|
+
|
|
122
|
+
## Sponsorship uses the same token
|
|
123
|
+
|
|
124
|
+
When a Fluent ID's Batch operation asks for Sponsorship, the widget authenticates it to Fluent's
|
|
125
|
+
sponsorship service with an Auth token for the person and the App, from the same Service session
|
|
126
|
+
as the one `getAuthToken()` returns. You do not pass it yourself. An External wallet is never
|
|
127
|
+
sponsored, so Sponsorship never asks it to sign a Sign-in challenge. What happens when no token
|
|
128
|
+
can be obtained or the service refuses it is in [sponsorship.md](sponsorship.md).
|
|
129
|
+
|
|
130
|
+
## Verify the token on a backend
|
|
131
|
+
|
|
132
|
+
Verify every token before you trust it:
|
|
133
|
+
|
|
134
|
+
1. **The signature**, ES256, against the keys the issuer publishes at
|
|
135
|
+
`<iss>/.well-known/jwks.json`. Fetch the key set from there rather than copying a key into
|
|
136
|
+
your backend.
|
|
137
|
+
2. **`iss`**, equal to the issuer you pinned. Ask Fluent for the issuer of each Network your App
|
|
138
|
+
runs on and pin it in your backend's configuration; never build the key URL from the `iss` of
|
|
139
|
+
a token you have not verified yet.
|
|
140
|
+
3. **`aud`**, equal to your `appId`.
|
|
141
|
+
4. **`exp`**, in the future.
|
|
142
|
+
|
|
143
|
+
Then read `sub` and look up or create the person's record by it. The example below is a Node
|
|
144
|
+
backend using the [`jose`](https://github.com/panva/jose) library:
|
|
145
|
+
|
|
146
|
+
```ts skip-check
|
|
147
|
+
// A Node backend: it needs `jose`, which this repository does not install.
|
|
148
|
+
import { createRemoteJWKSet, jwtVerify } from "jose";
|
|
149
|
+
|
|
150
|
+
const APP_ID = "app_0123456789abcdef0123456789abcdef";
|
|
151
|
+
// The issuer Fluent gave you for the Network this backend serves.
|
|
152
|
+
const ISSUER = "https://issuer-from-fluent.example";
|
|
153
|
+
|
|
154
|
+
const keys = createRemoteJWKSet(new URL(`${ISSUER}/.well-known/jwks.json`));
|
|
155
|
+
|
|
156
|
+
/** The Client subject of a verified Auth token; throws when the token does not verify. */
|
|
157
|
+
export async function verifyAuthToken(token: string): Promise<string> {
|
|
158
|
+
// Checks the ES256 signature, `iss`, `aud` and `exp`.
|
|
159
|
+
const { payload } = await jwtVerify(token, keys, {
|
|
160
|
+
issuer: ISSUER,
|
|
161
|
+
audience: APP_ID,
|
|
162
|
+
algorithms: ["ES256"],
|
|
163
|
+
});
|
|
164
|
+
if (!payload.sub) throw new Error("The Auth token names no person.");
|
|
165
|
+
return payload.sub;
|
|
166
|
+
}
|
|
167
|
+
```
|
|
168
|
+
|
|
169
|
+
## When `getAuthToken()` rejects
|
|
170
|
+
|
|
171
|
+
It rejects with a `FluentAuthError` for every refusal the service or the External wallet gives;
|
|
172
|
+
every code it throws today, what each means and what to do is in
|
|
173
|
+
[errors.md](../errors.md#fluentautherror). Keep a `default` branch in your `switch` over `code`:
|
|
174
|
+
a later release may add one. Keep a fallback for other errors too: a failure to read a Fluent
|
|
175
|
+
ID's Direct-login credential arrives as it was thrown. A refused refresh credential is not among
|
|
176
|
+
the rejections, as [Renewal](#renewal) describes.
|
|
@@ -0,0 +1,108 @@
|
|
|
1
|
+
# Iframe bridge
|
|
2
|
+
|
|
3
|
+
How a page the App embeds in an `<iframe>` uses the Widget account as its wallet. The Iframe
|
|
4
|
+
bridge answers the embedded page's wallet requests with the widget: the same Widget account, the
|
|
5
|
+
same Review and the same Batch operations as the App's own requests. The terms used here are
|
|
6
|
+
defined in [concepts.md](../concepts.md).
|
|
7
|
+
|
|
8
|
+
## Set it up
|
|
9
|
+
|
|
10
|
+
Call `useFluentIframeBridge(iframeRef, { allowedOrigin })` in a component rendered inside
|
|
11
|
+
`<FluentWidget>`:
|
|
12
|
+
|
|
13
|
+
- `iframeRef` is a ref to the `<iframe>`, typed `RefObject<FluentIframeElement | null>`. A
|
|
14
|
+
`useRef<HTMLIFrameElement>(null)` fits it. `FluentIframeElement` is the element reduced to the
|
|
15
|
+
window the bridge replies to; the bridge reads it on every message, so an element swapped in
|
|
16
|
+
after mount is still answered.
|
|
17
|
+
- `allowedOrigin` is the exact origin the embedded page is served from, such as
|
|
18
|
+
`"https://market.example"`. It must be an `http:` or `https:` origin: `"*"` and a bare host are
|
|
19
|
+
refused, with an `Error` thrown from the effect that builds the bridge, so the nearest error
|
|
20
|
+
boundary catches it. Messages from any other origin, or from any window other than the
|
|
21
|
+
iframe's, are dropped without a reply: this is the only origin check in the exchange.
|
|
22
|
+
|
|
23
|
+
The bridge lives while the component is mounted. A request the embedded page sent before the
|
|
24
|
+
component unmounts is still answered, as long as the `<iframe>` element is still mounted.
|
|
25
|
+
|
|
26
|
+
```tsx
|
|
27
|
+
import {
|
|
28
|
+
FluentWidget,
|
|
29
|
+
useFluentIframeBridge,
|
|
30
|
+
type FluentWidgetConfig,
|
|
31
|
+
} from "@fluent.xyz/connect";
|
|
32
|
+
import { useRef } from "react";
|
|
33
|
+
|
|
34
|
+
const config: FluentWidgetConfig = {
|
|
35
|
+
appId: "app_0123456789abcdef0123456789abcdef",
|
|
36
|
+
privyClientId: "client-0123456789abcdef",
|
|
37
|
+
network: "testnet",
|
|
38
|
+
};
|
|
39
|
+
|
|
40
|
+
function Marketplace() {
|
|
41
|
+
const iframeRef = useRef<HTMLIFrameElement>(null);
|
|
42
|
+
useFluentIframeBridge(iframeRef, { allowedOrigin: "https://market.example" });
|
|
43
|
+
return (
|
|
44
|
+
<iframe
|
|
45
|
+
ref={iframeRef}
|
|
46
|
+
src="https://market.example/collection/cards"
|
|
47
|
+
title="Marketplace"
|
|
48
|
+
style={{ width: "100%", height: 640, border: 0 }}
|
|
49
|
+
/>
|
|
50
|
+
);
|
|
51
|
+
}
|
|
52
|
+
|
|
53
|
+
export function App() {
|
|
54
|
+
return <FluentWidget config={config} mode="page" renderPage={() => <Marketplace />} />;
|
|
55
|
+
}
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
## What the embedded page sends
|
|
59
|
+
|
|
60
|
+
The embedded page speaks JSON-RPC 2.0 over `postMessage`, the protocol of
|
|
61
|
+
`@ledgerhq/iframe-provider`: it posts a request to `window.parent`, and the bridge posts the
|
|
62
|
+
reply back with the same `id`, holding `result` or `error`. Events carry no `id`. A message
|
|
63
|
+
without an `id` gets no reply.
|
|
64
|
+
|
|
65
|
+
```json
|
|
66
|
+
{ "jsonrpc": "2.0", "id": 1, "method": "eth_requestAccounts", "params": [] }
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
Before its first reply the bridge posts `chainChanged` with the Network's chain id and
|
|
70
|
+
`accountsChanged` with the connected Widget account. After that, connecting and disconnecting
|
|
71
|
+
reach the iframe as `accountsChanged` (an empty list on disconnect).
|
|
72
|
+
|
|
73
|
+
## What the bridge answers
|
|
74
|
+
|
|
75
|
+
| Method | Answer |
|
|
76
|
+
|---|---|
|
|
77
|
+
| `eth_accounts`, `eth_requestAccounts`, `enable` | `widget.account.address` in a list, or `[]` when it is empty. It does not open the connect dialog. |
|
|
78
|
+
| `eth_chainId` | The chain id of the widget's Network. |
|
|
79
|
+
| `personal_sign` | `widget.signMessage(…)`; a hex message is signed as raw bytes. |
|
|
80
|
+
| `eth_signTypedData_v4`, `eth_signTypedData_v3`, `eth_signTypedData` | `widget.signTypedData(…)`. |
|
|
81
|
+
| `eth_sendTransaction` | One Batch operation with one call, `widget.createBatchOp({ calls }).execute()`, answered with the operation's `hash` once it is included. `to` is required; `data` and `value` are passed on; gas fields are ignored, because the widget prices the operation itself. |
|
|
82
|
+
| `eth_blockNumber`, `eth_call`, `eth_estimateGas`, `eth_feeHistory`, `eth_gasPrice`, `eth_getBalance`, `eth_getBlockByHash`, `eth_getBlockByNumber`, `eth_getCode`, `eth_getLogs`, `eth_getStorageAt`, `eth_getTransactionByHash`, `eth_getTransactionCount`, `eth_getTransactionReceipt`, `eth_maxPriorityFeePerGas`, `net_version` | Forwarded to the Network's chain as they are. |
|
|
83
|
+
|
|
84
|
+
The signing and sending methods must name the connected Widget account (`from`, or the address
|
|
85
|
+
parameter of a signature); the bridge never acts for any other address. Every other method is
|
|
86
|
+
refused. The bridge reads the account from `widget.account.address`, which can hold the address of
|
|
87
|
+
a Widget session from an earlier visit while `status` is not `"connected"`
|
|
88
|
+
([getting-started.md](../getting-started.md)).
|
|
89
|
+
|
|
90
|
+
A signature shows the Review as `widget.signMessage` and `widget.signTypedData` do, and an
|
|
91
|
+
`eth_sendTransaction` as the App's own Batch operations do: see
|
|
92
|
+
[concepts.md](../concepts.md#prompt-mode-and-silent-mode).
|
|
93
|
+
|
|
94
|
+
## Errors the embedded page receives
|
|
95
|
+
|
|
96
|
+
The bridge answers a failed request with an EIP-1193 or JSON-RPC error `{ code, message }`:
|
|
97
|
+
|
|
98
|
+
| `code` | When |
|
|
99
|
+
|---|---|
|
|
100
|
+
| `4001` | The person dismissed the Review of the signature or the Batch operation. |
|
|
101
|
+
| `4100` | `widget.account.address` is empty, or the request names another address. |
|
|
102
|
+
| `4200` | The method is not one of those above. |
|
|
103
|
+
| `-32602` | The parameters are malformed: a missing address, typed data, message, recipient or transaction object, or a value that is not hex. |
|
|
104
|
+
| `-32603` | Any other failure, with its message. A `FluentAuthError` arrives as `"<code>: <message>"`. |
|
|
105
|
+
|
|
106
|
+
An External wallet's refusal in its own prompt is the wallet's error, not a dismissed Review, so
|
|
107
|
+
it reaches the iframe as `-32603` with the wallet's message. On the App's side, the codes of the
|
|
108
|
+
errors the widget throws are in [errors.md](../errors.md#how-to-branch).
|
|
@@ -0,0 +1,166 @@
|
|
|
1
|
+
# Link X
|
|
2
|
+
|
|
3
|
+
How an App lets a person link an X account to their Widget account. The Linked X account is the one
|
|
4
|
+
the service has bound to the person: at most one per person, used for their reputation and, while a
|
|
5
|
+
Fluent ID is connected, for its Account avatar. Linking it is a single call with no widget screen
|
|
6
|
+
and no settings page. The terms used here are defined in [concepts.md](../concepts.md).
|
|
7
|
+
|
|
8
|
+
## The call
|
|
9
|
+
|
|
10
|
+
Two ways in, both inside `<FluentWidget>`:
|
|
11
|
+
|
|
12
|
+
- `useLinkX()` returns `linkX`, the call, and three values describing the last call: `status`,
|
|
13
|
+
`x` and `error`. Use it in a component: it also finishes a link after the return from X on its
|
|
14
|
+
own (see [The return from X](#the-return-from-x)).
|
|
15
|
+
- `linkX()` on the render context (or on `useFluentWidget()`) is the same call without that
|
|
16
|
+
state.
|
|
17
|
+
|
|
18
|
+
`linkX()` resolves a `FluentLinkXResult`:
|
|
19
|
+
|
|
20
|
+
- `{ status: "linked", x }` when the person has a Linked X account. `x` is a `FluentXAccount`:
|
|
21
|
+
`id`, `handle` and `avatarUrl`.
|
|
22
|
+
- `{ status: "redirecting" }` when the person has none and the browser has started leaving the
|
|
23
|
+
page for X. Code after the `await` still runs, briefly, enough to show a "taking you to X"
|
|
24
|
+
state, but the page is unloading: nothing on it may wait for the link to finish.
|
|
25
|
+
|
|
26
|
+
`useLinkX()`'s `status` is a `FluentLinkXStatus`:
|
|
27
|
+
|
|
28
|
+
| `status` | Meaning |
|
|
29
|
+
|---|---|
|
|
30
|
+
| `"idle"` | No call yet, or a link resumed on mount was discarded. |
|
|
31
|
+
| `"pending"` | A call is running. |
|
|
32
|
+
| `"redirecting"` | The browser is about to leave for X. |
|
|
33
|
+
| `"linked"` | The call resolved with the Linked X account, which is in `x`. |
|
|
34
|
+
| `"error"` | The last call was refused; the `FluentAuthError` is in `error`. |
|
|
35
|
+
|
|
36
|
+
`x` is `null` until a call in this component resolves `linked`, even for a person who linked X
|
|
37
|
+
earlier, and goes back to `null` while a later call runs or after it fails. For a person with a
|
|
38
|
+
Linked X account, `linkX()` resolves `linked` without leaving the page; an External wallet may
|
|
39
|
+
sign first ([An External wallet signs first](#an-external-wallet-signs-first)). For a person
|
|
40
|
+
with no Linked X account, `linkX()` leaves the page, so call it from a click and not on mount.
|
|
41
|
+
|
|
42
|
+
```tsx
|
|
43
|
+
import {
|
|
44
|
+
FluentWidget,
|
|
45
|
+
useFluentWidget,
|
|
46
|
+
useLinkX,
|
|
47
|
+
type FluentAuthError,
|
|
48
|
+
type FluentWidgetConfig,
|
|
49
|
+
} from "@fluent.xyz/connect";
|
|
50
|
+
|
|
51
|
+
const config: FluentWidgetConfig = {
|
|
52
|
+
appId: "app_0123456789abcdef0123456789abcdef",
|
|
53
|
+
privyClientId: "client-0123456789abcdef",
|
|
54
|
+
network: "testnet",
|
|
55
|
+
};
|
|
56
|
+
|
|
57
|
+
function describeLinkXError(error: FluentAuthError): string {
|
|
58
|
+
switch (error.code) {
|
|
59
|
+
case "user_rejected":
|
|
60
|
+
return "Linking was cancelled.";
|
|
61
|
+
case "linked_to_another_user":
|
|
62
|
+
return "That X account is already linked to another person.";
|
|
63
|
+
case "not_authenticated":
|
|
64
|
+
return "Connect first, then try again.";
|
|
65
|
+
case "bad_request":
|
|
66
|
+
return "Linking X failed. Please report it.";
|
|
67
|
+
case "link_failed":
|
|
68
|
+
return "Linking X failed. Try again.";
|
|
69
|
+
default:
|
|
70
|
+
return `Linking X failed (${error.code}).`;
|
|
71
|
+
}
|
|
72
|
+
}
|
|
73
|
+
|
|
74
|
+
function LinkXButton() {
|
|
75
|
+
const { status: widgetStatus } = useFluentWidget();
|
|
76
|
+
const { linkX, status, x, error } = useLinkX();
|
|
77
|
+
if (widgetStatus !== "connected") return null;
|
|
78
|
+
if (x) return <p>Linked as @{x.handle}</p>;
|
|
79
|
+
return (
|
|
80
|
+
<div>
|
|
81
|
+
<button
|
|
82
|
+
// The error is also kept in `error`, so the rejection needs no handling here.
|
|
83
|
+
onClick={() => void linkX().catch(() => undefined)}
|
|
84
|
+
disabled={status === "pending" || status === "redirecting"}
|
|
85
|
+
>
|
|
86
|
+
Link X
|
|
87
|
+
</button>
|
|
88
|
+
{error ? <p>{describeLinkXError(error)}</p> : null}
|
|
89
|
+
</div>
|
|
90
|
+
);
|
|
91
|
+
}
|
|
92
|
+
|
|
93
|
+
export function App() {
|
|
94
|
+
return <FluentWidget config={config} mode="page" renderPage={() => <LinkXButton />} />;
|
|
95
|
+
}
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
## The return from X
|
|
99
|
+
|
|
100
|
+
Linking X needs a round trip to X that leaves the page. `useLinkX()` finishes the link after
|
|
101
|
+
the return on its own: when a component using the hook mounts in the tab that started the link,
|
|
102
|
+
the hook calls `linkX()` without waiting for the widget's `status`: on mount for a Fluent ID,
|
|
103
|
+
once the wallet is connected for an External wallet. The call waits, with `status`
|
|
104
|
+
`"pending"`, until the person's Widget account is connected again, and `status` then moves to
|
|
105
|
+
`"linked"` with `x` set.
|
|
106
|
+
|
|
107
|
+
With the render context's `linkX()`, nothing public tells your page that it is a return from X,
|
|
108
|
+
so use `useLinkX()` for a link that leaves the page.
|
|
109
|
+
|
|
110
|
+
A link started in this tab by someone else, or a stale record of one, is discarded rather than
|
|
111
|
+
resumed. The render context's `linkX()` then does no work and rejects with `link_failed`; call
|
|
112
|
+
it again to start a link for the connected person. `useLinkX()` resuming on mount goes back to
|
|
113
|
+
`"idle"` with no error instead.
|
|
114
|
+
|
|
115
|
+
## An External wallet signs first
|
|
116
|
+
|
|
117
|
+
A Fluent ID already holds what the link needs. An External wallet can be asked for two
|
|
118
|
+
signatures, never an on-chain transaction: a message that logs it in to the provider behind
|
|
119
|
+
Direct login, unless that login is still live on the page, and the Sign-in challenge, when no
|
|
120
|
+
Service session is open for the wallet (see [backend-auth.md](backend-auth.md#renewal)). Both
|
|
121
|
+
come before the page leaves for X. The connected account, its kind and the wallet's Auth token
|
|
122
|
+
are unchanged by the link.
|
|
123
|
+
|
|
124
|
+
## The sequence
|
|
125
|
+
|
|
126
|
+
What happens for one link, and what your backend sees of it:
|
|
127
|
+
|
|
128
|
+
1. The person clicks, and your code calls `linkX()`.
|
|
129
|
+
2. For an External wallet only: the signatures of the previous section.
|
|
130
|
+
3. A person who already has X: the widget asks Fluent's service and resolves `linked`. Done.
|
|
131
|
+
4. Otherwise the call resolves `redirecting`, the browser leaves for X, and the person approves
|
|
132
|
+
the link there.
|
|
133
|
+
5. The browser comes back. Once the person's Widget account is connected again, `useLinkX()`
|
|
134
|
+
runs `linkX()` again; the widget sends the link to Fluent's service, authenticated with the
|
|
135
|
+
person's Auth token, and the call resolves `linked`.
|
|
136
|
+
|
|
137
|
+
Your backend receives none of the link's requests, and there is nothing for it to verify.
|
|
138
|
+
|
|
139
|
+
## What to ask Fluent for
|
|
140
|
+
|
|
141
|
+
Some of what linking X needs is configured for your App by Fluent, not by you. Ask Fluent to:
|
|
142
|
+
|
|
143
|
+
- **Enable Auth tokens for the App.** The request that finishes the link carries the person's
|
|
144
|
+
Auth token. When none can be obtained, for example because Auth tokens are not enabled for the
|
|
145
|
+
App or the page's origin is not registered, `linkX()` rejects with `link_failed` and keeps the
|
|
146
|
+
message of the Auth token's refusal.
|
|
147
|
+
- **Register every origin your page is served from**, for the App's Auth tokens and for Direct
|
|
148
|
+
login with the login client Fluent issued you (the experimental
|
|
149
|
+
[`privyClientId`](../experimental.md#privyclientid)).
|
|
150
|
+
|
|
151
|
+
## Rejections
|
|
152
|
+
|
|
153
|
+
`linkX()`, on the render context and from `useLinkX()`, rejects with a `FluentAuthError`. The
|
|
154
|
+
five codes it throws today are `user_rejected`, `linked_to_another_user`, `not_authenticated`,
|
|
155
|
+
`bad_request` and `link_failed`; what each means and what to do is in
|
|
156
|
+
[errors.md](../errors.md#fluentautherror). Keep a `default` branch in your `switch` over `code`:
|
|
157
|
+
a later release may add one.
|
|
158
|
+
|
|
159
|
+
- `user_rejected` covers the person saying no at X or closing the flow, and an External wallet
|
|
160
|
+
declining either signature when the wallet reports the refusal as one; a wallet error that
|
|
161
|
+
does not say so arrives as `link_failed`.
|
|
162
|
+
- `not_authenticated` covers an External wallet whose client is not ready yet: wait for
|
|
163
|
+
`widget.account.executionReady` to be `true` and call again.
|
|
164
|
+
|
|
165
|
+
`useLinkX()`'s `linkX` both rejects and keeps the error: `status` becomes `"error"` and `error`
|
|
166
|
+
holds the same `FluentAuthError`, so a component can render from state and ignore the rejection.
|
|
@@ -0,0 +1,157 @@
|
|
|
1
|
+
# Signing messages and typed data
|
|
2
|
+
|
|
3
|
+
The Widget API signs for the Widget account: `widget.signMessage` produces an EIP-191 signature,
|
|
4
|
+
`widget.signTypedData` an EIP-712 one. This guide covers the two calls, when the widget shows its
|
|
5
|
+
Review, how to verify a signature and the rejections. The terms
|
|
6
|
+
are defined in [concepts.md](../concepts.md); the declarations are in
|
|
7
|
+
[api.md](../api.md#fluentsignapi).
|
|
8
|
+
|
|
9
|
+
## The two calls
|
|
10
|
+
|
|
11
|
+
Both resolve with the signature as a `Hex` string, for the address in `widget.account.address`:
|
|
12
|
+
|
|
13
|
+
- `widget.signMessage({ message })` signs a message, a string or viem's `{ raw }` form.
|
|
14
|
+
- `widget.signTypedData({ domain, types, primaryType, message })` signs EIP-712 typed data, with
|
|
15
|
+
viem's types, so `message` is checked against `types`.
|
|
16
|
+
|
|
17
|
+
A Fluent ID is a smart account: its signature is an ERC-1271 signature, wrapped as ERC-6492
|
|
18
|
+
while the account is not yet deployed. An External wallet signs with its own key, an ECDSA
|
|
19
|
+
signature for an ordinary key-held account.
|
|
20
|
+
|
|
21
|
+
```tsx
|
|
22
|
+
import { FluentReviewRejectedError, fluentTestnet, useFluentWidget } from "@fluent.xyz/connect";
|
|
23
|
+
import { useState } from "react";
|
|
24
|
+
import type { Address } from "viem";
|
|
25
|
+
|
|
26
|
+
const exchange: Address = "0x4444444444444444444444444444444444444444";
|
|
27
|
+
|
|
28
|
+
export function SignOrder() {
|
|
29
|
+
const { widget } = useFluentWidget();
|
|
30
|
+
const [note, setNote] = useState("");
|
|
31
|
+
|
|
32
|
+
async function sign() {
|
|
33
|
+
const maker = widget.account.address;
|
|
34
|
+
if (!maker) return;
|
|
35
|
+
try {
|
|
36
|
+
const signature = await widget.signTypedData({
|
|
37
|
+
domain: {
|
|
38
|
+
name: "Marketplace",
|
|
39
|
+
version: "1",
|
|
40
|
+
chainId: fluentTestnet.id,
|
|
41
|
+
verifyingContract: exchange,
|
|
42
|
+
},
|
|
43
|
+
types: {
|
|
44
|
+
Order: [
|
|
45
|
+
{ name: "maker", type: "address" },
|
|
46
|
+
{ name: "price", type: "uint256" },
|
|
47
|
+
],
|
|
48
|
+
},
|
|
49
|
+
primaryType: "Order",
|
|
50
|
+
message: { maker, price: 100n },
|
|
51
|
+
});
|
|
52
|
+
setNote(signature);
|
|
53
|
+
} catch (error) {
|
|
54
|
+
if (error instanceof FluentReviewRejectedError) return; // the person said no
|
|
55
|
+
setNote(error instanceof Error ? error.message : "Signing failed.");
|
|
56
|
+
}
|
|
57
|
+
}
|
|
58
|
+
|
|
59
|
+
return (
|
|
60
|
+
<div>
|
|
61
|
+
<button type="button" onClick={() => void sign()}>
|
|
62
|
+
Sign the order
|
|
63
|
+
</button>
|
|
64
|
+
<p>{note}</p>
|
|
65
|
+
</div>
|
|
66
|
+
);
|
|
67
|
+
}
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
## When the Review is shown
|
|
71
|
+
|
|
72
|
+
The Review is the widget's own screen that shows what will be signed, with the page that asks,
|
|
73
|
+
and waits for the person to confirm or dismiss it.
|
|
74
|
+
|
|
75
|
+
| Widget account | `signMessage`, `signTypedData` | A Batch operation's `execute()` |
|
|
76
|
+
|---|---|---|
|
|
77
|
+
| Fluent ID, Quick sign off | The Review, then the signature. | The Review (Prompt mode), unless `confirmation` asks for Silent mode and `quickSign.whitelistAddresses` allows it. |
|
|
78
|
+
| Fluent ID, Quick sign on | No Review (Silent mode). | No Review, unless `confirmation` or `quickSign.whitelistAddresses` asks for one. |
|
|
79
|
+
| External wallet | The Review, then the wallet's own prompt. | No widget Review: the wallet's own prompt. |
|
|
80
|
+
|
|
81
|
+
Signatures take no option. Quick sign, `confirmation` and `quickSign.whitelistAddresses` are
|
|
82
|
+
described in [concepts.md](../concepts.md#prompt-mode-and-silent-mode); Batch operations
|
|
83
|
+
themselves in the [transactions guide](transactions.md).
|
|
84
|
+
|
|
85
|
+
## Verifying a signature
|
|
86
|
+
|
|
87
|
+
A Fluent ID's address belongs to a contract, and no private key stands behind it. Its signature
|
|
88
|
+
does not recover to its address with `ecrecover` (or viem's `recoverMessageAddress`), so a check
|
|
89
|
+
that compares a recovered address with the account fails. Verify with ERC-1271, and with
|
|
90
|
+
ERC-6492 for an account that is not yet deployed: viem's `verifyMessage` and `verifyTypedData` on
|
|
91
|
+
a public client of the Network handle both, and an External wallet's ECDSA signature too.
|
|
92
|
+
|
|
93
|
+
```ts
|
|
94
|
+
import { fluentTestnet } from "@fluent.xyz/connect";
|
|
95
|
+
import { createPublicClient, http, type Address, type Hex } from "viem";
|
|
96
|
+
|
|
97
|
+
const publicClient = createPublicClient({ chain: fluentTestnet, transport: http() });
|
|
98
|
+
|
|
99
|
+
export function isValidSignIn(address: Address, signature: Hex): Promise<boolean> {
|
|
100
|
+
return publicClient.verifyMessage({ address, message: "Sign in to Marketplace", signature });
|
|
101
|
+
}
|
|
102
|
+
```
|
|
103
|
+
|
|
104
|
+
**EIP-2612 `permit` and a Fluent ID.** A token's `permit` accepts a signature only when the token
|
|
105
|
+
can verify it for the owner's address. Many tokens verify it with `ecrecover` alone (OpenZeppelin's
|
|
106
|
+
`ERC20Permit` does), which needs a private key behind the owner's address; a Fluent ID has none,
|
|
107
|
+
so those tokens refuse its permit. A token whose `permit` also accepts ERC-1271 signatures can
|
|
108
|
+
accept one; check the token's contract. For a Fluent ID, put the `approve` call in the same Batch
|
|
109
|
+
operation as the call that spends, where the two land atomically
|
|
110
|
+
([example](transactions.md#example-approve-and-deposit-in-one-batch-operation)). An External
|
|
111
|
+
wallet that is an ordinary key-held account can sign a `permit` as any such account does.
|
|
112
|
+
|
|
113
|
+
## Rejections
|
|
114
|
+
|
|
115
|
+
| Error | `code` | When |
|
|
116
|
+
|---|---|---|
|
|
117
|
+
| `FluentReviewRejectedError` | `"signature_review_rejected"` | The person dismissed the Review. |
|
|
118
|
+
| `FluentAuthError` | `"not_connected"` | No Widget account is connected, or an External wallet is connected but its client is not ready yet. |
|
|
119
|
+
| `FluentAuthError` | `"root_signer_required"` | A guard for a Fluent ID: no configuration of the widget reaches it today. |
|
|
120
|
+
|
|
121
|
+
When the person refuses in an External wallet's own prompt, after confirming the Review, the
|
|
122
|
+
call rejects with the wallet's error. A Review replaced by a newer one, or closed because the
|
|
123
|
+
widget unmounted, rejects with a plain `Error`. Branch on the class with `instanceof` and on
|
|
124
|
+
`code`, and keep a `default` branch in every `switch` over a `code`: a later release may add one.
|
|
125
|
+
|
|
126
|
+
```ts
|
|
127
|
+
import {
|
|
128
|
+
FluentAuthError,
|
|
129
|
+
FluentReviewRejectedError,
|
|
130
|
+
type FluentBatchApi,
|
|
131
|
+
} from "@fluent.xyz/connect";
|
|
132
|
+
import type { Hex } from "viem";
|
|
133
|
+
|
|
134
|
+
export async function signOrExplain(
|
|
135
|
+
widget: FluentBatchApi,
|
|
136
|
+
message: string,
|
|
137
|
+
): Promise<Hex | string> {
|
|
138
|
+
try {
|
|
139
|
+
return await widget.signMessage({ message });
|
|
140
|
+
} catch (error) {
|
|
141
|
+
if (error instanceof FluentReviewRejectedError) return "You dismissed the signature.";
|
|
142
|
+
if (error instanceof FluentAuthError) {
|
|
143
|
+
switch (error.code) {
|
|
144
|
+
case "not_connected":
|
|
145
|
+
return "Connect first.";
|
|
146
|
+
default:
|
|
147
|
+
return `Signing failed (${error.code}).`;
|
|
148
|
+
}
|
|
149
|
+
}
|
|
150
|
+
// A wallet's own refusal, or a failure of the Signer.
|
|
151
|
+
return error instanceof Error ? error.message : "Something went wrong.";
|
|
152
|
+
}
|
|
153
|
+
}
|
|
154
|
+
```
|
|
155
|
+
|
|
156
|
+
Every code and what to do about it: [errors.md](../errors.md#fluentautherror) and
|
|
157
|
+
[errors.md](../errors.md#fluentreviewrejectederror).
|