Merge pull request #38 from HomicideZero/pr/authenticated-mode-board-auth

fix: authenticate Paperclip API calls in authenticated deployment mode

Author: mvanhorn

src/commands.ts

@@ -41,7 +41,13 @@ interface Interaction {
 export interface CommandContext {
   baseUrl: string;
   companyId: string;
+  /** Discord bot token — used for Discord API calls. */
   token: string;
+  /** Optional Paperclip board API key — attached to Paperclip API calls that
+   * require board authentication (approve/reject, create issues, etc.).
+   * Empty string disables the Authorization header, which is correct for
+   * `local_trusted` deployments. */
+  paperclipBoardApiKey?: string;
   defaultChannelId: string;
   /** PluginContext for lazy company-ID resolution at command time. */
   pluginCtx?: PluginContext;
@@ -396,6 +402,7 @@ async function handleSlashCommand(
         getOption(subcommand.options ?? [], "id"),
         member?.user.username,
         baseUrl,
+        cmdCtx?.paperclipBoardApiKey,
       );
     case "budget":
       return handleBudget(ctx, getOption(subcommand.options ?? [], "agent"), companyId);
@@ -552,6 +559,7 @@ async function handleApprove(
   approvalId: string | undefined,
   username?: string,
   baseUrl?: string,
+  apiKey?: string,
 ): Promise<unknown> {
   if (!approvalId) {
     return respondToInteraction({
@@ -568,7 +576,7 @@ async function handleApprove(
         method: "POST",
         headers: { "Content-Type": "application/json" },
         body: JSON.stringify({ decidedByUserId: `discord:${username ?? "unknown"}` }),
-      });
+      }, apiKey);
       throwOnRetryableStatus(r);
       return r;
     });
@@ -1144,6 +1152,7 @@ async function handleButtonClick(
   const actor = username ?? "Discord user";
   const base = cmdCtx?.baseUrl ?? "http://localhost:3100";
   const token = cmdCtx?.token ?? "";
+  const apiKey = cmdCtx?.paperclipBoardApiKey ?? "";
 
   if (customId.startsWith("approval_approve_")) {
     const approvalId = customId.replace("approval_approve_", "");
@@ -1155,7 +1164,7 @@ async function handleButtonClick(
           method: "POST",
           headers: { "Content-Type": "application/json" },
           body: JSON.stringify({ decidedByUserId: `discord:${actor}` }),
-        });
+        }, apiKey);
         throwOnRetryableStatus(r);
         return r;
       });
@@ -1206,7 +1215,7 @@ async function handleButtonClick(
           method: "POST",
           headers: { "Content-Type": "application/json" },
           body: JSON.stringify({ decidedByUserId: `discord:${actor}` }),
-        });
+        }, apiKey);
         throwOnRetryableStatus(r);
         return r;
       });
@@ -1537,6 +1546,7 @@ async function handleCommands(
         channelId,
         getOption(sub.options ?? [], "name") ?? "",
         getOption(sub.options ?? [], "args") ?? "",
+        cmdCtx?.paperclipBoardApiKey ?? "",
       );
     case "delete":
       return handleCommandsDelete(ctx, companyId, getOption(sub.options ?? [], "name") ?? "");
