Changed: BREAKING: All integrations are now individual, always acting on behalf of a particular user.

Author: KrisBraun

.changeset/ninety-paths-kiss.md

@@ -0,0 +1,13 @@
+---
+"@plotday/tool-outlook-calendar": minor
+"@plotday/tool-google-calendar": minor
+"@plotday/tool-google-contacts": minor
+"@plotday/tool-linear": minor
+"@plotday/tool-asana": minor
+"@plotday/tool-gmail": minor
+"@plotday/tool-slack": minor
+"@plotday/tool-jira": minor
+"@plotday/twister": minor
+---
+
+Changed: BREAKING: All integrations are now individual, always acting on behalf of a particular user.

AGENTS.md

@@ -28,6 +28,7 @@ All type definitions are in `twister/src/` with full JSDoc:
 - **Runtime Environment**: `twister/docs/RUNTIME.md`
 - **Tools Guide**: `twister/docs/TOOLS_GUIDE.md`
 - **Twist Development**: `twister/cli/templates/AGENTS.template.md`
+- **Multi-User Auth**: `twister/docs/MULTI_USER_AUTH.md`
 - **Working Examples**: `tools/google-calendar/`, `tools/google-contacts/`, `tools/linear/`
 
 ## Common Pitfalls
@@ -37,6 +38,8 @@ All type definitions are in `twister/src/` with full JSDoc:
 3. **❌ Forgetting to clean up** - Delete callbacks and stored state when done
 4. **❌ Not handling missing auth** - Always check for stored tokens before operations
 5. **❌ Passing functions to `this.callback()`** - See `tools/AGENTS.md` for critical callback serialization pattern
+6. **❌ Non-private auth activities** - Auth activities in `activate()` should be `private: true` with mentions targeting `context.actor`
+7. **❌ Using installer auth for all write-backs** - Try acting user's credentials first for user-attributed actions (comments). See `twister/docs/MULTI_USER_AUTH.md`
 
 ---
 

tools/AGENTS.md

@@ -270,6 +270,8 @@ Building a tool? Follow this checklist:
 - [ ] Size batches appropriately - calculate requests per item to determine safe batch size
 - [ ] Use `this.runTask()` to create new executions with fresh request limits
 - [ ] Clean up stored state and callbacks in lifecycle methods
+- [ ] **Per-user auth for write-backs**: Try `actorId` as `authToken` first, fall back to installer's token
+- [ ] **Private auth activities**: Set `private: true` and add `mentions: [{ id: context.actor.id }]` in `activate()`
 
 ## Common Tool Pitfalls
 
@@ -279,7 +281,9 @@ Building a tool? Follow this checklist:
 4. **❌ Forgetting to store the callback token** - Store it immediately after creating
 5. **❌ Passing undefined instead of null** - Use `null` for optional values
 6. **❌ Not breaking loops into batches** - Each execution has ~1000 request limit; use `runTask()` for fresh limits
-7. **❌ Two-way sync without metadata correlation** - When pushing Plot items to an external system, embed the Plot ID (`Activity.id` / `Note.id`) in the external item's metadata, and update `source`/`key` after creation. In webhook handlers, check metadata for the Plot ID first. This prevents duplicates from a race condition where the webhook arrives before the `source`/`key` update. See SYNC_STRATEGIES.md §6 for a full example.
+7. **❌ Using installer auth for all write-backs** - In multi-user priorities, try the acting user's credentials first (`note.author.id` as authToken) before falling back to installer auth
+8. **❌ Non-private auth activities** - Auth activities from `activate()` should be `private: true` with mentions so only the installing user sees them
+9. **❌ Two-way sync without metadata correlation** - When pushing Plot items to an external system, embed the Plot ID (`Activity.id` / `Note.id`) in the external item's metadata, and update `source`/`key` after creation. In webhook handlers, check metadata for the Plot ID first. This prevents duplicates from a race condition where the webhook arrives before the `source`/`key` update. See SYNC_STRATEGIES.md §6 for a full example.
 
 ---
 

tools/asana/src/asana.ts

