@open-mercato/shared 0.7.0 → 0.7.1-develop.7102.1.b41f7e3e51

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-mercato/shared",
-  "version": "0.7.0",
+  "version": "0.7.1-develop.7102.1.b41f7e3e51",
   "license": "MIT",
   "type": "module",
   "main": "./dist/index.js",
@@ -40,6 +40,10 @@
       "types": "./src/lib/bootstrap/dynamicLoader.ts",
       "default": "./dist/lib/bootstrap/dynamicLoader.js"
     },
+    "./lib/auth/principal-service": {
+      "types": "./src/lib/auth/principal-service.ts",
+      "default": "./dist/lib/auth/principal-service.js"
+    },
     "./lib/webhooks": {
       "types": "./src/lib/webhooks/index.ts",
       "default": "./dist/lib/webhooks/index.js"
@@ -105,9 +109,11 @@
     "@mikro-orm/core": "^7.1.8",
     "@mikro-orm/decorators": "^7.1.8",
     "@mikro-orm/postgresql": "^7.1.8",
-    "@open-mercato/cache": "0.7.0",
+    "@open-mercato/cache": "0.7.1-develop.7102.1.b41f7e3e51",
+    "@types/html-to-text": "^9.0.4",
     "@types/sanitize-html": "^2.16.1",
     "dotenv": "^17.4.2",
+    "html-to-text": "^10.0.0",
     "pino": "^10.3.1",
     "rate-limiter-flexible": "^11.2.0",
     "re2js": "2.8.6",
@@ -129,5 +135,6 @@
     "type": "git",
     "url": "https://github.com/open-mercato/open-mercato",
     "directory": "packages/shared"
-  }
+  },
+  "stableVersion": "0.7.0"
 }

package/src/lib/auth/__tests__/jwt.test.ts

@@ -470,3 +470,16 @@ describe('jwt helpers', () => {
     })
   })
 })
+
+describe('isMfaPendingJwtPayload', () => {
+  it('flags pending challenge payloads only', async () => {
+    const { isMfaPendingJwtPayload } = await import('../jwt')
+    expect(isMfaPendingJwtPayload({ mfa_pending: true, mfa_verified: false })).toBe(true)
+    expect(isMfaPendingJwtPayload({ mfa_pending: true })).toBe(true)
+    expect(isMfaPendingJwtPayload({ mfa_pending: true, mfa_verified: true })).toBe(false)
+    expect(isMfaPendingJwtPayload({ mfa_pending: false, mfa_verified: true })).toBe(false)
+    expect(isMfaPendingJwtPayload({})).toBe(false)
+    expect(isMfaPendingJwtPayload(null)).toBe(false)
+    expect(isMfaPendingJwtPayload('token')).toBe(false)
+  })
+})

package/src/lib/auth/__tests__/mfaPendingAccess.test.ts

