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

@@ -257,7 +257,7 @@ export interface AccountClient {
   getWorkspaceUsersWithPermission: (params: { permission: string }) => Promise<AccountUuid[]>
 
   verify2fa: (code: string) => Promise<LoginInfo>
-  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[]>
@@ -1232,10 +1232,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

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

plugins/setting-assets/lang/en.json

@@ -250,6 +250,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

@@ -371,6 +371,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,6 +233,17 @@ export function registerRPC (app: Express, sessions: SessionManager, ctx: Measur
         }
       }
 
+      // 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)
 
       if (transactorRpc === undefined) {
@@ -305,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

@@ -826,3 +826,13 @@ function getV26Migration (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;
+    `
+  ]
+}

server/account/src/operations.ts

@@ -418,7 +418,7 @@ export async function validateOtp (
       throw new PlatformError(new Status(Severity.ERROR, platform.status.InvalidOtp, {}))
     }
 
-    let callerAccountUuid: AccountUuid | null = null
+    let callerAccountUuid: AccountUuid | undefined
     let callerAccount: Account | null = null
 
     if (action === 'verify') {
@@ -1967,7 +1967,7 @@ export async function getLoginInfoByToken (
   let extra: any
   let grant: PermissionsGrant | undefined
   let sub: AccountUuid | undefined
-  let account: AccountUuid | undefined
+  let account: AccountUuid
   let nbf: number | undefined
   let exp: number | undefined
 
@@ -2574,6 +2574,7 @@ async function deleteMailbox (
  * @param params.name Human-readable token name (1–255 chars)
  * @param params.workspaceUuid Target workspace — user must have access
  * @param params.expiryDays Token validity period (1–365 days)
+ * @param params.scopes Optional scopes array. NULL/undefined = full access. e.g. ['read:*', 'write:*']
  * @returns Token ID, signed JWT, and expiration timestamp (ms)
  * @throws BadRequest if validation fails
  * @throws Forbidden if user lacks workspace access
@@ -2587,9 +2588,10 @@ async function createApiToken (
     name: string
     workspaceUuid: WorkspaceUuid
     expiryDays: number
+    scopes?: string[]
   }
 ): Promise<{ id: string, token: string, expiresOn: number }> {
-  const { name, workspaceUuid, expiryDays } = params
+  const { name, workspaceUuid, expiryDays, scopes } = params
 
   if (
     name == null ||
@@ -2625,12 +2627,29 @@ async function createApiToken (
     throw new PlatformError(new Status(Severity.ERROR, platform.status.BadRequest, {}))
   }
 
+  // Validate scopes if provided
+  const validScopePattern = /^(read|write|delete):\*$/
+  if (scopes !== undefined) {
+    if (!Array.isArray(scopes) || scopes.length === 0) {
+      throw new PlatformError(new Status(Severity.ERROR, platform.status.BadRequest, {}))
+    }
+    for (const scope of scopes) {
+      if (typeof scope !== 'string' || !validScopePattern.test(scope)) {
+        throw new PlatformError(new Status(Severity.ERROR, platform.status.BadRequest, {}))
+      }
+    }
+  }
+
   const now = Date.now()
   const expiresOn = now + days * 86400000
   const expSec = Math.floor(expiresOn / 1000)
 
   const id = randomUUID()
-  const apiToken = generateToken(account, workspaceUuid, { apiTokenId: id }, undefined, { exp: expSec })
+  const extra: Record<string, string> = { apiTokenId: id }
+  if (scopes !== undefined) {
+    extra.scopes = JSON.stringify(scopes)
+  }
+  const apiToken = generateToken(account, workspaceUuid, extra, undefined, { exp: expSec })
 
   await db.apiToken.insertOne({
     id,
@@ -2639,10 +2658,11 @@ async function createApiToken (
     workspaceUuid,
     createdOn: now,
     expiresOn,
-    revoked: false
+    revoked: false,
+    scopes
   })
 
-  ctx.info('API token created', { id, account, workspaceUuid, days })
+  ctx.info('API token created', { id, account, workspaceUuid, days, scopes })
   return { id, token: apiToken, expiresOn }
 }
 
@@ -2680,7 +2700,8 @@ async function listApiTokens (
     workspaceName: wsMap.get(t.workspaceUuid) ?? t.workspaceUuid,
     createdOn: t.createdOn,
     expiresOn: t.expiresOn,
-    revoked: t.revoked
+    revoked: t.revoked,
+    scopes: t.scopes ?? undefined
   }))
 }
 
@@ -2764,7 +2785,8 @@ async function listWorkspaceApiTokens (
     workspaceUuid: t.workspaceUuid,
     createdOn: t.createdOn,
     expiresOn: t.expiresOn,
-    revoked: t.revoked
+    revoked: t.revoked,
+    scopes: t.scopes ?? undefined
   }))
 }
 
@@ -3210,7 +3232,7 @@ export async function getSubscriptions (
     targetWorkspace = tokenWorkspace
 
     // Verify user has OWNER or MAINTAINER role
-    const role = await db.getWorkspaceRole(account, targetWorkspace)
+    const role = await db.getWorkspaceRole(account, tokenWorkspace)
     if (role === null) {
       throw new PlatformError(new Status(Severity.ERROR, platform.status.Forbidden, {}))
     }