unbrowse 10.3.0 → 10.4.0

package/dist-sdk/client.d.ts

@@ -1,6 +1,7 @@
 import type { AccountMe, AccountCredits, ApiKeyCreateInput, ApiKeyCreateResponse, ApiKeyListResponse, ApiKeyRevokeResponse, ExecuteInput, ExecuteResponse, HealthResponse, RequestOptions, ResolveInput, ResolveResponse, SearchInput, SearchResponse, SponsorStatus, UnbrowseClientOptions } from "./types.js";
 import type { WorkerProxyCapabilities, WorkerProxyRequest, WorkerProxyResponse } from "./proxy-types.js";
 export declare class Unbrowse {
+    /** @deprecated web2 wrapper. Use `walletSigner` for web3-native auth. */
     readonly apiKey: string | undefined;
     readonly baseURL: string;
     readonly timeout: number;
@@ -8,6 +9,7 @@ export declare class Unbrowse {
     readonly logLevel: NonNullable<UnbrowseClientOptions["logLevel"]>;
     private readonly _fetch;
     private readonly defaultHeaders;
+    private readonly walletSigner;
     readonly account: AccountResource;
     readonly keys: KeysResource;
     readonly proxy: ProxyResource;

package/dist-sdk/client.js

@@ -4,6 +4,7 @@ const DEFAULT_TIMEOUT_MS = 60_000;
 const DEFAULT_MAX_RETRIES = 2;
 const SDK_VERSION = "7.0.0-preview.1";
 export class Unbrowse {
+    /** @deprecated web2 wrapper. Use `walletSigner` for web3-native auth. */
     apiKey;
     baseURL;
     timeout;
@@ -11,12 +12,21 @@ export class Unbrowse {
     logLevel;
     _fetch;
     defaultHeaders;
+    walletSigner;
     account;
     keys;
     proxy;
     constructor(opts = {}) {
         const env = readEnv();
+        // WEB3-NATIVE: wallet sig is PRIMARY (via walletSigner callback). The api-key
+        // Bearer is the deprecated web2 wrapper, kept for account-bound flow
+        // continuity. A wallet-only caller (no apiKey, walletSigner set)
+        // authenticates as `wallet:<pk>` on the backend — full principal.
         this.apiKey = opts.apiKey ?? env.UNBROWSE_API_KEY;
+        this.walletSigner = opts.walletSigner;
+        if (!this.apiKey && !this.walletSigner) {
+            throw new UnbrowseError("Unbrowse requires authentication. Pass `walletSigner` (web3-native, preferred) or `apiKey` (deprecated web2 wrapper).");
+        }
         this.baseURL = stripTrailingSlash(opts.baseURL ?? env.UNBROWSE_BASE_URL ?? DEFAULT_BASE_URL);
         this.timeout = opts.timeout ?? DEFAULT_TIMEOUT_MS;
         this.maxRetries = opts.maxRetries ?? DEFAULT_MAX_RETRIES;
@@ -55,6 +65,14 @@ export class Unbrowse {
             ...this.defaultHeaders,
             ...(opts.headers ?? {}),
         };
+        // WEB3-NATIVE auth: the wallet signature is the SOLE REQUIRED credential.
+        // The backend verifies the sig and authenticates as `wallet:<pk>` BEFORE
+        // any Bearer 401 path. The apiKey Bearer below is the deprecated web2
+        // wrapper, sent only when a legacy key is present.
+        if (this.walletSigner) {
+            const walletHeaders = await this.walletSigner();
+            Object.assign(headers, walletHeaders);
+        }
         if (this.apiKey)
             headers["Authorization"] = `Bearer ${this.apiKey}`;
         if (body !== undefined && method !== "GET")

package/dist-sdk/onboard.d.ts

@@ -22,9 +22,10 @@ export interface OnboardingStatus {
     nextStep: string;
 }
 /**
- * Ensure the agent has a usable identity, account-first then local wallet. When only a
- * local wallet exists and a `sync` is provided, the wallet is published onto an account.
- * Throws only when neither an account key nor a local wallet can be found (run setup).
+ * Ensure the agent has a usable identity, WALLET-FIRST. The wallet signature alone
+ * is a full credential on the backend (`wallet:<pk>` principal). An account-key, if
+ * present, is the optional web2 wrapper layered for payouts/sync continuity.
+ * Throws only when neither a local wallet nor an account key can be found (run setup).
  */
 export declare function ensureIdentity(opts?: OnboardOptions): Promise<Identity>;
 /** Report onboarding state + the single next step to show the user. */

package/dist-sdk/onboard.js

@@ -1,15 +1,17 @@
 /**
- * src/sdk/onboard.ts — identity onboarding for the hole.
+ * src/sdk/onboard.ts — identity onboarding for the agent.
  *
- * Best-practice credential chain, resolved in order:
- *   1. a BOUND ACCOUNT — an API key (from a frontend OAuth login or `unbrowse register`),
- *      which already carries payouts + sync;
- *   2. else the auto-created LOCAL SELF-CUSTODY WALLET (the keyless fallback every install
- *      gets — see src/values/signer.ts `ensureLocalWalletAddress`, surfaced at
- *      ~/.unbrowse/wallet.json), which can later be SYNCED onto an account.
+ * WEB3-NATIVE credential chain, resolved in order:
+ *   1. the LOCAL SELF-CUSTODY WALLET (the root identity every install gets —
+ *      src/values/signer.ts `ensureLocalWalletAddress`, surfaced at
+ *      ~/.unbrowse/wallet.json). The wallet signature authenticates as
+ *      `wallet:<pk>` on the backend — full principal, never key-gated.
+ *   2. else a BOUND ACCOUNT — a deprecated web2 api-key wrapper (from a frontend
+ *      OAuth login or `unbrowse register`), layered on top of the wallet to
+ *      carry account-bound flows (payouts accrual, dashboard sync).
  *
  * `onboardingStatus` reports what's configured and the one next step to tell the user.
- * Every input (api-key resolver, wallet peek, sync) is injectable so this is testable
+ * Every input (wallet peek, api-key resolver, sync) is injectable so this is testable
  * offline and embeddable in any frontend.
  */
 import { existsSync, readFileSync } from "node:fs";
@@ -35,26 +37,32 @@ function maskKey(key) {
     return key.length <= 10 ? key : `${key.slice(0, 4)}…${key.slice(-4)}`;
 }
 /**
- * Ensure the agent has a usable identity, account-first then local wallet. When only a
- * local wallet exists and a `sync` is provided, the wallet is published onto an account.
- * Throws only when neither an account key nor a local wallet can be found (run setup).
+ * Ensure the agent has a usable identity, WALLET-FIRST. The wallet signature alone
+ * is a full credential on the backend (`wallet:<pk>` principal). An account-key, if
+ * present, is the optional web2 wrapper layered for payouts/sync continuity.
+ * Throws only when neither a local wallet nor an account key can be found (run setup).
  */
 export async function ensureIdentity(opts = {}) {
-    const apiKey = (opts.resolveApiKey ?? defaultResolveApiKey)();
-    if (apiKey) {
-        return { kind: "account", id: maskKey(apiKey), synced: true };
-    }
     const wallet = (opts.peekWallet ?? defaultPeekWallet)();
     if (wallet) {
         const id = { kind: "wallet", id: wallet, synced: false };
-        if (opts.sync) {
+        const apiKey = (opts.resolveApiKey ?? defaultResolveApiKey)();
+        if (apiKey && opts.sync) {
             await opts.sync(id);
             id.synced = true;
         }
         return id;
     }
-    throw new Error("No identity yet. Run `unbrowse setup` to create a local self-custody wallet, " +
-        "or set UNBROWSE_API_KEY (`unbrowse register --email you@example.com`) to bind an account.");
+    // No wallet: legacy fallback to a web2 account-key (deprecated — agents
+    // without a wallet cannot sign the web3 auth challenge and will 401 on
+    // wallet-sig-required routes once the wrapper is fully retired).
+    const apiKey = (opts.resolveApiKey ?? defaultResolveApiKey)();
+    if (apiKey) {
+        return { kind: "account", id: maskKey(apiKey), synced: true };
+    }
+    throw new Error("No identity yet. Run `unbrowse setup` to create a local self-custody wallet " +
+        "(web3-native principal, preferred). Setting UNBROWSE_API_KEY (`unbrowse register`) " +
+        "binds a deprecated web2 account wrapper over the wallet.");
 }
 /** Report onboarding state + the single next step to show the user. */
 export function onboardingStatus(opts = {}) {
@@ -64,18 +72,22 @@ export function onboardingStatus(opts = {}) {
     const hasWallet = !!wallet;
     let identity = null;
     let nextStep;
-    if (hasAccount) {
-        identity = { kind: "account", id: maskKey(apiKey), synced: true };
-        nextStep = "You're set: a bound account handles sync, payouts, and paid routes.";
+    if (hasWallet && hasAccount) {
+        identity = { kind: "wallet", id: wallet, synced: true };
+        nextStep = "You're set: wallet is your principal, account-key wraps payouts/sync.";
     }
     else if (hasWallet) {
         identity = { kind: "wallet", id: wallet, synced: false };
         nextStep =
-            "Local self-custody wallet ready. Bind an account to sync earnings across machines: " +
-                "`unbrowse register --email you@example.com`.";
+            "Local self-custody wallet ready (web3-native principal). Optionally bind an account " +
+                "for payouts/sync: `unbrowse register --email you@example.com`.";
+    }
+    else if (hasAccount) {
+        identity = { kind: "account", id: maskKey(apiKey), synced: true };
+        nextStep = "Bound account-key only (deprecated web2 fallback). Run `unbrowse setup` to create a wallet.";
     }
     else {
-        nextStep = "Run `unbrowse setup` to create your local wallet (or set UNBROWSE_API_KEY).";
+        nextStep = "Run `unbrowse setup` to create your local wallet (the web3-native principal).";
     }
     return { identity, hasAccount, hasWallet, nextStep };
 }

package/dist-sdk/types.d.ts

@@ -129,7 +129,22 @@ export interface ApiKeyRevokeResponse {
     _request_id?: string;
 }
 export interface UnbrowseClientOptions {
+    /**
+     * @deprecated web2 web2 wrapper. The web3-native credential is the wallet
+     * signature (see `walletSigner`); a wallet-only caller authenticates as
+     * `wallet:<pk>` on the backend with no api-key. Kept for account-bound
+     * flow continuity during the wrapper's retirement window.
+     */
     apiKey?: string;
+    /**
+     * Web3-native auth signer. When set, the SDK calls it on every request and
+     * merges the returned headers (typically `X-Unbrowse-Wallet`,
+     * `X-Unbrowse-Auth-Ts`, `X-Unbrowse-Signature`) into the outbound request.
+     * The backend verifies the signature and authenticates as `wallet:<pk>`
+     * BEFORE any Bearer 401 path, so callers with NO api-key are full principals.
+     * Either `walletSigner` or `apiKey` MUST be set; `walletSigner` preferred.
+     */
+    walletSigner?: () => Promise<Record<string, string>>;
     baseURL?: string;
     timeout?: number;
     maxRetries?: number;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "unbrowse",
-  "version": "10.3.0",
+  "version": "10.4.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/unbrowse-ai/unbrowse.git"