@agenthifive/openclaw 0.1.0

package/dist/vault-token-manager.js

@@ -0,0 +1,124 @@
+import { importES256Key, exchangeToken } from "./jwt-utils.js";
+export class VaultTokenManager {
+    baseUrl;
+    agentId;
+    privateKeyJWK;
+    tokenAudience;
+    privateKeyObj = null;
+    accessToken = null;
+    tokenExpiresAt = 0; // epoch ms
+    refreshTimer = null;
+    refreshInFlight = null;
+    /** Called after every successful token refresh with the new token. */
+    onRefresh = null;
+    /** Called when token refresh fails with 401 — indicates the agent's key is no longer valid. */
+    onAuthFailure = null;
+    constructor(config) {
+        this.baseUrl = config.baseUrl.replace(/\/+$/, "");
+        this.agentId = config.agentId;
+        this.privateKeyJWK = config.privateKey;
+        this.tokenAudience = (config.tokenAudience ?? this.baseUrl).replace(/\/+$/, "");
+    }
+    /**
+     * Perform the initial token exchange and start the background refresh timer.
+     * Must be called (and awaited) before getToken().
+     */
+    async init() {
+        // Import the JWK once
+        this.privateKeyObj = await importES256Key(this.privateKeyJWK);
+        // Initial token exchange
+        await this.refreshToken();
+        // Schedule background refresh — check every 30s, refresh when near expiry
+        this.refreshTimer = setInterval(() => {
+            if (Date.now() >= this.tokenExpiresAt - 60_000) {
+                this.refreshToken().catch((err) => {
+                    const ttlLeft = Math.max(0, Math.round((this.tokenExpiresAt - Date.now()) / 1000));
+                    console.error(`[vault-token-manager] refresh failed (current token expires in ${ttlLeft}s, ` +
+                        `prefix: ${this.accessToken?.slice(0, 4) ?? "none"}): ${err instanceof Error ? err.message : String(err)}`);
+                });
+            }
+        }, 30_000);
+        // Don't keep the process alive just for token refresh
+        if (this.refreshTimer &&
+            typeof this.refreshTimer === "object" &&
+            "unref" in this.refreshTimer) {
+            this.refreshTimer.unref();
+        }
+    }
+    /**
+     * Get the current bearer token. Synchronous — relies on background refresh.
+     * Throws if init() hasn't been called.
+     */
+    getToken() {
+        if (!this.accessToken) {
+            throw new Error("VaultTokenManager not initialized — call init() first");
+        }
+        return this.accessToken;
+    }
+    /** Stop the background refresh timer. */
+    stop() {
+        if (this.refreshTimer) {
+            clearInterval(this.refreshTimer);
+            this.refreshTimer = null;
+        }
+    }
+    /**
+     * Force an immediate token refresh. Called on-demand when a 401 is received.
+     * Coalesces concurrent requests — if a refresh is already in flight, callers
+     * wait for the same promise instead of hammering the token endpoint.
+     */
+    async forceRefresh() {
+        if (this.refreshInFlight) {
+            try {
+                await this.refreshInFlight;
+                return true;
+            }
+            catch {
+                return false;
+            }
+        }
+        const attempt = this.refreshToken();
+        this.refreshInFlight = attempt;
+        try {
+            await attempt;
+            return true;
+        }
+        catch {
+            return false;
+        }
+        finally {
+            this.refreshInFlight = null;
+        }
+    }
+    async refreshToken() {
+        if (!this.privateKeyObj) {
+            throw new Error("Private key not imported — call init() first");
+        }
+        try {
+            const result = await exchangeToken(this.privateKeyObj, {
+                baseUrl: this.baseUrl,
+                agentId: this.agentId,
+                tokenAudience: this.tokenAudience,
+            });
+            const previousToken = this.accessToken;
+            this.accessToken = result.accessToken;
+            this.tokenExpiresAt = Date.now() + result.expiresIn * 1000;
+            console.log(`[vault-token-manager] Token refreshed (prefix: ${this.accessToken.slice(0, 4)}..., ` +
+                `ttl: ${result.expiresIn}s, previous: ${previousToken ? previousToken.slice(0, 4) + "..." : "none"})`);
+            // Notify listener (register.ts uses this to update the shared mutable auth object)
+            this.onRefresh?.(this.accessToken);
+        }
+        catch (err) {
+            // Check for 401 specifically
+            if (err instanceof Error && err.message.includes("401")) {
+                console.error("[vault-token-manager] Token exchange rejected (401). " +
+                    "The agent's key pair is no longer valid — agent may have been disabled or key rotated. " +
+                    "Generate a bootstrap secret from the AgentHiFive dashboard (Agents → Bootstrap Secret), " +
+                    "then run `openclaw configure` to reconnect.");
+                this.onAuthFailure?.();
+            }
+            throw err;
+        }
+    }
+}
+//# sourceMappingURL=vault-token-manager.js.map

