@memtensor/memos-local-openclaw-plugin 1.0.2 → 1.0.4-beta.0

package/src/client/hub.ts

@@ -0,0 +1,189 @@
+import type { PluginContext } from "../types";
+import type { SqliteStore } from "../storage/sqlite";
+import type { HubMemoryDetail, HubScope, HubSearchResult, HubSkillSearchResult } from "../sharing/types";
+
+export interface ResolvedHubClient {
+  hubUrl: string;
+  userToken: string;
+  userId: string;
+  username: string;
+  role: string;
+}
+
+export async function resolveHubClient(store: SqliteStore, ctx: PluginContext, overrides?: { hubAddress?: string; userToken?: string }): Promise<ResolvedHubClient> {
+  const persisted = store.getClientHubConnection() as any;
+  if (persisted?.hubUrl && persisted?.userToken) {
+    return {
+      hubUrl: normalizeHubUrl(String(persisted.hubUrl)),
+      userToken: String(persisted.userToken),
+      userId: String(persisted.userId),
+      username: String(persisted.username ?? ""),
+      role: String(persisted.role ?? "member"),
+    };
+  }
+
+  const hubAddress = overrides?.hubAddress ?? ctx.config.sharing?.client?.hubAddress ?? "";
+  const userToken = overrides?.userToken ?? ctx.config.sharing?.client?.userToken ?? "";
+  if (!hubAddress || !userToken) {
+    throw new Error("hub client connection is not configured");
+  }
+
+  const hubUrl = normalizeHubUrl(hubAddress);
+  const me = await hubRequestJson(hubUrl, userToken, "/api/v1/hub/me", { method: "GET" }) as any;
+
+  return {
+    hubUrl,
+    userToken,
+    userId: String(me.id),
+    username: String(me.username ?? ""),
+    role: String(me.role ?? "member"),
+  };
+}
+
+export async function hubListMemories(
+  store: SqliteStore,
+  ctx: PluginContext,
+  input?: { limit?: number; hubAddress?: string; userToken?: string },
+): Promise<{ memories: Array<any> }> {
+  const client = await resolveHubClient(store, ctx, { hubAddress: input?.hubAddress, userToken: input?.userToken });
+  const url = new URL(`${client.hubUrl}/api/v1/hub/memories`);
+  if (input?.limit != null) url.searchParams.set("limit", String(input.limit));
+  return hubRequestJson(url.origin, client.userToken, `${url.pathname}${url.search}`, {
+    method: "GET",
+  }) as Promise<{ memories: Array<any> }>;
+}
+
+export async function hubListTasks(
+  store: SqliteStore,
+  ctx: PluginContext,
+  input?: { limit?: number; hubAddress?: string; userToken?: string },
+): Promise<{ tasks: Array<any> }> {
+  const client = await resolveHubClient(store, ctx, { hubAddress: input?.hubAddress, userToken: input?.userToken });
+  const url = new URL(`${client.hubUrl}/api/v1/hub/tasks`);
+  if (input?.limit != null) url.searchParams.set("limit", String(input.limit));
+  return hubRequestJson(url.origin, client.userToken, `${url.pathname}${url.search}`, {
+    method: "GET",
+  }) as Promise<{ tasks: Array<any> }>;
+}
+
+export async function hubListSkills(
+  store: SqliteStore,
+  ctx: PluginContext,
+  input?: { limit?: number; hubAddress?: string; userToken?: string },
+): Promise<{ skills: Array<any> }> {
+  const client = await resolveHubClient(store, ctx, { hubAddress: input?.hubAddress, userToken: input?.userToken });
+  const url = new URL(`${client.hubUrl}/api/v1/hub/skills/list`);
+  if (input?.limit != null) url.searchParams.set("limit", String(input.limit));
+  return hubRequestJson(url.origin, client.userToken, `${url.pathname}${url.search}`, {
+    method: "GET",
+  }) as Promise<{ skills: Array<any> }>;
+}
+
+export async function hubSearchMemories(
+  store: SqliteStore,
+  ctx: PluginContext,
+  input: { query: string; maxResults?: number; scope?: HubScope; hubAddress?: string; userToken?: string },
+): Promise<HubSearchResult> {
+  const client = await resolveHubClient(store, ctx, { hubAddress: input.hubAddress, userToken: input.userToken });
+  return hubRequestJson(client.hubUrl, client.userToken, "/api/v1/hub/search", {
+    method: "POST",
+    body: JSON.stringify({
+      query: input.query,
+      maxResults: input.maxResults,
+      scope: input.scope,
+    }),
+  }) as Promise<HubSearchResult>;
+}
+
+
+export async function hubSearchSkills(
+  store: SqliteStore,
+  ctx: PluginContext,
+  input: { query: string; maxResults?: number; hubAddress?: string; userToken?: string },
+): Promise<HubSkillSearchResult> {
+  const client = await resolveHubClient(store, ctx, { hubAddress: input.hubAddress, userToken: input.userToken });
+  const url = new URL(`${client.hubUrl}/api/v1/hub/skills`);
+  url.searchParams.set("query", input.query);
+  if (input.maxResults != null) url.searchParams.set("maxResults", String(input.maxResults));
+  return hubRequestJson(url.origin, client.userToken, `${url.pathname}${url.search}`, {
+    method: "GET",
+  }) as Promise<HubSkillSearchResult>;
+}
+
+export async function hubGetMemoryDetail(
+  store: SqliteStore,
+  ctx: PluginContext,
+  input: { remoteHitId: string; hubAddress?: string; userToken?: string },
+): Promise<HubMemoryDetail> {
+  const client = await resolveHubClient(store, ctx, { hubAddress: input.hubAddress, userToken: input.userToken });
+  const detail = await hubRequestJson(client.hubUrl, client.userToken, "/api/v1/hub/memory-detail", {
+    method: "POST",
+    body: JSON.stringify({
+      remoteHitId: input.remoteHitId,
+    }),
+  }) as Omit<HubMemoryDetail, "remoteHitId">;
+
+  return {
+    remoteHitId: input.remoteHitId,
+    content: String(detail.content ?? ""),
+    summary: String(detail.summary ?? ""),
+    source: {
+      ts: Number(detail.source?.ts ?? 0),
+      role: String(detail.source?.role ?? "assistant") as any,
+    },
+  };
+}
+
+export async function hubUpdateUsername(
+  store: SqliteStore,
+  ctx: PluginContext,
+  newUsername: string,
+): Promise<{ ok: boolean; username: string; userToken: string }> {
+  const client = await resolveHubClient(store, ctx);
+  const result = await hubRequestJson(client.hubUrl, client.userToken, "/api/v1/hub/me/update-profile", {
+    method: "POST",
+    body: JSON.stringify({ username: newUsername }),
+  }) as { ok: boolean; username: string; userToken: string };
+  if (result.ok && result.userToken) {
+    store.setClientHubConnection({
+      hubUrl: client.hubUrl,
+      userId: client.userId,
+      username: result.username,
+      userToken: result.userToken,
+      role: client.role as "admin" | "member",
+      connectedAt: Date.now(),
+    });
+  }
+  return result;
+}
+
+export async function hubRequestJson(
+  hubUrl: string,
+  userToken: string,
+  route: string,
+  init: RequestInit = {},
+): Promise<unknown> {
+  const res = await fetch(`${normalizeHubUrl(hubUrl)}${route}`, {
+    ...init,
+    headers: {
+      authorization: `Bearer ${userToken}`,
+      ...(init.body ? { "content-type": "application/json" } : {}),
+      ...(init.headers ?? {}),
+    },
+  });
+
+  if (!res.ok) {
+    const body = await res.text();
+    throw new Error(`hub request failed (${res.status}): ${body || res.statusText}`);
+  }
+
+  if (res.status === 204) return null;
+  return res.json();
+}
+
+export function normalizeHubUrl(hubAddress: string): string {
+  const trimmed = hubAddress.trim().replace(/\/+$/, "");
+  if (!trimmed) return "";
+  if (/^https?:\/\//i.test(trimmed)) return trimmed;
+  return `http://${trimmed}`;
+}

package/src/client/skill-sync.ts

@@ -0,0 +1,202 @@
+import * as fs from "fs";
+import * as path from "path";
+import { randomUUID } from "crypto";
+import type { PluginContext, Skill, SkillVersion } from "../types";
+import type { SqliteStore } from "../storage/sqlite";
+import type { SkillGenerateOutput } from "../types";
+import type { SkillBundle } from "../sharing/types";
+import { resolveHubClient, hubRequestJson } from "./hub";
+
+export function buildSkillBundleForHub(store: SqliteStore, skillId: string): SkillBundle {
+  const skill = store.getSkill(skillId);
+  if (!skill) {
+    throw new Error(`Skill not found: ${skillId}`);
+  }
+
+  const latestVersion = store.getLatestSkillVersion(skillId);
+  const skillMd = readSkillMarkdown(skill.dirPath, latestVersion?.content ?? "");
+
+  return {
+    metadata: {
+      id: skill.id,
+      name: skill.name,
+      description: skill.description,
+      version: skill.version,
+      qualityScore: skill.qualityScore,
+    },
+    bundle: {
+      skill_md: skillMd,
+      scripts: readCompanionFiles(path.join(skill.dirPath, "scripts")),
+      references: readCompanionFiles(path.join(skill.dirPath, "references")),
+      evals: readEvals(path.join(skill.dirPath, "evals", "evals.json")),
+    } satisfies SkillGenerateOutput,
+  };
+}
+
+function readSkillMarkdown(dirPath: string, fallback: string): string {
+  const skillMdPath = path.join(dirPath, "SKILL.md");
+  if (fs.existsSync(skillMdPath)) {
+    return fs.readFileSync(skillMdPath, "utf8");
+  }
+  return fallback;
+}
+
+function readCompanionFiles(dirPath: string): Array<{ filename: string; content: string }> {
+  if (!fs.existsSync(dirPath)) return [];
+
+  const out: Array<{ filename: string; content: string }> = [];
+  walkFiles(dirPath, dirPath, out);
+  return out.sort((left, right) => left.filename.localeCompare(right.filename));
+}
+
+function walkFiles(rootDir: string, currentDir: string, out: Array<{ filename: string; content: string }>): void {
+  for (const entry of fs.readdirSync(currentDir, { withFileTypes: true })) {
+    const fullPath = path.join(currentDir, entry.name);
+    if (entry.isDirectory()) {
+      walkFiles(rootDir, fullPath, out);
+      continue;
+    }
+    if (!entry.isFile()) continue;
+    out.push({
+      filename: path.relative(rootDir, fullPath).replace(/\\/g, "/"),
+      content: fs.readFileSync(fullPath, "utf8"),
+    });
+  }
+}
+
+function readEvals(evalsPath: string): Array<{ id: number; prompt: string; expectations: string[] }> {
+  if (!fs.existsSync(evalsPath)) return [];
+  const raw = JSON.parse(fs.readFileSync(evalsPath, "utf8")) as { evals?: Array<{ id: number; prompt: string; expectations: string[] }> };
+  return Array.isArray(raw.evals) ? raw.evals : [];
+}
+
+
+export async function publishSkillBundleToHub(
+  store: SqliteStore,
+  ctx: PluginContext,
+  input: { skillId: string; visibility: "public" | "group"; groupId?: string; hubAddress?: string; userToken?: string },
+): Promise<{ skillId: string; visibility: "public" | "group" }> {
+  const bundle = buildSkillBundleForHub(store, input.skillId);
+  const client = await resolveHubClient(store, ctx, { hubAddress: input.hubAddress, userToken: input.userToken });
+  return hubRequestJson(client.hubUrl, client.userToken, "/api/v1/hub/skills/publish", {
+    method: "POST",
+    body: JSON.stringify({
+      visibility: input.visibility,
+      groupId: input.groupId,
+      metadata: bundle.metadata,
+      bundle: bundle.bundle,
+    }),
+  }) as Promise<{ skillId: string; visibility: "public" | "group" }>;
+}
+
+export async function fetchHubSkillBundle(
+  store: SqliteStore,
+  ctx: PluginContext,
+  input: { skillId: string; hubAddress?: string; userToken?: string },
+): Promise<SkillBundle & { skillId: string }> {
+  const client = await resolveHubClient(store, ctx, { hubAddress: input.hubAddress, userToken: input.userToken });
+  return hubRequestJson(client.hubUrl, client.userToken, `/api/v1/hub/skills/${encodeURIComponent(input.skillId)}/bundle`, {
+    method: "GET",
+  }) as Promise<SkillBundle & { skillId: string }>;
+}
+
+export function restoreSkillBundleFromHub(
+  store: SqliteStore,
+  ctx: PluginContext,
+  payload: SkillBundle & { skillId?: string },
+): { localSkillId: string; localName: string; dirPath: string } {
+  validateBundle(payload.bundle);
+
+  const skillsStoreDir = path.join(ctx.stateDir, "skills-store");
+  fs.mkdirSync(skillsStoreDir, { recursive: true });
+
+  const baseName = sanitizeName(payload.metadata.name) || `hub-skill-${(payload.skillId ?? payload.metadata.id).slice(0, 8)}`;
+  const resolvedName = resolveLocalSkillName(store, baseName, payload.skillId ?? payload.metadata.id);
+  const dirPath = path.join(skillsStoreDir, resolvedName);
+  fs.mkdirSync(dirPath, { recursive: true });
+  fs.writeFileSync(path.join(dirPath, "SKILL.md"), payload.bundle.skill_md, "utf8");
+
+  writeCompanionFiles(dirPath, "scripts", payload.bundle.scripts);
+  writeCompanionFiles(dirPath, "references", payload.bundle.references);
+  if (payload.bundle.evals.length > 0) {
+    const evalDir = path.join(dirPath, "evals");
+    fs.mkdirSync(evalDir, { recursive: true });
+    fs.writeFileSync(path.join(evalDir, "evals.json"), JSON.stringify({ skill_name: payload.metadata.name, evals: payload.bundle.evals }, null, 2), "utf8");
+  }
+
+  const now = Date.now();
+  const localSkillId = randomUUID();
+  const skill: Skill = {
+    id: localSkillId,
+    name: resolvedName,
+    description: payload.metadata.description,
+    version: payload.metadata.version,
+    status: "active",
+    tags: JSON.stringify(["hub-import"]),
+    sourceType: "manual",
+    dirPath,
+    installed: 0,
+    owner: "agent:main",
+    visibility: "private",
+    qualityScore: payload.metadata.qualityScore,
+    createdAt: now,
+    updatedAt: now,
+  };
+  const version: SkillVersion = {
+    id: randomUUID(),
+    skillId: localSkillId,
+    version: payload.metadata.version,
+    content: payload.bundle.skill_md,
+    changelog: "Imported from hub",
+    changeSummary: "Imported from hub",
+    upgradeType: "create",
+    sourceTaskId: null,
+    metrics: "{}",
+    qualityScore: payload.metadata.qualityScore,
+    createdAt: now,
+  };
+
+  store.insertSkill(skill);
+  store.insertSkillVersion(version);
+  return { localSkillId, localName: resolvedName, dirPath };
+}
+
+function validateBundle(bundle: SkillGenerateOutput): void {
+  const allowedExtensions = new Set([".md", ".ts", ".js", ".sh", ".json", ".yaml", ".yml", ".txt"]);
+  const files = [...bundle.scripts, ...bundle.references];
+  if (Buffer.byteLength(bundle.skill_md, "utf8") > 100 * 1024) throw new Error("SKILL.md exceeds size limit");
+  if (files.length > 50) throw new Error("bundle contains too many files");
+
+  let totalBytes = Buffer.byteLength(bundle.skill_md, "utf8");
+  for (const file of files) {
+    const name = file.filename;
+    if (!name || path.isAbsolute(name) || name.startsWith("/") || name.includes("..")) throw new Error(`unsafe filename: ${name}`);
+    if (!/^[A-Za-z0-9._/-]+$/.test(name)) throw new Error(`invalid filename: ${name}`);
+    const ext = path.extname(name).toLowerCase();
+    if (!allowedExtensions.has(ext)) throw new Error(`unsupported file type: ${name}`);
+    const fileSize = Buffer.byteLength(file.content, "utf8");
+    if (fileSize > 512 * 1024) throw new Error(`file exceeds size limit: ${name}`);
+    totalBytes += fileSize;
+  }
+  if (totalBytes > 5 * 1024 * 1024) throw new Error("bundle exceeds size limit");
+}
+
+function writeCompanionFiles(dirPath: string, root: "scripts" | "references", files: Array<{ filename: string; content: string }>): void {
+  if (files.length === 0) return;
+  const rootDir = path.join(dirPath, root);
+  fs.mkdirSync(rootDir, { recursive: true });
+  for (const file of files) {
+    const target = path.join(rootDir, file.filename);
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+    fs.writeFileSync(target, file.content, "utf8");
+  }
+}
+
+function sanitizeName(input: string): string {
+  return input.trim().replace(/[^A-Za-z0-9._-]+/g, "-").replace(/^-+|-+$/g, "");
+}
+
+function resolveLocalSkillName(store: SqliteStore, baseName: string, sourceId: string): string {
+  if (!store.getSkillByName(baseName)) return baseName;
+  return `${baseName}-hub-${sourceId.slice(0, 8)}`;
+}

package/src/config.ts

@@ -1,5 +1,6 @@
 import * as path from "path";
-import { DEFAULTS, type MemosLocalConfig, type PluginContext, type Logger } from "./types";
+import { DEFAULTS, type MemosLocalConfig, type PluginContext, type Logger, type EmbeddingConfig, type SummarizerConfig } from "./types";
+import { OpenClawAPIClient, type HostModelsConfig } from "./openclaw-api";
 
 const ENV_RE = /\$\{([A-Z_][A-Z0-9_]*)\}/g;
 
@@ -20,6 +21,24 @@ function deepResolveEnv<T>(obj: T): T {
   return obj;
 }
 
+function resolveProviderFallback<T extends { provider?: string; capabilities?: unknown }>(
+  config: T | undefined,
+  fallbackProvider: T["provider"],
+  enabled: boolean,
+): T | undefined {
+  if (!config) {
+    return enabled
+      ? ({ provider: fallbackProvider } as T)
+      : undefined;
+  }
+
+  if (config.provider == null && enabled) {
+    return { ...config, provider: fallbackProvider };
+  }
+
+  return config;
+}
+
 export function resolveConfig(raw: Partial<MemosLocalConfig> | undefined, stateDir: string): MemosLocalConfig {
   const cfg = deepResolveEnv(raw ?? {});
 
@@ -27,6 +46,11 @@ export function resolveConfig(raw: Partial<MemosLocalConfig> | undefined, stateD
   const telemetryEnabled =
     cfg.telemetry?.enabled ??
     (telemetryEnvVar === "false" || telemetryEnvVar === "0" ? false : true);
+  const sharingCapabilities = {
+    hostEmbedding: cfg.sharing?.capabilities?.hostEmbedding ?? false,
+    hostCompletion: cfg.sharing?.capabilities?.hostCompletion ?? false,
+    hostSkill: cfg.sharing?.capabilities?.hostSkill ?? false,
+  };
 
   return {
     ...cfg,
@@ -54,6 +78,61 @@ export function resolveConfig(raw: Partial<MemosLocalConfig> | undefined, stateD
       posthogApiKey: cfg.telemetry?.posthogApiKey ?? process.env.POSTHOG_API_KEY ?? "",
       posthogHost: cfg.telemetry?.posthogHost ?? process.env.POSTHOG_HOST ?? "",
     },
+    summarizer: (() => {
+      const summarizerConfig = resolveProviderFallback<SummarizerConfig>(
+        cfg.summarizer,
+        "openclaw",
+        sharingCapabilities.hostCompletion,
+      );
+      return summarizerConfig
+        ? {
+            ...summarizerConfig,
+            capabilities: sharingCapabilities,
+          }
+        : undefined;
+    })(),
+    embedding: (() => {
+      const embeddingConfig = resolveProviderFallback<EmbeddingConfig>(
+        cfg.embedding,
+        "openclaw",
+        sharingCapabilities.hostEmbedding,
+      );
+      return embeddingConfig
+        ? {
+            ...embeddingConfig,
+            capabilities: sharingCapabilities,
+          }
+        : undefined;
+    })(),
+    skillEvolution: cfg.skillEvolution ? {
+      ...cfg.skillEvolution,
+      summarizer: (() => {
+        const skSumCfg = resolveProviderFallback<SummarizerConfig>(
+          cfg.skillEvolution!.summarizer as SummarizerConfig | undefined,
+          "openclaw",
+          sharingCapabilities.hostSkill,
+        );
+        return skSumCfg
+          ? { ...skSumCfg, capabilities: sharingCapabilities }
+          : undefined;
+      })(),
+    } : undefined,
+    sharing: {
+      enabled: cfg.sharing?.enabled ?? false,
+      role: cfg.sharing?.role ?? "client",
+      hub: {
+        port: cfg.sharing?.hub?.port ?? 18800,
+        teamName: cfg.sharing?.hub?.teamName ?? "",
+        teamToken: cfg.sharing?.hub?.teamToken ?? "",
+      },
+      client: {
+        hubAddress: cfg.sharing?.client?.hubAddress ?? "",
+        userToken: cfg.sharing?.client?.userToken ?? "",
+        teamToken: cfg.sharing?.client?.teamToken ?? "",
+        pendingUserId: cfg.sharing?.client?.pendingUserId ?? "",
+      },
+      capabilities: sharingCapabilities,
+    },
   };
 }
 
@@ -62,6 +141,7 @@ export function buildContext(
   workspaceDir: string,
   rawConfig: Partial<MemosLocalConfig> | undefined,
   log?: Logger,
+  hostModels?: HostModelsConfig,
 ): PluginContext {
   const defaultLog: Logger = {
     debug: (...args) => console.debug("[memos-local]", ...args),
@@ -70,10 +150,19 @@ export function buildContext(
     error: (...args) => console.error("[memos-local]", ...args),
   };
 
+  const logger = log ?? defaultLog;
+  const config = resolveConfig(rawConfig, stateDir);
+
+  // Create OpenClawAPI instance if host capabilities are enabled
+  const openclawAPI = (config.sharing?.capabilities?.hostEmbedding || config.sharing?.capabilities?.hostCompletion || config.sharing?.capabilities?.hostSkill)
+    ? new OpenClawAPIClient(logger, hostModels)
+    : undefined;
+
   return {
     stateDir,
     workspaceDir,
-    config: resolveConfig(rawConfig, stateDir),
-    log: log ?? defaultLog,
+    config,
+    log: logger,
+    openclawAPI,
   };
 }

package/src/embedding/index.ts

@@ -1,4 +1,4 @@
-import type { EmbeddingConfig, Logger } from "../types";
+import type { EmbeddingConfig, Logger, OpenClawAPI } from "../types";
 import { embedOpenAI } from "./providers/openai";
 import { embedGemini } from "./providers/gemini";
 import { embedCohere, embedCohereQuery } from "./providers/cohere";
@@ -11,9 +11,13 @@ export class Embedder {
   constructor(
     private cfg: EmbeddingConfig | undefined,
     private log: Logger,
+    private openclawAPI?: OpenClawAPI,
   ) {}
 
   get provider(): string {
+    if (this.cfg?.provider === "openclaw" && this.cfg.capabilities?.hostEmbedding !== true) {
+      return "local";
+    }
     return this.cfg?.provider ?? "local";
   }
 
@@ -53,11 +57,13 @@ export class Embedder {
       switch (provider) {
         case "openai":
         case "openai_compatible":
+        case "azure_openai":
+        case "zhipu":
+        case "siliconflow":
+        case "bailian":
           result = await embedOpenAI(texts, cfg!, this.log); break;
         case "gemini":
           result = await embedGemini(texts, cfg!, this.log); break;
-        case "azure_openai":
-          result = await embedOpenAI(texts, cfg!, this.log); break;
         case "cohere":
           result = await embedCohere(texts, cfg!, this.log); break;
         case "mistral":
@@ -79,4 +85,20 @@ export class Embedder {
       throw err;
     }
   }
+
+  private async embedOpenClaw(texts: string[]): Promise<number[][]> {
+    if (!this.openclawAPI) {
+      throw new Error(
+        "OpenClaw API not available. Ensure sharing.capabilities.hostEmbedding is enabled in config."
+      );
+    }
+
+    this.log.debug(`Calling OpenClaw embed API for ${texts.length} texts`);
+    const response = await this.openclawAPI.embed({
+      texts,
+      model: this.cfg?.model,
+    });
+
+    return response.embeddings;
+  }
 }

package/src/hub/auth.ts

@@ -0,0 +1,78 @@
+import { createHmac, randomBytes, timingSafeEqual } from "crypto";
+import type { UserRole, UserStatus } from "../sharing/types";
+
+type UserTokenPayload = {
+  userId: string;
+  username: string;
+  role: UserRole;
+  status: UserStatus;
+  exp: number;
+};
+
+function base64url(input: Buffer | string): string {
+  return Buffer.from(input)
+    .toString("base64")
+    .replace(/\+/g, "-")
+    .replace(/\//g, "_")
+    .replace(/=+$/g, "");
+}
+
+function unbase64url(input: string): Buffer {
+  const padded = input.replace(/-/g, "+").replace(/_/g, "/") + "===".slice((input.length + 3) % 4);
+  return Buffer.from(padded, "base64");
+}
+
+function sign(value: string, secret: string): string {
+  return base64url(createHmac("sha256", secret).update(value).digest());
+}
+
+export function createTeamToken(secret: string): string {
+  const nonce = base64url(randomBytes(12));
+  const body = `team.${nonce}`;
+  return `${body}.${sign(body, secret)}`;
+}
+
+export function verifyTeamToken(token: string, secret: string): boolean {
+  const idx = token.lastIndexOf(".");
+  if (idx <= 0) return false;
+  const body = token.slice(0, idx);
+  const sig = token.slice(idx + 1);
+  const expected = sign(body, secret);
+  try {
+    return timingSafeEqual(Buffer.from(sig), Buffer.from(expected));
+  } catch {
+    return false;
+  }
+}
+
+export function issueUserToken(
+  payload: { userId: string; username: string; role: UserRole; status: UserStatus },
+  secret: string,
+  ttlMs = 24 * 60 * 60 * 1000,
+): string {
+  const full: UserTokenPayload = { ...payload, exp: Date.now() + ttlMs };
+  const body = base64url(JSON.stringify(full));
+  return `${body}.${sign(body, secret)}`;
+}
+
+export function verifyUserToken(token: string, secret: string): Omit<UserTokenPayload, "exp"> | null {
+  const idx = token.lastIndexOf(".");
+  if (idx <= 0) return null;
+  const body = token.slice(0, idx);
+  const sig = token.slice(idx + 1);
+  const expected = sign(body, secret);
+
+  try {
+    if (!timingSafeEqual(Buffer.from(sig), Buffer.from(expected))) return null;
+    const parsed = JSON.parse(unbase64url(body).toString("utf8")) as UserTokenPayload;
+    if (parsed.exp < Date.now()) return null;
+    return {
+      userId: parsed.userId,
+      username: parsed.username,
+      role: parsed.role,
+      status: parsed.status,
+    };
+  } catch {
+    return null;
+  }
+}