backeer-opencode 0.1.3 → 0.1.4

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 All notable changes to `backeer-opencode` are documented here.
 
+## 0.1.4 - 2026-09-01
+
+- Add `/backeer` and `/backeer status` for an in-session integration report.
+- Add secure, immediate token rotation with `/backeer token-file PATH`.
+- Keep raw tokens out of slash-command arguments, session messages, and logs.
+- Keep the management command available when notifications are disabled by a
+  missing token.
+
 ## 0.1.3 - 2026-09-01
 
 - Split configuration, logging, HTTP, SSE, event publishing, and permission

package/README.md

@@ -149,6 +149,30 @@ connection errors are suppressed for 30 seconds. Normal `info` output omits HTTP
 status codes and internal errors; set `BACKEER_LOG_LEVEL=debug` when technical
 details are needed. Set it to `error` for failures only or `silent` for no output.
 
+## OpenCode command
+
+The plugin registers a `/backeer` command inside OpenCode:
+
+```text
+/backeer
+/backeer status
+/backeer token
+/backeer token-file /absolute/path/to/a/protected-token-file
+```
+
+The status report shows the plugin version, gateway reachability, token source,
+notification switches, command-stream state, pending permissions, and log level.
+It never displays the token. Gateway reachability does not validate the source
+credential.
+
+`/backeer token` displays safe rotation instructions. Never paste a raw token
+into slash-command arguments because OpenCode may retain command text in session
+history. To rotate from inside OpenCode, first place the new token in an absolute
+file readable only by its owner (`chmod 600`), then use `token-file`. The plugin
+atomically copies it to the configured token location, applies mode `0600`, and
+activates it immediately without restarting OpenCode. The source file is not
+removed.
+
 ## Events and decisions
 
 The plugin publishes:

package/dist/backeer-permission.js