package/dist/vault-token-manager.js.map

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

package/openclaw.plugin.json

@@ -0,0 +1,59 @@
+{
+  "id": "agenthifive",
+  "name": "AgentHiFive Vault",
+  "description": "Vault-managed credentials, brokered API proxy, and policy-governed access for AI agents",
+  "version": "0.1.0",
+  "configSchema": {
+    "type": "object",
+    "properties": {
+      "baseUrl": {
+        "type": "string",
+        "description": "AgentHiFive Vault API base URL",
+        "default": "https://app.agenthifive.com"
+      },
+      "auth": {
+        "type": "object",
+        "properties": {
+          "mode": {
+            "type": "string",
+            "enum": ["bearer", "agent"],
+            "description": "Authentication mode: 'bearer' for opaque token, 'agent' for ES256 JWT"
+          },
+          "token": {
+            "type": "string",
+            "description": "Bearer token (only for mode=bearer)"
+          },
+          "agentId": {
+            "type": "string",
+            "description": "Agent ID (only for mode=agent)"
+          },
+          "privateKey": {
+            "type": "string",
+            "description": "ES256 private key as base64-encoded JWK (only for mode=agent)"
+          },
+          "tokenAudience": {
+            "type": "string",
+            "description": "Token audience override (optional, defaults to baseUrl)"
+          }
+        },
+        "required": ["mode"]
+      },
+      "pollTimeoutMs": {
+        "type": "number",
+        "description": "Approval polling timeout in milliseconds (default: 300000 = 5 min)",
+        "default": 300000
+      },
+      "pollIntervalMs": {
+        "type": "number",
+        "description": "Approval polling interval in milliseconds (default: 3000 = 3s)",
+        "default": 3000
+      },
+      "connectedProviders": {
+        "type": "array",
+        "items": { "type": "string" },
+        "description": "List of connected provider names for prompt injection (e.g., ['google', 'microsoft', 'notion'])"
+      }
+    },
+    "required": ["auth"]
+  }
+}

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@agenthifive/openclaw",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./runtime": {
+      "types": "./dist/runtime.d.ts",
+      "default": "./dist/runtime.js"
+    }
+  },
+  "openclaw": {
+    "extensions": ["./dist/register.js"]
+  },
+  "files": [
+    "dist",
+    "openclaw.plugin.json",
+    "patches"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "tsc -p tsconfig.json && node --experimental-transform-types --test src/__tests__/*.test.ts",
+    "lint": "echo Lint: OK"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/supersantux/AgentH5.git",
+    "directory": "packages/openclaw"
+  },
+  "homepage": "https://github.com/supersantux/AgentH5/tree/main/packages/openclaw#readme",
+  "keywords": [
+    "openclaw",
+    "agenthifive",
+    "vault",
+    "ai-agent",
+    "credential-management",
+    "oauth",
+    "policy-engine",
+    "plugin"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "jose": "^5.9.3"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.6.0"
+  }
+}

package/patches/README.md

