feat: implement Phase 1 API token scopes (read/write/delete)

Add coarse-grained scope enforcement for API tokens. Tokens can now
be created with scopes ['read:*'], ['read:*','write:*'], or
['read:*','write:*','delete:*']. Existing tokens without scopes
retain full access (backward compatible).

- DB: v26 migration adds scopes TEXT[] column to api_tokens
- Types: add scopes field to ApiToken and ApiTokenInfo
- Operations: createApiToken accepts/validates/persists scopes,
  embeds in JWT via extra.scopes
- Enforcement: withSession checks scopes against method; tx handler
  additionally requires delete:* for TxRemoveDoc
- Client: createApiToken signature accepts optional scopes param
- UI: scope preset dropdown in create popup (default: Read Only),
  permissions column in token list with i18n labels
- Also fixes 3 pre-existing TS2322/TS2345 errors in operations.ts

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Signed-off-by: Don Kendall <kendall@donkendall.com>

Author: dnplkndll

foundations/core/packages/account-client/src/client.ts

@@ -254,7 +254,7 @@ export interface AccountClient {
   getWorkspacePermissions: (params: { accountId: AccountUuid, permission: string }) => Promise<WorkspaceUuid[]>
   getWorkspaceUsersWithPermission: (params: { permission: string }) => Promise<AccountUuid[]>
 
-  createApiToken: (name: string, workspaceUuid: WorkspaceUuid, expiryDays: number) => Promise<ApiTokenResult>
+  createApiToken: (name: string, workspaceUuid: WorkspaceUuid, expiryDays: number, scopes?: string[]) => Promise<ApiTokenResult>
   listApiTokens: () => Promise<ApiTokenInfo[]>
   revokeApiToken: (tokenId: string) => Promise<void>
   listWorkspaceApiTokens: (workspaceUuid: WorkspaceUuid) => Promise<ApiTokenInfo[]>
@@ -1207,10 +1207,10 @@ class AccountClientImpl implements AccountClient {
     await this.rpc(request)
   }
 
-  async createApiToken (name: string, workspaceUuid: WorkspaceUuid, expiryDays: number): Promise<ApiTokenResult> {
+  async createApiToken (name: string, workspaceUuid: WorkspaceUuid, expiryDays: number, scopes?: string[]): Promise<ApiTokenResult> {
     const request = {
       method: 'createApiToken' as const,
-      params: { name, workspaceUuid, expiryDays }
+      params: { name, workspaceUuid, expiryDays, scopes }
     }
 
     return await this.rpc(request)

foundations/core/packages/account-client/src/types.ts

@@ -118,6 +118,7 @@ export interface ApiTokenInfo {
   createdOn: number
   expiresOn: number
   revoked: boolean
+  scopes?: string[]
 }
 
 export interface ApiTokenResult {

plugins/setting-assets/lang/en.json

@@ -241,6 +241,11 @@
     "ApiTokenCopyWarning": "Copy this token now. You won't be able to see it again.",
     "ApiTokenNoTokens": "No API tokens yet",
     "ApiTokenWorkspace": "Workspace",
+    "ApiTokenPermissions": "Permissions",
+    "ApiTokenScopePreset": "Permissions",
+    "ApiTokenScopeReadOnly": "Read Only",
+    "ApiTokenScopeReadWrite": "Read & Write",
+    "ApiTokenScopeFullAccess": "Full Access",
     "Created": "Created",
     "Expires": "Expires",
     "TokenStatus": "Status",

plugins/setting-resources/src/components/ApiTokenCreatePopup.svelte

@@ -32,6 +32,35 @@
   let copiedTime: Timestamp | undefined
   let copied = false
 
+  const scopePresets = [
+    { _id: 'read-only', label: 'Read Only', scopes: ['read:*'] },
+    { _id: 'read-write', label: 'Read & Write', scopes: ['read:*', 'write:*'] },
+    { _id: 'full-access', label: 'Full Access', scopes: ['read:*', 'write:*', 'delete:*'] }
+  ]
+  let scopePresetItems: ListItem[] = scopePresets.map((p) => ({ _id: p._id, label: p.label }))
+  let selectedScopePreset: ListItem = scopePresetItems[0]
+
+  async function resolveScopeLabels (): Promise<void> {
+    const lang = $themeStore.language
+    const labels = await Promise.all([
+      translate(setting.string.ApiTokenScopeReadOnly, {}, lang),
+      translate(setting.string.ApiTokenScopeReadWrite, {}, lang),
+      translate(setting.string.ApiTokenScopeFullAccess, {}, lang)
+    ])
+    const prevId = selectedScopePreset._id
+    scopePresetItems = [
+      { _id: 'read-only', label: labels[0] },
+      { _id: 'read-write', label: labels[1] },
+      { _id: 'full-access', label: labels[2] }
+    ]
+    selectedScopePreset = scopePresetItems.find((o) => o._id === prevId) ?? scopePresetItems[0]
+  }
+
+  function getSelectedScopes (): string[] {
+    const preset = scopePresets.find((p) => p._id === selectedScopePreset._id)
+    return preset?.scopes ?? ['read:*']
+  }
+
   const expiryKeys = [
     { _id: '7', intl: setting.string.ApiTokenExpiry7Days },
     { _id: '30', intl: setting.string.ApiTokenExpiry30Days },
@@ -72,10 +101,12 @@
     loading = true
     error = undefined
     try {
+      const scopes = getSelectedScopes()
       const result = await getAccountClient().createApiToken(
         name.trim(),
         selectedWs._id as WorkspaceUuid,
-        parseInt(selectedExpiry._id, 10)
+        parseInt(selectedExpiry._id, 10),
+        scopes
       )
       createdToken = result.token
     } catch (err: any) {
@@ -99,6 +130,7 @@
   onMount(() => {
     void loadWorkspaces()
     void resolveExpiryLabels()
+    void resolveScopeLabels()
   })
 </script>
 
@@ -139,6 +171,10 @@
       <span class="label"><Label label={setting.string.ApiTokenWorkspace} /></span>
       <Dropdown placeholder={setting.string.ApiTokenWorkspace} items={wsItems} bind:selected={selectedWs} />
     </div>
+    <div class="antiPopup-msg">
+      <span class="label"><Label label={setting.string.ApiTokenScopePreset} /></span>
+      <Dropdown placeholder={setting.string.ApiTokenScopePreset} items={scopePresetItems} bind:selected={selectedScopePreset} />
+    </div>
     <div class="antiPopup-msg">
       <span class="label"><Label label={setting.string.ApiTokenExpiry} /></span>
       <Dropdown placeholder={setting.string.ApiTokenExpiry} items={expiryOptions} bind:selected={selectedExpiry} />

plugins/setting-resources/src/components/ApiTokens.svelte

@@ -15,6 +15,7 @@
 <script lang="ts">
   import { Breadcrumb, Header, IconAdd, Label, Loading, ModernButton, Scroller, showPopup } from '@hcengineering/ui'
   import { MessageBox } from '@hcengineering/presentation'
+  import { translate } from '@hcengineering/platform'
   import setting from '@hcengineering/setting'
   import { type ApiTokenInfo } from '@hcengineering/account-client'
   import { getAccountClient } from '../utils'
@@ -83,6 +84,33 @@
     })
   }
 
+  let scopeLabels = {
+    readOnly: 'Read Only',
+    readWrite: 'Read & Write',
+    fullAccess: 'Full Access'
+  }
+
+  async function resolveScopeLabels (): Promise<void> {
+    const lang = $themeStore.language
+    scopeLabels = {
+      readOnly: await translate(setting.string.ApiTokenScopeReadOnly, {}, lang),
+      readWrite: await translate(setting.string.ApiTokenScopeReadWrite, {}, lang),
+      fullAccess: await translate(setting.string.ApiTokenScopeFullAccess, {}, lang)
+    }
+  }
+
+  function getScopeLabel (token: ApiTokenInfo): string {
+    const scopes = token.scopes
+    if (scopes == null || scopes.length === 0) return scopeLabels.fullAccess
+    const hasRead = scopes.includes('read:*')
+    const hasWrite = scopes.includes('write:*')
+    const hasDelete = scopes.includes('delete:*')
+    if (hasRead && hasWrite && hasDelete && scopes.length === 3) return scopeLabels.fullAccess
+    if (hasRead && hasWrite && scopes.length === 2) return scopeLabels.readWrite
+    if (hasRead && scopes.length === 1) return scopeLabels.readOnly
+    return `${scopes.length} scopes`
+  }
+
   function getStatus (token: ApiTokenInfo): 'active' | 'expiring' | 'revoked' | 'expired' {
     if (token.revoked) return 'revoked'
     const now = Date.now()
@@ -93,6 +121,7 @@
 
   onMount(() => {
     loadTokens()
+    void resolveScopeLabels()
   })
 </script>
 
@@ -132,6 +161,7 @@
               <tr class="scroller-thead__tr">
                 <th><Label label={setting.string.ApiTokenName} /></th>
                 <th><Label label={setting.string.ApiTokenWorkspace} /></th>
+                <th><Label label={setting.string.ApiTokenPermissions} /></th>
                 <th><Label label={setting.string.Created} /></th>
                 <th><Label label={setting.string.Expires} /></th>
                 <th><Label label={setting.string.TokenStatus} /></th>
@@ -144,6 +174,7 @@
                 <tr class="antiGrid-row">
                   <td class="overflow-label font-medium-14">{token.name}</td>
                   <td class="overflow-label">{token.workspaceName}</td>
+                  <td><span class="tag-item tag-scope">{getScopeLabel(token)}</span></td>
                   <td>{formatDate(token.createdOn)}</td>
                   <td>{token.revoked ? '—' : formatDate(token.expiresOn)}</td>
                   <td>
@@ -201,4 +232,8 @@
     background-color: var(--tag-accent-FlamingoColor);
     color: var(--tag-on-accent-FlamingoColor);
   }
+  .tag-scope {
+    background-color: var(--theme-button-default);
+    color: var(--theme-content-color);
+  }
 </style>

plugins/setting/src/index.ts

@@ -360,6 +360,11 @@ export default plugin(settingId, {
     ApiTokenCopyWarning: '' as IntlString,
     ApiTokenNoTokens: '' as IntlString,
     ApiTokenWorkspace: '' as IntlString,
+    ApiTokenPermissions: '' as IntlString,
+    ApiTokenScopePreset: '' as IntlString,
+    ApiTokenScopeReadOnly: '' as IntlString,
+    ApiTokenScopeReadWrite: '' as IntlString,
+    ApiTokenScopeFullAccess: '' as IntlString,
     Created: '' as IntlString,
     Expires: '' as IntlString,
     TokenStatus: '' as IntlString,

pods/server/src/rpc.ts

@@ -158,6 +158,34 @@ async function isApiTokenRevoked (apiTokenId: string, accountClient: AccountClie
   return cached.revoked
 }
 
+// ── Token Scope Enforcement ─────────────────────────────────────────
+// Phase 1: coarse scopes only (read:*, write:*, delete:*)
+
+function hasScope (scopes: string[], required: string): boolean {
+  return scopes.includes(required)
+}
+
+function getRequiredScope (method: string): string | null {
+  switch (method) {
+    case 'ping':
+    case 'generateId':
+      return null // Always allowed
+    case 'findAll':
+    case 'searchFulltext':
+    case 'loadModel':
+    case 'account':
+      return 'read:*'
+    case 'tx':
+      // write:* checked here; delete:* checked after body parsing in the tx handler
+      return 'write:*'
+    case 'domainRequest':
+    case 'ensurePerson':
+      return 'write:*'
+    default:
+      return 'read:*'
+  }
+}
+
 export function registerRPC (app: Express, sessions: SessionManager, ctx: MeasureContext, accountsUrl: string): void {
   const rpcSessions = new Map<string, RPCClientInfo>()
 
@@ -205,10 +233,16 @@ export function registerRPC (app: Express, sessions: SessionManager, ctx: Measur
         }
       }
 
-      // Roadmap: enforce token scopes here. When ApiToken gains a scopes field
-      // (see server/account/src/types.ts), check decodedToken.extra?.scopes against
-      // the `method` parameter to reject disallowed operations (e.g. reject 'tx'
-      // for read-only tokens, filter find-all by allowed classes).
+      // Enforce token scopes (Phase 1: coarse scopes — read:*, write:*, delete:*)
+      const scopesRaw = decodedToken.extra?.scopes
+      if (scopesRaw !== undefined) {
+        const scopes: string[] = JSON.parse(scopesRaw)
+        const requiredScope = getRequiredScope(method)
+        if (requiredScope !== null && !hasScope(scopes, requiredScope)) {
+          sendError(res, 403, { message: 'Insufficient token scope', required: requiredScope })
+          return
+        }
+      }
 
       let transactorRpc = rpcSessions.get(token)
 
@@ -310,9 +344,21 @@ export function registerRPC (app: Express, sessions: SessionManager, ctx: Measur
   })
 
   app.post('/api/v1/tx/:workspaceId', (req, res) => {
-    void withSession(req, res, 'tx', async (ctx, session, rateLimit) => {
+    void withSession(req, res, 'tx', async (ctx, session, rateLimit, token) => {
       const tx: any = (await retrieveJson(req)) ?? {}
 
+      // Enforce delete:* scope for remove transactions
+      if (tx._class === core.class.TxRemoveDoc) {
+        const scopesStr = decodeToken(token).extra?.scopes
+        if (scopesStr !== undefined) {
+          const scopes: string[] = JSON.parse(scopesStr)
+          if (!scopes.includes('delete:*')) {
+            sendError(res, 403, { message: 'Insufficient token scope', required: 'delete:*' })
+            return
+          }
+        }
+      }
+
       if (tx._class === core.class.TxDomainEvent) {
         const domainTx = tx as TxDomainEvent
         const { result } = await session.domainRequestRaw(ctx, domainTx.domain, {

server/account/src/collections/postgres/migrations.ts

@@ -82,7 +82,8 @@ export function getMigrations (ns: string, flavor: DBFlavor): [string, string][]
     getV22Migration(ns, flavor),
     getV23Migration(ns, flavor),
     getV24Migration(ns, flavor),
-    getV25Migration(ns, flavor)
+    getV25Migration(ns, flavor),
+    getV26Migration(ns, flavor)
   ]
 }
 
@@ -814,3 +815,13 @@ function getV25Migration(ns: string, flavor: DBFlavor): [string, string] {
     `
   ]
 }
+
+function getV26Migration (ns: string, flavor: DBFlavor): [string, string] {
+  return [
+    'account_db_v26_add_api_token_scopes',
+    `
+    ALTER TABLE ${ns}.api_tokens
+    ADD COLUMN IF NOT EXISTS scopes TEXT[] DEFAULT NULL;
+    `
+  ]
+}