@stina/extension-api 1.6.0 → 1.7.0

package/src/runtime.ts

@@ -57,6 +57,7 @@ import {
   buildUserStorageAPI,
   buildExtensionSecretsAPI,
   buildUserSecretsAPI,
+  buildUserAccountsAPI,
   createExecutionContext,
 } from './runtime/index.js'
 
@@ -358,7 +359,7 @@ async function handleSchedulerFire(payload: SchedulerFirePayload): Promise<void>
       sendRequest,
       extensionContext!,
       payload.userId,
-      grantedPermissions.includes('attachments.read')
+      grantedPermissions
     )
 
   // Run callbacks concurrently to avoid blocking
@@ -560,7 +561,7 @@ async function handleToolExecuteRequest(
       sendRequest,
       extensionContext!,
       payload.userId,
-      grantedPermissions.includes('attachments.read')
+      grantedPermissions
     )
 
     const result = await tool.execute(payload.params, execContext)
@@ -608,7 +609,7 @@ async function handleActionExecuteRequest(
       sendRequest,
       extensionContext!,
       payload.userId,
-      grantedPermissions.includes('attachments.read')
+      grantedPermissions
     )
 
     const result = await action.execute(payload.params, execContext)
@@ -990,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) }
+          : {}),
       })
     }
 
@@ -1039,6 +1043,9 @@ export type {
   ExecutionContext,
   ExtensionContext,
   ExtensionModule,
+  ConnectedAccountsAPI,
+  ConnectedAccount,
+  AccountAccessToken,
   Disposable,
   AIProvider,
   Tool,
@@ -1050,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

@@ -21,6 +21,7 @@ export const VALID_PERMISSIONS = [
   'chat.history.read',
   'chat.current.read',
   'attachments.read',
+  'accounts.use',
   'chat.message.write',
   'provider.register',
   'tools.register',
@@ -83,6 +84,7 @@ const UserDataPermissionSchema = z
     'chat.history.read',
     'chat.current.read',
     'attachments.read',
+    'accounts.use',
   ])
   .describe('User data access permission')
 

package/src/types.context.ts

@@ -94,6 +94,74 @@ export interface ExecutionContext {
    * so in its manifest and check before reaching for them.
    */
   readonly attachments?: AttachmentsAPI
+
+  /**
+   * The external accounts this user has connected to Stina.
+   *
+   * Present only for an extension holding `accounts.use`, and only on a request
+   * that knows whose it is - an account belongs to somebody, like an attachment.
+   */
+  readonly accounts?: ConnectedAccountsAPI
+}
+
+/**
+ * Working through an account the user signed in to in Stina's settings.
+ *
+ * The user connects a Microsoft account once, and every extension that declares
+ * Microsoft under `contributes.accounts` can use it. The extension never sees the
+ * refresh token; it asks for an access token when it needs one and gets a fresh
+ * one back, refreshed by the host when the old one has run out.
+ *
+ * One thing the host cannot narrow: Microsoft issues a Graph token carrying every
+ * permission the user has granted Stina, not only the ones this extension
+ * declared. The declaration decides whether an extension gets a token at all,
+ * and what the user is asked to approve - not what the token can do.
+ */
+export interface ConnectedAccountsAPI {
+  /**
+   * The accounts this user has connected for a provider, newest first.
+   *
+   * An empty list is the normal answer for a user who has not connected one yet:
+   * the extension should point them at Stina's settings rather than start a
+   * sign-in of its own.
+   */
+  list(provider: 'microsoft'): Promise<ConnectedAccount[]>
+
+  /**
+   * An access token for one of those accounts, for the scopes this extension
+   * declared.
+   *
+   * Rejects when the account is gone, when the user has not granted every
+   * declared scope yet, or when the provider has revoked the sign-in. The
+   * message says which, in words the user can act on - it is fine to show it.
+   */
+  getAccessToken(accountId: string): Promise<AccountAccessToken>
+}
+
+/** An account the user has connected, as an extension sees it. */
+export interface ConnectedAccount {
+  /** Stable id, to store alongside whatever the extension keeps for this account. */
+  id: string
+  provider: 'microsoft'
+  /** The address the user signs in with. */
+  email: string
+  displayName?: string
+  /**
+   * Whether the user has granted every scope this extension declared. False when
+   * the extension was installed after the account was connected, and the user has
+   * yet to reconnect it in the settings.
+   */
+  hasRequiredScopes: boolean
+  /** Set when the provider has refused the stored sign-in and it has to be redone. */
+  needsReconnect: boolean
+}
+
+/** An access token, and when it stops working. */
+export interface AccountAccessToken {
+  /** Bearer token for Microsoft Graph. */
+  token: string
+  /** ISO timestamp. Ask again after this; the host refreshes. */
+  expiresAt: string
 }
 
 /**

package/src/types.contributions.ts

@@ -25,6 +25,8 @@ export interface ExtensionContributions {
   commands?: CommandDefinition[]
   /** Prompt contributions for the system prompt */
   prompts?: PromptContribution[]