@@ -0,0 +1,85 @@
+# AgentHiFive OpenClaw Patches
+
+Optional patches that enable credential proxying features in OpenClaw core.
+
+**These patches are NOT required for basic functionality.** The AgentHiFive plugin
+works fully without patches — tools, prompt injection, approval flow, and the
+brokered API proxy (Model B) all work out of the box. Patches only enable
+**LLM credential proxying** (routing LLM API calls through the vault).
+
+## Available Patches
+
+### `model-auth.patch`
+
+Adds vault credential resolution to OpenClaw's `resolveApiKeyForProvider()` function
+in `src/agents/model-auth.ts`. This inserts two new resolution tiers before the
+existing local profile lookup:
+
+| Tier | What it does | When it activates |
+|------|-------------|-------------------|
+| **Tier 0** | Returns the vault bearer token directly | Provider is in `proxiedProviders` list |
+| **Tier 0.5** | Queries the vault credential provider chain | Always (falls through if no credentials found) |
+
+The patch uses `await import("@agenthifive/openclaw/runtime")` wrapped in try/catch,
+so it's a **complete no-op** when the plugin is not installed — safe for vanilla OpenClaw.
+
+## How to Apply
+
+### Using pnpm patch (recommended)
+
+```bash
+# 1. Start the patch session
+pnpm patch openclaw
+
+# 2. Apply the patch to the extracted directory
+#    (pnpm will print the temporary directory path)
+cd <temp-directory>
+patch -p1 < /path/to/@agenthifive/openclaw/patches/model-auth.patch
+
+# 3. Commit the patch
+pnpm patch-commit <temp-directory>
+```
+
+This adds a `patchedDependencies` entry to your `package.json` that pnpm applies
+automatically on `pnpm install`.
+
+### Manual application
+
+```bash
+cd /path/to/openclaw
+patch -p1 < node_modules/@agenthifive/openclaw/patches/model-auth.patch
+```
+
+Note: Manual patches are lost on `npm install` / `pnpm install`. Use `pnpm patch`
+for persistence.
+
+## Verification
+
+After applying, the AgentHiFive plugin will log at startup:
+
+```
+AgentHiFive: model-auth patch detected — credential proxying enabled
+```
+
+Without the patch, you'll see:
+
+```
+AgentHiFive: model-auth patch not detected. LLM credential proxying is unavailable.
+```
+
+## Compatibility
+
+| OpenClaw Version | Patch Status |
+|-----------------|-------------|
+| Latest (Mar 2026) | Compatible |
+
+The patch targets `resolveApiKeyForProvider()` in `src/agents/model-auth.ts`.
+If OpenClaw restructures this function significantly, the patch may need
+regeneration. Check the [AgentHiFive releases](https://github.com/supersantux/AgentH5/releases)
+for updated patches.
+
+## When Patches Become Unnecessary
+
+When OpenClaw merges support for `apiKeyOverride` in the `before_model_resolve`
+hook result type, the plugin can use the hook API directly and patches will be
+deprecated. Track progress in the upstream PR.

package/patches/model-auth.patch

@@ -0,0 +1,44 @@
+--- a/src/agents/model-auth.ts
++++ b/src/agents/model-auth.ts
+@@ -289,7 +289,41 @@
+ }): Promise<ResolvedProviderAuth> {
+   const { provider, cfg, profileId, preferredProfile } = params;
+   const store = params.store ?? ensureAuthProfileStore(params.agentDir);
+
++  // -- Tier 0: AgentHiFive proxied providers (vault bearer token) --
++  // When the provider is in proxiedProviders, the vault acts as an LLM proxy.
++  // Return the managed vault bearer token directly -- no local API key needed.
++  // @agenthifive/openclaw/runtime -- dynamic import is a no-op when plugin is not installed.
++  try {
++    const runtime = await import("@agenthifive/openclaw/runtime");
++    if (runtime.isInitialized()) {
++      const proxiedProviders = runtime.getProxiedProviders();
++      if (proxiedProviders.includes(provider)) {
++        const vaultToken = runtime.getVaultBearerToken();
++        if (vaultToken) {
++          return { apiKey: vaultToken, source: "vault:agent-token", mode: "api-key" };
++        }
++      }
++
++      // -- Tier 0.5: Credential provider chain --
++      // Try the vault credential provider before local profiles.
++      const vaultResult = await runtime.resolveCredential({
++        kind: "model_provider",
++        provider,
++        profileId: preferredProfile,
++      });
++      if (vaultResult?.apiKey) {
++        return {
++          apiKey: vaultResult.apiKey,
++          source: "credential-provider:vault",
++          mode: vaultResult.mode ?? "api-key",
++        };
++      }
++    }
++  } catch {
++    // Plugin not installed -- skip vault credential resolution
++  }
++
+   if (profileId) {
+     const resolved = await resolveApiKeyForProfile({
+       cfg,