@@ -83,11 +83,12 @@ function defaultConfigDirectory() {
 }
 function loadToken(tokenFile) {
   const environmentToken = process.env.BACKEER_INGEST_TOKEN?.trim();
-  if (environmentToken) return environmentToken;
+  if (environmentToken) return { token: environmentToken, source: "environment" };
   try {
-    return readFileSync(tokenFile, "utf8").trim();
+    const token = readFileSync(tokenFile, "utf8").trim();
+    return { token, source: token ? "file" : "missing" };
   } catch {
-    return "";
+    return { token: "", source: "missing" };
   }
 }
 function loadConfig(options = {}) {
@@ -98,11 +99,13 @@ function loadConfig(options = {}) {
     throw new Error("Backeer origin must use HTTPS");
   }
   const tokenFile = options.tokenFile ?? process.env.BACKEER_TOKEN_FILE ?? join(defaultConfigDirectory(), "secrets", "backeer-ingest-token");
+  const loadedToken = loadToken(tokenFile);
   return {
     origin,
     eventsEndpoint: new URL("/v1/events", origin),
     commandStreamEndpoint: new URL("/v1/commands/stream", origin),
-    token: loadToken(tokenFile),
+    token: loadedToken.token,
+    tokenSource: loadedToken.source,
     tokenFile,
     permissions: enabled(
       options.permissions ?? process.env.BACKEER_NOTIFY_PERMISSIONS
@@ -134,16 +137,16 @@ function isAbortError(error) {
   return error instanceof Error && error.name === "AbortError";
 }
 function sleep(milliseconds, signal) {
-  return new Promise((resolve) => {
+  return new Promise((resolve2) => {
     if (signal?.aborted) {
-      resolve();
+      resolve2();
       return;
     }
     const timeout = setTimeout(done, milliseconds);
     function done() {
       clearTimeout(timeout);
       signal?.removeEventListener("abort", done);
-      resolve();
+      resolve2();
     }
     signal?.addEventListener("abort", done, { once: true });
   });
@@ -344,6 +347,188 @@ async function publishTodoCompletion(config, reporter, request, eventID, client,
   reporter.success("Todo completion sent", `HTTP ${result.status}`);
 }
 
+// src/management.js
+import {
+  chmodSync,
+  mkdirSync,
+  readFileSync as readFileSync2,
+  renameSync,
+  statSync,
+  writeFileSync
+} from "node:fs";
+import { dirname, resolve } from "node:path";
+var PLUGIN_VERSION = "0.1.4";
+var COMMAND_DESCRIPTION = "Show Backeer status or manage its token: /backeer [status|token|token-file PATH]";
+function tokenFileState(path) {
+  try {
+    const stats = statSync(path);
+    const mode = (stats.mode & 511).toString(8).padStart(3, "0");
+    return stats.isFile() ? `present (mode ${mode})` : "not a regular file";
+  } catch {
+    return "missing";
+  }
+}
+function cleanPathArgument(value) {
+  const path = value.trim();
+  if (path.length >= 2 && (path.startsWith('"') && path.endsWith('"') || path.startsWith("'") && path.endsWith("'"))) {
+    return path.slice(1, -1);
+  }
+  return path;
+}
+function writeTokenAtomically(path, token) {
+  mkdirSync(dirname(path), { recursive: true, mode: 448 });
+  const temporaryPath = `${path}.${process.pid}.${Date.now()}.tmp`;
+  writeFileSync(temporaryPath, `${token}
+`, { encoding: "utf8", mode: 384 });
+  chmodSync(temporaryPath, 384);
+  renameSync(temporaryPath, path);
+}
+function rotateTokenFromFile(config, sourcePathValue) {
+  if (!sourcePathValue.trim()) throw new Error("A token file path is required");
+  const sourcePath = resolve(cleanPathArgument(sourcePathValue));
+  const sourceStats = statSync(sourcePath);
+  if (!sourceStats.isFile()) throw new Error("The token source is not a regular file");
+  if ((sourceStats.mode & 63) !== 0) {
+    throw new Error("The token source must not be readable by group or other users");
+  }
+  const token = readFileSync2(sourcePath, "utf8").trim();
+  if (!token || /\s/.test(token)) {
+    throw new Error("The token source must contain exactly one non-empty token");
+  }
+  const targetPath = resolve(config.tokenFile);
+  if (sourcePath !== targetPath) writeTokenAtomically(targetPath, token);
+  else chmodSync(targetPath, 384);
+  config.token = token;
+  config.tokenSource = "file";
+  return targetPath;
+}
+async function probeGateway(config) {
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), 3e3);
+  try {
+    const response = await fetch(config.origin, {
+      method: "HEAD",
+      redirect: "manual",
+      signal: controller.signal
+    });
+    return `reachable (HTTP ${response.status}; authentication not tested)`;
+  } catch {
+    return "unreachable";
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+async function buildStatus(config, permissionController) {
+  const gateway = await probeGateway(config);
+  const permissionStatus = permissionController.status();
+  return [
+    "## Backeer status",
+    "",
+    `- Plugin version: ${PLUGIN_VERSION}`,
+    `- Gateway: ${config.origin.origin} \u2014 ${gateway}`,
+    `- Token: ${config.token ? `configured via ${config.tokenSource}` : "missing"}`,
+    `- Token file: ${config.tokenFile} \u2014 ${tokenFileState(config.tokenFile)}`,
+    `- Permission notifications: ${config.permissions ? "enabled" : "disabled"}`,
+    `- Question notifications: ${config.questions ? "enabled" : "disabled"}`,
+    `- Todo notifications: ${config.todos ? "enabled" : "disabled"}`,
+    `- Command stream: ${permissionStatus.stream}`,
+    `- Pending permissions: ${permissionStatus.pending}`,
+    `- Log level: ${config.logLevel}`,
+    "",
+    "The token value is never displayed."
+  ].join("\n");
+}
+function helpMessage() {
+  return [
+    "## Backeer commands",
+    "",
+    "- `/backeer` or `/backeer status` \u2014 show integration status",
+    "- `/backeer token` \u2014 show secure token-change instructions",
+    "- `/backeer token-file /absolute/protected/path` \u2014 import and activate a token",
+    "",
+    "Never place a token directly in a slash command. Slash-command arguments may be stored in session history."
+  ].join("\n");
+}
+function tokenInstructions() {
+  return [
+    "## Change the Backeer token securely",
+    "",
+    "Do not paste the token into OpenCode or `/backeer` arguments.",
+    "",
+    "Use either:",
+    "",
+    "1. Hidden terminal input: `npx backeer-opencode@latest configure`",
+    "2. A protected file: `chmod 600 /path/to/token && /backeer token-file /path/to/token`",
+    "",
+    "`token-file` activates the new token immediately; no OpenCode restart is required."
+  ].join("\n");
+}
+async function sendCommandMessage(client, sessionID, text) {
+  if (typeof client?.session?.prompt !== "function") {
+    throw new Error("OpenCode session messaging is unavailable");
+  }
+  await client.session.prompt({
+    path: { id: sessionID },
+    body: {
+      noReply: true,
+      parts: [{ type: "text", text, ignored: true }]
+    }
+  });
+}
+function registerBackeerCommand(opencodeConfig) {
+  opencodeConfig.command ??= {};
+  opencodeConfig.command.backeer = {
+    template: "",
+    description: COMMAND_DESCRIPTION
+  };
+}
+function createBackeerCommandHandler({
+  client,
+  config,
+  permissionController,
+  reporter
+}) {
+  return async (input, output) => {
+    if (input.command !== "backeer") return;
+    output.parts.length = 0;
+    const argumentsValue = (input.arguments ?? "").trim();
+    const separator = argumentsValue.indexOf(" ");
+    const subcommand = (separator === -1 ? argumentsValue : argumentsValue.slice(0, separator)).toLowerCase();
+    const subcommandArguments = separator === -1 ? "" : argumentsValue.slice(separator + 1).trim();
+    let message;
+    try {
+      if (!subcommand || subcommand === "status") {
+        message = await buildStatus(config, permissionController);
+      } else if (subcommand === "token") {
+        message = tokenInstructions();
+      } else if (subcommand === "token-file") {
+        const targetPath = rotateTokenFromFile(config, subcommandArguments);
+        permissionController.refreshCredentials();
+        reporter.success("Access token updated");
+        message = [
+          "## Backeer token updated",
+          "",
+          `- Protected token file: ${targetPath}`,
+          "- File mode: 600",
+          "- The new token is active immediately."
+        ].join("\n");
+      } else {
+        message = helpMessage();
+      }
+    } catch (error) {
+      reporter.error("Access token could not be updated", error);
+      message = [
+        "## Backeer command failed",
+        "",
+        error instanceof Error ? error.message : String(error),
+        "",
+        "Use `/backeer token` for secure token-change instructions."
+      ].join("\n");
+    }
+    await sendCommandMessage(client, input.sessionID, message);
+  };
+}
+
 // src/sse.js
 function parseSseFrame(frame) {
   const data = [];
@@ -605,6 +790,16 @@ function createPermissionController({
       removePendingByRequestID(requestID);
       stopCommandStreamIfIdle();
     },
+    refreshCredentials() {
+      commandStream?.controller.abort();
+      if (!commandStream) ensureCommandStream();
+    },
+    status() {
+      return {
+        pending: pendingByExternalID.size,
+        stream: commandStream ? "active" : "idle"
+      };
+    },
     async dispose() {
       disposed = true;
       commandStream?.controller.abort();
@@ -632,13 +827,6 @@ async function BackeerPlugin({ client, directory }, options = {}) {
     return {};
   }
   const reporter = createConsoleReporter(config.logLevel);
-  if (!config.token) {
-    reporter.error(
-      "Plugin disabled \u2014 run: npx backeer-opencode@latest configure",
-      `Token not found at ${config.tokenFile}`
-    );
-    return {};
-  }
   const permissionController = createPermissionController({
     config,
     reporter,
@@ -647,6 +835,18 @@ async function BackeerPlugin({ client, directory }, options = {}) {
   });
   const todoCompletionBySessionID = /* @__PURE__ */ new Map();
   const publishedQuestions = /* @__PURE__ */ new Map();
+  const handleBackeerCommand = createBackeerCommandHandler({
+    client,
+    config,
+    permissionController,
+    reporter
+  });
+  if (!config.token) {
+    reporter.error(
+      "Notifications disabled \u2014 use /backeer token",
+      `Token not found at ${config.tokenFile}`
+    );
+  }
   async function handlePermissionAsked(event) {
     const identity = permissionIdentity(event.properties);
     if (!identity) {
@@ -699,7 +899,12 @@ async function BackeerPlugin({ client, directory }, options = {}) {
     ).catch((error) => reporter.error("Question could not be sent", error));
   }
   return {
+    config: async (opencodeConfig) => {
+      registerBackeerCommand(opencodeConfig);
+    },
+    "command.execute.before": handleBackeerCommand,
     event: async ({ event }) => {
+      if (!config.token) return;
       if (config.permissions && event.type === "permission.asked") {
         await handlePermissionAsked(event);
         return;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "backeer-opencode",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "description": "Backeer notifications and remote permission decisions for OpenCode",
   "type": "module",
   "main": "./src/index.js",

package/src/config.js

@@ -14,12 +14,13 @@ function defaultConfigDirectory() {
 
 function loadToken(tokenFile) {
   const environmentToken = process.env.BACKEER_INGEST_TOKEN?.trim()
-  if (environmentToken) return environmentToken
+  if (environmentToken) return { token: environmentToken, source: "environment" }
 
   try {
-    return readFileSync(tokenFile, "utf8").trim()
+    const token = readFileSync(tokenFile, "utf8").trim()
+    return { token, source: token ? "file" : "missing" }
   } catch {
-    return ""
+    return { token: "", source: "missing" }
   }
 }
 
@@ -36,11 +37,13 @@ export function loadConfig(options = {}) {
     process.env.BACKEER_TOKEN_FILE ??
     join(defaultConfigDirectory(), "secrets", "backeer-ingest-token")
 
+  const loadedToken = loadToken(tokenFile)
   return {
     origin,
     eventsEndpoint: new URL("/v1/events", origin),
     commandStreamEndpoint: new URL("/v1/commands/stream", origin),
-    token: loadToken(tokenFile),
+    token: loadedToken.token,
+    tokenSource: loadedToken.source,
     tokenFile,
     permissions: enabled(
       options.permissions ?? process.env.BACKEER_NOTIFY_PERMISSIONS,

package/src/management.js

@@ -0,0 +1,207 @@
+import {
+  chmodSync,
+  mkdirSync,
+  readFileSync,
+  renameSync,
+  statSync,
+  writeFileSync,
+} from "node:fs"
+import { dirname, resolve } from "node:path"
+
+export const PLUGIN_VERSION = "0.1.4"
+
+const COMMAND_DESCRIPTION =
+  "Show Backeer status or manage its token: /backeer [status|token|token-file PATH]"
+
+function tokenFileState(path) {
+  try {
+    const stats = statSync(path)
+    const mode = (stats.mode & 0o777).toString(8).padStart(3, "0")
+    return stats.isFile() ? `present (mode ${mode})` : "not a regular file"
+  } catch {
+    return "missing"
+  }
+}
+
+function cleanPathArgument(value) {
+  const path = value.trim()
+  if (
+    path.length >= 2 &&
+    ((path.startsWith('"') && path.endsWith('"')) ||
+      (path.startsWith("'") && path.endsWith("'")))
+  ) {
+    return path.slice(1, -1)
+  }
+  return path
+}
+
+function writeTokenAtomically(path, token) {
+  mkdirSync(dirname(path), { recursive: true, mode: 0o700 })
+  const temporaryPath = `${path}.${process.pid}.${Date.now()}.tmp`
+  writeFileSync(temporaryPath, `${token}\n`, { encoding: "utf8", mode: 0o600 })
+  chmodSync(temporaryPath, 0o600)
+  renameSync(temporaryPath, path)
+}
+
+export function rotateTokenFromFile(config, sourcePathValue) {
+  if (!sourcePathValue.trim()) throw new Error("A token file path is required")
+  const sourcePath = resolve(cleanPathArgument(sourcePathValue))
+
+  const sourceStats = statSync(sourcePath)
+  if (!sourceStats.isFile()) throw new Error("The token source is not a regular file")
+  if ((sourceStats.mode & 0o077) !== 0) {
+    throw new Error("The token source must not be readable by group or other users")
+  }
+
+  const token = readFileSync(sourcePath, "utf8").trim()
+  if (!token || /\s/.test(token)) {
+    throw new Error("The token source must contain exactly one non-empty token")
+  }
+
+  const targetPath = resolve(config.tokenFile)
+  if (sourcePath !== targetPath) writeTokenAtomically(targetPath, token)
+  else chmodSync(targetPath, 0o600)
+  config.token = token
+  config.tokenSource = "file"
+  return targetPath
+}
+
+async function probeGateway(config) {
+  const controller = new AbortController()
+  const timeout = setTimeout(() => controller.abort(), 3000)
+  try {
+    const response = await fetch(config.origin, {
+      method: "HEAD",
+      redirect: "manual",
+      signal: controller.signal,
+    })
+    return `reachable (HTTP ${response.status}; authentication not tested)`
+  } catch {
+    return "unreachable"
+  } finally {
+    clearTimeout(timeout)
+  }
+}
+
+async function buildStatus(config, permissionController) {
+  const gateway = await probeGateway(config)
+  const permissionStatus = permissionController.status()
+  return [
+    "## Backeer status",
+    "",
+    `- Plugin version: ${PLUGIN_VERSION}`,
+    `- Gateway: ${config.origin.origin} — ${gateway}`,
+    `- Token: ${config.token ? `configured via ${config.tokenSource}` : "missing"}`,
+    `- Token file: ${config.tokenFile} — ${tokenFileState(config.tokenFile)}`,
+    `- Permission notifications: ${config.permissions ? "enabled" : "disabled"}`,
+    `- Question notifications: ${config.questions ? "enabled" : "disabled"}`,
+    `- Todo notifications: ${config.todos ? "enabled" : "disabled"}`,
+    `- Command stream: ${permissionStatus.stream}`,
+    `- Pending permissions: ${permissionStatus.pending}`,
+    `- Log level: ${config.logLevel}`,
+    "",
+    "The token value is never displayed.",
+  ].join("\n")
+}
+
+function helpMessage() {
+  return [
+    "## Backeer commands",
+    "",
+    "- `/backeer` or `/backeer status` — show integration status",
+    "- `/backeer token` — show secure token-change instructions",
+    "- `/backeer token-file /absolute/protected/path` — import and activate a token",
+    "",
+    "Never place a token directly in a slash command. Slash-command arguments may be stored in session history.",
+  ].join("\n")
+}
+
+function tokenInstructions() {
+  return [
+    "## Change the Backeer token securely",
+    "",
+    "Do not paste the token into OpenCode or `/backeer` arguments.",
+    "",
+    "Use either:",
+    "",
+    "1. Hidden terminal input: `npx backeer-opencode@latest configure`",
+    "2. A protected file: `chmod 600 /path/to/token && /backeer token-file /path/to/token`",
+    "",
+    "`token-file` activates the new token immediately; no OpenCode restart is required.",
+  ].join("\n")
+}
+
+async function sendCommandMessage(client, sessionID, text) {
+  if (typeof client?.session?.prompt !== "function") {
+    throw new Error("OpenCode session messaging is unavailable")
+  }
+  await client.session.prompt({
+    path: { id: sessionID },
+    body: {
+      noReply: true,
+      parts: [{ type: "text", text, ignored: true }],
+    },
+  })
+}
+
+export function registerBackeerCommand(opencodeConfig) {
+  opencodeConfig.command ??= {}
+  opencodeConfig.command.backeer = {
+    template: "",
+    description: COMMAND_DESCRIPTION,
+  }
+}
+
+export function createBackeerCommandHandler({
+  client,
+  config,
+  permissionController,
+  reporter,
+}) {
+  return async (input, output) => {
+    if (input.command !== "backeer") return
+    output.parts.length = 0
+
+    const argumentsValue = (input.arguments ?? "").trim()
+    const separator = argumentsValue.indexOf(" ")
+    const subcommand = (
+      separator === -1 ? argumentsValue : argumentsValue.slice(0, separator)
+    ).toLowerCase()
+    const subcommandArguments = separator === -1
+      ? ""
+      : argumentsValue.slice(separator + 1).trim()
+
+    let message
+    try {
+      if (!subcommand || subcommand === "status") {
+        message = await buildStatus(config, permissionController)
+      } else if (subcommand === "token") {
+        message = tokenInstructions()
+      } else if (subcommand === "token-file") {
+        const targetPath = rotateTokenFromFile(config, subcommandArguments)
+        permissionController.refreshCredentials()
+        reporter.success("Access token updated")
+        message = [
+          "## Backeer token updated",
+          "",
+          `- Protected token file: ${targetPath}`,
+          "- File mode: 600",
+          "- The new token is active immediately.",
+        ].join("\n")
+      } else {
+        message = helpMessage()
+      }
+    } catch (error) {
+      reporter.error("Access token could not be updated", error)
+      message = [
+        "## Backeer command failed",
+        "",
+        error instanceof Error ? error.message : String(error),
+        "",
+        "Use `/backeer token` for secure token-change instructions.",
+      ].join("\n")
+    }
+
+    await sendCommandMessage(client, input.sessionID, message)
+  }
+}

package/src/permission-controller.js

@@ -169,6 +169,18 @@ export function createPermissionController({
       stopCommandStreamIfIdle()
     },
 
+    refreshCredentials() {
+      commandStream?.controller.abort()
+      if (!commandStream) ensureCommandStream()
+    },
+
+    status() {
+      return {
+        pending: pendingByExternalID.size,
+        stream: commandStream ? "active" : "idle",
+      }
+    },
+
     async dispose() {
       disposed = true
       commandStream?.controller.abort()

package/src/plugin.js

@@ -6,6 +6,10 @@ import {
   publishTodoCompletion,
   questionIdentity,
 } from "./event-publishers.js"
+import {
+  createBackeerCommandHandler,
+  registerBackeerCommand,
+} from "./management.js"
 import { createPermissionController } from "./permission-controller.js"
 import { createConsoleReporter } from "./reporter.js"
 import { rememberBounded } from "./utilities.js"
@@ -31,14 +35,6 @@ export default async function BackeerPlugin({ client, directory }, options = {})
 
   const reporter = createConsoleReporter(config.logLevel)
 
-  if (!config.token) {
-    reporter.error(
-      "Plugin disabled — run: npx backeer-opencode@latest configure",
-      `Token not found at ${config.tokenFile}`,
-    )
-    return {}
-  }
-
   const permissionController = createPermissionController({
     config,
     reporter,
@@ -47,6 +43,19 @@ export default async function BackeerPlugin({ client, directory }, options = {})
   })
   const todoCompletionBySessionID = new Map()
   const publishedQuestions = new Map()
+  const handleBackeerCommand = createBackeerCommandHandler({
+    client,
+    config,
+    permissionController,
+    reporter,
+  })
+
+  if (!config.token) {
+    reporter.error(
+      "Notifications disabled — use /backeer token",
+      `Token not found at ${config.tokenFile}`,
+    )
+  }
 
   async function handlePermissionAsked(event) {
     const identity = permissionIdentity(event.properties)
@@ -108,7 +117,15 @@ export default async function BackeerPlugin({ client, directory }, options = {})
   }
 
   return {
+    config: async (opencodeConfig) => {
+      registerBackeerCommand(opencodeConfig)
+    },
+
+    "command.execute.before": handleBackeerCommand,
+
     event: async ({ event }) => {
+      if (!config.token) return
+
       if (config.permissions && event.type === "permission.asked") {
         await handlePermissionAsked(event)
         return