@stina/extension-api 1.3.1 → 1.7.0

package/schema/extension-manifest.schema.json

@@ -110,6 +110,8 @@
                   "user.location.read",
                   "chat.history.read",
                   "chat.current.read",
+                  "attachments.read",
+                  "accounts.use",
                   "chat.message.write",
                   "provider.register",
                   "tools.register",
@@ -852,6 +854,44 @@
               ],
               "additionalProperties": false,
               "description": "Storage collection declarations"
+            },
+            "accounts": {
+              "type": "array",
+              "items": {
+                "type": "object",
+                "properties": {
+                  "provider": {
+                    "type": "string",
+                    "enum": [
+                      "microsoft"
+                    ],
+                    "description": "External account provider"
+                  },
+                  "scopes": {
+                    "type": "array",
+                    "items": {
+                      "type": "string",
+                      "pattern": "^[A-Za-z]+(\\.[A-Za-z]+)+$",
+                      "errorMessage": {
+                        "pattern": "Must be a Microsoft Graph permission name, such as \"Mail.Read\""
+                      }
+                    },
+                    "minItems": 1,
+                    "description": "Microsoft Graph delegated permissions"
+                  },
+                  "reason": {
+                    "$ref": "#/definitions/ExtensionManifest/properties/contributes/properties/tools/items/properties/confirmationPrompt",
+                    "description": "Why the extension needs them"
+                  }
+                },
+                "required": [
+                  "provider",
+                  "scopes"
+                ],
+                "additionalProperties": false,
+                "description": "An external account the extension works through"
+              },
+              "description": "External accounts the extension works through, signed in once in Stina's settings"
             }
           },
           "additionalProperties": false,

package/src/background.test.ts

@@ -318,6 +318,39 @@ describe('WorkerBackgroundTaskManager', () => {
       expect(receivedContext!.signal).toBeDefined()
       expect(receivedContext!.reportHealth).toBeDefined()
       expect(receivedContext!.log).toBeDefined()
+      // Not granted in this setup, so a task cannot reach for an account.
+      expect(receivedContext!.accounts).toBeUndefined()
+    })
+
+    it('hands a task the accounts of the user it runs for, when the extension may use them', async () => {
+      const accountsApi = { list: vi.fn(), getAccessToken: vi.fn() }
+      const createUserAccountsAPI = vi.fn(() => accountsApi)
+      const withAccounts = new WorkerBackgroundTaskManager({
+        extensionId: 'test-extension',
+        extensionVersion: '1.0.0',
+        storagePath: '/fake/path',
+        sendTaskRegistered,
+        sendTaskStatus,
+        sendHealthReport,
+        createLogAPI,
+        createStorageAPI,
+        createUserStorageAPI,
+        createSecretsAPI,
+        createUserSecretsAPI,
+        createUserAccountsAPI,
+      })
+
+      let receivedContext: BackgroundTaskContext | null = null
+      await withAccounts.start(
+        { id: 'task-2', name: 'Mail watch', userId: 'user-7', restartPolicy: { type: 'never' } },
+        vi.fn(async (context) => {
+          receivedContext = context
+        })
+      )
+      await withAccounts.handleStart('task-2')
+
+      expect(createUserAccountsAPI).toHaveBeenCalledWith('user-7')
+      expect(receivedContext!.accounts).toBe(accountsApi)
     })
   })
 

package/src/background.ts

@@ -14,6 +14,7 @@ import type {
   LogAPI,
   StorageAPI,
   SecretsAPI,
+  ConnectedAccountsAPI,
 } from './types.js'
 
 // ============================================================================
@@ -66,6 +67,11 @@ export interface WorkerBackgroundTaskManagerOptions {
   createSecretsAPI: () => SecretsAPI
   /** Create user-scoped secrets API */
   createUserSecretsAPI: (userId: string) => SecretsAPI
+  /**
+   * Create the connected accounts API for a user. Absent unless the extension
+   * holds `accounts.use`, which leaves `accounts` off the task's context.
+   */
+  createUserAccountsAPI?: (userId: string) => ConnectedAccountsAPI
 }
 
 // ============================================================================
