test: add unit tests for API token scope enforcement

- scopes.test.ts: 8 tests for hasScope() and getRequiredScope() logic
- apiTokenScopes.test.ts: 7 tests for createApiToken scope validation
  (valid scopes, multiple scopes, no scopes backward compat, invalid
  format rejection, empty array rejection, domain-scope rejection)
  and listApiTokens scopes inclusion
- Export hasScope/getRequiredScope from rpc.ts for testability

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

Author: dnplkndll

pods/server/src/__tests__/scopes.test.ts

@@ -0,0 +1,61 @@
+//
+// Copyright © 2025 Hardcore Engineering Inc.
+//
+// Licensed under the Eclipse Public License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License. You may
+// obtain a copy of the License at https://www.eclipse.org/legal/epl-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+//
+// See the License for the specific language governing permissions and
+// limitations under the License.
+//
+
+import { hasScope, getRequiredScope } from '../rpc'
+
+describe('hasScope', () => {
+  test('returns true when scope is present', () => {
+    expect(hasScope(['read:*', 'write:*'], 'read:*')).toBe(true)
+    expect(hasScope(['read:*', 'write:*'], 'write:*')).toBe(true)
+  })
+
+  test('returns false when scope is missing', () => {
+    expect(hasScope(['read:*'], 'write:*')).toBe(false)
+    expect(hasScope(['read:*'], 'delete:*')).toBe(false)
+  })
+
+  test('returns false for empty scopes array', () => {
+    expect(hasScope([], 'read:*')).toBe(false)
+  })
+
+  test('requires exact match', () => {
+    expect(hasScope(['read:tracker'], 'read:*')).toBe(false)
+    expect(hasScope(['read:*'], 'read:tracker')).toBe(false)
+  })
+})
+
+describe('getRequiredScope', () => {
+  test('ping and generateId require no scope', () => {
+    expect(getRequiredScope('ping')).toBeNull()
+    expect(getRequiredScope('generateId')).toBeNull()
+  })
+
+  test('read methods require read:*', () => {
+    expect(getRequiredScope('findAll')).toBe('read:*')
+    expect(getRequiredScope('searchFulltext')).toBe('read:*')
+    expect(getRequiredScope('loadModel')).toBe('read:*')
+    expect(getRequiredScope('account')).toBe('read:*')
+  })
+
+  test('write methods require write:*', () => {
+    expect(getRequiredScope('tx')).toBe('write:*')
+    expect(getRequiredScope('domainRequest')).toBe('write:*')
+    expect(getRequiredScope('ensurePerson')).toBe('write:*')
+  })
+
+  test('unknown methods default to read:*', () => {
+    expect(getRequiredScope('someUnknownMethod')).toBe('read:*')
+  })
+})

pods/server/src/rpc.ts