@@ -6,6 +6,7 @@ import {
   ActivityLinkType,
   ActivityMeta,
   ActivityType,
+  type ActorId,
   type NewActivity,
   type NewActivityWithNotes,
   type NewNote,
@@ -21,7 +22,6 @@ import type { NewContact } from "@plotday/twister/plot";
 import { Tool, type ToolBuilder } from "@plotday/twister/tool";
 import { type Callback, Callbacks } from "@plotday/twister/tools/callbacks";
 import {
-  AuthLevel,
   AuthProvider,
   type Authorization,
   Integrations,
@@ -58,16 +58,22 @@ export class Asana extends Tool<Asana> implements ProjectTool {
    * Create Asana API client with auth token
    */
   private async getClient(authToken: string): Promise<asana.Client> {
-    const authorization = await this.get<Authorization>(
-      `authorization:${authToken}`
-    );
-    if (!authorization) {
-      throw new Error("Authorization no longer available");
-    }
+    // Try new flow: look up by provider + actor ID
+    let token = await this.tools.integrations.get(AuthProvider.Asana, authToken as ActorId);
 
-    const token = await this.tools.integrations.get(authorization);
+    // Fall back to legacy authorization lookup
     if (!token) {
-      throw new Error("Authorization no longer available");
+      const authorization = await this.get<Authorization>(
+        `authorization:${authToken}`
+      );
+      if (!authorization) {
+        throw new Error("Authorization no longer available");
+      }
+
+      token = await this.tools.integrations.get(authorization.provider, authorization.actor.id);
+      if (!token) {
+        throw new Error("Authorization no longer available");
+      }
     }
 
     return asana.Client.create().useAccessToken(token.token);
@@ -82,9 +88,6 @@ export class Asana extends Tool<Asana> implements ProjectTool {
   >(callback: TCallback, ...extraArgs: TArgs): Promise<ActivityLink> {
     const asanaScopes = ["default"];
 
-    // Generate opaque token for authorization
-    const authToken = crypto.randomUUID();
-
     const callbackToken = await this.tools.callbacks.createFromParent(
       callback,
       ...extraArgs
@@ -94,11 +97,9 @@ export class Asana extends Tool<Asana> implements ProjectTool {
     return await this.tools.integrations.request(
       {
         provider: AuthProvider.Asana,
-        level: AuthLevel.User,
         scopes: asanaScopes,
       },
       this.onAuthSuccess,
-      authToken,
       callbackToken
     );
   }
@@ -108,14 +109,10 @@ export class Asana extends Tool<Asana> implements ProjectTool {
    */
   private async onAuthSuccess(
     authorization: Authorization,
-    authToken: string,
     callbackToken: Callback
   ): Promise<void> {
-    // Store authorization for later use
-    await this.set(`authorization:${authToken}`, authorization);
-
-    // Execute the callback with the auth token
-    await this.run(callbackToken, { authToken });
+    // Execute the callback with the actor ID as auth token
+    await this.run(callbackToken, { authToken: authorization.actor.id as string });
   }
 
   /**

tools/gmail/src/gmail.ts

@@ -1,4 +1,5 @@
 import {
+  type ActorId,
   type ActivityLink,
   type NewActivityWithNotes,
   Serializable,
@@ -13,7 +14,6 @@ import {
 } from "@plotday/twister/common/messaging";
 import { type Callback } from "@plotday/twister/tools/callbacks";
 import {
-  AuthLevel,
   AuthProvider,
   type Authorization,
   Integrations,
@@ -121,9 +121,6 @@ export class Gmail extends Tool<Gmail> implements MessagingTool {
       "https://www.googleapis.com/auth/gmail.modify",
     ];
 
-    // Generate opaque token for authorization
-    const authToken = crypto.randomUUID();
-
     const callbackToken = await this.tools.callbacks.createFromParent(
       callback,
       ...extraArgs
@@ -134,29 +131,34 @@ export class Gmail extends Tool<Gmail> implements MessagingTool {
     return await this.tools.integrations.request(
       {
         provider: AuthProvider.Google,
-        level: AuthLevel.User,
         scopes: gmailScopes,
       },
       this.onAuthSuccess,
-      authToken,
       callbackToken
     );
   }
 
   private async getApi(authToken: string): Promise<GmailApi> {
+    // Try new flow: authToken is an ActorId
+    const token = await this.tools.integrations.get(AuthProvider.Google, authToken as ActorId);
+    if (token) {
+      return new GmailApi(token.token);
+    }
+
+    // Fall back to legacy flow: authToken is an opaque key
     const authorization = await this.get<Authorization>(
       `authorization:${authToken}`
     );
     if (!authorization) {
       throw new Error("Authorization no longer available");
     }
 
-    const token = await this.tools.integrations.get(authorization);
-    if (!token) {
+    const legacyToken = await this.tools.integrations.get(authorization.provider, authorization.actor.id);
+    if (!legacyToken) {
       throw new Error("Authorization no longer available");
     }
 
-    return new GmailApi(token.token);
+    return new GmailApi(legacyToken.token);
   }
 
   async getChannels(authToken: string): Promise<MessageChannel[]> {
@@ -454,20 +456,13 @@ export class Gmail extends Tool<Gmail> implements MessagingTool {
 
   async onAuthSuccess(
     authResult: Authorization,
-    authToken: string,
     callback: Callback
   ): Promise<void> {
-    // Store the actual auth token using opaque token as key
-    await this.set(`authorization:${authToken}`, authResult);
-
     const authSuccessResult: MessagingAuth = {
-      authToken,
+      authToken: authResult.actor.id as string,
     };
 
     await this.run(callback, authSuccessResult);
-
-    // Clean up the callback token
-    await this.clear(`auth_callback_token:${authToken}`);
   }
 }
 

tools/google-calendar/README.md

@@ -13,7 +13,7 @@ npm install @plotday/tool-google-calendar @plotday/twister
 ```typescript
 import { Twist, Tools } from "@plotday/twister";
 import { GoogleCalendar } from "@plotday/tool-google-calendar";
-import { Integrations, AuthLevel, AuthProvider } from "@plotday/twister/tools/integrations";
+import { Integrations, AuthProvider } from "@plotday/twister/tools/integrations";
 
 export default class extends Twist {
   private googleCalendar: GoogleCalendar;
@@ -30,7 +30,6 @@ export default class extends Twist {
     const authLink = await this.integrations.request(
       {
         provider: AuthProvider.Google,
-        level: AuthLevel.User,
         scopes: ["https://www.googleapis.com/auth/calendar.readonly"],
       },
       {