@@ -235,6 +241,9 @@ export class WorkerBackgroundTaskManager {
       userStorage,
       secrets,
       userSecrets,
+      ...(config.userId && this.options.createUserAccountsAPI
+        ? { accounts: this.options.createUserAccountsAPI(config.userId) }
+        : {}),
       signal,
       reportHealth: (status: string) => {
         const timestamp = new Date().toISOString()

package/src/index.ts

@@ -36,6 +36,8 @@ export type {
   ToolDefinition,
   ToolConfirmationConfig,
   CommandDefinition,
+  AccountProvider,
+  AccountContribution,
 
   // Permissions
   Permission,
@@ -63,6 +65,11 @@ export type {
   ChatAPI,
   ChatInstructionMessage,
   ConversationPresentation,
+  AttachmentsAPI,
+  AttachmentContent,
+  ConnectedAccountsAPI,
+  ConnectedAccount,
+  AccountAccessToken,
   LogAPI,
 
   // Background workers
@@ -87,6 +94,7 @@ export type {
   ModelCapabilities,
   ChatMessage,
   ChatImage,
+  ChatFile,
   ChatOptions,
   GetModelsOptions,
   StreamEvent,

package/src/messages.ts

@@ -264,6 +264,11 @@ export type RequestMethod =
   // Tools cross-extension methods
   | 'tools.list'
   | 'tools.execute'
+  // Attachments
+  | 'attachments.read'
+  // Connected accounts
+  | 'accounts.list'
+  | 'accounts.getAccessToken'
 
 export interface ProviderRegisteredMessage {
   type: 'provider-registered'

package/src/runtime/accountsApi.ts

@@ -0,0 +1,26 @@
+/**
+ * Worker-side connected accounts API.
+ */
+
+import type { AccountAccessToken, ConnectedAccount, ConnectedAccountsAPI } from '../types.js'
+import type { RequestMessage } from '../messages.js'
+
+type SendRequest = <T>(method: RequestMessage['method'], payload: unknown) => Promise<T>
+
+/**
+ * Build the accounts API for one user.
+ *
+ * The user id is bound here, from the request that is being served, and not
+ * taken from the extension's own arguments: an extension cannot reach another
+ * user's account by passing a different id, because there is no id to pass.
+ */
+export function buildUserAccountsAPI(sendRequest: SendRequest, userId: string): ConnectedAccountsAPI {
+  return {
+    async list(provider: 'microsoft'): Promise<ConnectedAccount[]> {
+      return sendRequest<ConnectedAccount[]>('accounts.list', { provider, userId })
+    },
+    async getAccessToken(accountId: string): Promise<AccountAccessToken> {
+      return sendRequest<AccountAccessToken>('accounts.getAccessToken', { accountId, userId })
+    },
+  }
+}

package/src/runtime/executionContext.test.ts

@@ -0,0 +1,113 @@
+import { describe, it, expect, vi } from 'vitest'
+import { createExecutionContext } from './executionContext.js'
+import type { ExtensionContext } from '../types.js'
+
+const extensionContext = {
+  extension: { id: 'mail-reader', version: '1.0.0', storagePath: '/tmp/x' },
+} as ExtensionContext
+
+/**
+ * What a tool is handed when it runs.
+ *
+ * The attachments API is the part worth pinning: it is absent unless the extension
+ * asked for the permission *and* the request knows whose work it is, and an absent
+ * API is what makes a tool check before reaching for files it may not have.
+ */
+describe('createExecutionContext', () => {
+  it('leaves attachments out without the permission', () => {
+    const context = createExecutionContext(vi.fn(), extensionContext, 'user-1', [])
+
+    expect(context.attachments).toBeUndefined()
+  })
+
+  it('leaves attachments out without a user, whatever the permission says', () => {
+    // An attachment belongs to somebody. A request that cannot say whose work it is
+    // doing has no business reading one.
+    const context = createExecutionContext(vi.fn(), extensionContext, undefined, ['attachments.read'])
+
+    expect(context.attachments).toBeUndefined()
+  })
+
+  it('reads an attachment for the user the request belongs to', async () => {
+    const sendRequest = vi.fn().mockResolvedValue({
+      id: 'att-7',
+      mime: 'application/pdf',
+      data: 'JVBE',
+      byteSize: 4,
+    })
+
+    const context = createExecutionContext(sendRequest, extensionContext, 'user-1', ['attachments.read'])
+    const content = await context.attachments!.read('att-7')
+
+    // The user id is the runtime's to supply, not the tool's: it comes from the
+    // request, so a tool cannot reach another user's file by passing a different one.
+    expect(sendRequest).toHaveBeenCalledWith('attachments.read', {
+      attachmentId: 'att-7',
+      userId: 'user-1',
+    })
+    expect(content?.mime).toBe('application/pdf')
+  })
+
+  it('passes a missing attachment through as nothing', async () => {
+    const context = createExecutionContext(
+      vi.fn().mockResolvedValue(null),
+      extensionContext,
+      'user-1',
+      ['attachments.read']
+    )
+
+    expect(await context.attachments!.read('gone')).toBeNull()
+  })
+
+  it('still builds the rest of the context without the permission', () => {
+    const context = createExecutionContext(vi.fn(), extensionContext, 'user-1')
+
+    expect(context.userId).toBe('user-1')
+    expect(context.storage).toBeDefined()
+    expect(context.userStorage).toBeDefined()
+    expect(context.secrets).toBeDefined()
+    expect(context.userSecrets).toBeDefined()
+  })
+
+  describe('connected accounts', () => {
+    it('leaves them out without the permission', () => {
+      const context = createExecutionContext(vi.fn(), extensionContext, 'user-1', ['attachments.read'])
+
+      expect(context.accounts).toBeUndefined()
+    })
+
+    it('leaves them out without a user, whatever the permission says', () => {
+      const context = createExecutionContext(vi.fn(), extensionContext, undefined, ['accounts.use'])
+
+      expect(context.accounts).toBeUndefined()
+    })
+
+    it('asks for the user the request belongs to, not one the extension names', async () => {
+      const sendRequest = vi
+        .fn()
+        .mockResolvedValueOnce([{ id: 'ms-1', provider: 'microsoft', email: 'a@b.se' }])
+        .mockResolvedValueOnce({ token: 'tok', expiresAt: '2026-09-16T12:00:00.000Z' })
+
+      const context = createExecutionContext(sendRequest, extensionContext, 'user-1', ['accounts.use'])
+      await context.accounts!.list('microsoft')
+      const token = await context.accounts!.getAccessToken('ms-1')
+
+      expect(sendRequest).toHaveBeenNthCalledWith(1, 'accounts.list', {
+        provider: 'microsoft',
+        userId: 'user-1',
+      })
+      expect(sendRequest).toHaveBeenNthCalledWith(2, 'accounts.getAccessToken', {
+        accountId: 'ms-1',
+        userId: 'user-1',
+      })
+      expect(token.token).toBe('tok')
+    })
+
+    it('leaves attachments alone when only accounts were granted', () => {
+      const context = createExecutionContext(vi.fn(), extensionContext, 'user-1', ['accounts.use'])
+
+      expect(context.accounts).toBeDefined()
+      expect(context.attachments).toBeUndefined()
+    })
+  })
+})

package/src/runtime/executionContext.ts

@@ -2,10 +2,11 @@
  * Shared execution context builder for tool, action, and scheduler operations.
  */
 
-import type { ExecutionContext, ExtensionContext } from '../types.js'
+import type { AttachmentContent, ExecutionContext, ExtensionContext } from '../types.js'
 import type { RequestMessage } from '../messages.js'
 import { buildExtensionStorageAPI, buildUserStorageAPI } from './storageApi.js'
 import { buildExtensionSecretsAPI, buildUserSecretsAPI } from './secretsApi.js'
+import { buildUserAccountsAPI } from './accountsApi.js'
 
 type SendRequest = <T>(method: RequestMessage['method'], payload: unknown) => Promise<T>
 
@@ -16,8 +17,17 @@ type SendRequest = <T>(method: RequestMessage['method'], payload: unknown) => Pr
 export function createExecutionContext(
   sendRequest: SendRequest,
   extensionContext: ExtensionContext,
-  userId?: string
+  userId?: string,
+  /**
+   * What the extension was granted. The permission-gated APIs are left out here
+   * rather than only refused by the host, so a tool can see whether a capability
+   * is there at all, the way it can for storage — the host refuses them regardless.
+   */
+  granted: readonly string[] = []
 ): ExecutionContext {
+  const canReadAttachments = granted.includes('attachments.read')
+  const canUseAccounts = granted.includes('accounts.use')
+
   return {
     userId,
     extension: {
@@ -33,5 +43,21 @@ export function createExecutionContext(
     userSecrets: userId
       ? buildUserSecretsAPI(sendRequest, userId)
       : buildExtensionSecretsAPI(sendRequest),
+    // Only with a user to scope it to. An attachment belongs to somebody, and a
+    // request that cannot say whose work it is doing has no business reading one.
+    ...(canReadAttachments && userId
+      ? {
+          attachments: {
+            async read(attachmentId: string): Promise<AttachmentContent | null> {
+              return sendRequest<AttachmentContent | null>('attachments.read', {
+                attachmentId,
+                userId,
+              })
+            },
+          },
+        }
+      : {}),
+    // Scoped to a user for the same reason: a connected account is somebody's.
+    ...(canUseAccounts && userId ? { accounts: buildUserAccountsAPI(sendRequest, userId) } : {}),
   }
 }

package/src/runtime/index.ts

@@ -6,3 +6,4 @@
 export { buildExtensionStorageAPI, buildUserStorageAPI } from './storageApi.js'
 export { buildExtensionSecretsAPI, buildUserSecretsAPI } from './secretsApi.js'
 export { createExecutionContext } from './executionContext.js'
+export { buildUserAccountsAPI } from './accountsApi.js'

package/src/runtime.ts

@@ -57,6 +57,7 @@ import {
   buildUserStorageAPI,
   buildExtensionSecretsAPI,
   buildUserSecretsAPI,
+  buildUserAccountsAPI,
   createExecutionContext,
 } from './runtime/index.js'
 
@@ -105,6 +106,13 @@ const messagePort = getMessagePort()
 let extensionModule: ExtensionModule | null = null
 let extensionDisposable: Disposable | null = null
 let extensionContext: ExtensionContext | null = null
+/**
+ * What this extension was granted, kept from activation.
+ *
+ * A request-scoped context is built long after `handleActivate` has returned, and
+ * has to know the same things it did.
+ */
+let grantedPermissions: string[] = []
 let backgroundTaskManager: WorkerBackgroundTaskManager | null = null
 
 const pendingRequests = new Map<string, PendingRequest>()
@@ -284,6 +292,7 @@ async function handleActivate(payload: {
   settings: Record<string, unknown>
 }): Promise<void> {
   const { extensionId, extensionVersion, storagePath, permissions } = payload
+  grantedPermissions = permissions
 
   // Build the context based on permissions
   extensionContext = buildContext(extensionId, extensionVersion, storagePath, permissions)
@@ -346,7 +355,12 @@ function handleSettingsChanged(key: string, value: unknown): void {
 // ExecutionContext builder is in runtime/executionContext.ts
 
 async function handleSchedulerFire(payload: SchedulerFirePayload): Promise<void> {
-  const execContext = createExecutionContext(sendRequest, extensionContext!, payload.userId)
+  const execContext = createExecutionContext(
+      sendRequest,
+      extensionContext!,
+      payload.userId,
+      grantedPermissions
+    )
 
   // Run callbacks concurrently to avoid blocking
   const results = await Promise.allSettled(
@@ -543,7 +557,12 @@ async function handleToolExecuteRequest(
   }
 
   try {
-    const execContext = createExecutionContext(sendRequest, extensionContext!, payload.userId)
+    const execContext = createExecutionContext(
+      sendRequest,
+      extensionContext!,
+      payload.userId,
+      grantedPermissions
+    )
 
     const result = await tool.execute(payload.params, execContext)
 
@@ -586,7 +605,12 @@ async function handleActionExecuteRequest(
   }
 
   try {
-    const execContext = createExecutionContext(sendRequest, extensionContext!, payload.userId)
+    const execContext = createExecutionContext(
+      sendRequest,
+      extensionContext!,
+      payload.userId,
+      grantedPermissions
+    )
 
     const result = await action.execute(payload.params, execContext)
 
@@ -967,6 +991,9 @@ function buildContext(
         createUserStorageAPI: (userId) => buildUserStorageAPI(sendRequest, userId),
         createSecretsAPI: () => buildExtensionSecretsAPI(sendRequest),
         createUserSecretsAPI: (userId) => buildUserSecretsAPI(sendRequest, userId),
+        ...(hasPermission('accounts.use')
+          ? { createUserAccountsAPI: (userId: string) => buildUserAccountsAPI(sendRequest, userId) }
+          : {}),
       })
     }
 
@@ -1016,6 +1043,9 @@ export type {
   ExecutionContext,
   ExtensionContext,
   ExtensionModule,
+  ConnectedAccountsAPI,
+  ConnectedAccount,
+  AccountAccessToken,
   Disposable,
   AIProvider,
   Tool,
@@ -1027,6 +1057,11 @@ export type {
   ActionResult,
   ModelInfo,
   ChatMessage,
+  // What a message can carry. A provider extension reads these on every user turn,
+  // and until now had to reach for the root entry to name them — or declare them
+  // itself, which is what two of them did.
+  ChatImage,
+  ChatFile,
   ChatOptions,
   GetModelsOptions,
   ModelCapabilities,

package/src/schemas/accounts.schema.test.ts

@@ -0,0 +1,58 @@
+import { describe, it, expect } from 'vitest'
+import { AccountContributionSchema, ExtensionContributionsSchema } from './contributions.schema.js'
+
+/**
+ * What an extension may ask of a connected account.
+ *
+ * Every enabled extension's scopes go into one sign-in request. A scope Microsoft
+ * rejects therefore breaks the sign-in for all of them, which is why the schema
+ * is stricter than "any string".
+ */
+describe('AccountContributionSchema', () => {
+  it('accepts Graph permission names', () => {
+    const result = AccountContributionSchema.safeParse({
+      provider: 'microsoft',
+      scopes: ['Mail.Read', 'Mail.Send', 'Calendars.ReadWrite', 'Calendars.Read.Shared'],
+      reason: { en: 'Read your mail', sv: 'Läsa din mail' },
+    })
+
+    expect(result.success).toBe(true)
+  })
+
+  // Microsoft issues a token for one resource at a time. An Exchange scope next to
+  // Graph scopes makes the whole combined request fail.
+  it('refuses a scope for another resource', () => {
+    const result = AccountContributionSchema.safeParse({
+      provider: 'microsoft',
+      scopes: ['https://outlook.office.com/IMAP.AccessAsUser.All'],
+    })
+
+    expect(result.success).toBe(false)
+  })
+
+  it('refuses the scopes the host asks for itself', () => {
+    for (const scope of ['offline_access', 'User.Read', 'user.read', 'openid']) {
+      const result = AccountContributionSchema.safeParse({ provider: 'microsoft', scopes: [scope] })
+      expect(result.success, scope).toBe(false)
+    }
+  })
+
+  it('needs at least one scope', () => {
+    expect(AccountContributionSchema.safeParse({ provider: 'microsoft', scopes: [] }).success).toBe(false)
+  })
+
+  it('knows only the providers the host can sign in to', () => {
+    expect(
+      AccountContributionSchema.safeParse({ provider: 'google', scopes: ['Mail.Read'] }).success
+    ).toBe(false)
+  })
+
+  it('is part of what a manifest may contribute', () => {
+    const result = ExtensionContributionsSchema.safeParse({
+      accounts: [{ provider: 'microsoft', scopes: ['Calendars.ReadWrite'] }],
+    })
+
+    expect(result.success).toBe(true)
+    expect(result.success && result.data.accounts?.[0]?.scopes).toEqual(['Calendars.ReadWrite'])
+  })
+})

package/src/schemas/contributions.schema.ts

@@ -304,6 +304,48 @@ export const StorageContributionsSchema = z
   })
   .describe('Storage contributions')
 
+// =============================================================================
+// Connected Accounts
+// =============================================================================
+
+/**
+ * A Microsoft Graph delegated permission name: `Mail.Read`, `Calendars.ReadWrite`.
+ *
+ * Bare names only. A full URI would name some other resource, and Microsoft hands
+ * out tokens for one resource at a time - a manifest mixing Graph with, say,
+ * `https://outlook.office.com/IMAP.AccessAsUser.All` would make the combined
+ * sign-in fail for every extension, not just the one that asked.
+ */
+export const GRAPH_SCOPE_PATTERN = /^[A-Za-z]+(\.[A-Za-z]+)+$/
+
+/**
+ * Scopes the host always asks for and therefore does not accept from a manifest:
+ * a declared one would be redundant at best.
+ */
+export const HOST_ACCOUNT_SCOPES = ['offline_access', 'User.Read', 'openid', 'profile', 'email'] as const
+
+export const AccountProviderSchema = z.enum(['microsoft']).describe('External account provider')
+
+export const AccountContributionSchema = z
+  .object({
+    provider: AccountProviderSchema,
+    scopes: z
+      .array(
+        z
+          .string()
+          .regex(GRAPH_SCOPE_PATTERN, 'Must be a Microsoft Graph permission name, such as "Mail.Read"')
+          .refine(
+            (scope) =>
+              !HOST_ACCOUNT_SCOPES.some((hostScope) => hostScope.toLowerCase() === scope.toLowerCase()),
+            { message: 'Requested by the host already; leave it out' }
+          )
+      )
+      .min(1)
+      .describe('Microsoft Graph delegated permissions'),
+    reason: LocalizedStringSchema.optional().describe('Why the extension needs them'),
+  })
+  .describe('An external account the extension works through')
+
 // =============================================================================
 // Extension Contributions
 // =============================================================================
@@ -324,6 +366,10 @@ export const ExtensionContributionsSchema = z
     commands: z.array(CommandDefinitionSchema).optional().describe('Slash commands'),
     prompts: z.array(PromptContributionSchema).optional().describe('Prompt contributions'),
     storage: StorageContributionsSchema.optional().describe('Storage collection declarations'),
+    accounts: z
+      .array(AccountContributionSchema)
+      .optional()
+      .describe("External accounts the extension works through, signed in once in Stina's settings"),
   })
   .describe('What an extension can contribute to Stina')
 
@@ -353,4 +399,6 @@ export type PromptSection = z.infer<typeof PromptSectionSchema>
 export type PromptContribution = z.infer<typeof PromptContributionSchema>
 export type StorageCollectionConfig = z.infer<typeof StorageCollectionConfigSchema>
 export type StorageContributions = z.infer<typeof StorageContributionsSchema>
+export type AccountProvider = z.infer<typeof AccountProviderSchema>
+export type AccountContribution = z.infer<typeof AccountContributionSchema>
 export type ExtensionContributions = z.infer<typeof ExtensionContributionsSchema>

package/src/schemas/index.ts

@@ -58,6 +58,12 @@ export {
   CommandDefinitionSchema,
   PromptContributionSchema,
   PromptSectionSchema,
+  AccountProviderSchema,
+  AccountContributionSchema,
+  GRAPH_SCOPE_PATTERN,
+  HOST_ACCOUNT_SCOPES,
+  type AccountProvider,
+  type AccountContribution,
   type ExtensionContributions,
   type LocalizedString,
   type ToolSettingsViewDefinition,

package/src/schemas/permissions.schema.ts

@@ -20,6 +20,8 @@ export const VALID_PERMISSIONS = [
   'user.location.read',
   'chat.history.read',
   'chat.current.read',
+  'attachments.read',
+  'accounts.use',
   'chat.message.write',
   'provider.register',
   'tools.register',
@@ -75,7 +77,15 @@ const StoragePermissionSchema = z.enum(['storage.collections', 'secrets.manage']
  * User data permission schema
  */
 const UserDataPermissionSchema = z
-  .enum(['user.profile.read', 'user.list', 'user.location.read', 'chat.history.read', 'chat.current.read'])
+  .enum([
+    'user.profile.read',
+    'user.list',
+    'user.location.read',
+    'chat.history.read',
+    'chat.current.read',
+    'attachments.read',
+    'accounts.use',
+  ])
   .describe('User data access permission')
 
 /**