@@ -161,11 +161,11 @@ async function isApiTokenRevoked (apiTokenId: string, accountClient: AccountClie
 // ── Token Scope Enforcement ─────────────────────────────────────────
 // Phase 1: coarse scopes only (read:*, write:*, delete:*)
 
-function hasScope (scopes: string[], required: string): boolean {
+export function hasScope (scopes: string[], required: string): boolean {
   return scopes.includes(required)
 }
 
-function getRequiredScope (method: string): string | null {
+export function getRequiredScope (method: string): string | null {
   switch (method) {
     case 'ping':
     case 'generateId':

server/account/src/__tests__/apiTokenScopes.test.ts

@@ -0,0 +1,249 @@
+//
+// Copyright © 2025 Hardcore Engineering Inc.
+//
+// Licensed under the Eclipse Public License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License. You may
+// obtain a copy of the License at https://www.eclipse.org/legal/epl-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+//
+// See the License for the specific language governing permissions and
+// limitations under the License.
+//
+
+import {
+  AccountRole,
+  type MeasureContext,
+  type PersonUuid,
+  type WorkspaceUuid
+} from '@hcengineering/core'
+import platform, { PlatformError, Severity, Status } from '@hcengineering/platform'
+import { decodeTokenVerbose, generateToken } from '@hcengineering/server-token'
+
+import { type AccountDB } from '../types'
+import { getMethods } from '../operations'
+
+jest.mock('@hcengineering/platform', () => {
+  const actual = jest.requireActual('@hcengineering/platform')
+  return {
+    ...actual,
+    ...actual.default,
+    getMetadata: jest.fn(),
+    translate: jest.fn((id, params) => `${id} << ${JSON.stringify(params)}`)
+  }
+})
+
+jest.mock('@hcengineering/server-token', () => {
+  class TokenError extends Error {
+    constructor (msg: string) {
+      super(msg)
+      this.name = 'TokenError'
+    }
+  }
+  return {
+    decodeTokenVerbose: jest.fn(),
+    decodeToken: jest.fn(),
+    TokenError,
+    generateToken: jest.fn().mockImplementation((account: string, workspace: string, extra: any) => {
+      return `mocked-token-${account}-${workspace}-${JSON.stringify(extra)}`
+    })
+  }
+})
+
+describe('createApiToken scopes', () => {
+  const mockCtx = {
+    error: jest.fn(),
+    info: jest.fn(),
+    warn: jest.fn()
+  } as unknown as MeasureContext
+
+  const accountUuid = 'account-uuid' as PersonUuid
+  const workspaceUuid = 'workspace-uuid' as WorkspaceUuid
+
+  const mockDb = {
+    account: { findOne: jest.fn() },
+    workspace: { find: jest.fn().mockResolvedValue([]) },
+    apiToken: {
+      find: jest.fn().mockResolvedValue([]),
+      findOne: jest.fn(),
+      insertOne: jest.fn(),
+      update: jest.fn()
+    },
+    getWorkspaceRole: jest.fn()
+  } as unknown as AccountDB
+
+  const methods = getMethods()
+  const createApiToken = methods.createApiToken!
+
+  beforeEach(() => {
+    jest.clearAllMocks()
+    ;(decodeTokenVerbose as jest.Mock).mockReturnValue({
+      account: accountUuid,
+      workspace: workspaceUuid,
+      extra: {}
+    })
+    ;(mockDb.getWorkspaceRole as jest.Mock).mockResolvedValue(AccountRole.Owner)
+    ;(mockDb.apiToken.find as jest.Mock).mockResolvedValue([])
+    ;(mockDb.apiToken.insertOne as jest.Mock).mockResolvedValue(undefined)
+  })
+
+  test('creates token with valid scopes', async () => {
+    const result = await createApiToken(
+      mockCtx, mockDb, null,
+      { id: 1, params: { name: 'test', workspaceUuid, expiryDays: 30, scopes: ['read:*'] } },
+      'test-token'
+    )
+
+    expect(result.result).toBeDefined()
+    expect(result.result.id).toBeDefined()
+    expect(result.result.token).toContain('mocked-token')
+
+    // Verify scopes were passed to generateToken
+    expect(generateToken).toHaveBeenCalledWith(
+      accountUuid,
+      workspaceUuid,
+      expect.objectContaining({ scopes: '["read:*"]' }),
+      undefined,
+      expect.any(Object)
+    )
+
+    // Verify scopes were persisted to DB
+    expect(mockDb.apiToken.insertOne).toHaveBeenCalledWith(
+      expect.objectContaining({ scopes: ['read:*'] })
+    )
+  })
+
+  test('creates token with multiple valid scopes', async () => {
+    const result = await createApiToken(
+      mockCtx, mockDb, null,
+      { id: 1, params: { name: 'test', workspaceUuid, expiryDays: 30, scopes: ['read:*', 'write:*', 'delete:*'] } },
+      'test-token'
+    )
+
+    expect(result.result).toBeDefined()
+    expect(mockDb.apiToken.insertOne).toHaveBeenCalledWith(
+      expect.objectContaining({ scopes: ['read:*', 'write:*', 'delete:*'] })
+    )
+  })
+
+  test('creates token without scopes (full access, backward compat)', async () => {
+    const result = await createApiToken(
+      mockCtx, mockDb, null,
+      { id: 1, params: { name: 'test', workspaceUuid, expiryDays: 30 } },
+      'test-token'
+    )
+
+    expect(result.result).toBeDefined()
+
+    // No scopes in JWT extra
+    expect(generateToken).toHaveBeenCalledWith(
+      accountUuid,
+      workspaceUuid,
+      expect.not.objectContaining({ scopes: expect.anything() }),
+      undefined,
+      expect.any(Object)
+    )
+
+    // scopes field should be undefined in DB insert
+    const insertArg = (mockDb.apiToken.insertOne as jest.Mock).mock.calls[0][0]
+    expect(insertArg.scopes).toBeUndefined()
+  })
+
+  test('rejects invalid scope format', async () => {
+    const result = await createApiToken(
+      mockCtx, mockDb, null,
+      { id: 1, params: { name: 'test', workspaceUuid, expiryDays: 30, scopes: ['invalid'] } },
+      'test-token'
+    )
+
+    expect(result.error).toBeDefined()
+  })
+
+  test('rejects empty scopes array', async () => {
+    const result = await createApiToken(
+      mockCtx, mockDb, null,
+      { id: 1, params: { name: 'test', workspaceUuid, expiryDays: 30, scopes: [] } },
+      'test-token'
+    )
+
+    expect(result.error).toBeDefined()
+  })
+
+  test('rejects domain-scoped scopes in Phase 1', async () => {
+    const result = await createApiToken(
+      mockCtx, mockDb, null,
+      { id: 1, params: { name: 'test', workspaceUuid, expiryDays: 30, scopes: ['read:tracker'] } },
+      'test-token'
+    )
+
+    expect(result.error).toBeDefined()
+  })
+})
+
+describe('listApiTokens includes scopes', () => {
+  const mockCtx = {
+    error: jest.fn(),
+    info: jest.fn(),
+    warn: jest.fn()
+  } as unknown as MeasureContext
+
+  const accountUuid = 'account-uuid' as PersonUuid
+  const workspaceUuid = 'workspace-uuid' as WorkspaceUuid
+
+  const mockDb = {
+    workspace: {
+      find: jest.fn().mockResolvedValue([{ uuid: workspaceUuid, name: 'Test' }])
+    },
+    apiToken: {
+      find: jest.fn().mockResolvedValue([
+        {
+          id: 'token-1',
+          accountUuid,
+          name: 'Read Only',
+          workspaceUuid,
+          createdOn: 1000,
+          expiresOn: 2000,
+          revoked: false,
+          scopes: ['read:*']
+        },
+        {
+          id: 'token-2',
+          accountUuid,
+          name: 'Legacy',
+          workspaceUuid,
+          createdOn: 1000,
+          expiresOn: 2000,
+          revoked: false
+          // no scopes field (legacy)
+        }
+      ])
+    }
+  } as unknown as AccountDB
+
+  const methods = getMethods()
+  const listApiTokens = methods.listApiTokens!
+
+  beforeEach(() => {
+    jest.clearAllMocks()
+    ;(decodeTokenVerbose as jest.Mock).mockReturnValue({
+      account: accountUuid,
+      workspace: workspaceUuid,
+      extra: {}
+    })
+  })
+
+  test('returns scopes for scoped tokens and undefined for legacy', async () => {
+    const result = await listApiTokens(
+      mockCtx, mockDb, null,
+      { id: 1, params: {} },
+      'test-token'
+    )
+
+    const tokens = result.result
+    expect(tokens).toHaveLength(2)
+    expect(tokens[0].scopes).toEqual(['read:*'])
+    expect(tokens[1].scopes).toBeUndefined()
+  })
+})