Feature/request with auth

README.md

@@ -46,6 +46,10 @@ async function getMe() {
 }
 ```
 
+Every Mixin API request requires a keystore, including network queries and OAuth token exchange. `MixinApi({ keystore })` and individual clients require this argument; an Authorization header cannot replace it. Requests are signed automatically.
+
+Use `SessionKeystore` for signing credentials: `app_id`, `session_private_key`, and an optional `session_id`. Before login, a session may not have been issued, so its JWT `sid` is an empty string, matching the Go client. After OAuth login, use the existing `OAuthKeystore` with `authorization_id` and `scope`. `AppKeystore` and `NetworkUserKeystore` retain their additional PIN and Safe fields.
+
 2. Receive Mixin Messenger messages
 
 ```js
@@ -81,7 +85,10 @@ const client_secret = ''; // OAuth Client Secret of your bot
 
 const { seed, publicKey } = getED25519KeyPair(); // Generate random seed and ed25519 key pairs
 
-let client = MixinApi();
+// Sign the token exchange with the newly generated key before a session exists.
+let client = MixinApi({
+  keystore: { app_id, session_private_key: Buffer.from(seed).toString('hex') },
+});
 const { scope, authorization_id } = await client.oauth.getToken({
   client_id: app_id,
   code,

README.zh-CN.md

@@ -44,6 +44,10 @@ async function getMe() {
 }
 ```
 
+所有 Mixin API 请求（包括网络查询和 OAuth token 交换）都必须传入 keystore。`MixinApi({ keystore })` 和独立客户端均要求该参数，Authorization 请求头不能代替 keystore。SDK 会自动签名请求。
+
+请求签名使用 `SessionKeystore`：包含 `app_id`、`session_private_key` 和可选的 `session_id`。登录前尚未获取 session 时，JWT 的 `sid` 为空字符串，与 Go 客户端保持一致。OAuth 登录后使用已有的 `OAuthKeystore`，传入 `authorization_id` 和 `scope`。`AppKeystore` 和 `NetworkUserKeystore` 继续保留 PIN、Safe 操作需要的额外字段。
+
 2. 使用 Mixin 的消息功能
 
 ```js
@@ -79,7 +83,10 @@ const client_secret = ''; // OAuth Client Secret of your bot
 
 const { seed, publicKey } = getED25519KeyPair(); // Generate random seed and ed25519 key pairs
 
-let client = MixinApi();
+// 登录前使用刚生成的私钥为 token 交换请求签名，此时还没有 session。
+let client = MixinApi({
+  keystore: { app_id, session_private_key: Buffer.from(seed).toString('hex') },
+});
 const { scope, authorization_id } = await client.oauth.getToken({
   client_id: app_id,
   code,

example/scheme.js

@@ -1,9 +1,10 @@
 const { MixinApi } = require('../dist');
+const keystore = require('../keystore.json');
 
 const main = async () => {
   const url =
     'https://mixin.one/pay/MINAAAjAgICFJ4rl_85SKOyVF61rP1FStO-4jqB1EYukCoi2unvif8CbkgvwojeRRWr4UUrEd6-Z2YVLAszVTjvnsXK6X4pRyoKMC4wMDAwMDAwMQAJZXh0cmEgb25lAI7oV9hB2EfktLEwsvTmHQmWXlxuQ0w_qbeAxQ9DzZVcCjAuMDAwMDAwMDEACWV4dHJhIHR3bwEBAFguXmU';
-  const client = MixinApi();
+  const client = MixinApi({ keystore });
   const resp = await client.code.schemes(url);
   console.log(`https://mixin.one/schemes/${resp.scheme_id}`);
 };