+  /** External accounts the extension works through, signed in once in Stina's settings */
+  accounts?: AccountContribution[]
   /** Storage collection declarations */
   storage?: {
     collections: {
@@ -36,6 +38,51 @@ export interface ExtensionContributions {
   }
 }
 
+// ============================================================================
+// Connected Accounts
+// ============================================================================
+
+/**
+ * An external account provider the host can sign in to on the user's behalf.
+ *
+ * Only Microsoft for now, and only through Microsoft Graph: mail and calendar
+ * then share one sign-in and one token, instead of an IMAP token and a Graph
+ * token that an admin has to approve separately.
+ */
+export type AccountProvider = 'microsoft'
+
+/**
+ * What an extension needs from an account the user connects to Stina.
+ *
+ * Stina asks the provider for every scope that the enabled extensions declare,
+ * all at once, so that the user - and, at work, their administrator - approves
+ * one request instead of one per extension. Declaring a scope here is therefore
+ * also what makes it show up in that request, and in the list of what is asked
+ * for in the settings.
+ *
+ * @example
+ * ```json
+ * "accounts": [
+ *   {
+ *     "provider": "microsoft",
+ *     "scopes": ["Calendars.ReadWrite"],
+ *     "reason": { "en": "Read and book events in your calendar", "sv": "Läsa och boka i din kalender" }
+ *   }
+ * ]
+ * ```
+ */
+export interface AccountContribution {
+  provider: AccountProvider
+  /**
+   * Microsoft Graph delegated permissions, by name: `Mail.Read`,
+   * `Calendars.ReadWrite`. The host adds `offline_access` and `User.Read`
+   * itself, so they are not declared here.
+   */
+  scopes: string[]
+  /** Why the extension needs them, shown next to the scopes in the settings. */
+  reason?: LocalizedString
+}
+
 // ============================================================================
 // Tool Settings Views
 // ============================================================================

package/src/types.permissions.ts

@@ -35,6 +35,14 @@ export type UserDataPermission =
    * extension.
    */
   | 'attachments.read'
+  /**
+   * Get access tokens for the external accounts the user has connected to Stina
+   * itself - a Microsoft account, say - for the scopes the extension declares under
+   * `contributes.accounts`. The user signs in once, in Stina's settings, and every
+   * extension that declares the provider can use that sign-in. Refresh tokens stay
+   * with the host.
+   */
+  | 'accounts.use'
 
 /** Capability permissions */
 export type CapabilityPermission =

package/src/types.ts

@@ -47,6 +47,9 @@ export type {
   // Prompts
   PromptSection,
   PromptContribution,
+  // Connected accounts
+  AccountProvider,
+  AccountContribution,
 } from './types.contributions.js'
 
 // Manifest
@@ -103,6 +106,9 @@ export type {
   BackgroundWorkersAPI,
   AttachmentsAPI,
   AttachmentContent,
+  ConnectedAccountsAPI,
+  ConnectedAccount,
+  AccountAccessToken,
 } from './types.context.js'
 
 // Storage and Secrets