@@ -1666,6 +1676,7 @@ async function handleCommandsRun(
   channelId: string,
   name: string,
   args: string,
+  paperclipBoardApiKey: string,
 ): Promise<unknown> {
   if (!name.trim()) {
     return respondToInteraction({
@@ -1694,6 +1705,7 @@ async function handleCommandsRun(
     channelId,
     companyId,
     baseUrl,
+    paperclipBoardApiKey,
     workflow,
     args,
   });
@@ -1806,6 +1818,7 @@ async function handleWorkflowApprovalButton(
     baseUrl,
     approvalId,
     approved,
+    cmdCtx?.paperclipBoardApiKey ?? "",
   );
 
   const statusText = approved ? "Approved" : "Rejected";

src/constants.ts

@@ -1,5 +1,5 @@
 export const PLUGIN_ID = "paperclip-plugin-discord";
-export const PLUGIN_VERSION = "0.7.2";
+export const PLUGIN_VERSION = "0.7.3";
 
 export const WEBHOOK_KEYS = {
   discordInteractions: "discord-interactions",
@@ -15,6 +15,7 @@ export const EXPORT_NAMES = {
 
 export const DEFAULT_CONFIG = {
   discordBotTokenRef: "",
+  paperclipBoardApiKeyRef: "",
   defaultGuildId: "",
   defaultChannelId: "",
   approvalsChannelId: "",

src/manifest.ts

@@ -55,6 +55,14 @@ const manifest: PaperclipPluginManifestV1 = {
           "Secret UUID for your Discord Bot token. Create the secret in Settings → Secrets, then paste its UUID here.",
         default: DEFAULT_CONFIG.discordBotTokenRef,
       },
+      paperclipBoardApiKeyRef: {
+        type: "string",
+        format: "secret-ref",
+        title: "Paperclip Board API Key (secret reference)",
+        description:
+          "Optional. Secret UUID for a Paperclip board API key. Required when Paperclip is deployed in `authenticated` mode so that plugin-originated calls (approve/reject buttons, workflow steps, inbound reply routing) can satisfy server-side board-auth checks. Create a board API key in Settings → API Keys, store it as a secret, then paste the secret UUID here. Leave blank for `local_trusted` deployments.",
+        default: DEFAULT_CONFIG.paperclipBoardApiKeyRef,
+      },
       defaultGuildId: {
         type: "string",
         title: "Default Guild (Server) ID",

src/paperclip-fetch.ts

@@ -10,10 +10,23 @@
  *
  * Native `fetch` has no such restriction, so we use it for all calls
  * that target the Paperclip base URL.
+ *
+ * Auth: when Paperclip is deployed in `authenticated` mode (the default
+ * for public deployments), server routes that call `assertBoard(req)`
+ * (approvals, board mutations, etc.) require an Authorization: Bearer
+ * header carrying a board API key. Pass `apiKey` to attach it. In
+ * `local_trusted` deployments unauthenticated requests are implicitly
+ * promoted to `board`, so `apiKey` can be omitted.
  */
 export function paperclipFetch(
   url: string,
   init?: RequestInit,
+  apiKey?: string,
 ): Promise<Response> {
-  return fetch(url, init);
+  if (!apiKey) return fetch(url, init);
+  const headers = new Headers(init?.headers);
+  if (!headers.has("Authorization")) {
+    headers.set("Authorization", `Bearer ${apiKey}`);
+  }
+  return fetch(url, { ...init, headers });
 }

src/worker.ts

@@ -61,6 +61,7 @@ import {
 
 type DiscordConfig = {
   discordBotTokenRef: string;
+  paperclipBoardApiKeyRef?: string;
   defaultGuildId: string;
   defaultChannelId: string;
   approvalsChannelId: string;
@@ -269,6 +270,9 @@ const plugin = definePlugin({
     }
 
     const token = await ctx.secrets.resolve(config.discordBotTokenRef);
+    const paperclipBoardApiKey = config.paperclipBoardApiKeyRef
+      ? await ctx.secrets.resolve(config.paperclipBoardApiKeyRef)
+      : "";
     const baseUrl = config.paperclipBaseUrl || "http://localhost:3100";
     const retentionDays = config.intelligenceRetentionDays || 30;
     const defaultGuildId = normalizeDiscordId(config.defaultGuildId);
@@ -287,6 +291,7 @@ const plugin = definePlugin({
       baseUrl,
       companyId,
       token,
+      paperclipBoardApiKey,
       defaultChannelId,
       pluginCtx: ctx,
     };
@@ -386,6 +391,7 @@ const plugin = definePlugin({
                 authorUserId: `discord:${message.author.username}`,
               }),
             },
+            paperclipBoardApiKey,
           );
           await ctx.metrics.write(METRIC_NAMES.inboundRouted, 1);
           ctx.logger.info("Routed Discord reply to issue comment", {

src/workflow-engine.ts

@@ -121,6 +121,7 @@ async function execFetchIssue(
   step: WorkflowStep,
   wfCtx: WorkflowContext,
   baseUrl: string,
+  apiKey: string,
 ): Promise<StepResult> {
   const issueId = interpolate(step.issueId ?? "", wfCtx);
   if (!issueId) return { ok: false, error: "Missing issueId" };
@@ -129,7 +130,7 @@ async function execFetchIssue(
     const resp = await paperclipFetch(`${baseUrl}/api/issues/${issueId}`, {
       method: "GET",
       headers: { "Content-Type": "application/json" },
-    });
+    }, apiKey);
     if (!resp.ok) return { ok: false, error: `API ${resp.status}` };
     const data = await resp.json();
     return { ok: true, result: data };
@@ -232,6 +233,7 @@ async function execCreateIssue(
   wfCtx: WorkflowContext,
   companyId: string,
   baseUrl: string,
+  apiKey: string,
 ): Promise<StepResult> {
   const title = interpolate(step.title ?? "", wfCtx);
   if (!title) return { ok: false, error: "Missing title" };
@@ -250,7 +252,7 @@ async function execCreateIssue(
       method: "POST",
       headers: { "Content-Type": "application/json" },
       body: JSON.stringify(payload),
-    });
+    }, apiKey);
     if (!resp.ok) return { ok: false, error: `API ${resp.status}` };
     const data = await resp.json();
     return { ok: true, result: data };
@@ -355,6 +357,9 @@ export interface WorkflowRunOptions {
   channelId: string;
   companyId: string;
   baseUrl: string;
+  /** Paperclip board API key. Empty string disables Authorization header
+   * (correct for `local_trusted` deployments). Required for `authenticated`. */
+  paperclipBoardApiKey: string;
   workflow: Workflow;
   args: string;
   /** Resume from this step index (for approval continuation) */
@@ -369,7 +374,7 @@ export async function runWorkflow(opts: WorkflowRunOptions): Promise<{
   suspended?: boolean;
   error?: string;
 }> {
-  const { ctx, token, channelId, companyId, baseUrl, workflow, args } = opts;
+  const { ctx, token, channelId, companyId, baseUrl, paperclipBoardApiKey, workflow, args } = opts;
 
   const wfCtx: WorkflowContext = opts.resumeCtx
     ? { ...opts.resumeCtx, prevResult: null }
@@ -389,7 +394,7 @@ export async function runWorkflow(opts: WorkflowRunOptions): Promise<{
 
     switch (step.type) {
       case "fetch_issue":
-        result = await execFetchIssue(ctx, step, wfCtx, baseUrl);
+        result = await execFetchIssue(ctx, step, wfCtx, baseUrl, paperclipBoardApiKey);
         break;
       case "invoke_agent":
         result = await execInvokeAgent(ctx, step, wfCtx, companyId);
@@ -401,7 +406,7 @@ export async function runWorkflow(opts: WorkflowRunOptions): Promise<{
         result = await execSendMessage(ctx, step, wfCtx, token, channelId);
         break;
       case "create_issue":
-        result = await execCreateIssue(ctx, step, wfCtx, companyId, baseUrl);
+        result = await execCreateIssue(ctx, step, wfCtx, companyId, baseUrl, paperclipBoardApiKey);
         break;
       case "wait_approval":
         result = await execWaitApproval(ctx, step, wfCtx, token, channelId, workflow.name, i, companyId);
@@ -481,6 +486,7 @@ export async function resumeWorkflowAfterApproval(
   baseUrl: string,
   approvalId: string,
   approved: boolean,
+  paperclipBoardApiKey: string,
 ): Promise<{ ok: boolean; error?: string }> {
   const pending = (await ctx.state.get({
     scopeKind: "company",
@@ -527,6 +533,7 @@ export async function resumeWorkflowAfterApproval(
     channelId,
     companyId,
     baseUrl,
+    paperclipBoardApiKey,
     workflow,
     args: pending.wfCtx.fullArgs,
     resumeFromStep: pending.stepIndex + 1,

tests/commands.test.ts

@@ -58,6 +58,7 @@ const defaultCmdCtx: CommandContext = {
   baseUrl: "http://localhost:3100",
   companyId: "default",
   token: "test-token",
+  paperclipBoardApiKey: "test-board-key",
   defaultChannelId: "ch-1",
 };
 
@@ -235,6 +236,7 @@ describe("/clip approve", () => {
     expect(mockPaperclipFetch).toHaveBeenCalledWith(
       "https://app.example.com/api/approvals/apr-1/approve",
       expect.objectContaining({ method: "POST" }),
+      expect.any(String),
     );
     expect(result.data.embeds[0].color).toBe(COLORS.GREEN);
   });
@@ -333,6 +335,7 @@ describe("button clicks", () => {
     expect(mockPaperclipFetch).toHaveBeenCalledWith(
       "https://app.example.com/api/approvals/apr-1/approve",
       expect.objectContaining({ method: "POST" }),
+      expect.any(String),
     );
     expect(result.type).toBe(7);
     expect(result.data.embeds[0].description).toContain("Approved");
@@ -354,6 +357,7 @@ describe("button clicks", () => {
     expect(mockPaperclipFetch).toHaveBeenCalledWith(
       "https://app.example.com/api/approvals/apr-2/reject",
       expect.objectContaining({ method: "POST" }),
+      expect.any(String),
     );
     expect(result.type).toBe(7);
     expect(result.data.embeds[0].description).toContain("Rejected");

tests/workflow-engine.test.ts

@@ -63,6 +63,7 @@ const baseOpts = {
   channelId: "ch-1",
   companyId: "company-1",
   baseUrl: "http://localhost:3100",
+  paperclipBoardApiKey: "",
   args: "",
 };
 
@@ -90,6 +91,7 @@ describe("runWorkflow — template interpolation", () => {
     expect(mockPaperclipFetch).toHaveBeenCalledWith(
       expect.stringContaining("/api/issues/my-issue-id"),
       expect.anything(),
+      expect.any(String),
     );
   });
 
@@ -284,6 +286,7 @@ describe("runWorkflow — step types", () => {
         method: "POST",
         body: expect.stringContaining("Bug: login-broken"),
       }),
+      expect.any(String),
     );
   });