@@ -0,0 +1,69 @@
+import {
+  isMfaPendingAccessAllowed,
+  listMfaPendingAccessRoutes,
+  registerMfaPendingAccessRoutes,
+} from '../mfaPendingAccess'
+
+describe('mfaPendingAccess', () => {
+  it('ships an empty generic registry and denies unknown routes by default', () => {
+    const registeredPaths = listMfaPendingAccessRoutes().map((route) => route.path)
+    expect(registeredPaths).not.toContain('/api/acme-mfa/complete')
+    expect(isMfaPendingAccessAllowed('POST', '/api/acme-mfa/complete')).toBe(false)
+    expect(isMfaPendingAccessAllowed('GET', '/api/customers/people')).toBe(false)
+  })
+
+  it('allows registered completion routes for their exact methods only', () => {
+    registerMfaPendingAccessRoutes([{ path: '/api/acme-mfa/t2/verify', methods: ['POST'] }])
+
+    expect(isMfaPendingAccessAllowed('POST', '/api/acme-mfa/t2/verify')).toBe(true)
+    expect(isMfaPendingAccessAllowed('post', '/api/acme-mfa/t2/verify')).toBe(true)
+    expect(isMfaPendingAccessAllowed('POST', '/api/acme-mfa/t2/verify/')).toBe(true)
+    expect(isMfaPendingAccessAllowed('GET', '/api/acme-mfa/t2/verify')).toBe(false)
+    expect(isMfaPendingAccessAllowed('PUT', '/api/acme-mfa/t2/verify')).toBe(false)
+  })
+
+  it('rejects unregistered paths and near-misses', () => {
+    registerMfaPendingAccessRoutes([{ path: '/api/acme-mfa/t3/recovery', methods: ['POST'] }])
+
+    expect(isMfaPendingAccessAllowed('POST', '/api/customers/people')).toBe(false)
+    expect(isMfaPendingAccessAllowed('POST', '/api/acme-mfa/t3/unrelated')).toBe(false)
+    expect(isMfaPendingAccessAllowed('POST', '/api/acme-mfa/t3/recovery/impersonate')).toBe(false)
+    expect(isMfaPendingAccessAllowed('POST', '/api/auth/login')).toBe(false)
+    expect(isMfaPendingAccessAllowed('POST', '/api/acme-mfa/t3/recovery-codes')).toBe(false)
+  })
+
+  it('is fail-closed on missing or malformed input', () => {
+    registerMfaPendingAccessRoutes([{ path: '/api/acme-mfa/t4/complete', methods: ['POST'] }])
+
+    expect(isMfaPendingAccessAllowed(undefined, '/api/acme-mfa/t4/complete')).toBe(false)
+    expect(isMfaPendingAccessAllowed(null, '/api/acme-mfa/t4/complete')).toBe(false)
+    expect(isMfaPendingAccessAllowed('', '')).toBe(false)
+    expect(isMfaPendingAccessAllowed('POST', undefined)).toBe(false)
+    expect(isMfaPendingAccessAllowed('POST', 'not-a-path')).toBe(false)
+  })
+
+  it('registers additional routes additively and idempotently', () => {
+    const routeCountBefore = listMfaPendingAccessRoutes().length
+
+    registerMfaPendingAccessRoutes([
+      { path: '/api/acme-mfa/t5/complete', methods: ['post', 'POST'] },
+    ])
+    expect(isMfaPendingAccessAllowed('POST', '/api/acme-mfa/t5/complete')).toBe(true)
+
+    registerMfaPendingAccessRoutes([
+      { path: '/api/acme-mfa/t5/complete/', methods: ['POST'] },
+      { path: '/api/acme-mfa/t5/complete', methods: ['GET'] },
+    ])
+    const merged = listMfaPendingAccessRoutes().find((route) => route.path === '/api/acme-mfa/t5/complete')
+    expect(merged).toBeDefined()
+    expect(merged?.methods).toEqual(['GET', 'POST'])
+    expect(listMfaPendingAccessRoutes()).toHaveLength(routeCountBefore + 1)
+
+    registerMfaPendingAccessRoutes([
+      { path: 'no-leading-slash', methods: [] },
+      { path: '/api/acme-mfa/t5/broken', methods: [] },
+    ] as never)
+    expect(listMfaPendingAccessRoutes()).toHaveLength(routeCountBefore + 1)
+    expect(isMfaPendingAccessAllowed('POST', '/api/acme-mfa/t5/broken')).toBe(false)
+  })
+})

package/src/lib/auth/__tests__/organizationAccess.test.ts

