rivetkit 2.3.20 → 2.3.21

package/dist/browser/client.js

@@ -220,7 +220,7 @@ function noopNext() {
 // package.json
 var package_default = {
   name: "rivetkit",
-  version: "2.3.20",
+  version: "2.3.21",
   description: "Lightweight libraries for building stateful actors on edge platforms",
   license: "Apache-2.0",
   keywords: [
@@ -433,6 +433,7 @@ var package_default = {
     "@rivet-dev/agent-os-core": "^0.1.1",
     "@rivet-dev/services": "^0.1.5",
     "@rivetkit/bare-ts": "^0.6.2",
+    "@rivetkit/engine-api-full": "workspace:*",
     "@rivetkit/engine-cli": "workspace:*",
     "@rivetkit/engine-envoy-protocol": "workspace:*",
     "@rivetkit/on-change": "6.0.1",
@@ -1145,6 +1146,73 @@ function deserializeActorKey(keyString) {
   return parts;
 }
 
+// src/client/token-provider.ts
+function isInvalidToken(group, code) {
+  return group === "auth" && (code === "invalid_token" || code === "token_expired");
+}
+function isInvalidTokenResponse(response) {
+  if (response.status !== 401) return false;
+  const error = response.headers.get("x-rivet-error");
+  if (!error) return false;
+  const separator = error.indexOf(".");
+  return separator > 0 && isInvalidToken(error.slice(0, separator), error.slice(separator + 1));
+}
+var TokenProvider = class {
+  constructor(getToken) {
+    this.getToken = getToken;
+  }
+  #cached;
+  #pending;
+  #pendingForce = false;
+  async current() {
+    if (this.#cached && (this.#cached.expiresAt === void 0 || Date.now() < this.#cached.expiresAt - 5e3)) {
+      return this.#cached.token;
+    }
+    return this.#load(false);
+  }
+  /** A late rejection for an older token must never erase a newer credential. */
+  async refreshIfCurrent(failedToken) {
+    if (this.#pending !== void 0) {
+      const wasForced = this.#pendingForce;
+      const refreshed = await this.#pending;
+      if (wasForced || refreshed !== failedToken) return refreshed;
+    }
+    if (this.#cached?.token !== failedToken) {
+      return this.current();
+    }
+    return this.#load(true);
+  }
+  #load(forceRefresh) {
+    if (this.#pending !== void 0) return this.#pending;
+    const pending = Promise.resolve().then(() => this.getToken({ forceRefresh })).then((token) => {
+      if (typeof token !== "string" || token.length === 0) {
+        throw new Error(
+          "getToken must resolve to a nonempty string"
+        );
+      }
+      this.#cached = { token, expiresAt: jwtExpiration(token) };
+      return token;
+    }).finally(() => {
+      if (this.#pending === pending) this.#pending = void 0;
+    });
+    this.#pending = pending;
+    this.#pendingForce = forceRefresh;
+    return pending;
+  }
+};
+function jwtExpiration(token) {
+  try {
+    const payload = token.split(".")[1];
+    if (!payload) return void 0;
+    const claims = JSON.parse(
+      atob(payload.replace(/-/g, "+").replace(/_/g, "/"))
+    );
+    return typeof claims.exp === "number" && Number.isSafeInteger(claims.exp) ? claims.exp * 1e3 : void 0;
+  } catch {
+    return void 0;
+  }
+}
+
 // src/common/actor-router-consts.ts
 var PATH_CONNECT = "/connect";
 var PATH_WEBSOCKET_BASE = "/websocket";
@@ -1230,6 +1298,25 @@ function buildGuardHeaders(runConfig, actorRequest, options) {
 // src/client/config.ts
 import z3 from "zod/v4";
 
+// src/common/engine.ts
+var ENGINE_HOST = "127.0.0.1";
+var ENGINE_PORT = 6420;
+var ENGINE_ENDPOINT = buildEngineEndpoint(ENGINE_HOST, ENGINE_PORT);
+function buildEngineEndpoint(host, port) {
+  const urlHost = host.includes(":") && !host.startsWith("[") ? `[${host}]` : host;
+  return `http://${urlHost}:${port}`;
+}
+function isLocalEngineEndpoint(endpoint) {
+  let url;
+  try {
+    url = new URL(endpoint);
+  } catch {
+    return false;
+  }
+  const hostname = url.hostname.toLowerCase();
+  return hostname === "localhost" || hostname === "0.0.0.0" || hostname === "::" || hostname === "[::]" || hostname === "::1" || hostname === "[::1]" || /^127(?:\.\d{1,3}){0,3}$/.test(hostname);
+}
+
 // src/utils/endpoint-parser.ts
 function tryParseEndpoint(ctx, options) {
   const {
@@ -1327,6 +1414,8 @@ var ClientConfigSchemaBase = z3.object({
   }),
   /** Token to use to authenticate with the API. */
   token: z3.string().optional().transform((val) => val ?? getRivetToken()),
+  /** Issue and renew a client token on demand. Overrides the static token when provided. */
+  getToken: z3.custom().optional(),
   /** Namespace to connect to. */
   namespace: z3.string().optional().transform((val) => val ?? getRivetNamespace()),
   /** Name of the envoy pool. This is used to group together envoys in to different pools. */
@@ -1368,7 +1457,7 @@ function transformClientConfig(config, ctx) {
     ...config,
     endpoint: parsedEndpoint?.endpoint,
     namespace: parsedEndpoint?.namespace ?? config.namespace ?? "default",
-    token: parsedEndpoint?.token ?? config.token
+    token: parsedEndpoint?.token ?? config.token ?? (config.endpoint && isLocalEngineEndpoint(config.endpoint) ? "default" : void 0)
   };
 }
 
@@ -1679,7 +1768,8 @@ async function openWebSocketToGateway(runConfig, gatewayUrl, encoding, params, o
   const ackHookToken = typeof process !== "undefined" && process.env.VITEST ? crypto.randomUUID() : void 0;
   logger3().debug({
     msg: "opening websocket to actor via guard",
-    gatewayUrl
+    // Gateway URLs can embed credentials; never include the path or query in logs.
+    origin: new URL(gatewayUrl).origin
   });
   const ws = new WebSocket2(
     gatewayUrl,
@@ -3865,7 +3955,8 @@ async function sendHttpRequest(opts) {
         {
           metadata: responseData.metadata,
           rayId: rayId ?? void 0,
-          actor: responseData.actor
+          actor: responseData.actor,
+          statusCode: response.status
         }
       );
     } catch (error) {
@@ -3946,6 +4037,14 @@ async function apiCall(config, method, path, body) {
 }
 
 // src/engine-client/api-endpoints.ts
+async function issueToken(config, options) {
+  return apiCall(config, "POST", "/auth/tokens", {
+    namespace: config.namespace,
+    subject: options.subject,
+    duration: options.expiresIn,
+    grants: options.grants
+  });
+}
 async function getActor(config, _, actorId) {
   return apiCall(
     config,
@@ -4183,6 +4282,8 @@ function closeWebSocketIfOpen(ws, code, reason) {
 var RemoteEngineControlClient = class {
   #config;
   #metadataPromise;
+  #tokenProvider;
+  #webSocketTokens = /* @__PURE__ */ new WeakMap();
   constructor(runConfig) {
     if (getNextPhase() === "phase-production-build") {
       logger3().info(
@@ -4191,6 +4292,8 @@ var RemoteEngineControlClient = class {
       runConfig.disableMetadataLookup = true;
     }
     this.#config = { ...runConfig };
+    if (runConfig.getToken)
+      this.#tokenProvider = new TokenProvider(runConfig.getToken);
     if (!runConfig.disableMetadataLookup) {
       this.#metadataPromise = lookupMetadataCached(this.#config).then(
         (metadataData) => {
@@ -4199,14 +4302,13 @@ var RemoteEngineControlClient = class {
             if (metadataData.clientNamespace) {
               this.#config.namespace = metadataData.clientNamespace;
             }
-            if (metadataData.clientToken) {
+            if (metadataData.clientToken && !this.#tokenProvider) {
               this.#config.token = metadataData.clientToken;
             }
             logger3().info({
               msg: "overriding client endpoint",
               endpoint: metadataData.clientEndpoint,
-              namespace: metadataData.clientNamespace,
-              token: metadataData.clientToken
+              namespace: metadataData.clientNamespace
             });
           }
           logger3().info({
@@ -4219,12 +4321,47 @@ var RemoteEngineControlClient = class {
       );
     }
   }
+  async #authorizedConfig() {
+    if (!this.#tokenProvider) return this.#config;
+    return { ...this.#config, token: await this.#tokenProvider.current() };
+  }
+  async #withCredential(request, readOnly = false) {
+    const config = await this.#authorizedConfig();
+    try {
+      return await request(config);
+    } catch (error) {
+      if (this.#tokenProvider && config.token && error instanceof RivetError && error.statusCode === 401 && isInvalidToken(error.group, error.code)) {
+        if (readOnly) {
+          const token = await this.#tokenProvider.refreshIfCurrent(
+            config.token
+          );
+          return request({ ...this.#config, token });
+        }
+        await this.#tokenProvider.refreshIfCurrent(config.token);
+      }
+      throw error;
+    }
+  }
+  async issueToken(options) {
+    await this.#metadataPromise;
+    const response = await this.#withCredential(
+      (config) => issueToken(config, options)
+    );
+    return {
+      token: response.token,
+      issuedAt: response.issued_ts,
+      expiresAt: response.expires_ts
+    };
+  }
   async getForId({
     name,
     actorId
   }) {
     await this.#metadataPromise;
-    const response = await getActor(this.#config, name, actorId);
+    const response = await this.#withCredential(
+      (config) => getActor(config, name, actorId),
+      true
+    );
     const actor = response.actors[0];
     if (!actor) return void 0;
     if (actor.name !== name) {
@@ -4245,7 +4382,10 @@ var RemoteEngineControlClient = class {
     await this.#metadataPromise;
     logger3().debug({ msg: "getWithKey: searching for actor", name, key });
     try {
-      const response = await getActorByKey(this.#config, name, key);
+      const response = await this.#withCredential(
+        (config) => getActorByKey(config, name, key),
+        true
+      );
       const actor = response.actors[0];
       if (!actor) return void 0;
       logger3().debug({
@@ -4278,16 +4418,18 @@ var RemoteEngineControlClient = class {
       key
     });
     try {
-      const { actor, created } = await getOrCreateActor(this.#config, {
-        datacenter: region,
-        name,
-        key: serializeActorKey(key),
-        runner_name_selector: poolName ?? this.#config.poolName,
-        input: actorInput ? uint8ArrayToBase64(
-          encodeCborCompat(actorInput)
-        ) : void 0,
-        crash_policy: crashPolicy ?? "sleep"
-      });
+      const { actor, created } = await this.#withCredential(
+        (config) => getOrCreateActor(config, {
+          datacenter: region,
+          name,
+          key: serializeActorKey(key),
+          runner_name_selector: poolName ?? this.#config.poolName,
+          input: actorInput ? uint8ArrayToBase64(
+            encodeCborCompat(actorInput)
+          ) : void 0,
+          crash_policy: crashPolicy ?? "sleep"
+        })
+      );
       logger3().info({
         msg: "getOrCreateWithKey: actor ready",
         actorId: actor.actor_id,
@@ -4303,7 +4445,10 @@ var RemoteEngineControlClient = class {
           name,
           key
         });
-        const response = await getActorByKey(this.#config, name, key);
+        const response = await this.#withCredential(
+          (config) => getActorByKey(config, name, key),
+          true
+        );
         const existing = response.actors[0];
         if (!existing) throw error;
         logger3().info({
@@ -4327,14 +4472,18 @@ var RemoteEngineControlClient = class {
   }) {
     await this.#metadataPromise;
     logger3().info({ msg: "creating actor via engine api", name, key });
-    const result = await createActor(this.#config, {
-      datacenter: region,
-      name,
-      runner_name_selector: poolName ?? this.#config.poolName,
-      key: serializeActorKey(key),
-      input: input ? uint8ArrayToBase64(encodeCborCompat(input)) : void 0,
-      crash_policy: crashPolicy ?? "sleep"
-    });
+    const result = await this.#withCredential(
+      (config) => createActor(config, {
+        datacenter: region,
+        name,
+        runner_name_selector: poolName ?? this.#config.poolName,
+        key: serializeActorKey(key),
+        input: input ? uint8ArrayToBase64(
+          encodeCborCompat(input)
+        ) : void 0,
+        crash_policy: crashPolicy ?? "sleep"
+      })
+    );
     logger3().info({
       msg: "actor created",
       actorId: result.actor.actor_id,
@@ -4346,43 +4495,60 @@ var RemoteEngineControlClient = class {
   async listActors({ name }) {
     await this.#metadataPromise;
     logger3().debug({ msg: "listing actors via engine api", name });
-    const response = await listActorsByName(this.#config, name);
+    const response = await this.#withCredential(
+      (config) => listActorsByName(config, name),
+      true
+    );
     return response.actors.map(apiActorToOutput);
   }
   async destroyActor(actorId) {
     await this.#metadataPromise;
     logger3().info({ msg: "destroying actor via engine api", actorId });
-    await destroyActor(this.#config, actorId);
+    await this.#withCredential((config) => destroyActor(config, actorId));
     logger3().info({ msg: "actor destroyed", actorId });
   }
   async sendRequest(target, actorRequest, options = {}) {
     await this.#metadataPromise;
-    const path = requestPath(actorRequest);
-    const gatewayUrl = this.#buildGatewayUrlForTarget(
-      target,
-      path,
-      options
-    );
+    const config = await this.#authorizedConfig();
     const httpOptions = {
       ...options,
       directActorId: shouldSkipReadyWait(options) ? directActorIdFromTarget(target) : void 0
     };
-    return sendHttpRequestToGateway(
-      this.#config,
-      gatewayUrl,
+    const send = (current) => sendHttpRequestToGateway(
+      current,
+      this.#buildGatewayUrlForTarget(
+        current,
+        target,
+        requestPath(actorRequest),
+        options
+      ),
       actorRequest,
       httpOptions
     );
+    const response = await send(config);
+    if (!this.#tokenProvider || !config.token || !isInvalidTokenResponse(response))
+      return response;
+    if ((actorRequest.method === "GET" || actorRequest.method === "HEAD") && !("getOrCreateForKey" in target)) {
+      const token = await this.#tokenProvider.refreshIfCurrent(
+        config.token
+      );
+      await response.body?.cancel();
+      return send({ ...this.#config, token });
+    }
+    await this.#tokenProvider.refreshIfCurrent(config.token);
+    return response;
   }
   async openWebSocket(path, target, encoding, params, options = {}) {
     await this.#metadataPromise;
+    const config = await this.#authorizedConfig();
     const gatewayUrl = this.#buildGatewayUrlForTarget(
+      config,
       target,
       path,
       options
     );
-    return openWebSocketToGateway(
-      this.#config,
+    const ws = await openWebSocketToGateway(
+      config,
       gatewayUrl,
       encoding,
       params,
@@ -4391,24 +4557,58 @@ var RemoteEngineControlClient = class {
         directActorId: shouldSkipReadyWait(options) ? directActorIdFromTarget(target) : void 0
       }
     );
+    this.#watchWebSocketAuth(ws, config.token);
+    return ws;
+  }
+  async refreshAuthToken(ws) {
+    const context2 = this.#webSocketTokens.get(ws);
+    if (!context2?.refresh) return false;
+    await context2.refresh;
+    return true;
+  }
+  #watchWebSocketAuth(ws, token) {
+    const tokenProvider = this.#tokenProvider;
+    if (!tokenProvider || !token) return;
+    const context2 = {};
+    this.#webSocketTokens.set(ws, context2);
+    ws.addEventListener(
+      "close",
+      (event) => {
+        if (event.code !== 1008 || !event.reason) return;
+        const separator = event.reason.indexOf(".");
+        if (separator < 0) return;
+        const code = event.reason.slice(separator + 1).split(/[\s:#]/, 1)[0];
+        if (isInvalidToken(event.reason.slice(0, separator), code)) {
+          context2.refresh = tokenProvider.refreshIfCurrent(token).catch((error) => {
+            logger3().warn(
+              "failed to renew authentication token"
+            );
+            throw error;
+          });
+          context2.refresh.catch(() => {
+          });
+        }
+      }
+    );
   }
   async buildGatewayUrl(target, options = {}) {
     await this.#metadataPromise;
-    return this.#buildGatewayUrlForTarget(target, "", options);
+    return this.#buildGatewayUrlForTarget(
+      await this.#authorizedConfig(),
+      target,
+      "",
+      options
+    );
   }
   async proxyRequest(_c, actorRequest, actorId) {
-    await this.#metadataPromise;
-    const gatewayUrl = this.#buildGatewayUrlForTarget(
-      { directId: actorId },
-      requestPath(actorRequest)
-    );
-    return sendHttpRequestToGateway(this.#config, gatewayUrl, actorRequest);
+    return this.sendRequest({ directId: actorId }, actorRequest);
   }
   async proxyWebSocket(c, path, actorId, encoding, params) {
     await this.#metadataPromise;
-    const upgradeWebSocket = this.#config.getUpgradeWebSocket?.();
+    const config = await this.#authorizedConfig();
+    const upgradeWebSocket = config.getUpgradeWebSocket?.();
     invariant3(upgradeWebSocket, "missing getUpgradeWebSocket");
-    const endpoint = getEndpoint(this.#config);
+    const endpoint = getEndpoint(config);
     const guardUrl = combineUrlPath(endpoint, path);
     const wsGuardUrl = guardUrl.replace("http://", "ws://");
     logger3().debug({
@@ -4418,7 +4618,7 @@ var RemoteEngineControlClient = class {
       guardUrl
     });
     const protocols = buildWebSocketProtocols(
-      this.#config,
+      config,
       encoding,
       params,
       void 0,
@@ -4436,8 +4636,8 @@ var RemoteEngineControlClient = class {
   setGetUpgradeWebSocket(getUpgradeWebSocket) {
     this.#config.getUpgradeWebSocket = getUpgradeWebSocket;
   }
-  #buildGatewayUrlForTarget(target, path, options = {}) {
-    const endpoint = getEndpoint(this.#config);
+  #buildGatewayUrlForTarget(config, target, path, options = {}) {
+    const endpoint = getEndpoint(config);
     if (shouldSkipReadyWait(options) && directActorIdFromTarget(target) && canUseDirectSkipReadyWaitPath(path)) {
       return combineUrlPath(endpoint, path);
     }
@@ -4445,7 +4645,7 @@ var RemoteEngineControlClient = class {
       return buildActorGatewayUrl(
         endpoint,
         target.directId,
-        this.#config.token,
+        config.token,
         path
       );
     }
@@ -4453,20 +4653,20 @@ var RemoteEngineControlClient = class {
       return buildActorGatewayUrl(
         endpoint,
         target.getForId.actorId,
-        this.#config.token,
+        config.token,
         path
       );
     }
     if ("getForKey" in target || "getOrCreateForKey" in target) {
       return buildActorQueryGatewayUrl(
         endpoint,
-        this.#config.namespace,
+        config.namespace,
         target,
-        this.#config.token,
+        config.token,
         path,
-        this.#config.maxInputSize,
+        config.maxInputSize,
         void 0,
-        "getOrCreateForKey" in target ? target.getOrCreateForKey.poolName ?? this.#config.poolName : void 0,
+        "getOrCreateForKey" in target ? target.getOrCreateForKey.poolName ?? config.poolName : void 0,
         options
       );
     }
@@ -4949,6 +5149,7 @@ var ActorConnRaw = class {
   /** Promise used to indicate the socket has connected successfully. This will be rejected if the connection fails. */
   #onOpenPromise;
   #websocket;
+  #authRetryAvailable = true;
   #client;
   #driver;
   #currentActorInvocation;
@@ -5191,6 +5392,10 @@ var ActorConnRaw = class {
     if (error instanceof ActorConnDisposed) {
       return false;
     }
+    if (error instanceof RivetError && isInvalidToken(error.group, error.code) && this.#driver.refreshAuthToken && this.#authRetryAvailable) {
+      this.#authRetryAvailable = false;
+      return true;
+    }
     if (error instanceof RivetError && this.#shouldReconnectForStaleActor(error.group, error.code)) {
       return true;
     }
@@ -5315,6 +5520,7 @@ var ActorConnRaw = class {
         messageQueueLength: this.#messageQueue.length,
         connId: this.#connId
       });
+      this.#authRetryAvailable = true;
       this.#setConnStatus("connected");
       if (this.#onOpenPromise) {
         this.#onOpenPromise.resolve(void 0);
@@ -5456,6 +5662,7 @@ var ActorConnRaw = class {
   }
   /** Called by the onclose event from drivers. */
   async #handleOnClose(event) {
+    const failedSocket = this.#websocket;
     const closeEvent = event;
     const wasClean = closeEvent.wasClean;
     const wasConnected = this.#connStatus === "connected";
@@ -5477,6 +5684,20 @@ var ActorConnRaw = class {
       const parsed = parseWebSocketCloseReason(reason);
       if (parsed) {
         const { group, code, rayId } = parsed;
+        if (isInvalidToken(group, code) && closeEvent.code === 1008 && failedSocket) {
+          try {
+            if (!await this.#driver.refreshAuthToken?.(
+              failedSocket
+            )) {
+              this.#authRetryAvailable = false;
+            }
+          } catch {
+            logger2().warn("token renewal failed");
+            this.#authRetryAvailable = false;
+          }
+        } else if (isInvalidToken(group, code)) {
+          this.#authRetryAvailable = false;
+        }
         if (this.#shouldReconnectForStaleActor(group, code)) {
           this.#clearResolvedActorIdentity();
           this.#onOpenPromise?.reject(
@@ -5526,7 +5747,7 @@ var ActorConnRaw = class {
       if (error instanceof RivetError) {
         this.#dispatchActorError(error);
       }
-      if (wasConnected) {
+      if (wasConnected && this.#authRetryAvailable) {
         logger2().debug({
           msg: "triggering reconnect",
           connId: this.#connId
@@ -6832,6 +7053,22 @@ var ActorHandleRaw = class {
       "dynamic actor resolution did not produce a direct actor id"
     );
   }
+  /** Issue a token scoped to this actor. Defaults to actor gateway read access. */
+  async issueToken(options = {}) {
+    const actorId = await this.resolve();
+    const permissions = options.permissions ?? {
+      actor_gateway: ["read"]
+    };
+    const grants = Object.keys(permissions).flatMap((resource) => {
+      const operations = permissions[resource];
+      return operations ? [{ resource, target: { id: actorId }, operations }] : [];
+    });
+    return this.#driver.issueToken({
+      subject: options.subject,
+      expiresIn: options.expiresIn,
+      grants
+    });
+  }
   /**
    * Returns the raw URL for routing traffic to the actor.
    */
@@ -6866,6 +7103,8 @@ var ACTOR_CONNS_SYMBOL = /* @__PURE__ */ Symbol("actorConns");
 var CREATE_ACTOR_CONN_PROXY = /* @__PURE__ */ Symbol("createActorConnProxy");
 var ClientRaw = class {
   #disposed = false;
+  /** Issue namespace-scoped tokens with an explicit grant list. */
+  auth;
   [ACTOR_CONNS_SYMBOL] = /* @__PURE__ */ new Set();
   #driver;
   #encodingKind;
@@ -6877,6 +7116,9 @@ var ClientRaw = class {
    */
   constructor(driver, options = {}) {
     this.#driver = driver;
+    this.auth = {
+      issueToken: (issueOptions) => this.#driver.issueToken(issueOptions)
+    };
     this.#encodingKind = options.encoding ?? "bare";
     this.#gatewayOptions = options.gateway ?? {};
     this.#currentActorInvocation = options.currentActorInvocation;