@@ -1,4 +1,39 @@
-import { isOrganizationAccessAllowed } from '@open-mercato/shared/lib/auth/organizationAccess'
+import {
+  isOrganizationAccessAllowed,
+  isUnrestrictedOrganizationScope,
+} from '@open-mercato/shared/lib/auth/organizationAccess'
+
+describe('isUnrestrictedOrganizationScope', () => {
+  it('allows super admins regardless of allowed organizations', () => {
+    expect(
+      isUnrestrictedOrganizationScope({
+        isSuperAdmin: true,
+        allowedOrganizationIds: [],
+      }),
+    ).toBe(true)
+  })
+
+  it('allows truly unrestricted non-superadmin scopes', () => {
+    expect(
+      isUnrestrictedOrganizationScope({
+        isSuperAdmin: false,
+        allowedOrganizationIds: null,
+      }),
+    ).toBe(true)
+  })
+
+  it.each([undefined, [] as string[], ['org-a']])(
+    'denies restricted non-superadmin scopes with allowedOrganizationIds=%p',
+    (allowedOrganizationIds) => {
+      expect(
+        isUnrestrictedOrganizationScope({
+          isSuperAdmin: false,
+          allowedOrganizationIds,
+        }),
+      ).toBe(false)
+    },
+  )
+})
 
 describe('isOrganizationAccessAllowed', () => {
   it('allows super admins regardless of scope', () => {

package/src/lib/auth/__tests__/principalServiceExport.test.ts

@@ -0,0 +1,67 @@
+import { existsSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+const PACKAGE_ROOT = join(__dirname, '..', '..', '..', '..')
+const SUBPATH = './lib/auth/principal-service'
+
+type ExportTarget = { types?: string | string[]; default?: string }
+
+function readExports(): Record<string, ExportTarget | string> {
+  const packageJson = JSON.parse(readFileSync(join(PACKAGE_ROOT, 'package.json'), 'utf8')) as {
+    exports?: Record<string, ExportTarget | string>
+  }
+  return packageJson.exports ?? {}
+}
+
+/**
+ * Node's subpath resolution: an exact key wins outright, and only when none
+ * matches do the `*` patterns compete on the longest static prefix. Mirroring
+ * it here is the point of the test — a subpath that resolves only through a
+ * wildcard is at the mercy of whichever resolver a consumer happens to run
+ * (packed tarball, bundler, Jest), and those do not agree on wildcard handling.
+ */
+function resolveSubpath(exports: Record<string, ExportTarget | string>, subpath: string): string | null {
+  if (Object.prototype.hasOwnProperty.call(exports, subpath)) return subpath
+  let best: string | null = null
+  for (const key of Object.keys(exports)) {
+    const star = key.indexOf('*')
+    if (star < 0) continue
+    const prefix = key.slice(0, star)
+    const suffix = key.slice(star + 1)
+    if (!subpath.startsWith(prefix) || !subpath.endsWith(suffix)) continue
+    if (subpath.length < prefix.length + suffix.length) continue
+    if (!best || prefix.length > best.slice(0, best.indexOf('*')).length) best = key
+  }
+  return best
+}
+
+describe('@open-mercato/shared principal-service export map', () => {
+  const exports = readExports()
+
+  it('resolves through an explicit entry rather than a wildcard pattern', () => {
+    expect(resolveSubpath(exports, SUBPATH)).toBe(SUBPATH)
+  })
+
+  it('maps types to the source module and default to the built module', () => {
+    const target = exports[SUBPATH]
+    expect(typeof target).toBe('object')
+    expect(target).toEqual({
+      types: './src/lib/auth/principal-service.ts',
+      default: './dist/lib/auth/principal-service.js',
+    })
+  })
+
+  // Both halves of the mapping must exist in a packed package. `default` is
+  // produced by `yarn build:packages`, which the validation gate runs before
+  // `yarn test`.
+  it('ships both mapped files', () => {
+    const target = exports[SUBPATH] as ExportTarget
+    expect(existsSync(join(PACKAGE_ROOT, target.types as string))).toBe(true)
+    expect(existsSync(join(PACKAGE_ROOT, target.default as string))).toBe(true)
+  })
+
+  it('keeps the module importable under the mapped default condition', async () => {
+    const target = exports[SUBPATH] as ExportTarget
+    await expect(import(join(PACKAGE_ROOT, target.default as string))).resolves.toBeDefined()
+  })
+})

package/src/lib/auth/__tests__/server.apiKeyCache.test.ts

@@ -94,6 +94,244 @@ describe('resolveApiKeyAuth caching + lastUsedAt debounce', () => {
     expect(emFlush).toHaveBeenCalledTimes(1)
   })
 
+  it('retains the creator identity for a regular tenant-scoped key', async () => {
+    const { getAuthFromRequest } = await import('@open-mercato/shared/lib/auth/server')
+    findApiKeyBySecret.mockResolvedValue({
+      id: 'key-tenant-scoped',
+      name: 'tenant scoped',
+      tenantId: 'tenant-1',
+      organizationId: null,
+      rolesJson: [],
+      sessionToken: null,
+      sessionUserId: null,
+      sessionSecretEncrypted: null,
+      opencodeSessionId: null,
+      createdBy: 'creator-1',
+      expiresAt: null,
+      lastUsedAt: null,
+    })
+    emFindOne.mockImplementation(async (_entity: unknown, where: Record<string, unknown>) => {
+      if (where.id === 'tenant-1' && where.isActive === true) return { id: 'tenant-1' }
+      if (where.id === 'creator-1') {
+        return { id: 'creator-1', tenantId: 'tenant-1', organizationId: 'creator-org' }
+      }
+      return null
+    })
+
+    const auth = await getAuthFromRequest(buildRequest('tenant-scoped-secret'))
+
+    expect(auth).toMatchObject({
+      sub: 'api_key:key-tenant-scoped',
+      tenantId: 'tenant-1',
+      orgId: null,
+      isApiKey: true,
+      keyId: 'key-tenant-scoped',
+      userId: 'creator-1',
+    })
+    // The creator remains the key's legacy identity, but its concrete
+    // organization does not narrow a tenant-scoped key.
+    expect(emFindOne).toHaveBeenCalledWith(
+      expect.anything(),
+      { id: 'creator-1', deletedAt: null },
+    )
+  })
+
+  it('rejects a tenant-scoped regular key once its creator is soft-deleted', async () => {
+    const { getAuthFromRequest } = await import('@open-mercato/shared/lib/auth/server')
+    findApiKeyBySecret.mockResolvedValue({
+      id: 'key-deleted-creator',
+      name: 'deleted creator',
+      tenantId: 'tenant-1',
+      organizationId: null,
+      rolesJson: [],
+      sessionToken: null,
+      sessionUserId: null,
+      sessionSecretEncrypted: null,
+      opencodeSessionId: null,
+      createdBy: 'creator-1',
+      expiresAt: null,
+      lastUsedAt: null,
+    })
+    emFindOne.mockImplementation(async (_entity: unknown, where: Record<string, unknown>) => {
+      if (where.id === 'tenant-1' && where.isActive === true) return { id: 'tenant-1' }
+      return null
+    })
+
+    await expect(
+      getAuthFromRequest(buildRequest('deleted-creator-secret')),
+    ).resolves.toBeNull()
+  })
+
+  it('rejects a tenant-scoped regular key whose creator moved to another tenant', async () => {
+    const { getAuthFromRequest } = await import('@open-mercato/shared/lib/auth/server')
+    findApiKeyBySecret.mockResolvedValue({
+      id: 'key-foreign-creator',
+      name: 'foreign creator',
+      tenantId: 'tenant-1',
+      organizationId: null,
+      rolesJson: [],
+      sessionToken: null,
+      sessionUserId: null,
+      sessionSecretEncrypted: null,
+      opencodeSessionId: null,
+      createdBy: 'creator-1',
+      expiresAt: null,
+      lastUsedAt: null,
+    })
+    emFindOne.mockImplementation(async (_entity: unknown, where: Record<string, unknown>) => {
+      if (where.id === 'tenant-1' && where.isActive === true) return { id: 'tenant-1' }
+      if (where.id === 'creator-1') {
+        return { id: 'creator-1', tenantId: 'tenant-2', organizationId: null }
+      }
+      return null
+    })
+
+    await expect(
+      getAuthFromRequest(buildRequest('foreign-creator-secret')),
+    ).resolves.toBeNull()
+  })
+
+  it('accepts a tenant-scoped regular key that records no creator', async () => {
+    const { getAuthFromRequest } = await import('@open-mercato/shared/lib/auth/server')
+    findApiKeyBySecret.mockResolvedValue({
+      id: 'key-no-creator',
+      name: 'no creator',
+      tenantId: 'tenant-1',
+      organizationId: null,
+      rolesJson: [],
+      sessionToken: null,
+      sessionUserId: null,
+      sessionSecretEncrypted: null,
+      opencodeSessionId: null,
+      createdBy: null,
+      expiresAt: null,
+      lastUsedAt: null,
+    })
+    emFindOne.mockImplementation(async (_entity: unknown, where: Record<string, unknown>) => {
+      if (where.id === 'tenant-1' && where.isActive === true) return { id: 'tenant-1' }
+      return null
+    })
+
+    await expect(
+      getAuthFromRequest(buildRequest('no-creator-secret')),
+    ).resolves.toMatchObject({ keyId: 'key-no-creator', tenantId: 'tenant-1' })
+  })
+
+  it('retains the creator identity for an organization-scoped regular key', async () => {
+    const { getAuthFromRequest } = await import('@open-mercato/shared/lib/auth/server')
+    findApiKeyBySecret.mockResolvedValue({
+      id: 'key-organization-scoped',
+      name: 'organization scoped',
+      tenantId: 'tenant-1',
+      organizationId: 'org-1',
+      rolesJson: [],
+      sessionToken: null,
+      sessionUserId: null,
+      sessionSecretEncrypted: null,
+      opencodeSessionId: null,
+      createdBy: 'creator-1',
+      expiresAt: null,
+      lastUsedAt: null,
+    })
+    emFindOne.mockImplementation(async (_entity: unknown, where: Record<string, unknown>) => {
+      if (where.id === 'creator-1') {
+        return { id: 'creator-1', tenantId: 'tenant-1', organizationId: 'org-1' }
+      }
+      return null
+    })
+
+    await expect(
+      getAuthFromRequest(buildRequest('organization-scoped-secret')),
+    ).resolves.toMatchObject({
+      sub: 'api_key:key-organization-scoped',
+      tenantId: 'tenant-1',
+      orgId: 'org-1',
+      userId: 'creator-1',
+    })
+  })
+
+  it('rejects an organization-scoped regular key when its creator scope no longer matches', async () => {
+    const { getAuthFromRequest } = await import('@open-mercato/shared/lib/auth/server')
+    findApiKeyBySecret.mockResolvedValue({
+      id: 'key-organization-mismatch',
+      name: 'organization mismatch',
+      tenantId: 'tenant-1',
+      organizationId: 'org-1',
+      rolesJson: [],
+      sessionToken: null,
+      sessionUserId: null,
+      sessionSecretEncrypted: null,
+      opencodeSessionId: null,
+      createdBy: 'creator-1',
+      expiresAt: null,
+      lastUsedAt: null,
+    })
+    emFindOne.mockImplementation(async (_entity: unknown, where: Record<string, unknown>) => {
+      if (where.id === 'creator-1') {
+        return { id: 'creator-1', tenantId: 'tenant-1', organizationId: 'org-2' }
+      }
+      return null
+    })
+
+    await expect(
+      getAuthFromRequest(buildRequest('organization-scope-mismatch-secret')),
+    ).resolves.toBeNull()
+  })
+
+  it('keeps session keys strictly bound to their persisted user and scope', async () => {
+    const { getAuthFromRequest } = await import('@open-mercato/shared/lib/auth/server')
+    findApiKeyBySecret.mockResolvedValue({
+      id: 'key-session-scoped',
+      name: 'session scoped',
+      tenantId: 'tenant-1',
+      organizationId: null,
+      rolesJson: [],
+      sessionToken: 'sess_123',
+      sessionUserId: 'session-user-1',
+      sessionSecretEncrypted: null,
+      opencodeSessionId: null,
+      createdBy: 'session-user-1',
+      expiresAt: null,
+      lastUsedAt: null,
+    })
+    emFindOne.mockImplementation(async (_entity: unknown, where: Record<string, unknown>) => {
+      if (where.id === 'session-user-1') {
+        return { id: 'session-user-1', tenantId: 'tenant-1', organizationId: 'user-org' }
+      }
+      return null
+    })
+
+    await expect(
+      getAuthFromRequest(buildRequest('session-scope-mismatch-secret')),
+    ).resolves.toBeNull()
+  })
+
+  it('fails closed when a row has session markers but no bound session user', async () => {
+    const { getAuthFromRequest } = await import('@open-mercato/shared/lib/auth/server')
+    findApiKeyBySecret.mockResolvedValue({
+      id: 'key-malformed-session',
+      name: 'malformed session',
+      tenantId: 'tenant-1',
+      organizationId: null,
+      rolesJson: [],
+      sessionToken: 'sess_missing_user',
+      sessionUserId: null,
+      sessionSecretEncrypted: null,
+      opencodeSessionId: null,
+      createdBy: 'creator-1',
+      expiresAt: null,
+      lastUsedAt: null,
+    })
+
+    await expect(
+      getAuthFromRequest(buildRequest('malformed-session-secret')),
+    ).resolves.toBeNull()
+    expect(emFindOne).not.toHaveBeenCalledWith(
+      expect.anything(),
+      expect.objectContaining({ id: 'creator-1' }),
+    )
+  })
+
   it('caches negative lookups so invalid keys skip the bcrypt+DB path', async () => {
     const { getAuthFromRequest } = await import('@open-mercato/shared/lib/auth/server')
     findApiKeyBySecret.mockResolvedValue(null)
@@ -128,4 +366,90 @@ describe('resolveApiKeyAuth caching + lastUsedAt debounce', () => {
     await getAuthFromRequest(buildRequest('secret-invalidate'))
     expect(findApiKeyBySecret).toHaveBeenCalledTimes(2)
   })
+
+  describe('super-admin bit stays bounded by the effective key scope', () => {
+    async function resolveWithSuperAdminRole(input: {
+      secret: string
+      keyId: string
+      keyOrganizationId: string | null
+      aclOrganizations: string[] | null
+    }) {
+      const { RoleAcl } = await import('@open-mercato/core/modules/auth/data/entities')
+      const { Organization, Tenant } = await import('@open-mercato/core/modules/directory/data/entities')
+      const { getAuthFromRequest } = await import('@open-mercato/shared/lib/auth/server')
+      // A creator-less key is validated against a live tenant (and organization when bound).
+      emFindOne.mockImplementation(async (entity: unknown) => {
+        if (entity === Tenant) return { id: 'tenant-1' }
+        if (entity === Organization) return { id: input.keyOrganizationId, tenant: { id: 'tenant-1' } }
+        return null
+      })
+      findApiKeyBySecret.mockResolvedValue({
+        id: input.keyId,
+        name: 'super admin key',
+        tenantId: 'tenant-1',
+        organizationId: input.keyOrganizationId,
+        rolesJson: ['role-super'],
+        sessionToken: null,
+        sessionUserId: null,
+        sessionSecretEncrypted: null,
+        opencodeSessionId: null,
+        createdBy: null,
+        expiresAt: null,
+        lastUsedAt: null,
+      })
+      emFind.mockImplementation(async (entity: unknown) => {
+        if (entity === RoleAcl) {
+          return [{ isSuperAdmin: true, organizationsJson: input.aclOrganizations }]
+        }
+        return []
+      })
+      return getAuthFromRequest(buildRequest(input.secret))
+    }
+
+    it('withholds it from an organization-bound key even when a role grants it', async () => {
+      // Generic guards trust this bit before live RBAC, so an organization-restricted key must
+      // never take super-admin shortcuts outside its own scope.
+      const auth = await resolveWithSuperAdminRole({
+        secret: 'super-bound',
+        keyId: 'key-super-bound',
+        keyOrganizationId: 'org-1',
+        aclOrganizations: null,
+      })
+
+      expect(auth).toMatchObject({ isApiKey: true, isSuperAdmin: false })
+    })
+
+    it('withholds it when the granting role ACL is itself organization-restricted', async () => {
+      const auth = await resolveWithSuperAdminRole({
+        secret: 'super-restricted',
+        keyId: 'key-super-restricted',
+        keyOrganizationId: null,
+        aclOrganizations: ['org-1'],
+      })
+
+      expect(auth).toMatchObject({ isApiKey: true, isSuperAdmin: false })
+    })
+
+    it('grants it for an unbound key with an unrestricted role grant', async () => {
+      const auth = await resolveWithSuperAdminRole({
+        secret: 'super-global',
+        keyId: 'key-super-global',
+        keyOrganizationId: null,
+        aclOrganizations: null,
+      })
+
+      expect(auth).toMatchObject({ isApiKey: true, isSuperAdmin: true })
+    })
+
+    it('grants it for an unbound key whose role ACL uses the __all__ sentinel', async () => {
+      const auth = await resolveWithSuperAdminRole({
+        secret: 'super-all-sentinel',
+        keyId: 'key-super-all-sentinel',
+        keyOrganizationId: null,
+        aclOrganizations: ['__all__'],
+      })
+
+      expect(auth).toMatchObject({ isApiKey: true, isSuperAdmin: true })
+    })
+  })
 })